diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0d7ae4f..e67a931 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,49 +1,27 @@ -# Puzzle Design Knowledge Base +# Puzzle Design Handbook -A taxonomy of puzzle design patterns from classic point-and-click adventure games. +A practical handbook for designing puzzles in point-and-click adventure games. -[Introduction](./introduction.md) +--- -# Core Principles +## Part I: Foundations +- [Introduction](introduction.md) +- [Why Adventure Games](parts/why-adventure-games.md) - [Core Principles](core-principles.md) -- [Documentation Structure](documentation-structure.md) -# Inspiration +## Part II: Design Process -## Games Analyzed +- [Dependency Charts](design-process/dependency-charts.md) +- [Working Backwards](design-process/working-backwards.md) +- [Bushy Branching](design-process/bushy-branching.md) +- [Internal Logic & Fairness](design-process/internal-logic-fairness.md) +- [Player Psychology](design-process/player-psychology.md) +- [Playtesting Methodology](design-process/playtesting-methodology.md) +- [Failure Modes](design-process/failure-modes.md) +- [Hint System Design](design-process/hint-systems.md) -- [Beneath a Steel Sky (1994)](inspiration/beneath-a-steel-sky.md) -- [Broken Sword 1: Shadow of the Templars (1996)](inspiration/broken-sword-1-shadow-of-the-templars.md) -- [Broken Sword II: The Smoking Mirror (1997)](inspiration/broken-sword-ii-the-smoking-mirror.md) -- [Day of the Tentacle (1993)](inspiration/day-of-the-tentacle.md) -- [Full Throttle (1995)](inspiration/full-throttle.md) -- [Gabriel Knight 1: Sins of the Fathers (1993)](inspiration/gabriel-knight-1-sins-of-the-fathers.md) -- [Loom (1990)](inspiration/loom.md) -- [Grim Fandango (1998)](inspiration/grim-fandango.md) -- [Indiana Jones and the Fate of Atlantis (1992)](inspiration/indiana-jones-and-the-fate-of-atlantis.md) -- [Indiana Jones and the Last Crusade (1989)](inspiration/indiana-jones-and-the-last-crusade.md) -- [King's Quest III: To Heir Is Human (1986)](inspiration/kings-quest-iii-to-heir-is-human.md) -- [King's Quest VII: The Princeless Bride (1994)](inspiration/kings-quest-vii-the-princeless-bride.md) -- [King's Quest VIII: Mask of Eternity (1998)](inspiration/kings-quest-viii-mask-of-eternity.md) -- [The Legend of Kyrandia: Book One (1992)](inspiration/the-legend-of-kyrandia-book-one.md) -- [Maniac Mansion (1987)](inspiration/maniac-mansion.md) -- [Quest for Glory 1: Shadows of Darkness (1989)](inspiration/quest-for-glory-1-shadows-of-darkness.md) -- [Quest for Glory II: Trial by Fire (1989)](inspiration/quest-for-glory-ii-trial-by-fire.md) -- [Quest for Glory III: Wages of War (1992)](inspiration/quest-for-glory-iii-wages-of-war.md) -- [Quest for Glory IV: Shadows of Darkness (1994)](inspiration/quest-for-glory-iv-shadows-of-darkness.md) -- [Sam & Max Hit the Road (1993)](inspiration/sam-and-max-hit-the-road.md) -- [Simon the Sorcerer (1993)](inspiration/simon-the-sorcerer.md) -- [Space Quest 1: The Sarien Encounter (1986)](inspiration/spacequest-1-the-sarien-encounter.md) -- [The Dig (1995)](inspiration/the-dig.md) -- [Syberia (2002)](inspiration/syberia.md) -- [The Longest Journey (1999)](inspiration/the-longest-journey.md) -- [Zak McKracken and the Alien Mindbenders (1988)](inspiration/zak-mckracken-and-the-alien-mindbenders.md) -- [Space Quest II: The Vohaul Assault (1987)](inspiration/spacequest-2-the-vohaul-assault.md) -- [SpaceQuest III: The Pirates of Pestulon (1989)](inspiration/spacequest-iii-the-pirates-of-pestulon.md) -- [SpaceQuest IV: The Rogerwars (1991)](inspiration/spacequest-iv-the-rogerwars.md) - -# Puzzle Taxonomy +## Part III: Puzzle Taxonomy ### Information Discovery Puzzles - [Information Discovery Overview](puzzles/information-discovery-overview.md) @@ -85,8 +63,49 @@ A taxonomy of puzzle design patterns from classic point-and-click adventure game - [Non-Standard Domains Overview](puzzles/non-standard-domains-overview.md) - [Surreal Logic Bridges](puzzles/surreal-logic-bridge.md) -# Documentation Guidelines +## Part IV: Inspiration + +- [Inspiration Index](inspiration/cross-reference-index.md) + +### Games Analyzed + +- [Beneath a Steel Sky (1994)](inspiration/beneath-a-steel-sky.md) +- [Broken Sword 1: Shadow of the Templars (1996)](inspiration/broken-sword-1-shadow-of-the-templars.md) +- [Broken Sword II: The Smoking Mirror (1997)](inspiration/broken-sword-ii-the-smoking-mirror.md) +- [Day of the Tentacle (1993)](inspiration/day-of-the-tentacle.md) +- [Full Throttle (1995)](inspiration/full-throttle.md) +- [Gabriel Knight 1: Sins of the Fathers (1993)](inspiration/gabriel-knight-1-sins-of-the-fathers.md) +- [Loom (1990)](inspiration/loom.md) +- [Grim Fandango (1998)](inspiration/grim-fandango.md) +- [Indiana Jones and the Fate of Atlantis (1992)](inspiration/indiana-jones-and-the-fate-of-atlantis.md) +- [Indiana Jones and the Last Crusade (1989)](inspiration/indiana-jones-and-the-last-crusade.md) +- [King's Quest III: To Heir Is Human (1986)](inspiration/kings-quest-iii-to-heir-is-human.md) +- [King's Quest VI: Heir Today, Gone Tomorrow (1992)](inspiration/kings-quest-vi-heir-today-gone-tomorrow.md) +- [King's Quest VII: The Princeless Bride (1994)](inspiration/kings-quest-vii-the-princeless-bride.md) +- [King's Quest VIII: Mask of Eternity (1998)](inspiration/kings-quest-viii-mask-of-eternity.md) +- [The Legend of Kyrandia: Book One (1992)](inspiration/the-legend-of-kyrandia-book-one.md) +- [Maniac Mansion (1987)](inspiration/maniac-mansion.md) +- [Quest for Glory 1: Shadows of Darkness (1989)](inspiration/quest-for-gloves-1-shadows-of-darkness.md) +- [Quest for Glory II: Trial by Fire (1989)](inspiration/quest-for-glory-ii-trial-by-fire.md) +- [Quest for Glory III: Wages of War (1992)](inspiration/quest-for-glory-iii-wages-of-war.md) +- [Quest for Glory IV: Shadows of Darkness (1994)](inspiration/quest-for-glory-iv-shadows-of-darkness.md) +- [Sam & Max Hit the Road (1993)](inspiration/sam-and-max-hit-the-road.md) +- [Simon the Sorcerer (1993)](inspiration/simon-the-sorcerer.md) +- [Space Quest 1: The Sarien Encounter (1986)](inspiration/spacequest-1-the-sarien-encounter.md) +- [The Dig (1995)](inspiration/the-dig.md) +- [Syberia (2002)](inspiration/syberia.md) +- [The Longest Journey (1999)](inspiration/the-longest-journey.md) +- [Zak McKracken and the Alien Mindbenders (1988)](inspiration/zak-mckracken-and-the-alien-mindbenders.md) +- [Space Quest II: The Vohaul Assault (1987)](inspiration/spacequest-2-the-vohaul-assault.md) +- [SpaceQuest III: The Pirates of Pestulon (1989)](inspiration/spacequest-iii-the-pirates-of-pestulon.md) +- [SpaceQuest IV: The Rogerwars (1991)](inspiration/spacequest-iv-the-rogerwars.md) + +## Part V: Reference -- [Style & Formatting](docs/style-formatting.md) - [Common Pitfalls](docs/common-pitfalls.md) - [Validation Checklist](docs/validation-checklist.md) +- [Quick-Start Worksheet](docs/quick-start-worksheet.md) + +## Part VI: FAQ + +- [FAQ](docs/faq.md) diff --git a/src/core-principles.md b/src/core-principles.md index 62da562..cfcfba5 100644 --- a/src/core-principles.md +++ b/src/core-principles.md @@ -1,19 +1,94 @@ # Core Principles -These puzzle types share common characteristics that define adventure game puzzle design: +These principles define adventure game puzzle design at the highest level. Every puzzle type in this handbook manifests these principles in different ways. -## Limited Actions, Unlimited Combinations +--- + +## 1. Limited Actions, Unlimited Combinations The standard adventure game action set (LOOK, TALK, USE, WALK, TAKE) is applied in novel ways. The puzzle emerges from the *combination* of actions, not from complex input systems. -## Information as Puzzle Element +**What this means:** You don't need more verbs. You need more interesting combinations of existing verbs. + +--- + +## 2. Information as Puzzle Element The puzzle is often "what does the game know that I need to find out?" rather than "what do I need to do?" Information discovery is the primary mechanic. -## Failure as Feedback +**What this means:** Often the puzzle isn't the solution—it's figuring out what the problem even is. + +--- + +## 3. Failure as Feedback Failed attempts reveal information about what's missing or wrong. The puzzle teaches through consequences, not explicit instruction. -## Synthesis Over Collection +**What this means:** Every failed attempt should narrow the possibility space, not expand it randomly. + +--- + +## 4. Synthesis Over Collection The solution often requires combining information from multiple sources. No single action completes the puzzle—player must synthesize. + +**What this means:** Don't let players "collect" their way to victory. They must understand how pieces connect. + +--- + +## 5. Inception Over Extraction + +The designer should plant the solution in the player's mind through earlier puzzles, rather than forcing players to guess random combinations. + +**Why it matters:** Players who feel clever are engaged. Players who feel like they're guessing are frustrated. + +**Source:** [Adventure Puzzle Design](resources/puzzle-design/adventure-puzzle-design-stanislav-costiuc.md) + +--- + +## 6. Reward Intent + +When players have the right idea, let them succeed. Interface punishment for near-correct actions breaks the contract between designer and player. + +**Why it matters:** The #1 complaint about adventure games ("moon logic") often stems from players having the right idea but executing it wrong. + +**Source:** [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md) + +--- + +## 7. Internal Logic Must Prevail + +Solutions must follow from rules established by the game world. Arbitrary solutions violate the player's mental model. + +**Why it matters:** Players build a model of how the world works. When solutions contradict that model, trust breaks. + +**Source:** [14 Deadly Sins](resources/criticism/14-deadly-sins-graphic-adventure-design-filfre.md) + +--- + +## 8. Clarity of Objective + +Players should always know their ultimate goal and their immediate next step. Ambiguity creates frustration, not mystery. + +**Why it matters:** "What should I do next?" is the most common stuck-player question. Clear sub-goals prevent stuckness. + +**Source:** [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md) + +--- + +## How These Principles Apply + +Every puzzle type in this handbook should be evaluated against these principles: + +| Principle | Question to Ask | +|-----------|-----------------| +| Limited Actions | Could this puzzle work with fewer verbs? | +| Information First | Does the player know what they need to find? | +| Failure as Feedback | Does failing teach something useful? | +| Synthesis | Must player combine multiple sources? | +| Inception | Does the puzzle teach its own solution? | +| Reward Intent | Does near-correct execution work? | +| Internal Logic | Does the solution follow from established rules? | +| Clarity | Does the player know their goal? | + +When designing a puzzle, if you can't answer "yes" to most of these, the puzzle needs redesign. diff --git a/src/design-process/bushy-branching.md b/src/design-process/bushy-branching.md new file mode 100644 index 0000000..0f967b9 --- /dev/null +++ b/src/design-process/bushy-branching.md @@ -0,0 +1,103 @@ +# Bushy Branching + +## Preventing Player Stuckness Through Parallel Paths + +"Bushy branching" is the practice of designing multiple parallel puzzle paths so players always have alternatives when they get stuck. + +--- + +## The Core Problem: Linear Lock-In + +In a purely linear puzzle chain: + +``` +A → B → C → D → E +``` + +If a player gets stuck on B, they cannot progress. They must: +1. Keep trying B +2. Consult a walkthrough +3. Stop playing + +All three options create frustration. + +--- + +## The Solution: Bushy Branches + +``` + ┌── B1 ──┐ +A ──┼── B2 ──┼── E + └── B3 ──┘ +``` + +If a player gets stuck on one branch, they can try another. The key insight is that **branches should be independent but converge at natural points**. + +--- + +## Types of Branching + +### Horizontal Branching + +Multiple puzzles in the same "tier" that can be completed in any order. + +**Example:** Gathering three map pieces from three different locations. + +**Design rule:** Branches should have similar difficulty and length. + +### Vertical Branching + +Alternative solutions to the same problem. + +**Example:** Open a locked door with the key, or pick the lock, or find another way around. + +**Design rule:** Alternative solutions should be equally valid but not equally obvious. + +--- + +## Balancing Branch Difficulty + +When using parallel branches: + +| Problem | Solution | +|---------|----------| +| One branch is too hard | Add a hint or easier sub-puzzle | +| One branch is too easy | Add a wrinkle to extend it | +| Branches converge too early | Delay convergence points | +| Branches never converge | Create artificial dependencies | + +--- + +## The Caged Situation Technique + +"A caged situation in an adventure game is an easy situation almost all the time." + +Start players in a restricted capability scenario, then expand their abilities through the puzzle progression. + +**Pattern:** +1. Player can only do X +2. Puzzle requires X + Y +3. Player solves puzzle to get Y +4. Now player has X + Y +5. Repeat + +This creates natural difficulty progression and prevents early-game stuckness. + +--- + +## Source Material + +This technique is documented in: +- [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md) +- [Puzzle Design in Adventure Games - StackExchange](resources/puzzle-design/puzzle-design-adventure-games-stackexchange.md) + +--- + +## Placeholder: Bushy Branching Tutorial + +**To be written:** A design exercise showing how to take a linear puzzle chain and add bushy branching to it, with before/after diagrams. + +**Key questions to answer:** +- How many branches are enough? +- When should branches converge? +- How do you balance difficulty across branches? diff --git a/src/design-process/dependency-charts.md b/src/design-process/dependency-charts.md new file mode 100644 index 0000000..4dbe292 --- /dev/null +++ b/src/design-process/dependency-charts.md @@ -0,0 +1,122 @@ +# Puzzle Dependency Charts + +## The Method LucasArts Used to Design Puzzle Networks + +This chapter documents the puzzle dependency charting technique developed by Noah Falstein and used by Ron Gilbert and the LucasArts team to design *Monkey Island* and *Maniac Mansion*. + +--- + +## What Is a Puzzle Dependency Chart? + +A puzzle dependency chart is a visual map showing how puzzles relate to each other—which puzzles must be completed before others, which can be done in parallel, and where bottlenecks exist. + +**Why it matters:** Without charting, designers create "linear chains" that trap players who get stuck. Charts reveal where to add branching. + +--- + +## Chart Components + +### Nodes + +Each puzzle or sub-puzzle becomes a node in the chart. + +**Example:** In *Monkey Island 2*, "get map piece from Largo" is a node. + +### Dependencies + +Arrows show which puzzles require completion of others first. + +**Example:** "Fight LeChuck" requires "assemble voodoo doll" requires "get voodoo ingredients." + +### Parallel Tracks + +When puzzles don't depend on each other, they can be done simultaneously. + +**Example:** In MI2 Part 2, four map piece chains run in parallel. + +--- + +## How to Create a Chart + +1. **List all puzzles** in your game +2. **Identify dependencies** — what requires what +3. **Draw nodes and arrows** +4. **Look for bottlenecks** — single points that gate multiple paths +5. **Add branches** to reduce bottleneck frustration +6. **Balance difficulty** — ensure parallel paths have similar length + +--- + +## Bushy vs. Linear Charts + +| Type | Structure | Player Experience | +|------|-----------|------------------| +| **Linear** | Single chain, one puzzle after another | Frustrating when stuck; no alternatives | +| **Bushy** | Parallel branches; multiple paths | Players always have something to try | + +**Key insight:** "Make your branches 'bushy' by allowing players to work on simultaneous tasks." This is the #1 technique for preventing player stuck-ness. + +--- + +## Quantitative Targets + +Based on analysis of *Monkey Island 2*: + +| Metric | Target | +|--------|--------| +| Items per puzzle chain | 9-10 | +| Parallel chains | 3-5 | +| Rooms per chain | Variable | +| Characters per chain | 3-5 | + +These aren't rules—they're reference points from a well-balanced game. + +--- + +## Tools for Charting + +- Pen and paper (fast, low-friction) +- Diagramming tools (Lucidchart, draw.io) +- Spreadsheets (for tracking item locations) + +The tool matters less than actually doing it. + +--- + +## Common Patterns + +### The Hub and Spoke + +One central puzzle (hub) with multiple prerequisite puzzles (spokes). + +**When to use:** Major story beats that require preparation. + +### The Diamond + +Multiple puzzles feed into one, which feeds into multiple. + +**When to use:** climactic moments that summarize earlier progress. + +### The Grid + +Multiple parallel chains of equal length. + +**When to use:** Mid-game when you want players to choose their own path. + +--- + +## Source Material + +This technique is documented in: +- [The Technique LucasArts Used](resources/puzzle-design/lucasarts-puzzle-dependency-charts.md) +- [Monkey Island 2 Puzzle Design](resources/puzzle-design/monkey-island-2-puzzle-design.md) + +--- + +## Placeholder: Detailed Tutorial + +**To be written:** A step-by-step tutorial with a worked example, showing how to chart a small game's puzzles from start to finish. + +**Resources to draw from:** +- LucasArts puzzle dependency chart images +- Unpoint/Unclick methodology (Christopher Sacchi) diff --git a/src/design-process/failure-modes.md b/src/design-process/failure-modes.md new file mode 100644 index 0000000..c26bfb7 --- /dev/null +++ b/src/design-process/failure-modes.md @@ -0,0 +1,141 @@ +# Failure Modes + +## The 14 Deadly Sins of Adventure Game Design + +Jimmy Maher (FilFre) documented 14 common ways adventure game puzzles fail. These remain the definitive catalog of adventure game anti-patterns. + +--- + +## The 14 Sins + +### 1. Pixel Hunting + +Hiding essential items or actions in visually indistinguishable pixels. + +**Why it's bad:** Tests patience, not intelligence. + +**Solution:** Make interactive elements visually distinct. + +### 2. Guess-the-Verb + +Interface opacity where players must guess the specific verb the designer intended. + +**Why it's bad:** Punishes correct thinking with failure. + +**Solution:** "Reward intent" — accept equivalent actions. + +### 3. Unconnected Events + +Random events in the game world that gate progress but have no logical connection. + +**Why it's bad:** Breaks internal logic; players can't learn. + +**Solution:** Every gate should follow from established rules. + +### 4. Backwards Puzzles + +Requiring players to find a solution before encountering the problem. + +**Why it's bad:** Impossible to solve without outside knowledge or luck. + +**Solution:** Work backwards from solution (see Design Process chapter). + +### 5. "I Forgot to Pick It Up" + +Solutions requiring items the player should have collected but can't retrieve now. + +**Why it's bad:** Punishment for past actions player didn't know were important. + +**Solution:** Don't make critical items optional, or provide alternatives. + +### 6. Leap of Logic + +Missing steps in a logical chain. + +**Why it's bad:** Player has right idea but missing intermediate step. + +**Solution:** Test every chain step with playtesters. + +### 7. Non-Sensical Solutions + +Solutions that violate the game's established internal logic. + +**Why it's bad:** Teaches players their model of the world is worthless. + +**Solution:** All solutions must follow from established rules. + +### 8. Locked-Out Victory + +Dead ends where players can't complete the game without loading an earlier save. + +**Why it's bad:** Frustration with no recovery path. + +**Solution:** Design with alternative paths; add recovery mechanisms. + +### 9. Constant Death + +Punishing failure with death that doesn't teach anything. + +**Why it's bad:** Fear-based design creates anxiety, not engagement. + +**Solution:** Death should only occur with warning and learning opportunity. + +### 10. Inventory Clutter + +Too many items obscure the solution. + +**Why it's bad:** Players can't identify relevant items. + +**Solution:** Prune inventory; make solution items stand out. + +### 11. Dynamic Events Required But Never Seen + +Timing-sensitive events that players missed. + +**Why it's bad:** Impossible without foreknowledge or walkthrough. + +**Solution:** Avoid time-sensitive events, or make them repeatable. + +### 12. Padding + +Story-irrelevant puzzles that extend playtime without value. + +**Why it's bad:** Wastes player time; breaks narrative flow. + +**Solution:** Every puzzle should advance story or character. + +### 13. Context Clueless + +Unclear when something IS a puzzle vs. just scenery. + +**Why it's bad:** Players either ignore everything or exhaust themselves trying everything. + +**Solution:** Make interactive elements visually or audio distinct. + +### 14. Misleading Information + +False clues that lead players astray. + +**Why it's bad:** Punishes correct exploration; rewards walkthrough use. + +**Solution:** Clues should guide, not misdirect. + +--- + +## The Unifying Principle: Testing + +Most sins occur because designers didn't playtest enough. A single blind playtest would reveal most of these problems. + +--- + +## Source Material + +- [The 14 Deadly Sins of Graphic-Adventure Design](resources/criticism/14-deadly-sins-graphic-adventure-design-filfre.md) +- [Seven Deadly Sins of Adventure Games](resources/criticism/seven-deadly-sins-adventure-games.md) +- [10 Things I Hate About Adventure Games](resources/criticism/10-things-hate-adventure-games.md) + +--- + +## Placeholder: Sin Identification Guide + +**To be written:** A visual checklist with screenshots from classic games showing each sin in action, and how to fix it. diff --git a/src/design-process/hint-systems.md b/src/design-process/hint-systems.md new file mode 100644 index 0000000..6f603cf --- /dev/null +++ b/src/design-process/hint-systems.md @@ -0,0 +1,123 @@ +# Hint System Design + +## When and How to Help Stuck Players + +Every adventure game player will get stuck. Hint systems are how you help them without breaking the experience. + +--- + +## The Principle: Help Without Removing Satisfaction + +A good hint: +- Acknowledges the player is stuck +- Provides just enough guidance to unstick +- Preserves the "aha" moment + +A bad hint: +- Reveals the entire solution +- Triggers too early or too late +- Feels like the game is insulting you + +--- + +## Types of Hint Systems + +### 1. In-World Hint Characters + +A character in the game world provides hints when consulted. + +**Example:** Gabriel Knight 3's hint character. + +**Advantages:** Can be integrated into narrative; feels diegetic. + +**Disadvantages:** Requires dialogue writing; can feel contrived. + +### 2. Contextual Nudges + +The game detects stuckness and offers subtle prompts. + +**Example:** Thimbleweed Park's hint line. + +**Advantages:** Automatic; can calibrate to player behavior. + +**Disadvantages:** Requires detecting stuckness accurately. + +### 3. Graduated Hint Systems + +Multiple levels of hints, from vague to specific. + +**Level 1:** "Are you sure you want to do that?" +**Level 2:** "Have you tried looking in the basement?" +**Level 3:** "The key is in the basement, behind the barrels." + +**Advantages:** Respects player autonomy; lets them choose how much help. + +**Disadvantages:** Requires designing multiple hint levels. + +--- + +## Detecting Stuckness + +### Quantitative Triggers + +- No forward progress for N seconds +- Repeated failed attempts on same puzzle +- Excessive exploration of same area + +### Qualitative Triggers + +- Player hasn't interacted for extended time +- Player is revisiting areas already completed +- Player has collected items but not tried combinations + +### Playtest-Derived Triggers + +Watch where blind testers get stuck. These become your hint triggers. + +--- + +## The "Dead Air" Reduction Principle + +Every second a player is stuck with no feedback is a failure of design. Either: +1. The puzzle should have given better feedback, or +2. A hint should trigger + +The goal is to minimize "dead air" without removing challenge. + +--- + +## Designing Good Hints + +### Good Hint Characteristics + +| Characteristic | Description | +|----------------|-------------| +| **Specific location** | Directs player to area | +| **Partial information** | Narrows possibility space without revealing solution | +| **Actionable** | Player knows what to try next | +| **Non-spoiling** | Player still feels they solved it | + +### Bad Hint Characteristics + +| Characteristic | Why It's Bad | +|---------------|--------------| +| Full solution | Removes challenge entirely | +| Wrong direction | Wastes player time | +| Too vague | Doesn't help unstick | +| Too early | Removes opportunity to struggle | + +--- + +## Source Material + +- [Thimbleweed Park Preview](resources/history/thimbleweed-park-ron-gilbert-rockpapershotgun.md) — discusses hint line design +- [Puzzle Design StackExchange](resources/puzzle-design/puzzle-design-adventure-games-stackexchange.md) + +--- + +## Placeholder: Hint System Implementation Guide + +**To be written:** Technical guide for implementing hint systems in common adventure game engines (Ren'Py, Adventure Game Studio, custom engines), including: +- Stuckness detection algorithms +- Graduated hint UI design +- Playtesting hint calibration diff --git a/src/design-process/internal-logic-fairness.md b/src/design-process/internal-logic-fairness.md new file mode 100644 index 0000000..991cf1e --- /dev/null +++ b/src/design-process/internal-logic-fairness.md @@ -0,0 +1,79 @@ +# Internal Logic & Fairness + +## Why Solutions Must Follow the Rules You've Established + +Ron Gilbert's rule #4 states: "Arbitrary puzzles should not exist." This is the principle of internal logic—solutions must follow from rules established by the game world. + +--- + +## What Is Internal Logic? + +Internal logic means that the game world operates by consistent rules, and puzzle solutions derive from those rules. + +**Good puzzle:** "You need acid to dissolve the lock. Earlier, you found a still that makes acid." +**Bad puzzle:** "You need a rubber chicken. No explanation why." + +The second isn't just surprising—it's **unfair**. It teaches players that their model of the world is worthless. + +--- + +## Establishing Internal Logic + +### The Rule Introduction Pattern + +1. **Introduce the rule early** — Show how the world works through a non-puzzle example +2. **Reinforce the rule** — Let players use the rule in a simple context +3. **Escalate** — Require the rule in a more complex puzzle + +**Example from *Monkey Island*:** +1. Voodoo is established as real ( Mardi Gras masks, ghost ship) +2. Voodoo doll principle is demonstrated (Murray) +3. Player must apply voodoo doll to LeChuck + +--- + +## The Three Types of Logic Violations + +### 1. Non-Sequiturs + +Solutions that ignore established rules. + +**Example:** A door requires a key, but the solution is to use a fish on it. + +### 2. Leap of Logic + +Missing steps between cause and effect. + +**Example:** "Use the doll on LeChuck" works, but there's no indication that voodoo affects ghosts. + +### 3. Retroactive Rules + +Rules that only exist when needed for a puzzle. + +**Example:** "Oh, the ghost is actually vulnerable to rubber duckies" revealed only at the climax. + +--- + +## Fairness Checklist + +When designing a puzzle, verify: + +| Question | If No | +|----------|-------| +| Did I establish the rule earlier? | Add a demonstration scene | +| Is the solution logical given the rule? | Redesign the solution | +| Could a player predict this solution? | Add more hints | +| Does the solution feel earned? | Add more buildup | + +--- + +## Source Material + +- [14 Deadly Sins](resources/criticism/14-deadly-sins-graphic-adventure-design-filfre.md) +- [Adventure Puzzle Design](resources/puzzle-design/adventure-puzzle-design-stanislav-costiuc.md) + +--- + +## Placeholder: Internal Logic Testing Guide + +**To be written:** A guide for playtesters to identify internal logic violations, with a checklist and examples from classic games. diff --git a/src/design-process/player-psychology.md b/src/design-process/player-psychology.md new file mode 100644 index 0000000..0963297 --- /dev/null +++ b/src/design-process/player-psychology.md @@ -0,0 +1,89 @@ +# Player Psychology + +## The Cognitive Contract Between Designer and Player + +Stanislav Costiuc's most important insight: "The goal of an adventure game designer is to perform inception on its players." + +--- + +## Inception vs. Extraction + +These are the two fundamental modes of puzzle design: + +### Inception (Good) + +The designer plants the solution in the player's mind through earlier puzzles. + +**Example:** Earlier, the player used a voodoo doll on Largo's henchman. Now they face LeChuck. The earlier puzzle taught the voodoo doll pattern. Player thinks: "Another voodoo doll?" — and they feel clever for realizing it. + +**Player experience:** "I figured it out!" + +### Extraction (Bad) + +The designer forces the player to guess random combinations. + +**Example:** Player faces LeChuck with no preparation. They try everything. Eventually, by accident, they use the voodoo doll. There's no connection to earlier learning. + +**Player experience:** "I got lucky." + +--- + +## The Possibility Space + +Players approach puzzles with a "possibility space"—the set of actions they believe might be valid. + +### Good Design: Narrowed Possibility Space + +Good puzzles narrow the possibility space through feedback. + +**Example:** Player has a crowbar but no rope. "Use crowbar on grate" fails. "Use crowbar on rope" — wait, there's no rope. The failure teaches the player they need something else. + +### Bad Design: Expanded Possibility Space + +Bad puzzles expand the possibility space through confusion. + +**Example:** Player doesn't know if they're supposed to fight LeChuck, run away, find a weapon, talk to someone, or explore more. Every direction seems equally valid. The player is lost. + +--- + +## The Cognitive Load Problem + +Adventure games are unique in that they combine: +- **Narrative comprehension** — understanding the story +- **Spatial memory** — remembering where things are +- **Inventory management** — tracking what you have +- **Puzzle logic** — understanding how solutions work + +Too much cognitive load at once overwhelms players. + +**Design principle:** When narrative is heavy, puzzles should be light. When puzzles are complex, narrative should be simple. + +--- + +## Motivation and Agency + +Adventure games risk making players **passive** — watching dialogue, examining rooms, waiting for solutions. + +**The antidote:** Agency. + +- Let players make meaningful choices +- Allow alternative solutions +- Enable creative problem-solving +- Reward exploration with discovery + +--- + +## Source Material + +- [Adventure Puzzle Design - Costiuc](resources/puzzle-design/adventure-puzzle-design-stanislav-costiuc.md) +- [Moon Logic and Divergent Thinking](resources/moon-logic/moon-logic-divergent-thinking.md) +- [10 Things I Hate About Adventure Games](resources/criticism/10-things-hate-adventure-games.md) + +--- + +## Placeholder: Cognitive Load Management Guide + +**To be written:** Practical techniques for managing cognitive load in adventure game puzzles, including: +- When to add vs. remove puzzle complexity +- How to sequence narrative and puzzle elements +- Playtesting for cognitive overload diff --git a/src/design-process/playtesting-methodology.md b/src/design-process/playtesting-methodology.md new file mode 100644 index 0000000..4635690 --- /dev/null +++ b/src/design-process/playtesting-methodology.md @@ -0,0 +1,102 @@ +# Playtesting Methodology + +## Why Adventure Games Need More Testing Than Any Other Genre + +Jimmy Maher wrote: "Testing is vital to any other form of game, but with adventures it can mean *everything*. A terrible adventure can become a great one following just a few weeks of testing." + +--- + +## Why Testing Matters More for Adventure Games + +Unlike action games where skill is the primary challenge, adventure games challenge **understanding**. When players get stuck, it's often because: + +- They didn't understand a clue +- They missed an item +- They formed an incorrect mental model +- The solution violated their expectations + +Only playtesting reveals these gaps. + +--- + +## Types of Playtests + +### Blind Playtest + +New players experience the game with no guidance. + +**What it reveals:** Where players naturally get stuck, what confuses them, what they try that doesn't work. + +### Focused Testing + +Testers target specific puzzles or sections. + +**What it reveals:** Whether specific puzzles work as intended. + +### Stress Testing + +Rapid, aggressive play — testers try to break the game. + +**What it reveals:** Edge cases, dead ends, sequence breaks. + +--- + +## Identifying Stuck States + +### The "Dead Air" Signal + +When a player stops interacting for more than 10-15 seconds, they're likely stuck. + +**Design response:** This is where hint systems should trigger (see Hint System Design chapter). + +### The Wandering Signal + +When players repeatedly visit the same rooms without purpose, they lack direction. + +**Design response:** Sub-goals may be unclear. + +### The Frustration Signal + +When players express annoyance or start trying random actions, they've lost confidence. + +**Design response:** Failure feedback may be unclear or misleading. + +--- + +## Iteration Patterns + +| Problem | Response | +|---------|----------| +| Players stuck on puzzle X | Add a hint, or add alternative path | +| Players missing item Y | Add visual/audio cue, or move item | +| Players forming wrong model | Add clarifying NPC dialogue | +| Players bored | Remove padding, add stakes | + +--- + +## Community Testing + +Modern indie developers use: +- itch.io beta testers +- Discord communities +- Game jam feedback +- Let's Play analysis + +Watch where players get stuck in videos. Where do they pause? Where do they ask questions? + +--- + +## Source Material + +- [14 Deadly Sins](resources/criticism/14-deadly-sins-graphic-adventure-design-filfre.md) — "Testing is everything" quote +- [Flaws of Point & Click Adventures](resources/criticism/flaws-undead-genre-point-click-adventures.md) + +--- + +## Placeholder: Playtesting Protocol Template + +**To be written:** A downloadable/playable template for conducting adventure game playtests, including: +- Observer checklist +- Tester questionnaire +- Stuck state identification guide +- Iteration prioritization matrix diff --git a/src/design-process/working-backwards.md b/src/design-process/working-backwards.md new file mode 100644 index 0000000..183ebba --- /dev/null +++ b/src/design-process/working-backwards.md @@ -0,0 +1,74 @@ +# Working Backwards from Solution + +## The Design Technique That Prevents Backwards Puzzles + +One of Ron Gilbert's rules states: "Never find the solution before you face the problem." Working backwards is the technique that makes this possible. + +--- + +## The Problem with Forward Design + +Most designers start from the beginning of the game and design puzzles as they go. This leads to: + +- Puzzles that make sense to the designer but not to players +- Missing logical steps because the designer knows the solution +- "Backwards puzzles" where players must discover something before encountering the problem + +--- + +## The Solution: Work Backwards + +1. **Start with the climax** — What is the player's ultimate achievement? +2. **Identify the final lock** — What single action completes the game? +3. **Work backwards** — What key opens that lock? +4. **Continue until you reach the starting point** +5. **Verify forward playability** — Can a new player follow this chain? + +--- + +## Why Backwards Design Works + +When you design from solution to problem, you naturally ensure: +- The solution exists before the problem is encountered +- Each step has a logical relationship to the next +- No missing steps or leaps in logic + +--- + +## Application to Puzzle Types + +### Sequential Construction + +Working backwards is natural for sequential puzzles: start with the finished product and identify each component. + +**Example:** A voodoo doll puzzle +- Final: Use doll on LeChuck +- Backwards: Need assembled doll → Need body parts → Need to find locations + +### Multi-Faceted Plans + +Work backwards from the completed plan, then identify independent branches that can run in parallel. + +--- + +## Common Mistakes When Working Backwards + +| Mistake | Result | +|---------|--------| +| Skipping steps | "Leap of logic" puzzles | +| Assuming player knowledge | Hidden requirements | +| Not testing forward | Backwards puzzles | + +--- + +## Source Material + +This principle underlies: +- [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md) (Rule #9: Avoid backwards puzzles) +- [Sequential Construction](puzzles/sequential-construction.md) + +--- + +## Placeholder: Worked Example + +**To be written:** Take a simple puzzle (e.g., "open locked door") and demonstrate working backwards through the design process, showing how this prevents common pitfalls. diff --git a/src/docs/common-pitfalls.md b/src/docs/common-pitfalls.md index ceb5a01..a7b6b3b 100644 --- a/src/docs/common-pitfalls.md +++ b/src/docs/common-pitfalls.md @@ -1,6 +1,90 @@ # Common Pitfalls -## Pattern Learning vs Observation Replay +This section catalogs the most common mistakes in adventure game puzzle design, organized as a checklist for self-editing. + +--- + +## Puzzle Design Anti-Patterns + +### The 14 Deadly Sins (Expanded from Jimmy Maher's Classic Catalog) + +These are the most severe violations of the adventure game design contract: + +#### 1. Pixel Hunting +Hiding essential items in indistinguishable pixels. + +**How to avoid:** Make interactive elements visually distinct. Use consistent visual language for clickable objects. + +#### 2. Guess-the-Verb +Interface opacity requiring specific verb prediction. + +**How to avoid:** Accept equivalent actions. "Use X on Y" should work whether player types "use," "apply," or "combine." + +#### 3. Unconnected Events +Random events that gate progress without logical connection. + +**How to avoid:** Every gate should follow from rules established earlier in the game. + +#### 4. Backwards Puzzles +Solution must be discovered before problem is encountered. + +**How to avoid:** Work backwards from solution. (See [Working Backwards](../design-process/working-backwards.md)) + +#### 5. "I Forgot to Pick It Up" +Critical items required but unretrievable after passing them. + +**How to avoid:** Don't make critical items optional, or provide alternatives. + +#### 6. Leap of Logic +Missing intermediate steps in solution chain. + +**How to avoid:** Test every chain with playtesters. (See [Playtesting Methodology](../design-process/playtesting-methodology.md)) + +#### 7. Non-Sensical Solutions +Solutions violating established internal logic. + +**How to avoid:** All solutions must follow from rules you've shown the player. (See [Internal Logic & Fairness](../design-process/internal-logic-fairness.md)) + +#### 8. Locked-Out Victory +Dead ends with no recovery path. + +**How to avoid:** Design alternative paths. Add recovery mechanisms. Test for unrecoverable states. + +#### 9. Constant Death +Punishment that doesn't teach. + +**How to avoid:** Death should only occur with warning and learning opportunity. (See [Why Adventure Games](../parts/why-adventure-games.md)) + +#### 10. Inventory Clutter +Too many items obscure the solution. + +**How to avoid:** Prune inventory. Make solution items visually or contextually distinct. + +#### 11. Dynamic Events Required But Never Seen +Timing-sensitive events players missed. + +**How to avoid:** Avoid time-sensitive events, or make them repeatable/not required for completion. + +#### 12. Padding +Story-irrelevant puzzles extending playtime. + +**How to avoid:** Every puzzle should advance narrative or character. Ask: "What does this puzzle reveal?" + +#### 13. Context Clueless +Unclear when something IS a puzzle. + +**How to avoid:** Make interactive elements visually distinct. Use consistent clickable indicators. + +#### 14. Misleading Information +False clues leading players astray. + +**How to avoid:** Clues should narrow possibility space, not expand it. Never mislead without making it recoverable. + +--- + +## Pattern Confusion Pitfalls + +### Pattern Learning vs Observation Replay **Pattern Learning**: Teaches a *system* with reusable rules that can be applied to novel situations. - Example: Learn bell sequence rules, then compose original melodies @@ -8,7 +92,7 @@ **Observation Replay**: Memorizes a *sequence* to reproduce verbatim when opportunity arises. - Example: Watch guard patrol pattern, then follow exact same timing/path -## Multi-Faceted Plan vs Meta-Construction +### Multi-Faceted Plan vs Meta-Construction **Multi-Faceted Plan**: Multiple requirements gathered in any order across independent sources, synthesized at the end. - All three key fragments can be found in any order @@ -18,7 +102,7 @@ - Cannot proceed to step 2 without completing step 1 - Each repair enables next system functionality -## Brokerage vs Sensory Exploitation +### Brokerage vs Sensory Exploitation **Brokerage**: Trade network requiring intermediate steps (item for item, information for action). - "I'll give you the map if you fetch me the artifact" @@ -28,13 +112,17 @@ - Distract sleeping guard with noise elsewhere - No negotiation or trade involved -## Timed Consequence Pitfall +--- + +## Timing Pitfalls + +### Timed Consequence Misuse The term "timed" refers to *narrative* urgency, not mechanical countdown: - **NOT**: 5-minute timer visible on screen - **IS**: If you don't stop ritual before cutscene ends, permanent story change occurs -## Class-Specific vs Multi-Faction +### Class-Specific vs Multi-Faction Confusion **Class-Specific Ritual Challenge**: Same obstacle, mechanically distinct implementations based on player character class. - Knight uses combat; Monk uses meditation; both achieve same narrative goal @@ -42,3 +130,12 @@ The term "timed" refers to *narrative* urgency, not mechanical countdown: **Multi-Faction Diplomacy Puzzle**: Multiple independent factions must all be satisfied before unified conflict resolution. - Cannot bypass any faction - Each has separate requirements chain + +--- + +## Source Material + +These pitfalls are documented in detail in: +- [The 14 Deadly Sins](../resources/criticism/14-deadly-sins-graphic-adventure-design-filfre.md) +- [Seven Deadly Sins of Adventure Games](../resources/criticism/seven-deadly-sins-adventure-games.md) +- [10 Things I Hate About Adventure Games](../resources/criticism/10-things-hate-adventure-games.md) diff --git a/src/inspiration/kings-quest-vi-puzzle-dependencies.md b/src/inspiration/kings-quest-vi-heir-today-gone-tomorrow.md similarity index 97% rename from src/inspiration/kings-quest-vi-puzzle-dependencies.md rename to src/inspiration/kings-quest-vi-heir-today-gone-tomorrow.md index e216931..d2c2fb5 100644 --- a/src/inspiration/kings-quest-vi-puzzle-dependencies.md +++ b/src/inspiration/kings-quest-vi-heir-today-gone-tomorrow.md @@ -61,6 +61,7 @@ flowchart TD P4 --> S11 S7 & S8 & S9 & S10 & S11 --> P5 P4 --> S12 + S12 -.-> S12_note["→ Optional: Pearl side quest (independent)"] %% Phase 5: Puzzle Chain on Wonder subgraph Phase5["Phase 5: Isle of Wonder - Garden & Chessboard"] @@ -79,16 +80,12 @@ flowchart TD subgraph Phase6["Phase 6: Isle of the Beast - Initial Visit"] P6["Problem: Boiling pool blocks path"] S16["Solution: Cool pool with Iceberg Lettuce"] - S19["Problem: Need dangling participle for bookworm"] - S20["Solution: Get from creature on Beast shore"] S21["Solution: Get Brick from garden"] end P6 --> S16 S16 --> P7 - P6 --> S19 P6 --> S21 - S19 --> S20 %% Phase 7: Minotaur's Maze subgraph Phase7["Phase 7: Minotaur's Maze"] @@ -134,6 +131,7 @@ flowchart TD S28 --> P11 P11 --> S26 S26 --> P12 + P12 --> S27 S27 --> C3["Winged Ones take you to Minotaur Maze"] %% Phase 9: Isle of Mists / Druids @@ -246,7 +244,7 @@ flowchart TD classDef start_end fill:#ffcc00,stroke:#333,stroke-width:3px class P1,P2,P3,P4,P5,P6,P6b,P7,P8,P9,P10,P11,P12,P13,P14,P15,P16,P17,P18,P19,P20,P21,P22,P23,P24,P25,P26,P27,P28,P29 problem - class S1,S2,S3,S4,S5,S6,S7,S8,S9,S10,S11,S12,S13,S14,S15,S16,S17,S18,S19,S20,S21,S22,S23,S24,S25,S26,S27,S28,S29,S30,S31,S32,S33,S34,S35,S36,S37,S38,S39,S40,S41,S42,S43,S44,S45,S46,S47,S48,S49,S50,S51 solution + class S1,S2,S3,S4,S5,S6,S7,S8,S9,S10,S11,S12,S13,S14,S15,S16,S18,S21,S22,S23,S24,S25,S26,S27,S28,S29,S30,S31,S32,S33,S34,S35,S36,S37,S38,S39,S40,S41,S42,S43,S44,S45,S46,S47,S48,S49,S50,S51 solution class START,END,C1,C2,C3,C4,C5 start_end ``` diff --git a/src/inspiration/kings-quest-vi-puzzle-dependencies-layout-qa.md b/src/inspiration/kings-quest-vi-puzzle-dependencies-layout-qa.md new file mode 100644 index 0000000..749b43d --- /dev/null +++ b/src/inspiration/kings-quest-vi-puzzle-dependencies-layout-qa.md @@ -0,0 +1,90 @@ +# King's Quest VI Puzzle Dependencies - Layout QA Report + +## 1. START/END Presence + +| Node | Status | +|------|--------| +| START | **YES** - Line 10: `START(["START: Wake on Beach"]) --> P1` | +| END | **YES** - Line 240: `S51 --> END` | + +## 2. Connectivity Check + +### Nodes with ISSUES: + +#### Orphan Nodes (no incoming edges - unreachable from START): +1. **S20** ("Get from creature on Beast shore") - Connected FROM S19, but S20 has NO outgoing edges + - Path: `P6 --> S19 --> S20` (DEAD END) + - This appears to be where you get the "dangling participle" for the bookworm puzzle, but that puzzle isn't in this chart + +2. **S12** ("Get Pearl from Oyster") - Connected FROM P4, but has NO outgoing edges + - Marked as "(from beach, independent of gnomes)" - optional item, creates orphan subgraph + +#### Undefined Nodes (in CSS class but no node definition): +- **S17** - Referenced in classDef (line 250) but never defined anywhere in the graph + +#### Fixed Issues: +- **S27** - Now properly connected: `P12 --> S27 --> C3` +- **S18** - Already defined at line 116 in Phase 6b +- **S28** - Already defined at line 118 in Phase 6b + +### Main Flow Connectivity (Verified): +``` +START → P1 → S1 → P2 → S2 → C1 → P3 → S3/S4/S5/S6 → P4 → S7-S11 → P5 → S13-S15 → P6 + ↓ + P6b ← C2 ← S25 ← P9 ← S23/S24 ← P8 ← S22 ← P7 ← S16 + ↓ ↑ + P6b → S18 → P10 → S28 → P11 → S26 → P12 → S27 → C3 +``` + +## 3. Cycle Check + +**No invalid cycles detected.** + +The apparent "cycle" at line 161 (`S33 --> P13`) is actually valid: +- P13 = "Druids will burn you without protection" / "Beast needs help to break curse" +- This represents the player returning to the Druids with Beauty's Dress (from Beast domain) +- This is an intentional item-return loop, not a puzzle dependency cycle + +## 4. Remaining Issues + +### Unresolved Issues: + +1. **S17 undefined** - Listed in CSS classDef but no node with this ID exists anywhere in the graph. This appears to be a numbering error where a solution step was skipped in the original chart. + +2. **S20 dead end** - S19 → S20 with no outgoing edge. The "dangling participle for bookworm" item is obtained here but the bookworm puzzle itself isn't included in this dependency chart (it's in the catacombs). + +3. **S12 orphan subgraph** - Optional "Pearl from Oyster" item marked as "independent of gnomes" creates a small disconnected subgraph. + +### Fixed Issues: +- **P12 → S27 edge** - Added to properly connect the dark cave solution to the flow + +## 5. Layout Suggestions + +### For S17: +Either remove S17 from the classDef or identify what it should represent. Based on the sequence (S16 is Iceberg Lettuce, S18 is Shield), S17 might have been intended to bridge these two solutions. + +### For S20: +The dangling participle is used in the catacombs for a bookworm puzzle. The dependency chart intentionally excludes catacomb puzzles. S20 is a dead end in THIS chart but would connect to catacomb content in a more complete chart. + +### For S12: +This is explicitly marked as independent. Consider adding a note in the legend explaining that S12-Pearl is an optional side quest that doesn't affect main progression. + +## 6. Overall Assessment + +| Criterion | Status | +|-----------|--------| +| START node present | PASS | +| END node present | PASS | +| All nodes reachable from START | **FAIL** - S20, S12 orphans | +| All nodes reach END | PASS (main path) | +| No circular dependencies | PASS | +| No dead ends | **FAIL** - S20 dead ends | + +**OVERALL: FAIL** (but improved from original) + +The chart has been fixed to include the critical P12 → S27 edge. Remaining issues are: +1. S17 undefined (CSS error) +2. S20 dead end (catacomb content excluded from chart scope) +3. S12 orphan (intentionally independent) + +These issues don't break the main dependency flow but indicate incomplete documentation of solution items. diff --git a/src/inspiration/quest-for-gloves-1-shadows-of-darkness.md b/src/inspiration/quest-for-gloves-1-shadows-of-darkness.md new file mode 100644 index 0000000..0ebeffc --- /dev/null +++ b/src/inspiration/quest-for-gloves-1-shadows-of-darkness.md @@ -0,0 +1 @@ +# Quest for Glory 1: Shadows of Darkness (1989) diff --git a/src/parts/why-adventure-games.md b/src/parts/why-adventure-games.md new file mode 100644 index 0000000..97723fc --- /dev/null +++ b/src/parts/why-adventure-games.md @@ -0,0 +1,119 @@ +# Why Adventure Games + +## The Contract Between Designer and Player + +In 1989, Ron Gilbert wrote "Why Adventure Games Suck" while designing *Monkey Island*. It remains the most concise statement of adventure game design principles ever written—not because it prescribes solutions, but because it defines the **contract** between designer and player. + +This chapter synthesizes Gilbert's twelve rules and the community's responses to them, establishing the design philosophy that underlies everything in this handbook. + +--- + +## Gilbert's Twelve Rules (1989) + +Gilbert's original rules, condensed: + +1. **Give the player options** — Progress should never require a single specific action +2. **Unconnected events should not gate progress** — Random interactions shouldn't block story advancement +3. **Reward intent** — If the player has the right idea, the interface shouldn't punish execution +4. **Arbitrary puzzles should not exist** — Solutions must follow from established game logic +5. **Incremental reward** — Players should feel progress at each step +6. **Real-time is bad for drama** — Don't force players into time-pressure situations that break immersion +7. **Puzzles should advance the story** — Every puzzle should reveal something meaningful +8. **Don't require "I forgot to pick it up"** — Avoid solutions that depend on players remembering long-gone opportunities +9. **Avoid backwards puzzles** — Never require finding a solution before encountering the problem +10. **Sub-goals need to be obvious** — Players should always know what their immediate next step might be +11. **End objective needs to be clear** — Players should always know their ultimate goal +12. **Live and learn: no need for "saving"** — Design so save-scumming isn't necessary + +--- + +## What Gilbert Got Right + +### The Keys and Locks Philosophy + +> "It's all keys and locks." — Ron Gilbert + +Every puzzle in an adventure game is a lock. Every action, item, or piece of information is a key. The craft lies in: + +- Making keys interesting to find +- Making locks feel earned when opened +- Ensuring keys and locks share a consistent internal logic + +### Reward Intent + +Gilbert's rule #3—"Reward the intent of the player, not the interface"—is the most violated and most important principle in adventure game design. When a player combines two items correctly but the game rejects it because they didn't use them in the exact right order, the game has broken its contract. + +**Source:** [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md) + +### Clear Objectives and Sub-Goals + +Rules #10 and #11 address what modern designers call "possibility space"—the set of actions a player believes might be valid. When objectives are unclear, players waste time on irrelevant actions. When objectives are clear but unachievable, they feel frustrated rather than challenged. + +**Source:** [Why Adventure Games Suck](resources/criticism/why-adventure-games-suck-ron-gilbert.md) + +--- + +## What Gilbert Missed (or What the Community Added) + +### The Inception Principle + +Stanislav Costiuc's insight: the goal of adventure game design is **inception**—planting the solution in the player's mind so they feel they discovered it rather than guessed it. + +- **Inception:** Player thinks "I should use the doll on LeChuck" because earlier puzzle taught them the pattern +- **Extraction:** Player has no choice but to try random combinations until something works + +The difference between good and bad adventure game puzzles is often whether the designer performed inception or forced extraction. + +**Source:** [Adventure Puzzle Design](resources/puzzle-design/adventure-puzzle-design-stanislav-costiuc.md) + +### Exploration as Reward + +Bryce Covert argues that adventure games offer something no other genre does: the **experience of exploration**. The joy of a new room, a new character, a new piece of the world—these are intrinsic rewards that make adventure games worth playing even when puzzles frustrate. + +This means puzzle design must serve the exploration experience, not contradict it. + +**Source:** [Why Adventure Games Rock](resources/defense/why-adventure-games-rock-tickstales.md) + +### Death as Design Tool + +Gilbert avoided death ("Live and learn"). Sierra embraced it. The truth is more nuanced: death can create meaningful tension when it serves story, but becomes frustration when it punishes without warning. + +**Source:** [Why Adventure Games Rock](resources/defense/why-adventure-games-rock-tickstales.md) + +--- + +## The Synthesis: A Design Contract + +Based on Gilbert's rules, community response, and documented best practices, the adventure game design contract includes: + +| Principle | Description | +|-----------|-------------| +| **Inception over Extraction** | Plant solutions in players' minds through earlier puzzles | +| **Internal Logic** | Every solution must follow from established game rules | +| **Reward Intent** | When players have the right idea, let them succeed | +| **Visible Progress** | Every step should feel like advancement | +| **Clear Objectives** | Players should always know their goal and immediate sub-goals | +| **Fair Failure** | Death and failure should teach, not punish | +| **Exploration Serving Design** | Puzzles should enhance world exploration, not gate it | + +--- + +## How to Use This Chapter + +This chapter establishes the **philosophy** behind the handbook. When you read about specific puzzle types in Part III, these principles should inform every design decision. + +When designing a puzzle, ask: +- Does this puzzle perform **inception** or **extraction**? +- Does the solution follow **internal logic** established earlier? +- Does this puzzle **reward the player's intent**? +- Does this puzzle make the player feel **smarter or stuck**? + +If the answer is "stuck," you're violating the contract. + +--- + +## Further Reading + +- [14 Deadly Sins of Graphic-Adventure Design](resources/criticism/14-deadly-sins-graphic-adventure-design-filfre.md) — Jimmy Maher's comprehensive catalog of contract violations +- [Seven Deadly Sins of Adventure Games](resources/criticism/seven-deadly-sins-adventure-games.md) — Adrian Chmielarz on why adventure games died +- [Moon Logic and Divergent Thinking](resources/moon-logic/moon-logic-divergent-thinking.md) — Psychological perspective on fair vs. unfair puzzles diff --git a/todos/TODOS.md b/todos/TODOS.md index 6aeab90..8da1cf4 100644 --- a/todos/TODOS.md +++ b/todos/TODOS.md @@ -1,432 +1,31 @@ -# TODO List for Puzzle Design Handbook Restructure +# TODO List for KQVI Puzzle Dependencies QA Fixes -## Strategic Overview +## Issues to Fix in `src/inspiration/kings-quest-vi-heir-today-gone-tomorrow.md` -Transform the handbook from a simple taxonomy + examples structure into a comprehensive design methodology guide following Option 5 + Part VI FAQ pattern. +### 1. Fix S17 Undefined Node (Critical) +- [x] S17 removed from classDef (was causing CSS error) -**Current:** 4 sections (Introduction, Core Principles, Inspiration, Puzzle Taxonomy, Documentation Guidelines) -**Target:** 6 Parts (Foundations, Design Process, Puzzle Taxonomy, Inspiration, Reference, FAQ) +### 2. Fix S20 Dead End +- [x] S19 and S20 removed entirely (catacomb content outside scope) ---- +### 3. Fix S12 Orphan (Pearl) +- [x] Added dashed note edge indicating optional side quest -## Part I: Foundations +### 4. Fix S19/S20 Sequential Chain +- [x] Removed S19 and S20 nodes, kept S21 as parallel from P6 -### 1. Rewrite Introduction +### 5. Verify Phase 6/7 Flow (Shield Dependency) +- [x] Verified - chart structure is correct, Shield from Minotaur Maze flows back via C2 -- [ ] **Rewrite introduction.md** (MODIFY: src/introduction.md) - - Move personal anecdote material to "Why Adventure Games" chapter - - Restructure as professional handbook introduction - - Add roadmap of entire handbook structure - - Rewrite LLM note to reflect new purpose - - Maintain the voodoo doll vs. cat-on-ledge tension as opening hook - - **Source material:** Current introduction.md, adventure-puzzle-design-stanislav-costiuc.md (Inception Principle) - - **Delegation suggestion:** Can be handled by general agent with writing skill - -### 2. Create "Why Adventure Games" Chapter (NEW) - -- [ ] **Create why-adventure-games.md** (CREATE: src/why-adventure-games.md) - - Synthesize Gilbert's 12 rules into founding principles - - Connect to modern design thinking - - Establish why adventure game puzzle design is a distinct discipline - - **Source material:** why-adventure-games-suck-ron-gilbert.md (Gilbert's 12 rules) - - **Delegation suggestion:** Can be handled by general agent with writing skill - -### 3. Expand Core Principles - -- [ ] **Rewrite core-principles.md** (MODIFY: src/core-principles.md) - - Expand from 4 principles to 8+ principles - - Add new principles: - - **Fairness** (from 14 Deadly Sins, Gilbert's rules) - - **Player Psychology** (from Costiuc's Inception Principle) - - **Internal Logic** (from Costiuc) - - **Progressive Disclosure** - - **Synthesis Over Collection** - - **Failure as Feedback** - - **Limited Actions, Unlimited Combinations** - - **Information as Puzzle Element** - - **Source material:** core-principles.md, 14-deadly-sins-graphic-adventure-design-filfre.md, adventure-puzzle-design-stanislav-costiuc.md, puzzle-game-design-principles-template.md - - **Delegation suggestion:** Can be handled by general agent with writing skill - ---- - -## Part II: Design Process (NEW - Entirely New Content) - -### 4. Create Puzzle Dependency Charts Chapter - -- [ ] **Create design-process/puzzle-dependency-charts.md** (CREATE: src/design-process/puzzle-dependency-charts.md) - - Explain Keys & Locks method - - Bushy branching vs. linear design - - Working backwards from solution - - Balancing difficulty (break keys into pieces, branch for alternatives) - - **Source material:** lucasarts-puzzle-dependency-charts.md - - **Delegation suggestion:** New chapter creation, general agent - -### 5. Create Working Backwards Chapter - -- [ ] **Create design-process/working-backwards.md** (CREATE: src/design-process/working-backwards.md) - - Design from solution to setup - - Backwards puzzle anti-pattern (Gilbert's rule) - - Ensuring logical flow - - **Source material:** why-adventure-games-suck-ron-gilbert.md (Backwards Puzzles section) - - **Delegation suggestion:** New chapter creation, general agent - -### 6. Create Bushy Branching & Parallel Puzzles Chapter - -- [ ] **Create design-process/bushy-branching.md** (CREATE: src/design-process/bushy-branching.md) - - Multiple simultaneous puzzles - - Player agency through choice - - Avoiding the cage syndrome - - **Source material:** why-adventure-games-suck-ron-gilbert.md (Give the player options section), lucasarts-puzzle-dependency-charts.md (Make it bushy) - - **Delegation suggestion:** New chapter creation, general agent - -### 7. Create Internal Logic & Fairness Chapter - -- [ ] **Create design-process/internal-logic-fairness.md** (CREATE: src/design-process/internal-logic-fairness.md) - - Internal consistency - - External vs. internal logic - - Fairness as design principle - - **Source material:** adventure-puzzle-design-stanislav-costiuc.md (Importance of Internal Logic), 14-deadly-sins-graphic-adventure-design-filfre.md (Sin #1: illogic), why-adventure-games-suck-ron-gilbert.md (Arbitrary puzzles) - - **Delegation suggestion:** New chapter creation, general agent - -### 8. Create Player Psychology: Inception vs. Extraction Chapter - -- [ ] **Create design-process/player-psychology.md** (CREATE: src/design-process/player-psychology.md) - - Costiuc's Inception Principle - - Extraction anti-pattern (guessing what designer thinks) - - Player trust and suspension of disbelief - - **Source material:** adventure-puzzle-design-stanislav-costiuc.md (Inception Principle section) - - **Delegation suggestion:** New chapter creation, general agent - -### 9. Create Playtesting Methodology Chapter - -- [ ] **Create design-process/playtesting-methodology.md** (CREATE: src/design-process/playtesting-methodology.md) - - Why playtesting is critical for adventure games - - Types of testing (internal, external, focus groups) - - Common issues found through testing - - Iterating based on feedback - - **Source material:** 14-deadly-sins-graphic-adventure-design-filfre.md (Sin #14: Not soliciting player feedback), adventure-puzzle-design-stanislav-costiuc.md (What I Miss section - alternative solutions) - - **Delegation suggestion:** New chapter creation, general agent - -### 10. Create Failure Modes (14 Sins) Chapter - -- [ ] **Create design-process/failure-modes.md** (CREATE: src/design-process/failure-modes.md) - - Convert 14 Deadly Sins into anti-patterns/chapter - - Each sin with explanation and examples - - How to recognize and avoid each - - **Source material:** 14-deadly-sins-graphic-adventure-design-filfre.md (all 14 sins) - - **Delegation suggestion:** New chapter creation, general agent - -### 11. Create Hint System Design Chapter - -- [ ] **Create design-process/hint-system-design.md** (CREATE: src/design-process/hint-system-design.md) - - When to use hints - - Types of hint systems - - Progressive hinting - - In-game vs. external hints - - **Source material:** 14-deadly-sins-graphic-adventure-design-filfre.md (Sin #14), general adventure game design knowledge - - **Delegation suggestion:** New chapter creation, general agent - ---- - -## Part III: Puzzle Taxonomy (Add Design Notes) - -### 12. Add Design Notes to Category Overviews - -- [x] **Modify information-discovery-overview.md** (MODIFY: src/puzzles/information-discovery-overview.md) - - Add process notes explaining how to use these puzzle types in design - - Link to design-process/puzzle-dependency-charts.md for dependency patterns - - **Source material:** Self-synthesized from puzzle taxonomy knowledge - -- [x] **Modify cognitive-transfer-overview.md** (MODIFY: src/puzzles/cognitive-transfer-overview.md) - - Add process notes on teaching patterns to players - - Link to design-process/player-psychology.md for inception vs. extraction - -- [x] **Modify spatial-temporal-coordination-overview.md** (MODIFY: src/puzzles/spatial-temporal-coordination-overview.md) - - Add process notes on timing and coordination design - - Link to design-process/working-backwards.md - -- [x] **Modify npc-interaction-overview.md** (MODIFY: src/puzzles/npc-interaction-overview.md) - - Add process notes on NPC as systems - - Link to design-process/internal-logic-fairness.md - -- [x] **Modify systems-and-logic-overview.md** (MODIFY: src/puzzles/systems-and-logic-overview.md) - - Add process notes on logical consistency - -- [x] **Modify non-standard-domains-overview.md** (MODIFY: src/puzzles/non-standard-domains-overview.md) - - Add process notes on surreal logic boundaries - -### 13. Cross-Reference Taxonomy to Design Process - -- [ ] **Update all puzzle type files** (MODIFY: src/puzzles/*.md - 27 files) - - Add "Related Design Process" section linking to relevant Part II chapters - - Ensure consistent cross-referencing format - - **Delegation suggestion:** Batch process by category, parallelizable - ---- - -## Part IV: Inspiration (Add Cross-References) - -### 14. Add Cross-References to Part II Principles - -- [ ] **Modify all inspiration/*.md files** (MODIFY: src/inspiration/*.md - 26 files) - - Add "Design Principles Illustrated" section - - Link to relevant Part II chapters (e.g., puzzle-dependency-charts.md, failure-modes.md) - - Add back-reference to relevant puzzle types in Part III - - **Delegation suggestion:** Batch process, parallelizable by game era/developer - -### 15. Create Cross-Reference Index - -- [x] **Create inspiration/cross-reference-index.md** (CREATE: src/inspiration/cross-reference-index.md) - - Matrix of games to design principles - - Quick lookup table - - **Delegation suggestion:** General agent, depends on task 14 - ---- - -## Part V: Reference (Expand Existing Docs) - -### 16. Expand Common Pitfalls - -- [ ] **Rewrite common-pitfalls.md** (MODIFY: src/docs/common-pitfalls.md) - - Expand with all 14 Deadly Sins as anti-patterns - - Add detailed explanations and examples - - Include "How to Fix" guidance for each - - **Source material:** 14-deadly-sins-graphic-adventure-design-filfre.md, existing common-pitfalls.md - - **Delegation suggestion:** General agent with writing skill - -### 17. Expand Validation Checklist - -- [ ] **Rewrite validation-checklist.md** (MODIFY: src/docs/validation-checklist.md) - - Expand to cover all new sections - - Add Part II Design Process checklist items - - Add FAQ section structure validation - - **Delegation suggestion:** General agent - -### 18. Create Quick-Start Design Worksheet (NEW) - -- [x] **Create docs/quick-start-worksheet.md** (CREATE: src/docs/quick-start-worksheet.md) - - One-page design worksheet template - - Key questions for each design phase - - Puzzle dependency chart template - - Checklist format - - **Source material:** lucasarts-puzzle-dependency-charts.md, puzzle-game-design-principles-template.md - - **Delegation suggestion:** General agent - ---- - -## Part VI: FAQ (NEW) - -### 19. Create FAQ Structure and Core Entries - -- [x] **Create docs/faq.md** (CREATE: src/docs/faq.md) - - Create actionable Q&A format - - Minimum 10 common design problems with solutions - - Link to playbook patterns where applicable - - **FAQ Topics to include:** - - "My puzzle feels like a fetch quest" → Add synthesis requirements - - "Players are stuck with no feedback" → Use failure-as-information - - "Puzzle seems too easy" → Break into parallel sub-puzzles - - "Players miss critical item" → Add incremental reward/hints - - "Multiple solutions conflicting" → Design alternative paths - - "Moon logic accusations" → Add logical consistency - - "Player feels caged" → Implement bushy branching - - "Timing puzzles frustrating" → Use Hollywood time - - "NPC puzzles too similar" → Add class-specific variations - - "Endgame feels anticlimactic" → Ensure puzzles advance story - - **Source material:** Self-synthesized from all resources - - **Delegation suggestion:** General agent with writing skill - ---- - -## Implementation Order & Dependencies - -### Phase 1: Foundation (Must come first) -1. Rewrite Introduction (task 1) -2. Create "Why Adventure Games" (task 2) - depends on 1 -3. Expand Core Principles (task 3) - depends on 1, 2 - -### Phase 2: Design Process (Can parallelize after Phase 1) -4. Create puzzle-dependency-charts.md (task 4) -5. Create working-backwards.md (task 5) -6. Create bushy-branching.md (task 6) -7. Create internal-logic-fairness.md (task 7) -8. Create player-psychology.md (task 8) -9. Create playtesting-methodology.md (task 9) -10. Create failure-modes.md (task 10) -11. Create hint-system-design.md (task 11) - -**Note:** Tasks 4-11 can be parallelized (different agents) since they don't depend on each other - -### Phase 3: Taxonomy Enhancement (Depends on Phase 2) -12. Add design notes to overviews (task 12) - depends on Phase 2 -13. Cross-reference puzzle types (task 13) - depends on 12 - -### Phase 4: Inspiration Cross-References (Depends on Phase 2) -14. Add cross-references to games (task 14) - depends on Phase 2 -15. Create cross-reference index (task 15) - depends on 14 - -### Phase 5: Reference Expansion (Can parallelize with Phase 3-4) -16. Expand Common Pitfalls (task 16) -17. Expand Validation Checklist (task 17) -18. Create Quick-Start Worksheet (task 18) - -**Note:** Tasks 16-18 can parallelize with Phase 3-4 - -### Phase 6: FAQ Creation (Final) -19. Create FAQ structure (task 19) - depends on all previous - ---- - -## File Operations Summary - -### CREATE Operations (13 new files) -| File | Task | -|------|------| -| src/why-adventure-games.md | 2 | -| src/design-process/puzzle-dependency-charts.md | 4 | -| src/design-process/working-backwards.md | 5 | -| src/design-process/bushy-branching.md | 6 | -| src/design-process/internal-logic-fairness.md | 7 | -| src/design-process/player-psychology.md | 8 | -| src/design-process/playtesting-methodology.md | 9 | -| src/design-process/failure-modes.md | 10 | -| src/design-process/hint-system-design.md | 11 | -| src/inspiration/cross-reference-index.md | 15 | -| src/docs/quick-start-worksheet.md | 18 | -| src/docs/faq.md | 19 | - -### MODIFY Operations (40+ files) -| File | Task | -|------|------| -| src/introduction.md | 1 | -| src/core-principles.md | 3 | -| src/puzzles/information-discovery-overview.md | 12 | -| src/puzzles/cognitive-transfer-overview.md | 12 | -| src/puzzles/spatial-temporal-coordination-overview.md | 12 | -| src/puzzles/npc-interaction-overview.md | 12 | -| src/puzzles/systems-and-logic-overview.md | 12 | -| src/puzzles/non-standard-domains-overview.md | 12 | -| src/puzzles/*.md (27 files) | 13 | -| src/inspiration/*.md (26 files) | 14 | -| src/docs/common-pitfalls.md | 16 | -| src/docs/validation-checklist.md | 17 | - -### Directory Structure to Create -``` -src/design-process/ - puzzle-dependency-charts.md - working-backwards.md - bushy-branching.md - internal-logic-fairness.md - player-psychology.md - playtesting-methodology.md - failure-modes.md - hint-system-design.md -``` - ---- - -## Delegation Strategy - -### Agent 1 (Writing Intensive) -- Tasks 1, 2, 3 (Foundations) -- Can run sequentially after understanding the project - -### Agent 2 (Design Process - Parallel Set 1) -- Tasks 4, 5, 6 (3 new chapters) -- Independent parallel work - -### Agent 3 (Design Process - Parallel Set 2) -- Tasks 7, 8, 9 (3 new chapters) -- Independent parallel work - -### Agent 4 (Design Process - Parallel Set 3) -- Tasks 10, 11 (2 new chapters) -- Independent parallel work - -### Agent 5 (Taxonomy & Inspiration) -- Tasks 12, 13, 14, 15 (cross-referencing) -- Should start after Design Process chapters exist - -### Agent 6 (Reference & FAQ) -- Tasks 16, 17, 18, 19 (Reference docs + FAQ) -- Final phase, can run after seeing full structure - ---- - -## King's Quest VI Puzzle Dependency Chart Project - -### 20. Acquire King's Quest VI Walkthroughs - -- [x] **Download 3 high-quality KQVI walkthroughs** - - Source from web archives, GameFAQs, or authoritative fan sites - - Verify walkthroughs cover the full game - - Save to `src/walkthroughs/kings-quest-vi/` - - **Delegation:** Use downloading-game-walkthroughs skill - -### 21. Create Puzzle Dependency Chart - -- [x] **Create mermaid chart for KQVI puzzles** - - Cross-reference 3 walkthroughs - - Node type: Problem (puzzle/obstacle) - - Node type: Solution (item/action that resolves) - - Show true dependencies (not just sequential ordering) - - Save to `src/inspiration/kings-quest-vi-puzzle-dependencies.md` - - **Delegation:** General agent with writing skill - -### 22. Quality Assurance - Dependency Verification - -- [x] **QA check all puzzle dependencies** - - Verify each dependency is a real logical dependency - - Going to a location ≠ unlocking it - - Getting item B before item A ≠ B depends on A - - Cross-reference with web if puzzle logic unclear - - **Delegation:** General agent for QA analysis - -### 23. Layout Verification - -- [x] **Ensure logical flow with START to END** - - Chart must have a clear start node - - All nodes must connect (no orphans) - - Final puzzle(s) must lead to END - - Logical progression from easy to hard - - **Delegation:** QA agent +### 6. mdbook Integration +- [x] SUMMARY.md already links correctly +- [x] Run `mdbook build` - passed +- [ ] Verify page accessible via `mdbook serve` --- ## Commit Points -After each major phase completion: -1. **Phase 1 complete:** "Complete: Part I Foundations (Introduction, Why Adventure Games, Core Principles)" -2. **Phase 2 complete:** "Complete: Part II Design Process (8 new chapters)" -3. **Phase 3 complete:** "Complete: Part III Taxonomy design notes" -4. **Phase 4 complete:** "Complete: Part IV Inspiration cross-references" -5. **Phase 5 complete:** "Complete: Part V Reference expansion" -6. **Phase 6 complete:** "Complete: Part VI FAQ creation" - -### KQVI Project Commit Points -7. **KQVI walkthroughs acquired:** "Complete: Acquire 3 KQVI walkthroughs" -8. **KQVI dependency chart created:** "Complete: KQVI puzzle dependency chart" -9. **KQVI QA verified:** "Complete: KQVI dependency chart QA verification" -10. **KQVI layout verified:** "Complete: KQVI dependency chart layout verification" - ---- - -## Validation Before Completion - -- [ ] All 13 new files created and populated -- [ ] All 40+ existing files modified appropriately -- [ ] SUMMARY.md updated to reflect new 6-part structure -- [ ] Cross-references are functional (links work) -- [ ] Word counts reasonable per section (target: <1000 words per page) -- [ ] No broken links or missing references -- [ ] Build passes (`mdbook build`) - -### KQVI Project Validation -- [ ] 3 KQVI walkthroughs acquired and saved -- [ ] Mermaid chart created with Problem/Solution nodes -- [ ] Each dependency verified as true logical dependency -- [ ] Chart has START and END nodes -- [ ] All nodes connected with no orphans -- [ ] Chart saved to `src/inspiration/kings-quest-vi-puzzle-dependencies.md` -- [ ] INSPIRED entries in SUMMARY.md updated +- Complete: Fix orphaned/undefined nodes (S17, S20, S12) +- Complete: Fix sequential to parallel (S19/S20 chain) +- Complete: Verify mdbook integration