Multiblock Modules Advanced

What are Multiblock Modules?

The LOGO machine is a multiblock structure built from physical blocks. With the API, addon mods can register custom block types that the multiblock validator recognizes. This lets you add blocks that read new kinds of inputs (rotation, fluid levels, RF rates) or write new kinds of outputs (motor speeds, valve positions) — all integrated into the standard LOGO programming environment.

What you need

Multiblock Layout

The LOGO multiblock is a 3-tall grid that extends rightward from the processing unit:

SpcMultiblockPosition — Where Modules Go

SpcModuleType — Declaring a Module

SpcModuleType is a record that declares a custom module type's identity and placement rules.

Record components

Constructors

// Custom input module type:
SpcModuleType ROT_INPUT = new SpcModuleType(
    "mymod:rotational_input",
    "Rotational Input",
    SpcMultiblockPosition.INPUT_ROW
);

// Custom structural module (no I/O):
SpcModuleType CUSTOM_CASING = new SpcModuleType(
    "mymod:reinforced_casing",
    "Reinforced Casing",
    SpcMultiblockPosition.MIDDLE_ROW,
    false  // not an I/O module
);

ISpcMultiblockModule — Block Interface

Implement this @FunctionalInterface on your Block subclass. The multiblock BFS discovery recognizes blocks that implement this interface.

public class RotationalInputBlock extends Block implements ISpcMultiblockModule {
    @Override
    public String getModuleTypeId() {
        return "mymod:rotational_input";
    }
}

ISpcPhysicalIoHandler — Reading & Writing

The I/O handler bridges your physical block to the signal bus. Registered alongside the SpcModuleType.

public class RotationalIoHandler implements ISpcPhysicalIoHandler {
    @Override
    public SpcSignalValue readInput(ServerLevel level, BlockPos modulePos) {
        var be = level.getBlockEntity(modulePos);
        if (be instanceof RotationalInputBlockEntity rot) {
            return SpcSignalValue.integer(rot.getRotationalSpeed());
        }
        return SpcSignalValue.INTEGER_ZERO;
    }
}

SpcModuleTypeRegistry — Registration

Methods

SpcModuleTypeRegistration (inner record)

Step-by-Step: Custom Input Module

SpcModuleType ROT_INPUT = new SpcModuleType(
    "mymod:rotational_input",
    "Rotational Input",
    SpcMultiblockPosition.INPUT_ROW
);

public class RotationalIoHandler implements ISpcPhysicalIoHandler {
    @Override
    public SpcSignalValue readInput(ServerLevel level, BlockPos pos) {
        if (level.getBlockEntity(pos) instanceof RotInputBE be)
            return SpcSignalValue.integer(be.getRpm());
        return SpcSignalValue.INTEGER_ZERO;
    }
}

public class RotationalInputBlock extends Block implements ISpcMultiblockModule {
    @Override
    public String getModuleTypeId() {
        return "mymod:rotational_input";
    }
}

SpcModuleTypeRegistry.register(ROT_INPUT, new RotationalIoHandler());

SpcSignalValue rpm = context.readCustomInput("mymod:rotational_input", 1);
int speed = rpm.asInteger();

Step-by-Step: Custom Output Module

Same process as input, but:

• Use SpcMultiblockPosition.OUTPUT_ROW
• Override applyOutput() instead of readInput()
• Called during OUTPUT_APPLY phase

public class MotorOutputHandler implements ISpcPhysicalIoHandler {
    @Override
    public void applyOutput(ServerLevel level, BlockPos pos, SpcSignalValue value) {
        if (level.getBlockEntity(pos) instanceof MotorOutputBE be) {
            be.setTargetSpeed(value.asInteger());
        }
    }
}

// Registration:
SpcModuleType MOTOR_OUT = new SpcModuleType(
    "mymod:motor_output", "Motor Output",
    SpcMultiblockPosition.OUTPUT_ROW);
SpcModuleTypeRegistry.register(MOTOR_OUT, new MotorOutputHandler());

// Writing from a node:
context.applyCustomOutputs("mymod:motor_output",
    Map.of(1, SpcSignalValue.integer(targetSpeed)));

Step-by-Step: Non-I/O Module

Structural modules (custom casings, decorative panels) don't provide I/O channels but still validate as part of the multiblock.

// Just register the type with isIoModule = false, no handler:
SpcModuleType CASING = new SpcModuleType(
    "mymod:reinforced_casing", "Reinforced Casing",
    SpcMultiblockPosition.MIDDLE_ROW, false);
SpcModuleTypeRegistry.register(CASING);

// Block still implements ISpcMultiblockModule:
public class ReinforcedCasingBlock extends Block implements ISpcMultiblockModule {
    @Override
    public String getModuleTypeId() {
        return "mymod:reinforced_casing";
    }
}

Reading Custom Modules in Nodes

Once registered, custom modules appear as channels on the execution context. Use readCustomInput() and applyCustomOutputs() (see Execution Context → Custom Module I/O).

Connected Textures (MB_POS)

When the LOGO multiblock forms, every member block receives a MultiblockPosition value via the mb_pos block state property. This removes borders on internal seams so the structure looks like a single unit. The system is property-driven — any block that registers MB_POS will participate automatically. No callback code needed.

MultiblockPosition Enum

Located at com.hypernova.spc.multiblock.model.MultiblockPosition (included in the API jar since v1.1.3). Ten position values for a 3-row × variable-column grid, plus NONE for unformed state:

NONE — block is not part of a formed multiblock (default / disassembled state).

For a 2-column multiblock, FIRST and LAST are the only columns (no MID). For a 1-column multiblock, every block is both FIRST and LAST.

Step 1 — Java: Register MB_POS on Your Block

Three things are needed in your block class:

@Override
protected void createBlockStateDefinition(
        StateDefinition.Builder<Block, BlockState> builder) {
    super.createBlockStateDefinition(builder);
    builder.add(BlockStateProperties.HORIZONTAL_FACING, MultiblockPosition.MB_POS);
}

public MyAddonBlock(Properties props) {
    super(props);
    registerDefaultState(stateDefinition.any()
        .setValue(BlockStateProperties.HORIZONTAL_FACING, Direction.NORTH)
        .setValue(MultiblockPosition.MB_POS, MultiblockPosition.NONE));
}

public final class SpcMultiblockHelper {
    private static final Method REVALIDATE_AROUND;

    static {
        try {
            Class<?> clazz = Class.forName(
                "com.hypernova.spc.multiblock.runtime.LogoMultiblockManager");
            REVALIDATE_AROUND = clazz.getMethod(
                "revalidateAround", Level.class, BlockPos.class);
        } catch (Exception e) {
            throw new RuntimeException("SPC Core not found", e);
        }
    }

    public static void revalidateAround(Level level, BlockPos pos) {
        if (!level.isClientSide()) {
            try {
                REVALIDATE_AROUND.invoke(null, level, pos);
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }
    }
}

@Override
public void onPlace(BlockState state, Level level, BlockPos pos,
        BlockState oldState, boolean movedByPiston) {
    super.onPlace(state, level, pos, oldState, movedByPiston);
    SpcMultiblockHelper.revalidateAround(level, pos);
}

@Override
public BlockState onRemove(BlockState state, Level level, BlockPos pos,
        BlockState newState, boolean movedByPiston) {
    SpcMultiblockHelper.revalidateAround(level, pos);
    return super.onRemove(state, level, pos, newState, movedByPiston);
}

Full block class example

import com.hypernova.spc.multiblock.model.MultiblockPosition;
import com.hypernova.spc.api.multiblock.ISpcMultiblockModule;

public class MyAddonBlock extends Block implements ISpcMultiblockModule {

    public MyAddonBlock(Properties props) {
        super(props);
        registerDefaultState(stateDefinition.any()
            .setValue(BlockStateProperties.HORIZONTAL_FACING, Direction.NORTH)
            .setValue(MultiblockPosition.MB_POS, MultiblockPosition.NONE));
    }

    @Override
    protected void createBlockStateDefinition(
            StateDefinition.Builder<Block, BlockState> builder) {
        builder.add(BlockStateProperties.HORIZONTAL_FACING, MultiblockPosition.MB_POS);
    }

    @Override
    public String getModuleTypeId() {
        return "mymod:my_block";
    }

    @Override
    public void onPlace(BlockState state, Level level, BlockPos pos,
            BlockState oldState, boolean movedByPiston) {
        super.onPlace(state, level, pos, oldState, movedByPiston);
        SpcMultiblockHelper.revalidateAround(level, pos);
    }

    @Override
    public BlockState onRemove(BlockState state, Level level, BlockPos pos,
            BlockState newState, boolean movedByPiston) {
        SpcMultiblockHelper.revalidateAround(level, pos);
        return super.onRemove(state, level, pos, newState, movedByPiston);
    }
}

That’s all the Java you need. SPC’s multiblock manager will automatically set MB_POS when the structure forms and reset it to NONE when it breaks.

Step 2 — Blockstate JSON

Your blockstate file must map every (facing, mb_pos) combination to a model. For a standard 4-facing block this is 44 variants (4 facings × 11 positions). Blocks with 6 facings (e.g. directional kinetic blocks) need 66 variants.

Structure:

// assets/<modid>/blockstates/my_addon_block.json
{
  "variants": {
    "facing=north,mb_pos=none":          { "model": "mymod:block/my_addon_block" },
    "facing=north,mb_pos=top_first":     { "model": "mymod:block/my_addon_block_mb_top_first" },
    "facing=north,mb_pos=top_mid":       { "model": "mymod:block/my_addon_block_mb_top_mid" },
    "facing=north,mb_pos=top_last":      { "model": "mymod:block/my_addon_block_mb_top_last" },
    "facing=north,mb_pos=center_first":  { "model": "mymod:block/my_addon_block_mb_center_first" },
    "facing=north,mb_pos=center_mid":    { "model": "mymod:block/my_addon_block_mb_center_mid" },
    "facing=north,mb_pos=center_last":   { "model": "mymod:block/my_addon_block_mb_center_last" },
    "facing=north,mb_pos=bottom_first":  { "model": "mymod:block/my_addon_block_mb_bottom_first" },
    "facing=north,mb_pos=bottom_mid":    { "model": "mymod:block/my_addon_block_mb_bottom_mid" },
    "facing=north,mb_pos=bottom_last":   { "model": "mymod:block/my_addon_block_mb_bottom_last" },

    // Repeat for facing=south with "y": 180
    "facing=south,mb_pos=none":          { "model": "mymod:block/my_addon_block", "y": 180 },
    "facing=south,mb_pos=top_first":     { "model": "mymod:block/my_addon_block_mb_top_first", "y": 180 },
    // ... all 9 positions with "y": 180 ...

    // Repeat for facing=east with "y": 90
    "facing=east,mb_pos=none":           { "model": "mymod:block/my_addon_block", "y": 90 },
    // ... all 9 positions with "y": 90 ...

    // Repeat for facing=west with "y": 270
    "facing=west,mb_pos=none":           { "model": "mymod:block/my_addon_block", "y": 270 }
    // ... all 9 positions with "y": 270 ...
  }
}

Step 3 — Model Architecture

SPC uses a two-layer model inheritance system. You only need to create per-block models that inherit from SPC’s shared parent templates.

Layer 1: SPC’s parent template models

SPC provides 11 parent models (storedprogramcontrols:block/logo_mb_*.json) that define the correct casing textures for all non-front faces (back, sides, top, bottom) based on position. Each parent removes border pixels on internal seams:

Layer 2: Your per-block models

Each of your 11 model files inherits a parent template and only overrides the front face (north texture) and optionally the up face. The parent handles everything else.

// models/block/my_addon_block.json  (mb_pos = none)
{
  "parent": "storedprogramcontrols:block/logo_mb_none",
  "textures": {
    "up":    "mymod:block/my_addon_block_top",
    "north": "mymod:block/my_addon_block_front"
  }
}

// models/block/my_addon_block_mb_top_first.json
{
  "parent": "storedprogramcontrols:block/logo_mb_top_first",
  "textures": {
    "up":    "mymod:block/my_addon_block_top",
    "north": "mymod:block/my_addon_block_front_mb_top_first"
  }
}

// models/block/my_addon_block_mb_center_mid.json
{
  "parent": "storedprogramcontrols:block/logo_mb_center_mid",
  "textures": {
    "up":    "mymod:block/my_addon_block_top",
    "north": "mymod:block/my_addon_block_front_mb_center_mid"
  }
}

// ... repeat for all 10 positions, following the naming pattern:
//   my_addon_block_mb_{position}.json

Step 4 — Front Face Textures (Edge Map)

Each position determines which edges of the block’s front face need their 1-pixel border removed. An internal edge (shared with an adjacent block) gets its border removed; an external edge (structure boundary) keeps its border.

To create your per-position front textures, start from your base front texture and remove the 1-pixel bevel on each “remove” edge by stretching the interior pixels to the edge. This typically means extending the inner area of the texture to fill the border row/column on that side.

Complete File Checklist

For a single addon block called my_block, you need:

Automating Asset Generation

Creating 44+ blockstate variants, 11 model files, and 10 front texture variants by hand is tedious and error-prone. SPC Core includes a Python script (generate_connected_textures.py in the project root) that automates the entire pipeline:

• Generates all position-specific front face textures from your base texture
• Generates all per-position model JSON files inheriting from SPC’s parent templates
• Generates the complete blockstate JSON with all facing × mb_pos variants

You can adapt this script for your addon’s blocks, or use it as a reference for writing your own generator. The script’s edge-removal logic mirrors the edge map table above.

ISpcConnectedDisplay — Display Neighbours

Display blocks use a separate connected-texture system with boolean properties (LEFT_CONNECTED, RIGHT_CONNECTED, TOP_CONNECTED, BOTTOM_CONNECTED) that update reactively via neighborChanged(). If your addon adds a display-type block, implement ISpcConnectedDisplay so SPC’s built-in displays recognize it as a valid texture neighbour.

import com.hypernova.spc.api.multiblock.ISpcConnectedDisplay;

public class MyDisplayBlock extends Block
        implements ISpcMultiblockModule, ISpcConnectedDisplay {

    @Override
    public Direction getDisplayFacing(BlockState state) {
        return state.getValue(BlockStateProperties.HORIZONTAL_FACING);
    }
}

Return the facing direction of your display surface. SPC will connect textures only between displays that share the same facing direction.

ISpcDiagnosticsProvider — Live Diagnostics

Addon block entities can contribute entries to the Live Diagnostics Panel (visible in the programming screen). Implement ISpcDiagnosticsProvider on your BlockEntity and return SpcDiagnosticEntry records.

import com.hypernova.spc.api.multiblock.ISpcDiagnosticsProvider;
import com.hypernova.spc.api.multiblock.SpcDiagnosticEntry;

public class MyBlockEntity extends BlockEntity
        implements ISpcDiagnosticsProvider {

    @Override
    public List<SpcDiagnosticEntry> getDiagnosticEntries(
            Level level, BlockPos pos) {
        return List.of(
            new SpcDiagnosticEntry("Speed", speed + " RPM"),
            new SpcDiagnosticEntry("Stress", stress + " su", stress > 0)
        );
    }
}