Most game documentation fails for a boring reason: it is unstructured prose about structured things. A level is a graph. It has zones, routes, sightlines, interactive props, light cues, encounter triggers, streaming boundaries, and a pacing curve, all with relations between them. Storing that as a wiki page throws the graph away and leaves you re-deriving it by hand every sprint.
Shapezo's answer is to model the location first and render prose second. Content becomes typed objects with a schema, and the design brief is a build artifact. This post walks through the model and the pipeline.
The level schema
A Shapezo level object is deliberately small. Four entities cover nearly every environment:
Two fields deserve attention because they are the Shapezo-specific part. narrative.shape selects the brief structure from a fixed enum (corridor_with_destination, hub_with_radiating_promises, loop_that_returns_changed, descent_trading_light_for_information). anchor_details names the one or two physical details the prose is allowed to go deep on. Everything else stays at summary depth. That single constraint is what keeps generated briefs readable.
Rendering prose from the model
The renderer is a template per narrative shape. Each template is a sequence of sections with slots bound to schema paths. Nothing free-form: if a slot has no data, the section renders a visible TODO marker rather than silently vanishing, so gaps surface in review instead of in production.
Because the output is deterministic for a given schema, diffs are meaningful. A schema change shows up as a clean brief diff in code review, which is exactly where level knowledge changes should be reviewed.
The asset pipeline
Images are treated as build inputs with contracts, not decorations. Each level declares three slots — establishing, working_layer, consequence — and the pipeline enforces geometry and weight on ingest:
# 16:9 crop, 720p, target ~200KB JPEG
magick in.png -gravity center -crop 16:9+0+0 -resize 1280x720 out.jpg
The weight target matters more than it sounds. Design briefs get read on laptops in playtest rooms, on build machines, on hotel wifi at conferences. A 200KB budget per image keeps a full three-scene brief under a megabyte.
The rooftop vantage below is a good example of an establishing asset: one elevated frame captures skyline relation, roof topology, and traversal affordances that would take six ground screenshots to convey.
Why the stylized pass is the load-bearing shot
Of the three slots, working_layer is the one that pays for the pipeline, and a simplified render pass is its best expression. Route lines, cover volumes, climb affordances, and light cues all change on a sprintly cycle, so a low-detail stylized frame doubles as an affordance baseline. Keeping it in the schema means the comparison is a git diff of images at a fixed viewpoint, not an archaeology project.
What you get
Model first, render second, and three things change. Documentation becomes reviewable, because schema changes produce brief diffs. It becomes complete, because empty required slots fail loudly. And it becomes cheap, because updating a level is editing four YAML blocks instead of rewriting prose.
Shapezo is not a CMS and not a static site generator. It is the discipline of deciding the shape of your content before you write it, plus just enough tooling to enforce that decision. For game worlds, where the underlying asset is already a well-defined graph, that discipline is almost unfair leverage.
Top comments (1)
The idea of treating level documentation as structured data rather than free-form prose is really interesting. I especially like the use of
TODOmarkers for missing fields because it makes gaps visible during review instead of letting them slip into production. The fixed-viewpoint image diffs are also a smart way to track changes in routes, cover, and lighting between sprints. This approach could be useful beyond game development anywhere structured information needs to stay consistent with its documentation.Some comments may only be visible to logged-in visitors. Sign in to view all comments.