Core Concepts Beginner

What is a Node?

A node (or "function block") is the basic building block in SPC programs. Players place nodes on the programming canvas, connect them with wires, and the LOGO runtime executes them every server tick (20 times per second).

Each node has three aspects:

Node Schema

SpcNodeSchema is a Java record that declares everything about a node type. Think of it as the "blueprint" — it tells the editor what ports to show, what parameters to offer, and when the node runs.

Schema fields

new SpcNodeSchema(
    "mymod:temperature_sensor",     // typeId
    SpcExecutionPhase.INPUT_READ,    // phase
    List.of( /* ports */ ),              // ports
    List.of( /* params */ ),             // parameters
    false                              // requiresDisplay
);

Ports & Connections

Ports are the inputs and outputs of a node. In the editor, they appear as connection points on the node's left (inputs) and right (outputs) sides. Wires connect an output port of one node to an input port of another.

SpcPortSpec fields

Common port naming conventions

// A node with 2 digital inputs, 1 digital output, and 1 integer output
List.of(
    new SpcPortSpec("I1",  SpcPortDirection.INPUT,  SpcSignalType.DIGITAL, false),
    new SpcPortSpec("I2",  SpcPortDirection.INPUT,  SpcSignalType.DIGITAL, false),
    new SpcPortSpec("Q",   SpcPortDirection.OUTPUT, SpcSignalType.DIGITAL, false),
    new SpcPortSpec("AQ",  SpcPortDirection.OUTPUT, SpcSignalType.INTEGER, false)
)

Inverted inputs

Players can place a negation bubble on any digital input in the editor. At compile time, your factory can check ctx.isInverted("I1") and apply ! to the value.

Signal Types & Values

Signals are the data flowing through wires between nodes. Each signal has a type and a value. The SpcSignalValue record carries both.

The six signal types

Creating signal values

// Factory methods on SpcSignalValue:
SpcSignalValue.digital(true);                      // DIGITAL
SpcSignalValue.integer(42);                        // INTEGER
SpcSignalValue.decimal(3.14);                      // DECIMAL
SpcSignalValue.text("hello");                      // TEXT
SpcSignalValue.item("minecraft:diamond", 64);       // ITEM
SpcSignalValue.itemId("minecraft:diamond");         // ITEM_ID

Cross-type conversion

You can read any signal as any type using conversion methods. This is useful when different node types need to interoperate:

Pre-defined constants

To avoid allocations, use the static constants for common values:

SpcSignalValue.DIGITAL_FALSE   // false
SpcSignalValue.DIGITAL_TRUE    // true
SpcSignalValue.INTEGER_ZERO    // 0
SpcSignalValue.DECIMAL_ZERO    // 0.0
SpcSignalValue.TEXT_EMPTY      // ""
SpcSignalValue.ITEM_EMPTY      // empty item
SpcSignalValue.ITEM_ID_EMPTY   // empty item ID

Execution Phases

Every server tick, the LOGO runtime processes all nodes in a fixed 4-phase order. Each node declares which phase it belongs to. This ensures deterministic execution: inputs are always read before logic runs, logic always before state updates, etc.

Which phase should I use?

Parameters

Parameters are user-configurable values set in the editor's properties dialog. Unlike signals (which change every tick), parameters are set once and remain constant during program execution.

SpcParameterSpec fields

SpcParameterValueType enum

In your factory, read parameters from the NodeCompilationContext:

int radius = ctx.intParameter("radius", 16);         // default: 16
double threshold = ctx.doubleParameter("thresh", 0.5); // default: 0.5
String filter = ctx.stringParameter("filter", "");     // default: ""
boolean invert = ctx.booleanParameter("inv", false);  // default: false

Compilation & Factories

When a player runs a program, the LOGO compiler converts the visual canvas into an executable form. For each placed node, the compiler calls the node's ISpcNodeFactory.create(NodeCompilationContext) method.

NodeCompilationContext

The context provides everything your factory needs:

SpcSignalAddress

A SpcSignalAddress is a (UUID nodeId, String portId) pair that uniquely identifies a signal slot on the runtime bus. You receive them from the compilation context and pass them to your compiled node.

Runtime State

The ISpcRuntimeState interface is the signal bus and persistent storage. Every compiled node receives it in execute(context, state).

Signal bus

Read signals from upstream nodes and write your output signals:

// Read from upstream connections
boolean input = state.readDigitalSignal(myInputAddress);
int value = state.readIntegerSignal(myInputAddress);
double decimal = state.readDecimalSignal(myInputAddress);  
SpcSignalValue raw = state.readSignalValue(myInputAddress);

// Write your outputs
state.setSignal(myOutputAddress, SpcSignalValue.digital(true));
state.setSignal(myOutputAddress, SpcSignalValue.integer(42));

Persistent slots

For stateful nodes (timers, counters, latches), use persistent slots. Values survive across ticks. Use setPending* methods — values are committed after each phase completes, preventing mid-tick race conditions.

Physical output channels

Output nodes that drive real-world I/O use numbered channels:

state.setDigitalOutput(0, true);       // digital output channel 0
state.setAnalogOutput(1, 15);          // analog channel 1, strength 15
state.setFeOutput(0, 1000);             // FE output channel 0, 1000 FE/t

Markers (global variables)

Named global values accessible by all nodes in the program:

boolean flag = state.getMarkerValue("alarm_active");
state.setPendingMarkerValue("alarm_active", true);

int level = state.getAnalogMarkerValue("temp_setpoint");
state.setPendingAnalogMarkerValue("temp_setpoint", 100);

Registries

SPC provides two registries for addon content:

SpcNodeRegistry

Register your node schemas + factories + categories. The compiler and editor query this to find addon nodes.

SpcNodeRegistry.register(schema, factory, category);

SpcContextExtensionRegistry

Register execution context extensions for custom world interactions. See Context Extensions for details.

SpcContextExtensionRegistry.register(IMyExt.class, new MyExtImpl());