api
The public API of Trapwright, the dungeon traps, secret rooms and puzzles kit (`local Dungeon = require("dungeonKit.api")`). `Dungeon.place(kind, opts)` makes any of the 12 traps, 7 secrets, 6 puzzles, the door or the bridge in one of 8 looks; trigger, disarm, arm, retarget, use,…
dungeonKit.api
The public API of Trapwright, the dungeon traps, secret rooms and puzzles kit (local Dungeon = require("dungeonKit.api")). Dungeon.place(kind, opts) makes any of the 12 traps, 7 secrets, 6 puzzles, the door or the bridge in one of 8 looks; trigger, disarm, arm, retarget, use, open, close, hit, solve, reset, repair and breakPiece act on a placed piece by id; on() listens to events; useRewrite() hands every piece to a hacking or spell power; foundCount() and hasFound() read the saved per-player secret counter. Game code and the kit's components call it.
Since 1.0.1: the arena family of boss arena hazards (Dungeon.ARENA: shockwaveRing, fallingDebris, floorPanels, pillarCover) with arenaPhase(id, n), arenaPhaseAll(n, prefix?), hitPillar(id, pillar?, by?) and covered(x, z, fromX, fromZ), the arenaPhase event, and setVisualRange(metres, every?).
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2nonstrict Dungeon (dungeonKit.api): the public API of the Trapwright dungeon kit. `Dungeon.place(kind, opts)` makes any trap, secret, puzzle, door or bridge; every other call acts on a placed piece by its id. Pieces build their look on every peer; the host owns their state.
place(kind: string, opts: any?) → string
Place a piece. kind: any id in Dungeon.kinds(). opts: id (deterministic id, default "<kind>#n"), at {x,y,z}, yaw (degrees), look, target ("players"|"monsters"|"all"|"nobody"), trigger ("plate"|"tripwire"|"timer"|"proximity"|"lever"), damage, interval, windup/active/cooldown, armed, link (ids a puzzle opens), puzzle (id a puzzleDoor waits for), code, broken, locked, length, style, loot. Call it on every peer with the same id (a scene component does). Returns the id.
| arg | type | description |
|---|---|---|
| kind | string | |
| opts | any? |
examples
Dungeon.place("pendulum", { id = "crypt.blade1", at = { 0, 0, 12 }, look = "crypt", trigger = "timer", interval = 3 })kinds(family: string?) → void
Every kind id, or those of one family ("trap" | "secret" | "puzzle" | "door" | "bridge" | "arena").
| arg | type | description |
|---|---|---|
| family | string? |
looks( ) → void
The eight look ids.
get(id: string) → any
A placed piece: { id, kind, family, look, title, state } or nil.
| arg | type | description |
|---|---|---|
| id | string |
state(id: string) → any
A placed piece's live state table (read only), or nil.
| arg | type | description |
|---|---|---|
| id | string |
ids( ) → void
Every placed piece id, in placement order.
act(id: string, action: string, arg: any?, by: string?) → void
Run any action on a piece (the host runs it; others send it). Returns ok, why.
| arg | type | description |
|---|---|---|
| id | string | |
| action | string | |
| arg | any? | |
| by | string? |
use(id: string, arg: any?, by: string?) → void
Use a piece as a player would (pull the lever, strike the wall, turn statue `arg`...). by: the user's body id.
| arg | type | description |
|---|---|---|
| id | string | |
| arg | any? | |
| by | string? |
trigger(id: string) → void
Set a trap off now (as if its trigger fired).
| arg | type | description |
|---|---|---|
| id | string |
disarm(id: string) → void
Disarm a trap.
| arg | type | description |
|---|---|---|
| id | string |
arm(id: string) → void
Re-arm a trap.
| arg | type | description |
|---|---|---|
| id | string |
retarget(id: string, target: string) → void
Point a trap at "players", "monsters", "all" or "nobody".
| arg | type | description |
|---|---|---|
| id | string | |
| target | string |
repair(id: string, by: string?) → void
Repair a broken door or bridge.
| arg | type | description |
|---|---|---|
| id | string | |
| by | string? |
breakPiece(id: string) → void
Break a door or bridge.
| arg | type | description |
|---|---|---|
| id | string |
open(id: string, by: string?) → void
Open a secret or door (a secret counts as found).
| arg | type | description |
|---|---|---|
| id | string | |
| by | string? |
close(id: string) → void
Close a door or secret.
| arg | type | description |
|---|---|---|
| id | string |
solve(id: string, by: string?) → void
Solve a puzzle now (fires "solved" and trips its links).
| arg | type | description |
|---|---|---|
| id | string | |
| by | string? |
reset(id: string) → void
Reset a puzzle to its start.
| arg | type | description |
|---|---|---|
| id | string |
hit(id: string, by: string?) → void
Strike a breakable wall once (three strikes break it), e.g. from your attack code.
| arg | type | description |
|---|---|---|
| id | string | |
| by | string? |
arenaPhase(id: string, n: number) → void
Set a boss arena hazard's fight phase: 0 dormant, 1 to 3 ever faster, denser and harsher (shockwaveRing, fallingDebris, floorPanels, pillarCover). Phase 1 also stands every pillar of a pillarCover up again.
| arg | type | description |
|---|---|---|
| id | string | |
| n | number |
examples
Dungeon.arenaPhase("boss.ring", 2)arenaPhaseAll(n: number, prefix: string?) → number
Set the phase of every arena hazard (or those whose id starts with `prefix`, such as "boss."). Returns how many it asked.
| arg | type | description |
|---|---|---|
| n | number | |
| prefix | string? |
hitPillar(id: string, pillar: number?, by: string?) → void
Knock one hit off a pillarCover pillar (`pillar` index, or the one nearest `by`). Returns ok, why.
| arg | type | description |
|---|---|---|
| id | string | |
| pillar | number? | |
| by | string? |
covered(x: number, z: number, fromX: number, fromZ: number) → boolean return Arena
Is a body at world (x, z) behind an intact arena pillar as seen from (fromX, fromZ)?
| arg | type | description |
|---|---|---|
| x | number | |
| z | number | |
| fromX | number | |
| fromZ | number |
setVisualRange(metres: number, every: number?) → void
How far from the local player's avatar pieces keep animating their looks (metres, default 60; 0 = always). `every` > 0 animates far pieces every Nth frame instead. Host logic (triggers, damage, puzzles) always runs.
| arg | type | description |
|---|---|---|
| metres | number | |
| every | number? |
setLook(id: string?, look: string) → void
Rebuild one piece in another look (id), or with id nil set the default look and rebuild every piece.
| arg | type | description |
|---|---|---|
| id | string? | |
| look | string |
remove(id: string) → void
Remove one piece.
| arg | type | description |
|---|---|---|
| id | string |
clear( ) → void
Remove every piece.
on(evt: string, fn: (any) → void
Listen to an event on this machine ("*" for all; see Dungeon.EVENTS). Returns a connection with :Disconnect().
| arg | type | description |
|---|---|---|
| evt | string | |
| fn | (any |
useRewrite(api: any) → void
Plug in a rewrite power (rewriteKit's api or anything with expose(entityId, spec) / unexpose(entityId)). Every piece exposes itself with the rewriteKit contract { kind, title, lines, fields, apply }. nil turns it off. The kit never requires rewriteKit.
| arg | type | description |
|---|---|---|
| api | any |
examples
Dungeon.useRewrite(require("rewriteKit.api"))rewriteSpec(id: string) → any
The rewrite spec a piece exposes (for your own power or tests).
| arg | type | description |
|---|---|---|
| id | string |
foundCount( ) → number return K
Secrets the local player has found, saved in runtime_data under <saveRoot>/secrets/<id>.
hasFound(id: string) → boolean return K
Has the local player found this secret (saved)?
| arg | type | description |
|---|---|---|
| id | string |
setSaveRoot(path: string) → void
Where found secrets are saved in each player's runtime_data (default "dungeonKit").
| arg | type | description |
|---|---|---|
| path | string |
setFanfare(fn: any) → void
Replace the secret-found fanfare: fn(payload { id, kind, by }, first) runs on the finder's machine.
| arg | type | description |
|---|---|---|
| fn | any |
nearestUsable( ) → any
What the local player could use now: { id, label } or nil.
useNearest( ) → string
The local player uses the nearest usable thing (the Director does this on E / gamepad X / the tap prompt). Returns the id.
slowFactor(bodyId: string) → number return K
The speed multiplier a frost field left on a body (1 = none); multiply your movement speed by it.
| arg | type | description |
|---|---|---|
| bodyId | string |
now( ) → number return K
Seconds on the shared clock.
tick(dt: number) → void
Step every piece by hand (the Director does this every frame; tests call it).
| arg | type | description |
|---|---|---|
| dt | number |
isHost( ) → boolean return K
True on the machine that owns piece state (host, or alone).
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.