⏱️ Lectura: 10 min
In 1989, designer Ron Gilbert published an internal essay at LucasArts arguing that adventure games were broken by design, and proposed fixing it with a puzzle dependency diagram: a map where each puzzle is a node and each prerequisite an arrow. Almost a decade later, that same method was used to design Grim Fandango, and in 2008 a scanned copy of the original document ended up published on a video game blog.
📑 En este artículo
The find is not just an archival curiosity. The puzzle diagram LucasArts drew by hand is, in its structure, the same directed acyclic graph that today resolves task order in a build system or a data pipeline, and it can be reconstructed in minutes with Graphviz, Mermaid, or a few lines of Python.
TL;DR
- Ron Gilbert introduced the concept of the puzzle dependency diagram in his 1989 essay ‘Why Adventure Games Suck.’
- LucasArts applied the technique to the design of Grim Fandango, released in 1998 under the direction of Tim Schafer.
- Blogger Jason McIntosh published a scan of the internal LucasArts document on gameshelf.jmac.org on November 13, 2008.
- The diagram models each puzzle as a node and each prerequisite as a directed edge of a directed acyclic graph (DAG).
- That structure is the same one tools like Make, npm, or Airflow use today to resolve the execution order of tasks with dependencies.
- A topological sorting algorithm automatically detects whether the puzzle graph has an unsolvable cycle.
- Graphviz and Mermaid make it possible to build today the same kind of diagram LucasArts drew by hand in the ’90s.
What Happened
On November 13, 2008, blogger Jason McIntosh published on The Gameshelf the scan of an internal LucasArts document: the puzzle dependency diagram used during the development of Grim Fandango, the graphic adventure directed by Tim Schafer and released in 1998 (Grim Fandango on Wikipedia). The original file is a large image, the result of scanning a sheet of paper covered in boxes and arrows drawn by hand by the design team.
Each box in the puzzle diagram represents a goal or a story milestone, such as getting Manny Calavera’s boat ticket, buying sandpaper on the black market, or bribing the Department of Death inspector. Each arrow indicates which other goal must be resolved before that puzzle becomes accessible to the player. The visual result looks more like a circuit board layout than a narrative script, and that was exactly the point: turning the design of a nonlinear story into something that could be audited by eye before writing a single line of dialogue. The document circulated quickly among LucasArts fan communities and is still cited today in forums and video game design courses as one of the few real production artifacts publicly available for a game of that scale.
Context and History
The technique didn’t originate with Grim Fandango. Ron Gilbert described it in 1989, while working at LucasArts designing the first Monkey Island game, in an internal essay about why so many adventure games ended up frustrating the people who played them. His diagnosis was simple: if a puzzle depended on an item the player could lose, sell, or leave behind in another part of the map, the game became unsolvable with no prior warning that this had happened. Before this philosophy took hold, it was common for graphic adventures to include consumable items that left the player unable to finish the game hours later, something Gilbert singled out as one of the worst possible design sins (Ron Gilbert’s profile on Wikipedia).
The solution Gilbert proposed was to draw, before writing a single line of dialogue, the complete map of dependencies between puzzles. If that map had a cycle (a puzzle A that needed B, and B that in turn needed A) or a node that no path could reach, the design was broken by definition, with no need to play it first to find out. Grim Fandango, released almost ten years after that essay, inherited the method with almost no changes. The document McIntosh uploaded is direct evidence that the team kept applying it puzzle by puzzle, act by act, throughout the game’s entire production.
Technical Details of the Puzzle Diagram
In terms of data structures, a puzzle diagram is a directed acyclic graph, known as a DAG. The nodes are the puzzles, and the edges point from the prerequisite toward the puzzle it enables. That restriction (the graph must have no cycles) is the same one required by any system capable of resolving an execution order from declared dependencies, from a Makefile to an Apache Airflow DAG.
The following diagram recreates, in simplified form, four typical nodes from that kind of document:
flowchart TD
A["Get Manny's ticket"] --> B["Buy sandpaper on the black market"]
B --> C["Bribe the DOD inspector"]
D["Talk to Glottis about the car"] --> C
C --> E["Leave Rubacava"]Getting Manny’s ticket enables buying the sandpaper, and both the sandpaper and having talked to Glottis about the car are prerequisites for bribing the inspector, which in turn enables leaving Rubacava. That same logic underlies a continuous integration pipeline, where the test step can’t start before the build step if it depends on its result.
| Tool | When to use it | Advantage | Limitation |
|---|---|---|---|
| Graphviz | Large diagrams generated by script | Automatic layout from plain text (DOT) | Learning curve for DOT syntax |
| Mermaid | Documentation embedded in Markdown or wikis | Renders directly on GitHub and Notion | Gets cluttered with very large graphs |
| Miro / draw.io | Collaborative team design sessions | Real-time visual editing, no code required | Doesn’t version well in Git |
| NetworkX (Python) | Validating the graph with code, not just drawing it | Detects cycles and calculates topological order | Doesn’t produce a nice-looking diagram on its own |
The technique has a practical limit. Past a few dozen puzzles, the diagram becomes hard to read at a glance even with automatic layout tools like Graphviz, and large teams tend to end up splitting it by acts or chapters, which is apparently reflected in the structure of the Grim Fandango document. A puzzle diagram also doesn’t capture mechanics that depend on time or chance, only pure prerequisite relationships.
💭 Key takeaway: a puzzle dependency diagram is, in essence, the same directed acyclic graph used by a build system like Make or an orchestrator like Airflow to decide in what order to execute tasks with dependencies.
💡 Tip: if you document your project on GitHub or Notion, Mermaid renders directly in Markdown without installing anything extra, unlike Graphviz, which needs to generate the image separately with the dot command.
How to Build Your Own Puzzle Diagram
To reproduce today the same exercise LucasArts used to do by hand, Graphviz is enough, available in most package managers with apt install graphviz on Debian and Ubuntu, or brew install graphviz on macOS. A minimal .dot file describes the nodes and arrows of the puzzle diagram in plain text, with no graphical editor required.
digraph puzzles {
manny_boleto -> lija_mercado;
lija_mercado -> sobornar_inspector;
hablar_glottis -> sobornar_inspector;
sobornar_inspector -> salir_rubacava;
}With the command dot -Tpng puzzles.dot -o puzzles.png, that text turns into an image using the same kind of automatic layout that Graphviz, and under the hood tools like Mermaid, use. The step that didn’t exist in 1989 is validating the graph with code instead of checking it by eye. Python’s NetworkX library detects cycles and calculates a valid resolution order in just two lines.
import networkx as nx
grafo = nx.DiGraph()
grafo.add_edges_from([
("manny_boleto", "lija_mercado"),
("lija_mercado", "sobornar_inspector"),
("hablar_glottis", "sobornar_inspector"),
("sobornar_inspector", "salir_rubacava"),
])
print(nx.is_directed_acyclic_graph(grafo))
print(list(nx.topological_sort(grafo)))The first line prints True if the design is solvable and False if there’s a cycle, meaning a puzzle that’s impossible to complete as currently laid out. The second prints a valid order in which, in theory, a player could solve every puzzle without getting stuck. To confirm your own diagram passes the test, run nx.is_directed_acyclic_graph(grafo) after every change. If it returns False, there’s a circular dependency you should break before writing any more dialogue.
Impact and Analysis
The puzzle diagram didn’t solve the problem of making graphic adventures fun, only the problem of making them completable. That distinction explains why the technique survived for forty years. It’s a quality control tool, not a creativity tool, which is why it fits well with software engineering processes that already use the same graph logic for other things. The idea’s staying power is also explained by the fact that it doesn’t depend on any specific software: it works just as well drawn on paper in 1989 as generated by script in 2026.
Outside video games, the idea of modeling tasks as nodes with prerequisites underlies package managers like npm and orchestrators like Apache Airflow, which automatically calculate the order in which to execute each step based on its declared dependencies. The difference with the LucasArts document is that there, an algorithm resolves the graph, not a designer with a ruler and a pencil.
What’s Next
Game design studios still cite Gilbert’s essay as required reading in nonlinear narrative courses, and the Grim Fandango document circulates as real-world proof that the technique was applied in a commercial game and didn’t remain purely theoretical. At the same time, the current generation of narrative design tools, from Twine to engines with native graph support, builds cycle validation in as a standard feature, the same check that used to require drawing everything by hand and checking it by eye.
📖 Summary on Telegram: View summary
Try it yourself: install Graphviz with apt install graphviz and turn your own project’s dependencies into a .dot file to see if the graph is hiding a cycle.
Frequently Asked Questions
What is a puzzle dependency diagram?
It’s a map where each puzzle in a game appears as a node and each arrow indicates which other puzzle must be solved first. It’s used to verify, before any coding begins, that the game can be completed from start to finish.
Who invented the technique?
Designer Ron Gilbert, who described it in a 1989 essay while working at LucasArts, the company that later used the same method for Grim Fandango.
Did Grim Fandango use this diagram throughout its entire development?
The document published on The Gameshelf shows that the team applied it act by act, following the different chapters the game’s story is divided into.
How is it similar to a software dependency graph?
Both are directed acyclic graphs. A node can’t depend, directly or indirectly, on itself, whether it’s a video game puzzle or a step in a build pipeline.
What tool is best for making one today?
Graphviz or Mermaid for drawing it, and a library like NetworkX if you also want to validate with code that the graph has no cycles.
Does it work for genres other than graphic adventures?
Yes. Any design with prerequisite-based progression, such as RPGs with quest trees, crafting games, or metroidvanias, can be modeled with the same type of graph.
References
- The Gameshelf: the scanned document of the Grim Fandango puzzle dependency diagram, published by Jason McIntosh on November 13, 2008.
- Wikipedia: Grim Fandango: the game’s profile, release year, and development team.
- Wikipedia: Ron Gilbert: biography of the designer who proposed the technique in 1989.
- Graphviz: official documentation for the tool used to generate dependency diagrams from plain text.
- Mermaid: official documentation for the syntax used in this article’s diagram.
📱 Like this content? Follow @programacion on Telegram for daily tech content in Spanish: quick summaries, fresh content every day.
0 Comments