Terraform for Minecraft: modules, contraption compilation, and resource transformations

[TeamDman]

Plan status: Active design exploration; implementation gates remain open.
Primary implementation target: Not selected. Source reconnaissance used the public 1.19.2 branch at 1be4b3cff9387f0b2870bc281017b3589f0119ef.
Last updated: 2026-09-14.

The idea is to make an automation module expressible as SFML, as a physical Minecraft contraption, or as a mixture of both. A layout engine could choose a realization that fits the available blocks, space, mods, and operating requirements. A builder could then consume construction materials to place it, or recover an owned contraption into inventories.

“Terraform for Minecraft” describes the deployment side: declare a desired contraption, inspect the current world, calculate a change plan, and apply it. Terraform's planning model and state bindings are useful references. The additional SFM idea is compiling behavior into alternative implementations of that contraption.

The common representation

flowchart TD
    A[Module definitions and function calls] --> C[Typed graph of ports, storage, actions and timing]
    B[Recognized world contraption] --> C
    C --> D[Choose implementations from available capabilities]
    D --> E[SFML programs]
    D --> F[Blocks, orientation and connections]
    E --> G[Desired contraption and change plan]
    F --> G
    H[Observed world and ownership bindings] --> G
    G --> I[Builder applies bounded changes]
    I --> H

Loading

This graph is an intermediate representation: a description both the language compiler and world builder understand. It needs inventories and other stores, typed connections, actions, transformations, schedules, conditions, and persistent instance state.

A practical initial translation supports a restricted, explicit subset. Arbitrary imperative programs and arbitrary modded machines cannot be assumed to have a finite physical equivalent. Unsupported behavior should produce a diagnostic or remain an opaque component with declared ports. Importing a recognized hopper arrangement also cannot recover the original author's function names or source structure without saved metadata.

Functions, module instances, and jobs

The motivating sketch is:

def a():
  4

every ticks do
  let x = new a
  input from x
  output to b
end

This is exploratory notation, not accepted SFML. The inspected grammar does not define functions, return values, new, recipes, or create/destroy statements.

Three operations need different lifetime rules:

Operation	Meaning to decide
Call a function	Execute reusable logic, with defined arguments, results, effects, and caller input scope.
Instantiate a module	Allocate a named instance with ports, storage, and possibly world blocks; repeated application can find the same instance.
Submit a job to an instance	Start one unit of work, with defined capacity, completion, and cancellation behavior.

Putting new a inside an every-tick trigger must not accidentally request another permanent machine every tick. Decide whether it references a stable declaration, allocates a bounded temporary instance, or explicitly spawns a new one. Spawning needs limits and reclamation.

The literal 4 also needs a type: a number, a count encoded by items, a four-item result, or a production rate are different meanings. A module handle usable by INPUT must expose a resource port; a numeric return value alone does not identify an inventory. Syntax should follow these decisions.

Relevant existing work: functions #146, built-in functions/arithmetic #363, and variables #282.

A boundary makes replacement meaningful

For the arrangement:

C       C = chest
H       H = hopper
C

one candidate realization is:

C       top chest = above
MC      manager plus private memory chest
C       bottom chest = below

The motivating SFML sketch is refined below with an explicit FORGET between stages:

EVERY 10 TICKS DO
    INPUT 1 FROM above
    OUTPUT TO memory
    FORGET
    INPUT FROM memory
    OUTPUT 1 TO below
END

FORGET matters because current SFM inputs accumulate within a trigger; INPUT establishes eligible sources rather than picking up a detached stack. The existing example documents this. Without isolation, the second output can still consider the first input when its allowance remains. Function boundaries need to specify this same scope behavior.

This is a candidate buffered transfer, not a demonstrated hopper emulator. It changes footprint and material requirements, and the memory chest changes available buffering. The two transfers can happen in one trigger, so this does not automatically introduce a ten-tick residence time in memory.

Define the interface before claiming equivalence:

Contract dimension	Example decision
Ports	External input/output inventories and an optional enable signal; memory stays private.
Resources	Accepted item predicates, counts, components/NBT, slots, sides, and stack limits.
Time	Maximum throughput, minimum/maximum latency, tick phase, ordering, and enabled conditions.
Capacity	Buffer size and behavior when input is empty or output is full.
Other observations	Redstone lock, comparator-visible state, item-entity pickup, and any behavior exposed outside the boundary.
Lifecycle	Chunk unload, restart, missing ports, removal, and recovery of in-flight resources.

A broad “eventually move items” contract allows more substitutions than tick-for-tick equivalence. The compiler must report which contract it preserves and any deliberate difference; it must not silently weaken the contract to fit a cheaper layout.

Named slots such as ingredient, result, and recipe can be part of this interface. #595 — Additional/custom slot names provides related design context. Resolve them through an instance's bindings, not accidental global label names.

Space can be discontinuous

Compact Machines motivates an explicit boundary whose wall ports connect to a private interior. Entangloporters, tesseracts, and quantum bridges motivate connections between endpoints that need not be physically adjacent. These are candidate provider families; support and semantics depend on the installed mod/version.

The layout engine should represent both local geometry and logical connectivity. A remote link can have dimension, channel, orientation, ownership, resource-type support, throughput, energy cost, latency, and chunk-availability requirements. It is not a zero-cost cable simply because it spans distance.

Provider discovery should offer capabilities such as “connect item ports across dimensions” and “host a private interior,” then list valid realizations for the installed mods. A resource bridge need not carry redstone. Tunnelled cables #422 and the redstone support summary are related surfaces.

Identity belongs to a module instance and port. A position is one current binding. This supports relocation, dimensional interiors, and replacement without treating every moved block as a new logical machine.

Creation, destruction, and recipes

For planning, distinguish these effects:

Effect	Accounting rule
Transfer	Decrease a source and increase a destination by the amount actually accepted.
Create	Introduce a typed resource under an explicit configured creation capability.
Destroy	Consume a typed resource through an explicit sink.
Transform	Consume specified inputs and produce specified outputs, with time, state, conditions, and possible byproducts.
Place/recover	Convert construction inventory into world blocks, or recover blocks/drops into inventory under provider rules.

The proposed ability to create items from thin air is a valid design mode. Keep it explicit so a survival realization can require material/fuel/energy inputs and a synthetic realization can declare its creation authority. A builder in the style of a BuildCraft quarry or RFTools builder needs both inventory-to-world and world-to-inventory operations. Breaking a block may yield drops rather than the original block, and contained inventories/block-entity state need their own recovery contract.

A furnace fits a timed transformation with persistent state:

idle
  -> accept/reserve recipe inputs when requirements are met
processing
  -> spend work/fuel/energy according to the provider's clock
ready
  -> deliver result when capacity exists
  -> return to idle

Sand items can encode remaining work in the proposed sand_counting_down / sand_rest stores. The recipe store represents work in progress. Choose whether each step moves sand between stores or destroys it, how the timer is initialized/reset, and where the output comes from. Those rules need explicit source/sink/transform support. The original sand sketch is a state-machine idea, not executable SFML or a complete furnace recipe.

Physical furnaces remain responsible for their own recipe mechanics when selected as a backend. A synthetic recipe interpreter must define recipe identity, ingredient matching, catalysts/remainders, byproducts, work duration, fuel use, blocked output, cancellation, and reload behavior. Recipe data alone may not capture a modded machine's behavior. Do not delete ingredients and hope a later independent create action succeeds; retain recoverable work state or choose a documented failure policy.

Related proposals: transactional resource groups #436, bundles #472, sequencing #492, and sleep/async #416.

Plan, apply, observe, and import

A deployment plan should name stable instances and show placements, removals/recoveries, program/label changes, connections, material requirements, and capability prerequisites. World changes since inspection require revalidation. Reapplying an unchanged declaration should not place duplicate machines or restart completed jobs.

Ownership must distinguish blocks managed by the module, imported blocks, and externally supplied ports. Reconciliation must not continuously “repair” inventory contents that a running machine is expected to consume. Construction state and production state have different lifecycles. Recovery must handle a full salvage inventory and interrupted work without silently losing or duplicating resources.

The prior packet-computation design remains a separate transport foundation: sfm:packet is a Minecraft item; observations and addressed sends are one-shot; duplicates are preserved; send_attempted does not acknowledge inventory delivery. If a planner uses the worker connection, durable deployment state, retry recognition, and acknowledgments must be supplied above that carrier. No RADIUS or UDP implementation is implied.

One command comparison is useful: Java's /loot insert already supports container insertion described as similar to shift-clicking. A loot table can specify the produced item. That answers part of the command-block example; the SFM proposal adds reusable resource-flow contracts and alternative world realizations. Mojang command reference

Work items and decision gates

Update [ ] to [~] for active work, [x] only with completion evidence, or [!] with an exact blocker. Keep evidence under the affected item. Current focus: the first design gate below; later items are contingent.

[ ] 1. Define the module interface and lifetime

Work: Decide function effects/input scope, typed ports and slot names, stable instance identity, call versus instantiation versus job, timing contracts, and bounded dynamic allocation.

Validation: Specify two isolated instances and the hopper replacement as worked examples, including full destination, restart, redstone disable, and repeated application. Reject or explicitly represent unbounded topology.

Complete when: Every external observation and owned internal resource is identified, and new has an unambiguous lifecycle. Exact syntax remains open until then.

[ ] 2. Define the graph and prove one SFML realization

Work: Represent stores, typed edges, conditions, time, and effects. Start with one declared buffered item-transfer module and a reference simulator.

Validation: Compare simulator and in-world inventory traces under the declared contract, including input-scope isolation. For the inspected baseline, the test entry points are ./gradlew.bat test and ./gradlew.bat runGameTestServer in platform/minecraft; revalidate prerequisites on the chosen implementation checkout. No tests were run in this planning session.

Complete when: The emitted program passes the chosen behavioral contract. Do not claim arbitrary program equivalence.

[ ] 3. Define physical providers and bounded deployment

Work: Choose supported Minecraft/loader versions; define builder placement/recovery, material accounting, ownership, plan/apply state, drift, and one recognized contraption import. Select costs and layout objectives explicitly.

Validation: Apply twice, change one module, interrupt/restart a build, fill salvage storage, and externally move a block. Compare resulting graph and port behavior, not source-text identity.

Complete when: One physical and one SFML realization satisfy the same declared interface, with a reviewed footprint/material difference and recoverable deployment state.

[ ] 4. Add optional spatial providers and resource transformations

Work: Close redstone gates from the linked summary; add one nonlocal connection adapter and one furnace transformation adapter. Specify the synthetic create/destroy mode separately from physical recipe execution.

Validation: Test with the optional mod absent and present, unavailable dimensions/endpoints, blocked recipe outputs, interrupted processing, and exact resource accounting. Add a target matrix with per-version/loader/adapter evidence before advertising support.

Complete when: Each advertised provider passes its capability and lifecycle contract; unsupported combinations produce useful diagnostics.

[ ] 5. Document and maintain the public design

Work: Publish accepted contracts, examples, support matrix, implementation references, and release notes as capabilities land. Keep decisions in the top-level Discussion; use replies for evidence and proposals. Follow the repository triage direction.

Validation: A reader can distinguish existing behavior, proposed syntax, accepted decisions, tested support, and outstanding gates without reading this originating conversation.

Complete when: Documentation and implementation evidence agree for every advertised realization.

Acceptance and risks

The design succeeds when a named module can be deployed, observed, changed, and recovered; supported code/world realizations preserve its stated interface; and resource accounting survives failure. The main risks are silent timing changes, leaked input/label scope, accidental per-tick construction, incomplete mod semantics, stale world bindings, and loss/duplication during interrupted transformations. Work items 1–4 each provide the corresponding proof obligation.