Skip to content
Conduit

Scene runtime

A Scene is a live instantiation of a Prefab in a specific dimension at a specific origin. It tracks every block it placed, every screen/label/display it pushed, and every zone it attached, so Scene.remove(level) can roll the world back to exactly what was there before. SceneStore is the runtime registry — it loads prefabs at server start and on /reload, keeps a list of “live” scenes the engine should maintain across reloads, and tears down + re-instantiates them when the JSON changes on disk.

When to use it

Section titled “When to use it”
  • You’re spawning a staging-box, arena room, or decorative structure from a prefab.
  • You want /reload to re-build edited prefabs without restarting the server.
  • You’re authoring a one-shot scene (no live registration) for a transient effect.

API

Section titled “API”
package me.zlex.conduit.prefab;


public final class Scene {
    public static Scene instantiate(ServerLevel level, BlockPos origin,
                                    PrefabBindings bindings, Prefab.Id id,
                                    Prefab prefab, SceneStore store);


    public Map<String, BlockPos> anchors();
    public Map<String, AABB> zones();
    public Integer screenId(String name);
    public Integer labelId(String name);
    public Integer displayId(String name);


    public void addElement(PrefabElement element, ServerLevel level);
    public boolean removeElement(PrefabElement element, ServerLevel level);


    public Prefab toPrefab();           // round-trip to JSON-able shape


    public void remove(ServerLevel level);
}


public final class SceneStore {
    public static void init(MinecraftServer server);
    public static @Nullable Prefab prefab(Prefab.Id id);
    public static SceneStore get();


    public static void registerLive(Prefab.Id id, LiveSceneSpec spec);
}

Example

Section titled “Example”
import me.zlex.conduit.prefab.Prefab;
import me.zlex.conduit.prefab.PrefabBindings;
import me.zlex.conduit.prefab.Scene;
import me.zlex.conduit.prefab.SceneStore;
import net.minecraft.core.BlockPos;
import net.minecraft.server.level.ServerLevel;


public final class ArenaRoom {


    private Scene scene;


    public void build(ServerLevel level, int cx, int cz) {
        Prefab.Id id = Prefab.Id.of("my-mod", "arena-room");
        Prefab prefab = SceneStore.prefab(id);
        if (prefab == null) throw new IllegalStateException("prefab missing");


        PrefabBindings bindings = PrefabBindings.empty()
                .putAll(prefab.params())
                .put("xMin", cx - 16).put("xMax", cx + 16)
                .put("zMin", cz - 16).put("zMax", cz + 16)
                .put("yFloor", 100).put("yCeiling", 110);


        scene = Scene.instantiate(level, new BlockPos(0, 0, 0),
                                  bindings, id, prefab, SceneStore.get());
    }


    public void teardown(ServerLevel level) {
        if (scene != null) {
            scene.remove(level);
            scene = null;
        }
    }
}

Notes

Section titled “Notes”
  • Re-running a live spec on /reload tears down the previous scene first and re-instantiates — block state mirrors the JSON on disk exactly.
  • Editor mutations made via addElement / removeElement round-trip back to a Prefab via toPrefab(); the editor writes that back to the file as the durable source of truth.
  • Ad-hoc one-shot scenes don’t need to register with SceneStore.registerLive — just call Scene.instantiate and hold the returned reference until you want to tear it down.
Section titled “Related”