The Two Layers of Scripts and Mods

This chapter's thesis: the rewrite's extension system must be a two-layer structure — a sandbox layer (safe, hot-reloadable, restricted content creation) and a native layer (full-capability, versioned, risk-assumed system extension) — and neither is optional: keep only the sandbox and you die of a capability ceiling and a queue of unmet requests; keep only the native layer and you die of merged blast radii and the rising cost of trust; and between the two layers there must be a promotion path. If a single-layer scheme (either one) could satisfy safety, capability, and ecosystem scale all at once, this thesis would be wrong.

1The problem

Today's extension system grew into two layers as a historical accident: datapacks live inside the umbrella (safe, restricted, compatibility promised), mods live outside it (all-powerful, fragile, self-reliant) — chapter 13 covered the politics of that boundary. The rewriter's temptation is to simplify this accident into one clean single-layer scheme: "with a scripting layer this powerful, why keep native mods at all?" Or the reverse: "scripts can't be trusted with the big jobs — open native up to everyone and be done."

This chapter argues that both directions fail, and fail in precisely predictable ways — because today's ecosystem has already demonstrated one half of each failure. The datapack's ceiling is the capability ceiling (Volume II chapter 8's four signals — a new verb, a new interface, new state, new scale; any one of them drives authors out the door to write Java). The mod's hell is the merged blast radius (chapter 12: one mod's error blows up the whole server, and the compatibility matrix explodes along three dimensions). The ideal two-layer design gives "the safe" and "the all-powerful" each their own gate — and builds a road between the gates.

2The failure modes of all-script and all-native

Two thought experiments first, walking each dead end to its end.

The all-script scheme (abolish the native layer; every extension goes through the sandbox): the first cause of death is the capability ceiling. A sandbox's essence is restriction, and restricted expression is guaranteed to miss things — the community queues forever at the gate marked "please, officials, open slot XX," and every slot you open is an interface promise (chapter 13's debt argument). The second cause of death is subtler: the tax on performance and determinism. All logic runs in an interpreter, and every tick's scheduling budget (chapter 5) has to feed one more virtual machine; the strict-ordering kind of hard real-time demand — the redstone kind (see Redstone's Implementation) — is very hard for a sandbox to promise in any general-purpose way. The third cause of death is the security arms race: sandbox versus escape is a perpetual cat-and-mouse game, and betting the entire ecosystem on the sandbox's perfection means betting the foundation on an assumption that has never fully held in history.

The all-native scheme (abolish the sandbox layer; every extension goes straight into the engine): the first cause of death is the merged blast radius — every extension shares fate with the core, one line of bad code blows up the whole world, and ordinary server owners are conscripted into being code reviewers. The second is the steep rise in the cost of trust: chapter 13 covered why "arbitrary code cannot be audited"; without a sandbox layer, everything platform-shaped (stores, review, signings) loses its premise — the Marketplace's technical foundation is precisely "an auditable format" (chapter 15). The third is frozen authorship: the native layer demands engineering ability by nature, while the overwhelming majority of this ecosystem's authors are hobbyists who "know a little scripting" — a native-only ecosystem is an oligarchy of geeks.

The two failures are mirror images: all-script dies of "nothing can be built," all-native dies of "everything is dangerous." The conclusion surfaces on its own: two layers is not a compromise — it is a division of labor.

Run that division through one real server owner's requirement. Say the owner wants a BedWars server. The mainstream move today is to install a plugin suite (the Bukkit family), because every item on the requirements list is a member of Volume II chapter 8's four-signal set: queues and matchmaking are cross-player state machines; automatic start has to hang on events; scores refresh every tick; rooms must spin up and tear down at will. Try writing it in pure datapacks? Scoreboards and functions can assemble a version that "looks right," but queue fairness, the atomicity of backfilling a disconnected player, the performance of hundreds of concurrent games — each one pushes the datapack past the interpreter's limits. This is the moment the "capability ceiling" stops being a noun and becomes an experience. Now flip it: say the owner wants only "tweak drops and the economy under vanilla rules." The plugin route is suddenly the clumsy one — installing a whole plugin runtime for a single drop table, then chasing version updates with it — when a datapack is one line of configuration. Today's server owners hop between the two toolkits on accumulated experience alone; the two-layer proposal simply draws that experience curve as formal institutions.

3The two-layer model and the separation of blast radii

Write each layer's permissions as a table (this chapter's deliverable):

The table's most important row is blast radius. When a mod fails today, it takes the whole server down with it (chapter 12's compatibility hell); when a sandbox-layer script fails, it takes down only itself — the system disables it, the world keeps turning, the other scripts keep running. Blast-radius separation is not a technical detail; it is the ecosystem's insurance institution: it moves the cost of trial and error off the heads of all players and onto the experimenter alone — the extension-layer mirror of chapter 2's "ship it first, fix it later": risk-taking is allowed, but the risk-taker carries a predictable share of it.

Blast-radius separation has one more undervalued value: it changes authors' courage. The mental preparation a server owner makes before installing a third-party plugin today is "this thing might kill my server" — so either they dare not install (the ecosystem shrinks), or they run a test server first and production later (costs double). The sandbox layer's promise dismantles that psychological threshold: the risk of installing a script is bounded at "it might not work," owners dare to install, and only then do an author's works get an audience. Chapter 6 drew the author funnel; the blast radius is the valve in the funnel's middle section — between the valve closing and opening lie two different fates for an ecosystem.

The two layers' grammatical isomorphism also deserves to be written into the design: if the scripting layer's concepts (events, components, world predicates) map one-to-one onto the native layer's — the same vocabulary, differing only in permissions — then an author promoted from sandbox to native pays a learning cost of "engineering discipline" only, not "relearning a foreign language." Today the datapack and mod ecosystems speak nearly parallel-universe vocabularies (functions versus event listeners, tags versus registries), and promotion means tearing it all down and starting over; in a two-layer design, this is a seam that can be repaired.

Another row of the table is just as critical: the promotion path. A mature work grown inside the sandbox (a gameplay script in use by tens of thousands of servers) ought to have a road to "naturalization" as a native implementation — the way the piston walked in from a mod (Volume I chapter 4, Mods as the Second Author). The promotion path's existence makes the sandbox layer more than a toy yard: it is the native layer's nursery. A two-layer design without the passage is two severed castes.

4The stable API surface: three lines

"Risk assumed by you" in the native layer does not mean "left completely feral." The rewrite should convert today's unacknowledged contracts (chapter 10's "unacknowledged public API" — see The Network Protocol) into an explicitly promised stable surface, in three lines.

The world API: stable predicates and operations for reading and writing world state — its semantic anchor is the invariants of Volume III chapter 18 (the voxel ledger's read-write rules). The events API: today's "notifications hidden inside the implementation" (block updates, entity events) organized into an explicit event catalog — an earlier chapter told how today's event system was generalized by Bukkit out of the cracks in the implementation; the rewritten version should make events an interface by design, not a regularity by observation. The protocol API: chapter 10 said it — the protocol is the unacknowledged contract the whole ecosystem uses as a constitution. Promoting it means version changes must obey their own rules (a notice period, deprecation cycles), instead of every internal refactor becoming an overtime week for the entire ecosystem.

The institution shared by all three lines is the versioned schema (a generalization of chapter 7's componentization): every interface carries a version number, changes have a notice period, and deprecation is not deletion (parallel run first, retire later). Mod authors' annual "version doomsday" (chapter 12) comes from "the officials promise nothing, the community simply chases"; a versioned schema turns that once-a-year doomsday into a predictable migration calendar.

One question of ownership must be answered head-on: who maintains the stable surface? The answer is three-party co-governance. The officials maintain semantics (final interpretive authority over the invariants and core behavior — without that, a promise is not even possible). An interface committee maintains rhythm (version and deprecation cycles — and the committee should hold seats for mods, server platforms, and datapacks alike, because the cost of every interface change is split three ways). The community maintains coverage (discovering edge usages, expanding the test suite — chapter 16's "semantic reference implementation" role becomes institutional here as "the behavioral test suite is part of the specification"). Chapter 8's four-step process (observe → come to depend on → freeze) was the old road, formed spontaneously; the stable surface repaves that road with streetlights — same direction, no more feeling through the dark.

5Hot reload and schemas: author productivity is ecosystem productivity

The sandbox layer's /reload-style hot reload (chapter 13) is its greatest productivity advantage — a debug loop measured in seconds. The two-layer scheme institutionalizes that advantage and lets it percolate upward: the sandbox layer hot-reloads by default; the native layer provides a controlled, limited reload (at minimum the configuration and resource layers hot-swap), and "change one line, restart the whole game" is classified as a pain point to be eliminated, not an industry constant.

The supporting institution is schema lifecycle management: every API change walks the standard cycle "proposal → announcement → dual-track parallel run → deprecation → removal," with the dual-track period leaving the ecosystem time to catch up. Chapter 2 covered DataFixerUpper's add-only migration system (see Storage and Serialization) — that was data, versioned; this chapter's proposal is its interface edition: old data formats stay readable, old interface versions stay alive. The two institutions together are the full redemption of "the world outlives the engine" — the world lives on, and the code written around the world deserves a way to live on too.

6Author experience is the product

This chapter's last proposal is the softest and the hardest: treat author experience as a formal part of the product. Error messages must locate the problem (not spill a wall of obfuscated class names); a local test environment must work out of the box (not demand an evening of toolchain assembly first); documentation must move with the version (not remain an archaeological dig on a wiki). Chapter 8 said redstone's computer tutorials were "turning what geniuses achieved into a ramp ordinary people can climb" — the grade of that ramp is the author experience.

The economic basis for the proposal is the ecosystem's funnel model: authors enter through the sandbox layer (low threshold, fast feedback) and are promoted to the native layer as they mature (great capability, heavy responsibility); every layer's attrition is paid for by "the next layer's supply" — the quality of the sandbox layer's error messages decides the native layer's author stock five years out. Today's datapack and mod ecosystems are already validating the funnel (countless well-known mod authors' first line of code was a datapack function); if the rewrite treats author experience as icing on the cake, the funnel's top layer runs dry — and an ecosystem whose funnel has run dry will not be around when the next piston's inventor shows up.

7What this chapter leaves behind

• For players: that two-layer permission table, translated into plain words: if you want to try writing gameplay, enter through the layer that cannot kill the world; when your experiment grows into something big, move into the layer with heavier responsibilities — the staircase is drawn in this chapter.
• For developers: what you can take away is the two-layer permission table and the principle of blast-radius separation — safety and capability each get a layer, a promotion path connects the two, and the stable API runs on versioned schemas — plus the most easily defunded piece of common sense: author experience is retention. What you cannot take away is the water supply at the top of the funnel: the sandbox layer needs a scripting language and a documentation system simple enough and honest enough — that is another ten years' worth of community assets, accumulated.