unreal-nodecode-common

NodeCode Common Rules

NodeCode is the unified text-based representation used by UCP to read/write node graphs across Materials, Blueprints, Niagara scripts, and Widget trees. All domain-specific editing skills share the same underlying diff/apply engine. This document describes the common behaviors that apply to all of them.

API

CDO: /Script/UnrealClientProtocolEditor.Default__NodeCodeEditingLibrary

Function	Params	Description
Outline	AssetPath	List available sections for an asset
ReadGraph	AssetPath, Section	Read a section's text representation. Empty Section = all.
WriteGraph	AssetPath, Section, GraphText	Write a section. Triggers recompile/refresh as appropriate.

Node ID Format

• Existing nodes: N_<base62> — 22-character Base62-encoded GUID. ReadGraph always outputs this form.
• New nodes: N_new<int> — temporary ID for nodes you are creating (e.g. N_new0, N_new1). The system assigns a real GUID after WriteGraph.

Connection Syntax (Graph Sections)

Connections are declared on the source (output) node, indented with >:

  > OutputPin -> N_<target>.InputPin    # named output to named input
  > OutputPin -> [GraphOutput]          # output to graph-level output
  > -> N_<target>.InputPin              # single-output node (omit pin name)
  > -> N_<target>                       # single-output to single-input

Domain-specific pin names and graph outputs vary — see each editing skill for details.

Key Rules

1. Preserve node IDs — existing nodes use N_<base62> IDs that encode their GUID. Always keep them unchanged when writing back. Use N_new<int> only for genuinely new nodes.
2. ReadGraph before WriteGraph — always read first to understand the current state.
3. Undo support — all WriteGraph operations are wrapped in transactions and support Ctrl+Z.
4. Incremental diff — WriteGraph only modifies nodes/connections/properties that actually changed. Unchanged parts are left intact.
5. Properties are additive, not resetting — WriteGraph only modifies properties that appear in {...}. Omitting a property does not reset it to its default value; the existing value is preserved. To change a property back to default, you must write it explicitly (e.g. {Period:1.000000} to reset Period). This is critical when correcting previously set non-default values.
6. Verify all node IDs before writing — every N_<id> referenced in > -> connection lines must be defined as a node in the same graph. Referencing an undefined ID silently drops that connection.