dungeonKit
Trapwright (`dungeonKit`) fills a dungeon with things that bite, hide and make you think, in any Zero game, multiplayer-safe. One call places anything; the host owns its state; every player sees the same blade at the same swing.
Trapwright 1.0.1: dungeon traps, secret rooms, puzzles and boss arena hazards
Trapwright (dungeonKit) fills a dungeon with things that bite, hide and make you think, in any Zero game, multiplayer-safe. One call places anything; the host owns its state; every player sees the same blade at the same swing.
- 12 traps, each with a wind-up tell (a sound, a danger glow and a shake) and any of five triggers:
spikes(floor spikes),pendulum(pendulum blade),arrowWall,flameJet,boulder(rolling boulder),collapsingFloor,gasVent(poison gas),crushingWalls,sawTrack,lightningPylon,turret(pressure-plate gargoyle turret),frostRunes(frost rune field, slows). - 5 triggers:
plate,tripwire,timer,proximity,lever. Any trap can be disarmed (walk up and press E), re-armed, fired by script, or retargeted atplayers,monsters,allornobody. A lamp beside each trap shows its target (red players, green monsters, violet all, grey nobody). - 7 secrets:
breakableWall(three strikes),hiddenLever(a torch sconce that sinks a wall panel),illusoryWall(walk through it),slidingShelf(bookshelf, orstyle = "statue"),trapdoor(lift the rug, pull the ring),puzzleDoor(opens when its puzzle is solved),hiddenChest(search the rubble, then loot). Opening one the first time plays the SECRET FOUND fanfare on the finder's screen and saves it in that player'sruntime_datacounter. - 6 puzzles:
platesOrder(pressure plates in the order the stele shows),mirrors(turn mirrors to bend a light beam onto a crystal),symbolStatues(rotate statues to the symbols on the stele),leverCombo(lamps count the levers you have right),blockPush(push the block onto the glowing tile),codeTerminal(dial the code, or READ and REWRITEACCESSwith a hacking power). A solved puzzle opens, repairs or disarms everything in itslinklist. - Broken doors and bridges:
door(open, closed, locked or broken off its hinge) andbridge(planks fallen into the chasm, its deck collider off).Dungeon.repair(id), a linked puzzle, or a rewrite of theINTEGRITYline rebuilds them with an animation. - 4 boss arena hazards driven by fight phases:
shockwaveRing(a ring of force expanding from a dais: jump it or stand behind a pillar),fallingDebris(rocks drop on flashing ground markers),floorPanels(safe and unsafe tiles that flip; one tile always stays safe) andpillarCover(destructible pillars with colliders that block shockwaves; debris and the boss knock them down). Each sits dormant at phase 0;Dungeon.arenaPhase(id, n)orDungeon.arenaPhaseAll(n, prefix?)sets phase 1 to 3, every phase faster, denser and harsher. Rewritable like traps (TARGET,ARMED,DMG,PHASE). - 8 looks for every piece:
crypt(grey ashlar, iron, ember runes),ruins(overgrown forest temple),codeVault(the signature look: black circuit monoliths, neon cyan and magenta, glitch voxels that blink around every piece, a scan frame sweeping it and parts that jump out of place),ice,lava,scifi,cartoon(rounded cel-shaded) andpixel(voxels, 8-frame stepped motion, chip-pitched sounds). Generated PBR surfaces, generated meshes (pendulum blade, boulder, gargoyle turret, tesla pylon, chest, lever plate, bookshelf, statue) and 18 generated sounds.
Depends on SecondWind (health and damage, installed with it). It never requires a rewrite power: your game passes one in.
Install
Search ZeroMind for "dungeon traps secret rooms puzzles" and install dungeonKit.package, or in bash: zero zeromind installAsset <package guid>.
Quick start
local Dungeon = require("dungeonKit.api")
-- every peer runs this with the same ids (a scene component or entrypoint does)
Dungeon.place("spikes", { id = "hall.spikes", at = { 0, 0, 8 }, look = "crypt", trigger = "plate" })
Dungeon.place("pendulum", { id = "hall.blade", at = { 0, 0, 13 }, look = "crypt", trigger = "timer", interval = 3 })
Dungeon.place("breakableWall", { id = "hall.secret", at = { -4, 0, 10 }, yaw = 90, look = "crypt" })
Dungeon.place("codeTerminal", { id = "vault.term", at = { 3, 0, 20 }, look = "codeVault", code = "4096", link = { "vault.door" } })
Dungeon.place("puzzleDoor", { id = "vault.door", at = { 0, 0, 24 }, look = "codeVault", puzzle = "vault.term" })
Dungeon.place("bridge", { id = "chasm.bridge", at = { 0, 0, 30 }, look = "ruins", broken = true, length = 8 })
Dungeon.retarget("hall.spikes", "monsters") -- now it hurts monsters only
Dungeon.on("found", function(e) print("secret " .. e.id) end)
print(Dungeon.foundCount()) -- secrets this player has found, saved
Or drop the components: dungeonKit.Piece (one piece where its entity stands), dungeonKit.DemoDungeon (the whole demo crypt), dungeonKit.Gallery (everything in one look). A dungeonKit.Director is spawned on its own: it ticks the pieces, maps E (keyboard), X (gamepad) or a tap on the prompt to "use the nearest thing", and draws the prompt and the SECRET FOUND banner.
API (require("dungeonKit.api"))
| Call | What it does |
|---|---|
place(kind, opts) -> id | Place any piece. opts: id (deterministic, default kind#n), at, yaw, look, target, trigger, damage, interval, windup/active/cooldown, armed, range, link, puzzle, code, order, broken, locked, length, style, loot, hint. |
kinds(family?), looks(), ids(), get(id), state(id) | What exists and what state it is in (families: trap, secret, puzzle, door, bridge, arena). A piece whose entities ended with a play session reads as nil, and place with its id builds it fresh. |
use(id, arg?, by?) | Use it as a player would (pull a lever, strike a wall, turn statue arg). |
trigger(id), disarm(id), arm(id), retarget(id, target) | Traps. |
open(id), close(id), hit(id) | Secrets and doors (hit strikes a breakable wall). |
solve(id), reset(id) | Puzzles. |
repair(id), breakPiece(id) | Doors and bridges. |
arenaPhase(id, n), arenaPhaseAll(n, prefix?), hitPillar(id, pillar?, by?), covered(x, z, fromX, fromZ) | Boss arena hazards: set the fight phase (0 dormant, 1 to 3), knock a pillar, ask whether a pillar shields a spot. |
setVisualRange(metres, every?) | How far from the local avatar pieces keep animating their looks (default 60 m; 0 = always; every animates far pieces every Nth frame). Host logic always runs. |
act(id, action, arg?, by?) | Any action by name (all of the above, plus step, push, enter, unlock, lock, setTrigger, setDamage). |
setLook(id or nil, look) | Rebuild one piece, or every piece and the default. |
on(event, fn) | Events: placed triggered fired hit disarmed armed retargeted opened closed found foundByMe solved progress wrong reset repaired broken unlocked looted slowed hint arenaPhase (* for all). |
useRewrite(api), rewriteSpec(id) | The rewrite hook (below). |
foundCount(), hasFound(id), setSaveRoot(path), setFanfare(fn) | The saved per-player secret counter. |
nearestUsable(), useNearest() | The use interaction. |
slowFactor(bodyId) | Speed multiplier a frost field left on a body. |
now(), tick(dt), isHost() | Shared clock, manual stepping, authority. |
Multiplayer
Each piece's look is built on every peer from its deterministic id; nothing visual replicates. The host (multiplayer.isHost(), or the only machine offline) owns all state and broadcasts patches on dungeonKit:state; a late joiner asks with dungeonKit:hello and gets everything (and the host clock) on dungeonKit:all; clients send actions on dungeonKit:act; events go out on dungeonKit:evt. Damage is applied by the host through SecondWind's HK.damage, so its teams, i-frames and kill feed apply. A trap's players target means SecondWind team players (or any player avatar); monsters means every other body with SecondWind health.
Secrets saved per player
The finder's machine writes runtime_data.player(localId) at dungeonKit/secrets/<id> (change the root with setSaveRoot), so foundCount() survives sessions. Your own fanfare: Dungeon.setFanfare(function(e, first) ... end).
Rewrite hook
Dungeon.useRewrite(require("rewriteKit.api")) -- or anything with expose(entityId, spec)
Every piece calls api.expose(rootEntityId, spec) with the rewriteKit contract { kind = "trap"|"door"|"bridge"|"chest", title, lines = {...}, fields = { { key, label, value, options, cost }, ... }, apply = function(key, value, playerId) end }. Traps expose TARGET (players / monsters / nobody), ARMED and DMG; doors INTEGRITY and LOCK; bridges INTEGRITY; secrets HIDDEN; puzzles SOLVED; the code terminal ACCESS. apply routes to the host, so a rewrite is validated and seen by everyone.
Demo and gallery
scenes/DemoCrypt(this world's startup scene): spikes with a ghoul standing on them, a pendulum, a chasm with a broken bridge that the lever combination repairs, crushing walls, a cracked wall hiding a secret room with a hidden chest, a code terminal (1337) that opens the sealed door, a frost rune field and a broken exit door. Q opens rewriteKit's power on any piece.scenes/TrapwrightShowcase: all 31 pieces animating (the arena hazards walk through phases 1 to 3), keys 1 to 8 switch looks. TheGallerycomponent'sfamily = "arena"shows the arena hazards alone.
Tests
zero tests run trapwright: 28 tests covering the catalogue (every kind, arena hazards included, builds in all 8 looks with a valid rewrite spec), the trap state machine and all five triggers, disarm, retargeting and the rewrite hook, secrets and the saved counter, every puzzle's solve and wrong paths and links, door and bridge repair, every arena hazard (phase start and tiers, jumping and taking cover from the shockwave, seeded debris, the always-safe floor tile, pillar hits and restore, the PHASE rewrite), re-placing a piece whose play session ended, clearing play pieces when play stops, and the visual range.
Known limits
- Collapsing floors drop visually and deal fall damage; they do not remove the floor collider.
- Arrow and turret bolts are hitscan boxes along the lane, not physics projectiles.
- Ghouls in the demo are SecondWind dummies with no AI.
Performance
Dungeon.tick runs every piece's host logic each frame on the host, but a piece's look only animates within setVisualRange (60 m) of the local player's avatar. Measured on the DemoCrypt scene (11 pieces, native desktop): 2.06 ms of script time per tick with the player among them, 0.11 ms with the player 500 m away (every look skipped, host logic still running). Before 1.0.1 a far player still paid the full 1.8 to 2.0 ms; in a 19-piece level that was about 5.9 ms a frame.
History
- 1.0.1: FIX: module state outlived a play session while its entities did not, so a piece placed again with the same id kept a dead root (no hitbox, nothing for a rewrite to find).
placenow rebuilds a piece whose root is gone,getforgets it, and pieces placed during play are cleared when play stops. PERFORMANCE: looks beyond 60 m of the local avatar no longer animate (setVisualRange), host logic still runs. NEW: thearenafamily (shockwaveRing, fallingDebris, floorPanels, pillarCover) driven byarenaPhase, rewritable, in all 8 looks, in the gallery; 10 new tests. - 1.0.0: first release.
Scoped to this part · feeds back into the world's score.