Stored Program Controls - Changelog

Version 0.2.0 — Addon API & Diagnostics

Addon API (API v1.1.6)

• Full public addon API with 39 classes across 12 packages (com.hypernova.spc.api.**).
• Separate API jar built automatically (storedprogramcontrols-0.2.0-api.jar) for addon compile-only dependency.
• SPC Core (spc_core) companion mod provides the API entry point for addon dependency.

Node Registry & Custom Nodes

• SpcNodeRegistry: Addons register custom function block node types (schema + factory + category).
• SpcNodeSchema: Declares type ID, execution phase, ports, parameters, display requirement, displayName, shortLabel, description, and labelPrefix.
• SpcNodeSchema displayName/shortLabel/description: Optional metadata fields for human-readable names, palette abbreviations, and tooltip descriptions. Fallback defaults are generated automatically if omitted.
• SpcNodeSchema labelPrefix: Optional 1-3 character prefix for PLC-style editor labels. When set and the node has a channel parameter, the editor shows prefix + channel (e.g. "RI1", "RQ2") instead of the generic "B001" label.
• ISpcNodeFactory + NodeCompilationContext: Factories receive resolved signal addresses and parameter values at compile time.
• ISpcCompiledNode: Per-tick execution interface with access to the signal bus and world context.
• All registries use a freeze-after-setup pattern — late registration throws IllegalStateException.

Custom Node Colors

• SpcNodeColors: Addons can define custom ARGB colors (fill, stroke, text, labelText, activeFill) for their nodes in the programming editor.
• Convenience factories: SpcNodeColors.fromAccent(int) derives all 5 colors from one accent color; SpcNodeColors.of(int fill, int stroke) auto-derives text colors using luminance contrast.
• Addon nodes with custom colors render correctly in both the canvas and the palette glyph.
• Nodes without custom colors fall back to the default brass palette.

Programming Block Categories

• SpcProgramBlockCategory: Addons can register themed programming block variants with custom display names and visual styles.
• SpcProgramBlockStyle: Defines primaryTint, secondaryTint, and emissiveTint for block models. Defaults to brass if null. Includes fromAccent(int) factory.
• SpcProgramBlockRegistry: Thread-safe static registry for block categories, frozen after setup.

Node Categories & Palette

• SpcNodeCategory: Custom palette groups with categoryId, displayName, sortOrder, and optional iconTexture for addon icons.
• 17 built-in node categories (IO, Basic Logic, Memory, Timer, Counter, Compare, Math, Signal Helper, Visualization, World Condition, Analog Input, World Sensor, Effect Output, Item, String, Energy) plus a dedicated ADDON category.
• Addon nodes are merged into the palette sorted by category sortOrder.

Context Extension System

• SpcContextExtensionRegistry: Addons register ISpcExecutionContextExtension implementations for custom world interactions (e.g., Create rotational force, Mekanism gas levels).
• Extensions receive onTickStart(ServerLevel, BlockPos) each tick before node execution.
• Compiled nodes retrieve extensions via ISpcExecutionContext.getExtension(Class).

Multiblock Module API

• SpcModuleTypeRegistry: Register custom multiblock module types with optional I/O handlers.
• ISpcMultiblockModule: Interface for blocks to participate in LOGO multiblock BFS discovery.
• ISpcPhysicalIoHandler: Channel-based I/O handling for custom input/output modules.
• SpcMultiblockPosition: Position tracking within the multiblock structure.
• MultiblockPosition (MB_POS): Exposed in the API jar. Addon blocks that register the MB_POS block state property automatically receive position-aware connected textures when the LOGO multiblock forms — borders are removed on internal seams, matching built-in blocks.
• ISpcConnectedDisplay: Interface for addon display blocks to connect textures with neighbouring displays. Return the display facing direction and SPC handles the rest.
• ISpcDiagnosticsProvider + SpcDiagnosticEntry: Interface for addon block entities to contribute live diagnostic entries (label, value, active flag) to the Diagnostics Panel in the programming editor.
• Fixed multiblock validator not recognizing addon ISpcMultiblockModule blocks during BFS structure discovery and type validation.

Network Device API

• SpcNetworkRegistry: Register custom network device types.
• ISpcNetworkDevice, ISpcNetworkActivation, ISpcCableTraversable: Interfaces for custom network-connected blocks (buttons, levers, displays, etc.).

Runtime Events API

• SpcRuntimeEventRegistry: Register ISpcRuntimeEventListener implementations.
• Listeners receive callbacks for program lifecycle events (start, stop, error, tick).

Signal System

• 6 signal types: Digital, Integer, Decimal, Text, Item, Item_ID.
• Full cross-type conversion (asDigital, asInteger, asDecimal, asText).
• SpcSignalAddress (nodeId + portId) for resolved signal bus addressing.
• Signal domains for port compatibility checking.
• readDecimalSignal() and double persistent slots (getDoubleSlot/setPendingDoubleSlot) for precise floating-point state.
• Port signal type mismatches (e.g. from addon schema changes between versions) are now reported as warnings instead of blocking errors, with an actionable "Re-place the node to update" message.

Diagnostics System

• Live diagnostics panel in the programming editor showing machine status and faulted nodes.
• Per-node error handling: nodes that throw exceptions are captured as FaultedNodeEntry (nodeId, typeId, message) without halting program execution.
• Diagnostics network protocol: client requests snapshots from the server via RequestDiagnosticsPayload / DiagnosticsResponsePayload.
• Diagnostics button in the programming editor chrome toolbar.

Function Blocks

• 110+ built-in function block node types across all categories.
• String processing: 16 nodes (string_constant, number_to_string, string_concatenate, string_template, string_trim, string_uppercase/lowercase, string_substring, string_replace, string_compare, string_contains, string_length, string_is_empty, progress_bar_string, string_mux, string_to_number, string_index).
• Item processing: 11+ nodes (item_input, inventory_change_input, item_output, item_match, item_compare, item_stack_size, item_filter, item_switch, item_merge, item_empty_check, item_constant, item_max_stack).
• World sensors: 8 nodes (weather, light level, player proximity, entity counter, block scanner, container level, biome, moon phase).
• Effects: 3 nodes (note_output, particle_emitter, signal_flare).
• Energy: FE digital/analog input and output nodes.
• Timers: weekly_timer, yearly_timer, astronomical_clock, stopwatch, and all standard LOGO! timer types.
• Math: analog_filter, average_value, max_min_tracker, pi_controller, pwm.

Data Generation

• Automated data generation for block loot tables, block tags, and mining requirements.
• SpcDataGenerator, SpcBlockTagProvider, SpcBlockLootSubProvider integrated into the build pipeline via GatherDataEvent.

Programming Block GUI

• Decomposed ProgrammingBlockScreen into smaller focused components.
• Diagnostics panel integration with toggle button.
• Custom addon node colors rendered in canvas, palette glyphs, and placement previews.

Documentation

• 18-page addon developer wiki (HTML) covering: Getting Started, Core Concepts, Tutorial, Custom Nodes, Node Categories, State & Persistence, Signal Processing, Context Extensions, Signal Types & Domains, Execution Context, Multiblock Modules, Network Devices, Runtime Events, Registries, API Reference, Examples, FAQ.
• Complete API reference with all 39+ classes documented.

Testing

• 8 JUnit 5 addon smoke tests verifying registration, schema creation, compilation context, signal value conversion, node category, and registry freeze behavior.