State & Persistence Intermediate

Why Persistent Slots?

Simple nodes (AND gate, comparator) are stateless — they compute an output from the current inputs and nothing else. But many useful nodes need to remember data between ticks:

• Counters — how many times has this input gone HIGH?
• Timers — how many ticks has this input been HIGH?
• Toggle switches — is this currently on or off?
• Moving averages — what's the average of the last N readings?
• Edge detectors — was the input different last tick?

You cannot store this data in Java instance fields because compiled nodes must be stateless. Instead, use persistent slots on ISpcRuntimeState. The runtime saves and restores slot values automatically — even across world saves.

public class BadCounter implements ISpcCompiledNode {
    private int count = 0;  // ❌ WRONG — lost on save/load!

    public void execute(...) {
        count++;  // ❌ This won't survive a world reload
    }
}

Available Slot Types

The runtime provides 5 slot types. Each slot is identified by a (nodeId, slotName) pair, so every node instance has its own private storage.

Double Buffering Explained

The SPC runtime uses double buffering for all slot writes. This means:

1. When you call setPending*Slot(), the new value is stored in a pending buffer.
2. The current value (from get*Slot()) is unchanged during this tick.
3. After all nodes in the current phase finish executing, pending values are committed.
4. On the next phase (or next tick), get*Slot() returns the new value.

Why does this matter?

• All nodes in the same phase see the same slot values, regardless of execution order.
• You can't read-your-own-write within the same phase — setPending then get returns the old value.
• This prevents subtle order-dependent bugs where Node A's write affects Node B's read within one tick.

Example: Tick Counter

Counts how many ticks the input has been HIGH. Resets when input goes LOW. Outputs the current count as an integer.

public record TickCounterNode(
    UUID nodeId,
    SpcSignalAddress input,
    SpcSignalAddress output
) implements ISpcCompiledNode {

    @Override public String typeId() { return "mymod:tick_counter"; }
    @Override public SpcExecutionPhase phase() { return STATE_UPDATE; }

    @Override
    public void execute(ISpcExecutionContext ctx, ISpcRuntimeState state) {
        boolean active = state.readDigitalSignal(input);

        if (active) {
            // Read current count, increment, save for next tick
            int count = state.getIntegerSlot(nodeId, "count");
            state.setPendingIntegerSlot(nodeId, "count", count + 1);
            state.setSignal(output, SpcSignalValue.integer(count + 1));
        } else {
            // Input is LOW — reset counter
            state.setPendingIntegerSlot(nodeId, "count", 0);
            state.setSignal(output, SpcSignalValue.integer(0));
        }
    }
}

Example: On-Delay Timer

Output goes HIGH only after the input has been HIGH for at least N ticks. If the input drops LOW before the threshold, the timer resets.

public record OnDelayTimerNode(
    UUID nodeId,
    SpcSignalAddress input,
    SpcSignalAddress output,
    int delayTicks
) implements ISpcCompiledNode {

    @Override public String typeId() { return "mymod:on_delay"; }
    @Override public SpcExecutionPhase phase() { return STATE_UPDATE; }

    @Override
    public void execute(ISpcExecutionContext ctx, ISpcRuntimeState state) {
        boolean active = state.readDigitalSignal(input);
        int elapsed = state.getIntegerSlot(nodeId, "elapsed");

        if (active) {
            elapsed = Math.min(elapsed + 1, delayTicks);
        } else {
            elapsed = 0;  // reset when input drops
        }

        state.setPendingIntegerSlot(nodeId, "elapsed", elapsed);

        boolean triggered = elapsed >= delayTicks;
        state.setSignal(output, SpcSignalValue.digital(triggered));
    }
}

Example: Toggle Switch (Flip-Flop)

Each time the input transitions from LOW → HIGH, the output toggles. Uses a boolean slot to remember the current state and another to detect the edge.

public record ToggleNode(
    UUID nodeId,
    SpcSignalAddress input,
    SpcSignalAddress output
) implements ISpcCompiledNode {

    @Override public String typeId() { return "mymod:toggle"; }
    @Override public SpcExecutionPhase phase() { return STATE_UPDATE; }

    @Override
    public void execute(ISpcExecutionContext ctx, ISpcRuntimeState state) {
        boolean currentInput = state.readDigitalSignal(input);
        boolean prevInput    = state.getBooleanSlot(nodeId, "prev");
        boolean outputState  = state.getBooleanSlot(nodeId, "state");

        // Detect rising edge: was LOW, now HIGH
        if (currentInput && !prevInput) {
            outputState = !outputState;  // toggle!
        }

        // Save state for next tick
        state.setPendingBooleanSlot(nodeId, "prev", currentInput);
        state.setPendingBooleanSlot(nodeId, "state", outputState);

        state.setSignal(output, SpcSignalValue.digital(outputState));
    }
}

Example: Running Average

Computes a smoothed moving average of a decimal input using the double slot type. Useful for smoothing noisy sensor data.

public record RunningAverageNode(
    UUID nodeId,
    SpcSignalAddress input,
    SpcSignalAddress output,
    double alpha     // smoothing factor 0.0–1.0
) implements ISpcCompiledNode {

    @Override public String typeId() { return "mymod:running_avg"; }
    @Override public SpcExecutionPhase phase() { return STATE_UPDATE; }

    @Override
    public void execute(ISpcExecutionContext ctx, ISpcRuntimeState state) {
        double current = state.readDecimalSignal(input);
        double avg     = state.getDoubleSlot(nodeId, "avg");

        // Exponential moving average: new = alpha*current + (1-alpha)*old
        avg = alpha * current + (1.0 - alpha) * avg;

        state.setPendingDoubleSlot(nodeId, "avg", avg);
        state.setSignal(output, SpcSignalValue.decimal(avg));
    }
}

Example: Peak Detector

Tracks the highest value seen on an integer input. A reset input clears the peak.

public record PeakDetectorNode(
    UUID nodeId,
    SpcSignalAddress valueIn,
    SpcSignalAddress resetIn,   // nullable (optional port)
    SpcSignalAddress peakOut
) implements ISpcCompiledNode {

    @Override public String typeId() { return "mymod:peak_detector"; }
    @Override public SpcExecutionPhase phase() { return STATE_UPDATE; }

    @Override
    public void execute(ISpcExecutionContext ctx, ISpcRuntimeState state) {
        // Check if reset is connected and active
        boolean reset = resetIn != null && state.readDigitalSignal(resetIn);

        int peak = reset ? 0 : state.getIntegerSlot(nodeId, "peak");
        int current = state.readIntegerSignal(valueIn);

        if (current > peak) {
            peak = current;
        }

        state.setPendingIntegerSlot(nodeId, "peak", peak);
        state.setSignal(peakOut, SpcSignalValue.integer(peak));
    }
}

Global Markers

While persistent slots are per-node (scoped to a UUID), markers are global variables shared across the entire program. Any node can read or write them by name.

Built-in Latch State

The runtime provides built-in latch and delay counter state. These are used by SPC's own timer/latch nodes, but addons can use them too:

Rules & Gotchas

The golden rules

1. Read with get*Slot(), write with setPending*Slot().
2. Never store mutable state in instance fields on your compiled node.
3. setPending is deferred — your write isn't visible until the next phase.
4. Slots default to zero/false/empty — no initialization needed.
5. Slots survive world saves — saved to NBT automatically.
6. Slots are per-node-instance — two copies of the same node type have independent slots.

Common gotchas