Redstone support: existing requests, current behavior, and design gates

[TeamDman]

Status: Design summary; implementation decisions remain open.
Last reviewed: 2026-09-14 against the public 1.19.2 branch at 1be4b3cff9387f0b2870bc281017b3589f0119ef.

SFM needs a clear contract for reading and controlling redstone at labelled blocks. This is a shared reference for the existing requests, the partial implementation, and the decisions needed before expanding it.

Existing requests

These six issues were open when reviewed. Their requests overlap, but do not all describe the same behavior.

Reference	Requested behavior	Design consequence
#108 — Feature Request: Redstone querying	Query labelled sources, including AE2 level emitters and arrays of levers. The comments propose using redstone:: and raise ambiguity with redstone dust.	Define labelled signal observation and distinguish signal values from items.
#229 — Support Redstone querying and Restone output	Read and write redstone.	Reading and output need separate, explicit contracts.
#170 — [Suggestion]Add two functions	First request: read and output redstone. Second request: select members of a label group by their state.	Include the redstone request here; retain the separate group-selection request.
#129 — Feature request: controlling factory manager with redstone signal	Disable a manager with redstone for performance reasons.	Decide whether disabled means skipping actions, skipping evaluation, or pausing runtime state.
#465 — Tunnelled manager should also pass through redstone queries	Forward redstone through a tunnelled manager. Comments ask about comparators and strong/weak signal behavior.	Define where a forwarded query is evaluated and which side it addresses.
#591 — Add game tests for redstone resource type	Establish whether the WIP resource query works, testing each signal strength.	Start with runtime characterization; do not infer working support from a registered resource type.

Two existing Ideas Discussions contain design proposals:

• #400 — Add redstone sidedness: manager-side conditions, labelled conditions, and labelled pulse triggers; comments consider cable-based observation. Syntax remains proposed.
• #202 — Redstone as a resource: redstone::, counter buffers, signal emission, change triggers, and limits on re-entry. Its proposal rejects conflating unrelated scalar resources into one generic unit type. Its example clamp-to-14 and buffer limits are historical design choices, not verified current behavior.

Related lifecycle work: #597 — manager removing its own program disk. A redstone-disable feature must state what happens to the current trigger and later triggers.

What the inspected source actually provides

Surface	Verified source behavior	Limit of this evidence
IF REDSTONE ...	BoolRedstone reads getBestNeighborSignal at the manager's position.	This condition has no label or side argument.
Pulse syntax	The grammar accepts EVERY REDSTONE PULSE DO.	Labelled/sided pulse syntax in #400 is not in this grammar.
Signal observation	RedstoneSignalCapabilityProvider calls state.getSignal(..., direction) and wraps the result in storage. Exceptions, including possible unsupported null-side queries, yield no capability.	This reads a block's emitted signal, which differs from asking what powers a block. Runtime discovery, freshness, sides, and tunnels need tests.
redstone:: resource operations	RedstoneResourceType exposes a stored amount; extract and insert both return zero.	There is partial infrastructure, not completed transferable redstone support.

No new runtime tests were executed for this summary. Source inspection does not establish behavior across Minecraft versions or published releases.

Decisions to close

Gate	Required decision	Proof needed
R1: observation	Distinguish signal emitted by a block, signal received at a position, strong/direct signal, and comparator output. Choose explicit names/defaults.	Known fixtures for each meaning; emitted and received values must not be silently interchangeable.
R2: address and side	Define label scope, multiple matching blocks, absolute versus local sides, null/default side, and missing/unloaded targets.	Rotated fixtures; zero/one/many matches; unloaded or removed targets have documented results.
R3: group semantics	Decide whether a condition tests any/every target, maximum strength, or a deliberately requested sum.	A pair of strength-8 sources must not silently become one strength-16 signal.
R4: events	Choose sampled changes versus event subscriptions; define rising/falling edges, pulse counts, ordering, and re-entry limits.	Multiple changes within an interval, feedback loops, label changes, disk removal, and reloads.
R5: output	Choose an emitting endpoint, set-versus-increment behavior, reset/lifetime, competing writers, and actual emitted range.	Observe powered blocks; prove shutdown behavior and neighbor updates. Writing a temporary sampled value is insufficient.
R6: stored counters	Decide whether stored redstone units and observed signals share a surface, and which operations mutate persistent storage.	Reading a lever cannot consume its signal. Counter consumption and signal sampling remain distinguishable.
R7: tunnels	Specify forwarding of received/emitted/comparator queries, side transforms, loops, and unavailable endpoints.	Direct and tunnelled observations match the declared contract, including orientation and invalidation.
R8: manager control	Define disabled behavior, wake-up cost, pending pulses, and resumption.	A disabled manager meets the intended evaluation-cost and lifecycle guarantees.

Proposed work order

[ ] 1. Characterize existing behavior

Work: Use #591 to cover values 0–15 through actual SFML evaluation and registered capability discovery, followed by side and signal-change cases. Inspect cache invalidation as well as the provider itself.

Validation: Run focused GameTests on the implementation checkout. The inspected baseline provides ./gradlew.bat test and ./gradlew.bat runGameTestServer with working directory platform/minecraft; confirm current task configuration and runtime prerequisites before execution. These commands were inspected, not run here.

Complete when: Published evidence identifies supported queries and concrete failures. File new bug Issues only for documented defects; keep missing-feature design here.

[ ] 2. Specify labelled reads and sidedness

Work: Close R1–R3 with #108 and #400; then close tunnel semantics in R7 with #465. Preserve existing manager-local conditions.

Validation: Parser/formatter agreement plus runtime fixtures for every selected observation, side, and target-availability rule.

Complete when: Syntax and observable behavior are explicit enough for a contributor to implement without guessing.

[ ] 3. Specify events, output, counters, and disable behavior

Work: Close R4–R6 and R8 using #202, #229, #170, and #129. Record separate work items and tests for each accepted behavior.

Validation: Pulse sequences, feedback, competing writers, stop/reload behavior, and server-work budgets.

Complete when: Each capability has a bounded implementation contract and a runtime acceptance case. Supported game versions and adapters must be named before propagation.

Connection to contraption compilation

See the contraption design for the broader module/contraption proposal.

A generated hopper replacement needs a redstone control port if it promises redstone locking. A generated machine in another dimension needs an explicit signal connection if redstone is part of its interface. Resource connectivity alone does not imply signal connectivity. These gates therefore form part of the module boundary, rather than an unrelated syntax enhancement.

Maintaining this reference

Edit this top-level body when facts or decisions change; use replies for new evidence. Keep source Issues linked and preserve their separate histories. Reference the exact version/commit for implementation claims and add links to relevant PRs or runtime results when available. The repository workflow proposal lives in #612.