chore(puzzles): audit and tier authored puzzle content

[zoeyrose]

Architecture amendment — one authored content source (2026-08-13)

Initiative atrinik/atrinik#357 supersedes every future live-branch instruction below. atrinik/content@main is the sole mutable authored source for replacement and Classic targets. Future authored changes land only on main; supported Classic artifacts are deterministically derived from the same immutable main revision. Do not create, restore, author, backport, validate, or publish through a live 1.x branch.

Exact historical 1.x commits, tags, releases, assets, preserved local snapshots, provenance, parity records, and comparisons remain valid immutable evidence. This amendment changes no other feature, balance, lore, compatibility, licensing, validation, or ownership acceptance criterion.

Outcome

Establish a source-backed baseline for Atrinik's authored puzzles, classify them by player-facing complexity, identify defects and underused mechanics, and use this issue as the planning index for puzzle improvements.

Audit status (2026-08-11): the static source audit is complete. Runtime behavior, reset timing, path reachability, and multiplayer interference still require focused Classic playtests in the implementation issues.

Baseline and method

The audit compared both authored release lines:

• content main at fde585e2dce52915704fa49608c07e8889f77bf5
• content 1.x at b342d5632563730b12806414041cd4a4f575e07d

The content catalog found 8,098 definitions and 68,560 references, including 3,650 map definitions and 16 quests, with no catalog diagnostics. Static searches found candidate mechanisms; map connections, scripts, readables, quest state, exits, and reset declarations were then traced manually. Thirty-eight named puzzle maps/scripts/interfaces were byte-compared between the two revisions, and all audited candidates are identical.

This is a source audit, not a claim that every inferred behavior has been reproduced in a running server or editor.

Puzzle tiers

Puzzle tier describes reasoning and state complexity, not monster level or map difficulty.

Tier	Player loop	Intended scope	Recovery contract
Tier 1 — observe and act	Notice one clue and perform one nearby interaction	1–3 minutes; one room or landmark	Immediate feedback; no irreversible failure; reset is obvious
Tier 2 — connect and manipulate	Combine 2–4 clues/actions, spatial relationships, or a short sequence	5–15 minutes; one area or compact route	Wrong states are readable; manual or timed reset; safe re-entry
Tier 3 — investigate and synthesize	Join distributed evidence, manipulate persistent state, or execute under environmental pressure	15–45 minutes; multiple maps or lore sources	Checkpoints, explicit escape/reset, duplicate-safe progress, party semantics

Record search radius, execution pressure, required character capabilities, and world danger separately. A one-click altar in a level-90 temple remains a Tier 1 logic puzzle; a low-level maze can still be unfair if it silently routes into level-65 content.

Mechanism distribution

Raw map-instance counts are not puzzle counts, but they show how concentrated the vocabulary is:

Archetype	Instances	Maps
button	51	7
handle_lever	38	22
pedestal	133	9
check_inv	155	57
detector	45	7
creator / duplicator / director	88 / 85 / 59	9 / 6 / 5
spinner	4	1
teleporter	2	1

Both spinners and connection-controlled teleporters occur only in the Plane of Creation mechanism showcase. Directors are concentrated in four live-world maps, all in Underground City. Atrinik already has a rich switch/checker/detector/creator vocabulary, but authored puzzles use it in a small number of dense locations and often as invisible automation.

Existing puzzle inventory

Content	Tier	What works	Audit finding
Promethia/Scursaur Underground Maze (challenge, reset exits, success exit)	T2	Nonlethal navigation/memory trial with a clear fantasy challenge	Most reset tiles are unmarked; there are no checkpoints; difficulty-1 entry can deliver the player to difficulty-65 Dragons Island. Coordinate the route-danger fix with #20.
Abandoned Mine passphrase (Lothost's Notes, gate script)	T1	Connects a fixed readable to a world gate	The note discloses the literal answer, minno/mino is inconsistent, input handling is brittle, and the recognizable Tolkien “mellon” puzzle is a lore/provenance mismatch rather than an Atrinik-native deduction.
Berri Lur four statues (pedestals, voice clue)	T2	Strong place/name matching that opens the Temple of Loki	Shared rollable statues permit interference. A one-minute vacant-map reset is recoverable but can erase a party's progress.
Temple of Loki altars (three outcomes)	T1	The choice, ambush, and escape fit a trickster temple	The lethal choice is arbitrary and explained only after success; shared triggers can punish bystanders.
Loki's escaping ladder and Old Treant (ladder behavior, push hint)	T2 / T1	Herding a fleeing ladder against a wall is an excellent lore-matched spatial trick; the treant clearly teaches pushing	The ladder is random, shared, and mutable across tiled maps with no explicit missing-state recovery. The basic push tutorial appears very late.
Brynknot Sewer four-rock route (reset/reward script)	T2	Multi-map Sokoban-style routing with a tangible key reward	Completion forcibly resets all four shared rocks, disrupting another party; feedback before completion is minimal; missing beacon/object assumptions and consumed/lost-key behavior need tests.
Underground City II wall switch and four torches (torch script)	T1 / T2	Observation/ranged interaction plus an atmospheric all-dark state and remote gate response	The torch solution has little fixed local clueing, uses global cross-map state and a timer/monster/waypoint chain, and gives only distant gear audio as confirmation.
Underground City III expedition reconstruction (Day 1–7 notes and clue, security feedback)	T3	The strongest existing puzzle: journal fragments, a fake torch, obscured “magic bullet,” northwest trajectory, bridge warning, and environmental result form a coherent lore deduction	A specific spell/capability appears required; notes and traps are shared; the fake-torch type override and bridge/security chain are brittle; recovery and success feedback need runtime proof.
Incuna Water Well anti-flood machine (start/success messages)	T2 player loop / T3 state	Strong diegetic industrial spectacle with flooding, boulders, gates, and drainage	Much of the long connection graph is hidden automation rather than player reasoning; drowning raises recovery stakes; connection 144 appears orphaned in static inspection; retrigger, reset, and multiplayer behavior need verification.
Berri Lur bog cleansing trail (status removal pool)	T1	Existing status, barred-town response, NPC direction, and cleansing pool already form an environmental secret	It lacks journal state and progressive environmental breadcrumbs; players must find an exact tile while carrying a nuisance status.
Lairwenn's Notes / Greyton jail secret / Portal of Llwyfen	T1 / T2	Per-character quest containers, hidden switches, keys, and maze-like navigation demonstrate reusable low-risk patterns	Lairwenn's target is deliberately unreadable; the jail switch has no visual language; Llwyfen is mainly combat/key gating and should not be overcounted as logic.
Hierro's darkness encounter (three authored histories, light restriction)	T2 knowledge encounter	Readables establish darkness, heat-sight, torches, and the trap before the lair enforces the rule	This is a strong boss gimmick rather than a pure logic puzzle; all three histories are co-located, reducing discovery.
Glacial Hollow fire-crystal route (player-facing development sign)	Intended T2/T3; not live	The proposed scarce-crystal/melting-wall route is lore-matched to a fire/ice dungeon	The sign says its scripts were removed, exposes development prose, and warns the player can become trapped. Fire-crystal drops remain, but no matching switch/check implementation was found.

Puzzle-adjacent moral choices such as the two resolutions to the ant problem in Lost Memories, illusionary walls, one-way environmental secrets, quest key chains, and boss knowledge checks are valuable, but should be classified separately from stateful logic puzzles.

Conclusions

Strengths

• The best puzzles explain themselves through the place: Loki's ladder, Berri's statues, Incuna's waterworks, and Underground City's expedition/security sequence.
• The engine/content vocabulary already supports weights, inventory checks, detectors, creators, duplicators, directors, spinners, movable objects, timed state, readable clues, and per-character quest containers.
• Existing fixed journals and quest state are enough to prototype order-independent collectible investigations without first inventing a new minigame engine.

Systemic gaps

1. Clue quality is uneven. Some solutions are disclosed verbatim; others rely on random/global books, invisible switches, or trial and error.
2. State ownership is unclear. Rocks, statues, ladders, torches, altars, and flood machinery are shared map state without documented party/concurrency behavior.
3. Recovery is rarely explicit. Missing objects, death, disconnect, map reset, consumed keys, and simultaneous parties are not covered by focused scenarios.
4. Difficulty signalling and logic tier are conflated. Simple mechanics arrive in high-level zones while a difficulty-1 maze leads to level-65 danger.
5. Mechanics are concentrated. The Plane of Creation demonstrates patterns that the live world seldom reuses; live puzzle density clusters in Underground City and a few legacy dungeons.
6. Accessibility needs a contract. Color-only clues, exact wording, class-specific spells, and low-contrast secret switches need alternate signals.
7. No focused puzzle regression suite surfaced. Static correctness does not prove reset, re-entry, or multiplayer safety.

New puzzle opportunities

Tier	Area and lore fit	Proposed mechanic
T1	Asteria Royal Library	Re-shelve a small set of Atrinik-native chronicles by fiction/history, then use Elvish/Dwarvish translator annotations as the confirmation clue. Reuses inventory checks and shelves.
T1	Berri Lur bog and Portu Baserrian	Add smell, tracks, tainted-water, and clean-water breadcrumbs to the existing stench/cleansing loop.
T1	Clearhaven Mine	After #25's bomb lesson, read a safety placard and set one or two existing-style levers before a controlled blast.
T2	Asteria palace dungeon	Fulfil the existing drow intelligence report's promise: transfer enchanted keys at marked exchange points, with each handoff changing the safe route.
T2	Nawerhals fire/ice boundary	Balance paired thermal cairns using weighted plates, detectors, and timed creators; solve by cancelling extremes, matching the region's origin.
T2	Rockforge underground farm	Route daylight through runic mirrors/shutters to crops. Prototype with directional floor states and detectors before requesting a reusable beam system.
T2	Muddy Pit / Incuna Water Well	Expose pressure, valve order, and gauges so the player reasons about flow instead of watching an invisible connection cascade.
T2/T3	Vielumin Ruins	Reconstruct rebel-drow experiments by ordering archive fragments and reagents; defer final faction claims until drow canon is settled.
T3	Underground City	Extend the excellent expedition-note pattern with capability-neutral alternatives and explicit checkpoints, coordinated with #107.
T3	Morliana–Brynknot–Incuna–Glacial Hollow	A distributed scientist notebook and crystal-resonance synthesis puzzle, owned by the linked hidden-lore audit and its Resonance Papers epic.

Puzzle contract for new and repaired content

Every implementation child must specify and test:

• clue source, progressive hints, and a solution that is deduced rather than guessed;
• visible/audible initial, intermediate, wrong-state, success, and already-complete feedback;
• reset timer or manual reset, missing-object recovery, safe escape, re-entry, and no permanent item loss;
• character-local versus party versus shared-map state, including two-party interference;
• alternatives to color-only, exact-phrase, and class/spell-only solutions;
• reward ownership, repeatability, duplicate prevention, and whether lore completion is optional;
• exact map difficulty and route-danger changes;
• solve, wrong input, abandon/reset, death, reconnect, map reload, and concurrent-use validation.

Coordination

• Audit progression-route danger and pilot safer travel loops #20 owns the broader route-danger audit; this issue owns puzzle-specific signalling and recovery.
• Add explicit elemental-readiness paths for Dark Cave and Old Outpost #21 establishes the precedent that preparation hints must not simply expose puzzle solutions.
• Clearhaven Mine #25 owns Clearhaven Mine's broader implementation.
• feat(maps): continue the Underground City skeletal-dragon arc in Bone Cairn #107 already owns the deterministic Underground City/Bone Cairn lore trail; do not duplicate or reparent it.
• atrinik/server#54 and atrinik/server#59 own replacement trigger/action-graph and puzzle/environmental-trigger migration. Content issues should prove authored requirements without inventing parallel engine ownership.

Native implementation children:

• fix(puzzles): harden existing puzzle feedback, recovery, and shared state #143 — harden feedback, recovery, accessibility, and shared state in live legacy puzzles;
• feat(puzzles): add a Tier 1 observe-and-act pilot pack #144 — add the Tier 1 Asteria/Berri/Clearhaven pilot pack;
• fix(puzzles): restore Glacial Hollow's fire-crystal route safely #146 — restore Glacial Hollow's absent fire-crystal route safely.

The hidden-lore audit #142 owns the cross-area Tier 3 notebook arc and backlinks here.

Acceptance criteria

• Existing authored puzzles are inventoried with source evidence and tiered by player-facing complexity.
• Strengths, defects, underused mechanisms, and candidate regions are recorded without conflating combat difficulty with puzzle tier.
• Both release lines and audit limitations are explicit.
• Native implementation children are linked and each adopts the puzzle contract above.
• Representative Classic runtime scenarios establish the first repeatable reset/concurrency baseline.
• Completed children update this index with validation evidence and any revised tier assessment.

Release lines

The audited candidates are currently byte-identical on main and 1.x. Shared authored-content changes should be authored canonically on main, backported to 1.x in a separate worktree and linked pull request, and validated independently. Only the canonical main pull request closes an issue; any single-line exception needs concrete format, consumer, runtime, attribution, or provenance evidence.