Guide

Game door, key and lock puzzle systems explained

Harbor Vault’s optional treasure wing looked straightforward: find the red key, open the red door, collect loot. In telemetry, 68% of players who entered the wing quit before the chest — not because combat was hard, but because the red key unlocked a second red door that consumed the key with no return path to the first gate. The level taught backtracking by accident. After restructuring the lock graph so keys persisted in inventory and each colored door had at most one mandatory consumption point, optional-route completion rose from 22% to 71% while main-path time stayed flat.

Door-key-lock puzzles gate spatial progress with permission tokens: keys, keycards, codes, or abstract “capabilities.” Unlike pressure-plate signal graphs that route state through combinators, lock puzzles ask players to plan routes through a mutable topology. This guide covers key types, lock state machines, dependency graphs, inventory vs world-state keys, consumable vs reusable locks, the Harbor Vault refactor, a technique decision table versus plates and beam puzzles, pitfalls, and a production checklist.

Core vocabulary: keys, locks, and gates

A lock is any interaction that blocks traversal or container access until a condition is satisfied. A key is anything that satisfies that condition — a physical item, a boolean flag, a party member ability, or a puzzle output from another room.

Common key types

Inventory keys — picked up, shown in UI, consumed or retained on use (classic Zelda, Metroid).
Colored keys — typed tokens (red/blue/yellow) where lock color must match; often single-use per door in retro dungeon design.
Keycards and tiers — level 1/2/3 access; higher tier supersedes lower (facility crawlers, immersive sims).
World-state keys — no inventory slot; flipping a lever or solving a remote puzzle sets gate_A_open globally.
Abstract capabilities — double jump, grappling hook, ice spell; functionally keys that permanently expand the reachable graph.
One-time codes — numeric or symbol passwords discovered in notes; same lock semantics without a physical prop.

Lock behaviors

Persistent unlock — door stays open after first valid use; standard for main progression.
Consumable unlock — key is destroyed; door may relock on zone reset or never reopen behind the player.
Timed relock — door closes after N seconds; key not consumed but route pressure increases.
One-way gate — drop-down ledge or portcullis that cannot be reversed; acts as implicit key consumption.

Players reason about lock puzzles as reachability on a graph: nodes are rooms, edges are doors, and keys temporarily add edges. If your graph has traps where a key permanently removes an edge the player still needs, you get softlocks — the Harbor Vault failure mode.

Lock state machines and interaction contracts

Implement each lock as a small finite-state machine (FSM) with explicit transitions. Ambiguous states (“maybe open”) cause desync in co-op and save/load bugs.

Minimal lock FSM

States: LOCKED, UNLOCKED, OPEN (traversable), optional BROKEN.
Events: try_key(key_id), use_lever, force_open (explosive), zone_reset.
Effects: consume key, play animation, update navmesh, emit quest flag, log analytics.

Expose a consistent player-facing contract through your interaction system: locked doors show required key type on examine; wrong-key attempts give immediate feedback (“Needs blue keycard”) instead of silent failure.

Server authority and persistence

In multiplayer or cloud saves, treat lock_id → state as authoritative server state. Client animations are cosmetic. On load, replay unlock transitions so navmesh and spawned enemies match door states. Version lock definitions with content patches — changing which key opens a door without migrating saves strands players.

Designing solvable lock dependency graphs

Before greyboxing, sketch a lock graph: directed edges for keys found in room A that open doors leading to room B. Validate the graph with a simple reachability solver or brute-force key permutation script in your level editor.

Graph patterns that work

Linear chain — key₁ → door₁ → key₂ → door₂; easy to teach, low backtracking.
Hub and spoke — central room with multiple locked branches; players choose order; good for optional loot.
Master key finale — sub-keys in parallel branches combine into one craft or slot puzzle at a central lock.
Key escrow — deposit key in receptacle to power a distant door while a duplicate or alternate route returns the token.

Patterns that cause softlocks

Single-use key required for two mutually exclusive doors with no reordering.
One-way drop into a wing that needs a key placed on the far side of a consumed lock.
Key behind a door that itself requires the same key (unless intentional tutorial with two copies).
Inventory cap that forces dropping a progression key to pick up loot.

Run an automated softlock detector: simulate all key pickup and door use sequences up to depth N. Flag states where the exit node is unreachable. Harbor Vault added this check in CI after the red-key incident; two later levels failed the test before ship.

Consumable vs persistent keys: player mental models

Classic Doom-style colored keys are consumable per door in player memory even when the engine does not delete the item — because each door vanishes the key from relevance. Modern adventure games usually prefer persistent keys: open any matching door forever, key stays in inventory for backtracking and completionist cleanup.

When to consume keys

Puzzle is explicitly about resource allocation (which of three doors gets the only bomb?).
Roguelike runs where keys are run-scoped loot.
Escape-room timers where inserting a key powers a mechanism for 60 seconds.

When to persist keys

Metroidvania backtracking across a large map.
Any optional content behind doors players may revisit after main quest.
Co-op where one player might hold the key while another scouts.

If you mix both behaviors, telegraph consumption in UI: key icon cracks, door animation shows key snapping, audio cue differs from persistent unlock. Silent consumption is the top support ticket driver in lock-heavy games.

Pairing locks with other puzzle primitives

Pure key hunts feel dated if every obstacle is “find colored object.” Layer locks with other systems so keys reward comprehension, not hallway scanning:

Plate + lock — door opens only while a plate is held; key is on the far side; player props a crate (see pressure plates).
Beam + lock — receiver powers the maglock; key is optional shortcut (see light beam puzzles).
Enemy key drop — key is loot; lock teaches combat gating.
Information key — code written on a note is the key; door is the lock; no inventory item.

The lock should answer where progress happens; the paired primitive answers how the player earns access. Escape rooms especially benefit from this layering — see escape room design for pacing across chained locks.

Harbor Vault refactor: from key traps to readable graphs

The failing wing layout:

Red key in room R1; red door D1 (consumes key) to R2.
Red door D2 in R2 (consumes second red key that did not exist).
One-way drop from R2 to R3; blue branch later required revisiting R1 through D1 — impossible after consumption.

The refactor:

Persistent red key in inventory; both doors use the same token without consumption.
D2 changed to blue with blue key placed in R3 before the one-way drop; graph solver confirmed full optional loop.
Examine hints on doors: icon + “Red access” / “Blue access”.
Automated graph test in level export pipeline; blocks merge on unreachable exit.

Optional completion rose from 22% to 71%; support tickets mentioning “stuck door” fell 84%. Main critical path length unchanged because the fix only touched optional topology.

Technique decision table

Approach	Best for	Weakness
Colored single-use keys	Short dungeon levels, clear binary progress	Backtracking traps; feels arbitrary in large maps
Persistent inventory keys	Metroidvania, open-world dungeons, optional content	Key ring UI clutter; less resource tension
World-state / remote unlock	Boss rewards, narrative beats, co-op sync	Opaque without map feedback or quest log
Pressure-plate routing	Timing, co-op weight, simultaneous conditions	Spatial not inventory reasoning; different skill
Light-beam routing	Optical planning, orthogonal thinking	Hard to combine with tight combat corridors
Abstract ability gates	Long-form progression, mastery fantasy	Weaker moment-to-moment puzzle if overused

Choose locks when routing and permission are the puzzle; choose plates or beams when continuous state or geometry is the puzzle. Hybrid levels should teach one primitive at a time before combining — a principle from fair puzzle design.

Common pitfalls

Softlock graph — no automated reachability check before ship.
Silent key consumption — players do not know a key is gone until they need it again.
Duplicate key ambiguity — two red keys in one level without clear labeling; players hoard the wrong one.
Invisible locks — door looks open but triggers cutscene block; breaks trust in lock iconography.
Key loss on death — roguelike rule applied to progression keys in a checkpoint game.
No examine text — players pixel-hunt identical doors; add color trim, sound, and UI prompt.
Co-op race — one player consumes the only key while partner is on the wrong side; use shared inventory or dual-key doors.

Production checklist

Sketch lock dependency graph before greybox; validate with solver script.
Define per lock: key type, consumable vs persistent, relock rules.
Implement lock FSM with explicit states and save-game serialization.
Show required key type on examine and wrong-key feedback on attempt.
Telegraph consumable keys with distinct animation and SFX.
Run softlock detection in level CI on every export.
Update navmesh and spawn tables on unlock transitions.
Map optional doors separately; do not sacrifice optional graph for main path.
Log door attempts, unlocks, and backtrack time for telemetry.
Playtest with intentional wrong-order key pickup sequences.
Document key-door pairs in a level design spreadsheet linked to lock IDs.
Pair pure locks with at least one non-key puzzle primitive per dungeon wing.

Key takeaways

Lock puzzles are reachability graphs. Validate them before art pass.
Persistent keys reduce softlocks in large or optional-heavy maps.
Harbor Vault optional completion rose from 22% to 71% after graph and consumption fixes.
Combine locks with plates, beams, or combat to avoid fetch quest monotony.
FSM + examine UI + CI graph tests prevent the expensive post-launch patch cycle.