Cogwheel — Dungeon Objects, Light Beams & Push Puzzles

Cogwheel turns dungeon objects into a property of the event, not a program inside it. Put <cog:block> in an event's note box and it is a pushable block — with the whole interaction matrix behind it, and its own drawn body: since v1.1.0 the dungeon draws itself, from an atlas of 46 procedural marks with no image files anywhere in the product.

The problem it removes

One pushable block, evented properly, is a page of work: check the tile ahead, check what is on it, check the terrain, move the event, set a self-switch, handle the hole, handle the corner that makes the room unsolvable. Then copy that page for every block in the dungeon — and change it everywhere when the rule changes.

Cogwheel replaces all of it with a notetag and three region colours.

Every shove is previewed before you commit

Face an object and the readout names what the push will do — moves, slides four tiles, falls and bridges, sinks, shatters, blocked — with the reason underneath, and the destination cell boxed on the map.

The preview runs the real resolver and restores the state, so what it promises and what happens cannot disagree. That is not a UI nicety. A puzzle where a wrong shove silently ruins the room is a puzzle players quit.

What you author

Paint terrain with regions:

• hole — things fall in, and a block pushed in fills it permanently and becomes floor
• ice — things slide until the ice ends, stopping where the ice stops rather than where you wanted
• water — things sink, and become a crossing

Walls need no region at all — Cogwheel asks the tileset the same passability question the engine does, so a wall you already drew is already a wall.

Then put a notetag on an event:

• <cog:block> — pushable block. Name a material — <cog:block wood>, iron, gild, rune, ice — and both its body and the crossing it leaves behind are drawn in it
• <cog:boulder> — rolls until stopped, and shatters against a wall; granite, amber or obsidian
• <cog:mirror /> and <cog:mirror \> — pushable mirrors that fold a beam through 90°
• <cog:plate switch=5> — pressure plate, flush with the floor, driving switch 5
• <cog:receiver switch=6> — lit when a beam reaches it
• <cog:emitter 2> — emits a beam downward

Everything else — what happens when a boulder rolls across ice toward a hole with a plate under it — is the matrix's problem, not yours.

It draws itself — 46 marks, zero image files

Leave a Cogwheel event's graphic blank and the plugin draws it: blocks in six materials, boulders in three, silvered mirrors, plates that sink and light, receivers whose iris floods open when the beam arrives. A spent block is redrawn as what it became — timber planks over a pit, an inlaid gilded deck, a ford closing over in the water, shards where a boulder shattered. Give an event your own art and Cogwheel steps aside; the atlas never overrides you.

And press TAB for the Blueprint Lens: the whole room redrawn as Cogwheel's own instrument — surveyed floor, hatched matter, open pits with depth rings, faceted sheet ice, your player as a surveyor's reticle. The puzzle exactly as the machine reads it, and a readability tool players keep switched on.

Cogwheel draws no RPG Maker windows at all. The beam is an additive PIXI layer with a bloom at the emitter and a flooded iris at the receiver; every glyph, body, ground cell and icon is the product's own drawing.

Built to live in a real project

• No core method is replaced. Every engine method it extends saves the original and calls it — enforced by a test that reads the shipped source against the real MZ source.
• Lossless, versioned saves. A room stores a small mutation record; beams, links and bridge state are recomputed on load. The live runtime object is never serialised.
• Nothing allocated in the per-frame path — enforced by a static scan that is itself proven to fire against a deliberately sabotaged copy.
• Raw, readable JavaScript with full JSDoc. No minification, ever.
• Room reset un-fills every bridge and safely returns a stranded player to the entrance.

Verified, with numbers

• 221/221 checks green across five suites — the interaction matrix cell by cell, the atlas (all 46 marks proven distinct, deterministic and non-trivial), the notetag parser, the zero-allocation scan, and the patch-discipline guard.
• In-engine verified, not merely unit-tested: 47/47 checks inside a real running MZ engine — bodies tracking their events to the pixel, the lens building one drawn cell per tile — with 0 page errors.
• All four demo rooms proven solvable by exhaustive search, with room reset proven to recover every reachable dead end.
• Frame cost measured in that engine, lens on: this plugin's own code costs 0.15 ms per frame against a 2 ms budget, with 15 draw calls and zero texture uploads, bitmap redraws or window refreshes.

⚠️ Before you buy

Cogwheel is grid-native. It resolves pushes in whole tiles against the tile grid, so it is not compatible with pixel-movement plugins or action-battle systems that move the player off the grid. Said here rather than discovered later.

Not in this version: cranks, and lift / carry / throw — the kit is push-based.

What you get

Four plugins — CogwheelCore.js (the rules engine, pure logic), CogwheelAtlas.js (the artwork, as code), CogwheelMap.js (the RPG Maker bridge), CogwheelInspector.js (the bodies, lens, overlay and readout) — plus four worked demo rooms and a full user guide.

---

More RPG Maker MZ systems from CSAF:
Township — NPC daily routines and living towns
Aperture Core · Bazaar Core · Chronicle Core · Verdict Core · Sigil Core · Loop Core · Voyage Core · Colosseum Core · Cipher Core