plan

Compiles a per-component spec into a reusable conversion plan and formats Luau input into the Rust-shaped payload the ecs verbs apply. A plan is compiled once per component at module load; format is the only per-call work.

Exports

• M.compile(spec) -> plan — builds a plan from a spec's entries: { rust, entries, byLuau, rustFields }, where byLuau maps each public field name to its entry and rustFields is the set of underlying rust field names.
• M.format(plan, input) -> table — converts Luau input to the rust-shaped payload. Expands vec3 fields into their three rust scalars (reading {r,g,b}, {x,y,z}, or array form), resolves handle fields to their guid, passes scalars through, and raises on an unknown field.
• M.resolveMeshHandle(value) -> string — reads the live GPU registry guid off a MeshHandle, raising on a category mismatch or a missing guid.
• M.resolveMaterialHandle(value) -> string — reduces any of the forms that identify a material to the one string rust holds: a MaterialHandle (its guid), a registry key or asset guid string (passed through), or an AssetRef (its __ref). These are the forms renderer.mesh.drawInstanced takes for the same job. A handle or envelope naming another category raises — a handle names its category in category, an AssetRef names it in type, and both are read.
• M.resolveTextureHandle(value) -> string — accepts a typed TextureHandle (returns its guid), a bare guid string (passed through), or nil / "" to clear.

Usage

local plan = require("modules.api.engine.ecs.plan")
local compiled = plan.compile(spec)
local payload = plan.format(compiled, { visible = true, tint = { 1, 0, 0 } })