shared

Cross-tool helpers for the terrainSystem.toolbox. Loaded via require(".shared") from every tool inside the box. The module is intentionally thin — only result envelopes (ok / fail), the op dispatcher, and a couple of resolvers that every dispatching tool would otherwise duplicate. Per-tool logic lives in each <x>.tool/init.luau; this module is not a forwarder hub.

Exports

Result envelopes:

• shared.ok(value?, formatted?) -> TerrainSystemToolResult — success.
• shared.fail(message, exitCode?) -> TerrainSystemToolResult — failure (default exitCode = 1; pass 2 for argument-shape errors).

Argument plumbing:

• shared.requireField(opts, name, context) — raise the canonical <context>: opts.<name> required error when the field is missing, otherwise return its value.
• shared.dispatch(context, ops, opts) — op-keyed dispatch with uniform error messages listing the known ops.

Resolvers:

• shared.resolveEntity(target) — normalize a string id, a string name (via entity.find), or a table with .entityId / .id / .__id to an entity id.
• shared.handleOrAsset(value, context) — accept either an in-memory terrain handle or a .terrain asset ref (path / guid / AssetRef envelope) and return a handle.

Bound module reference (the toolbox's only seam into the underlying API):

• shared.terrainSystem — the terrainSystem.* system module. Tools must reach the system through this field instead of re-requiring the module directly.

Types

• TerrainSystemToolResult = { stdout, stderr, exitCode, ok, value } — the structured result shape every tool in this toolbox returns.

Usage

local shared = require(".shared")
local terrainSystem = shared.terrainSystem

local ops = {}
function ops.raise(opts)
    local handle = shared.handleOrAsset(opts.target, "terrainSystem.edit(op='raise')")
    terrainSystem.raise(handle, opts)
    return shared.ok(handle, "raised")
end

return {
    edit = function(opts)
        return shared.dispatch("terrainSystem.edit", ops, opts)
    end,
}

Notes

• The shared.terrainSystem field is the only way tools reach into the terrainSystem.* namespace. New helpers that need a different module go through the same require-once-here pattern so the toolbox boundary stays a single import.
• Don't extend the dispatcher with op-specific logic. Each op handler lives in its tool's own init.luau; the dispatcher only routes.