Signal Types & Domains Beginner

What are Signals?

Signals are the data values flowing through wires between nodes. Every wire carries a signal. Every signal has a type (what kind of data) and a value (the actual data). Signals are refreshed every server tick (20 times per second).

The signal system consists of three main classes:

The 6 Signal Types (SpcSignalType)

SpcSignalType is an enum with 6 values. Each represents a different kind of data that can flow through connections.

Enum methods

SpcSignalValue — Creating Signals

SpcSignalValue is a Java record that holds a signal at runtime. It stores all possible value fields plus the active type. Use factory methods to create instances (never the raw constructor).

Record components

Factory Methods

Always use these static methods to create SpcSignalValue instances:

// Examples:
SpcSignalValue.digital(true);                      // DIGITAL true
SpcSignalValue.digital(false);                     // DIGITAL false
SpcSignalValue.integer(42);                        // INTEGER 42
SpcSignalValue.integer(0);                         // returns INTEGER_ZERO constant
SpcSignalValue.decimal(3.14);                      // DECIMAL 3.14
SpcSignalValue.text("hello");                      // TEXT "hello"
SpcSignalValue.text(null);                         // returns TEXT_EMPTY constant
SpcSignalValue.item("minecraft:diamond", 64);       // ITEM diamond x64
SpcSignalValue.itemId("minecraft:diamond");         // ITEM_ID diamond

Pre-defined Constants

Use these static constants to avoid allocating new objects for common values. The factory methods already return these when applicable, but you can reference them directly for clarity:

Cross-type Conversion Methods

You can read any SpcSignalValue as any Java type using the conversion methods. This is how different node types interoperate — an INTEGER signal can be read as a boolean by a digital gate, for example.

Full Conversion Matrix

This table shows exactly what you get when calling each conversion method on each signal type. The Source column is the signal's type; each column shows the conversion result.

SpcSignalAddress

A SpcSignalAddress uniquely identifies a signal slot on the runtime bus. It's how nodes find each other's outputs.

You never create these yourself — you receive them from NodeCompilationContext:

// In your factory:
SpcSignalAddress inputAddr  = ctx.inputAddress("I1");   // where to READ from (null if unconnected)
SpcSignalAddress outputAddr = ctx.outputAddress("Q");    // where to WRITE to (always non-null)

// In your compiled node's execute():
boolean input = state.readDigitalSignal(inputAddr);      // read upstream output
state.setSignal(outputAddr, SpcSignalValue.digital(result)); // write your output

SpcPortSpec — Declaring Ports

SpcPortSpec is a record that declares a single port on a node type. Ports are the connection points shown in the editor.

Constructors

Record components

Common port naming conventions

SpcPortDirection

Methods: getSerializedName(), fromSerializedName(String)

Signal Domains

Signal domains are an API feature that add a compatibility layer on top of signal types. Two ports can only be connected if they have the same signal type and compatible domains.

Why domains exist

Without domains, any INTEGER port can connect to any other INTEGER port. But a "rotational speed" integer and a "redstone level" integer are semantically different — connecting them makes no sense. Domains prevent this.

How domains work

• A port's signalDomain is a String tag, or null
• null = universal — connects to any port of the same signal type
• A non-null domain only connects to ports with the same domain or to universal ports

Example domains you might define

// A rotational speed input — only connects to other "rotation" ports:
new SpcPortSpec("RPM", SpcPortDirection.INPUT, SpcSignalType.INTEGER, true, "rotation")

// A generic integer input — connects to ANY integer port:
new SpcPortSpec("AI1", SpcPortDirection.INPUT, SpcSignalType.INTEGER, true)
// or equivalently:
new SpcPortSpec("AI1", SpcPortDirection.INPUT, SpcSignalType.INTEGER, true, null)

Domain Compatibility Rules

Use portA.isDomainCompatible(portB) to check compatibility:

How to Choose the Right Signal Type