game.clowns.Roster

The four faces of GREASEPAINT. Everything the Director needs from the clowns slice goes through here.

local Roster = require("game.clowns.Roster")
local clown = Roster.spawn("pinch", entity.find("ClownMark"))
clown:react("enter")
clown:despawn()

Exports

• Roster.kinds() -> { string } — pinch, bello, slats, marrow.
• Roster.spawn(kind, at) -> handle — build the figure under at and mount its driver. The handle carries kind, root, dims, parts, and answers :react(event) and :despawn(). It yields: the figure assembles over several frames, so call it from a coroutine. The handle comes back once the figure is whole.
• handle:react(event) — enter, idle, attack, hit, guard, laugh, die. guard and die hold until the next reaction; die holds for good.
• handle:despawn() — take the whole figure away.
• Roster.prewarm(kind?) -> task — warm a kind ahead of its entrance. No kind warms all four.
• Roster.stopPrewarm() — cancel a warm-up still running.
• Roster.retireStandin() — the scene's stand-in steps down.

Authoring probes

Not on any gameplay path — these exist so an author working in a live engine can ask the roster what it currently believes:

• Roster.kinds() — the ids it can build.
• Roster.warmed(kind) -> boolean — will this entrance cost a frame, or a fifth of a second?
• Roster.painted(kind) -> boolean — has the generated paint landed on the materials yet?
• Roster.lastSpawn() — what the last assembly cost: { kind, totalMs, frames, worstFrameMs, warm }. The answer to "was that entrance a hitch?" without reading a frame graph.
• Roster.probe() — what it reads a design as, held against a fresh read of the module: the answer to "did my edit reach the running roster?".
• Roster.clear() — every clown down, whoever spawned it.
• Roster.flush() — drop every cached figure, mesh, handle and paint and re-read the designs. For an author editing game.clowns.figures live.

Notes

• The greasepaint and the cloth are generated (game.clowns.paint), which costs a second or two of CPU per clown. That work runs chunked in a background task and binds its textures into the kind's materials when it lands, so a spawn never blocks a frame and a figure is never missing. A kind is generated once per session and then lives on the materials.
• A mesh handle is cheap to make and expensive to DRAW for the first time. The warm-up therefore attaches each of a kind's handles to a throwaway entity far under the tent and takes it away again, a frame's worth at a time; a cold figure costs about 200 ms in one frame, a warm one about 11. The first mount of the Clown driver is warmed the same way, once.
• spawn retires the scene's clown_standin and assembles the figure well below the mark, then sets it down whole — nothing is ever seen half-built.
• Spawning a kind sweeps any figure of that kind already standing, by name, so a hot reload cannot leave two of one clown in the ring.