italink/unrealclientprotocol/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

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.

Property Format

Node properties are serialized in {Key:Value, Key2:Value2} on the same line as the node declaration. Values use UE reflection import format:

• Scalars: {R:1.0}, {ConstB:0.5}
• Strings: {ParameterName:"MyParam"}
• Structs: {Constant:(R=1,G=0.5,B=0,A=1)}
• Booleans: {R:True}, {TwoSided:true}
• Enums: {ShadingModel:MSM_Unlit}

Error Handling

WriteGraph returns a diff object with:

• nodes_added, nodes_removed, nodes_modified — structural changes
• links_added, links_removed — connection changes
• compile_errors — compilation errors (if applicable)

Common errors:

• "Property not found: ..." — typo in property name
• "Failed to import ..." — invalid property value format
• "Input 'X' not found on N_... (ClassName). Available: [...]" — wrong pin name