docs: a game design document, distilled from the transcript

COMPOSER-NOTES.md is a conversation: chronological, with my wrong turns kept
on purpose so nobody re-derives them. That is the right shape for us reading it
back and the wrong shape for anyone else, including Codex.

GDD.md is the other half -- the decided state without the journey. Seventeen
sections covering the premise, the core loop, the city, the depths, a strate,
descending, the economy, death, housing, the verbs, the season, the community
layer and the opening. Every section separates what Jahni decided from what is
still open, and design that is mine rather than his says so, so nothing reads
as settled that isn't.

Written deliberately plainer than the notes: prose rather than dense tables,
because a design document that only its authors can read has failed at the one
thing it exists for.

Also records why the file is in the wrong folder. This is a document about the
game, and most of it -- the city, combat, the economy, seasons -- is nothing to
do with VoxelForge. It lives in the plugin because the plugin is the only part
of the project under version control. It should move to the project root once
that becomes a repository.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DPUuCtn5zTLui6WybLbkNb
This commit is contained in:
Fr0zkaandClaude Opus 5 committed 2026-08-29 15:44:35 +02:00
1 parent b7cf12af4c
commit b781e3bab2
2 files changed
+556

No files matched your search

+80
View File
@@ -1479,3 +1479,83 @@ library · housing instances.
**Cargo now has two destinations** — your own progression, or the city. A real recurring choice with a **Cargo now has two destinations** — your own progression, or the city. A real recurring choice with a
communal dimension; it gives otherwise-worthless materials a use; and it makes the corpse run hit communal dimension; it gives otherwise-worthless materials a use; and it makes the corpse run hit
harder. *That ore wasn't just yours — it was the aqueduct.* harder. *That ore wasn't just yours — it was the aqueduct.*
---
## 2026-08-17 — THE VERBS: digging and combat
### Digging — a REVEAL-AND-SHAPE verb, not a movement verb
⛔ **Correction: I over-designed this.** I pitched digging as traversal (the Deep Rock model). Jahni:
it is for **digging walls that hide something behind**, **uncovering half-buried ruins**, **tiny
shortcuts within the same strate**, and **terraforming for builds**.
- ⏸️ **Noise attracting monsters: parked** ("not for now"). Recorded because it is still the cheapest way
to price digging in *safety* rather than in resources, if it is ever wanted.
- Useful fact from the code, unchanged: `VF_ApplyOriginSpine` deliberately leaves the boundary **seals
intact** *"so the player must still dig through to descend"* — descending by digging is intentional
but effortful; passages and elevators stay the fast path.
### Combat — MMORPG-like
Ranged/melee × magic/physical · stuns, roots, mutes · AoE and **targeted** AoE · DoTs. **Party of 6.**
**First person must remain possible.** **No friendly fire** — an AoE in a tunnel is simply strong, and
that is accepted.
### ⭐ This puts HARD SPATIAL REQUIREMENTS on the composer — and they are measurable
Arena sizes, translated into the composer's own units (**1 chunk = 32 voxels × 25 cm = 8 m**):
| space | size | chunks |
|---|---|---|
| **boss arena** (6 players + adds + movement) | ~25–30 m across | **3–4** |
| **ordinary fight space** | ~15–20 m | **~2** |
| **third-person camera clearance** | ~6–8 m of headroom | **~1** |
*Starting estimates, not gospel.* Arenas are **small relative to strates** (1–256 chunks tall), so
guaranteeing a supply of them is a **placement** problem, not a size problem.
⇒ A fightable space needs: minimum floor area · slope below a threshold · minimum clearance · clear
sightlines. **All of these the measurement pass already computes or trivially can** ⇒ a strate can be
**validated** to contain N fightable spaces, exactly as it is validated to have an entrance and an exit.
**"Fights don't feel blergh" becomes a GENERATION GUARANTEE rather than a tuning hope.**
**What caves add that a flat MMO arena cannot: VERTICALITY.** MMO fights are overwhelmingly flat; a
fight across ledges and drops is genuinely different — and it is already in the danger metrics as fall
exposure. The composer can deliberately produce arenas that are **spacious but vertical**, which is what
makes cave combat *better* than field combat instead of a worse version of it.
### ⭐ First person + ground telegraphs conflict — so TELEGRAPH THE SOURCE, NOT THE FLOOR
A circle painted on the ground only works if you can see the ground, which is exactly what first person
removes (you cannot see a telegraph under your feet, or behind you). If instead the **enemy visibly
winds up** (glow, raised arm, rising particles), the threat is read off the creature and you move away
from it. Works identically in FP and TP, **works when the floor is lumpy voxel rock where decals project
badly anyway**, and reading an animation is more skilful and more legible than reading a decal.
⚠️ **Supporting both perspectives means the constraints are the UNION:** full third-person camera
clearance **and** source-readable telegraphs.
### ⛔ CORRECTION — six players do NOT break streaming; the architecture already solved it
I raised this as a 6x streaming cost. **Wrong, and Jahni was right:** the host cares only about
**collision**; mesh and everything visual is **per client**, since every client generates the same world
(ARCHITECTURE §9.3/§9.4). Verified in code: `RegisterStreamingAnchor` defaults to `XYRadiusChunks=1,
ZBelow=1, ZAbove=0` = a 3x3x2 box = **18 level-0 tiles per remote player** (~90 for five), against a
player clipmap of hundreds-to-thousands across LODs at `ViewDistanceXY=16`. A rounding error, not a
multiplier. `CollisionOnly` skips **rendering** (`MeshComp->SetVisibility(false)`: no draw, no VSM, no
culling); it still runs density + marching cubes + the collision cook, because collision needs geometry
-- but at 18 tiles each that is small.
**Two things that DO scale with six players:**
- ⚠️ **Carve-driven re-meshing, which is BURSTY, not steady-state.** Six players digging in six places =
six streams of dirty-tile work: the host re-cooks collision for each, every client re-meshes what it
can see. This is the multiplier that actually tracks party size, and it arrives in spikes. Digging is
now a *reveal* verb (walls hiding things, ruins to uncover), so a party will do a lot of it at once.
- ⚠️ **Client-side meshing makes determinism a HARD RUNTIME REQUIREMENT, not a nice property.** If two
clients generate even slightly different geometry they disagree about where the walls are -- and the
host collision is authoritative, so one player hits an invisible wall where another sees a passage.
⇒ `VoxelForge.Determinism.CrossPlatformDigest` currently **reports rather than asserts** (informational
until someone pins the values). **This architecture promotes it to must-be-green.** Windows client +
Linux host, or two clients on different CPUs, producing different floats is now a visible gameplay
bug.
### Other consequences
- ⚠️ **The corpse mirror breaks for SUPPORT builds.** A healer's corpse heals itself and the fight is
unwinnable for reasons unrelated to skill. ⇒ the corpse should be a **combat-shaped** version of you —
your weapons and damage, minus the abilities that make the fight impossible — not a literal copy.
- **No friendly fire** removes a whole class of party friction (important with pick-up groups). Its
consequence: the cost of a cramped fight becomes **visual clutter**, not damage. Six players' effects
in an 8 m tunnel is unreadable noise and nobody can find the telegraph in it. The arena requirement
survives — for a different reason than "nowhere to dodge".
+476
View File
@@ -0,0 +1,476 @@
# Game Design Document
**Status:** first consolidation, 2026-08-17. Distilled from `COMPOSER-NOTES.md`, which stays as the
working transcript (chronological, with wrong turns preserved on purpose). This document is the
opposite: **the decided state, without the journey.**
> **Where this file lives, and why it is the wrong place.** This is a design document for *the game*.
> Most of it is not about VoxelForge at all — the city, combat, the economy and seasons are all
> outside the plugin. It lives here only because the plugin folder is the only part of the project
> under version control. Move it to the project root once that becomes a repository.
**How to read this:** everything under **Decided** was settled by Jahni. Everything under **Open** has
not been. Where a design is mine rather than his, it says so. Nothing here is a proposal wearing a
decision's clothes.
---
## 1. The game, in a paragraph
A fantasy exploration and combat RPG, online-first and party-based. The setting is medieval-ish and
progresses toward better and more modern infrastructure without ever leaving fantasy. Players descend
from a city on the surface into an endless underworld to find the resources that surface has none of,
and bring them back to build that city up. Side systems: housing and farming. The underworld is
generated, shared by everyone, and replaced every season. The city is hand-built, shared by everyone,
and permanent.
## 2. The premise
**Civilization emerged from the depths.** The first strate below the surface is artificial — someone
built it — and it holds crystals with humans inside them. The game opens on one of those humans being
un-crystallized.
The surface is a sky island, or a mountain so tall nobody can descend it. Either way it is small and it
has no resources. Everything a civilization needs has to come from below.
So descending is not conquest. **It is a return.** You are going back to where you came from, and
nobody remembers why you left.
## 3. The core loop
> The surface is limited, so you must descend. The depths supply resources. Resources build the
> settlement. The settlement lets you descend further.
Every system in this document hangs off that loop, and it closes. The sky island does quiet work in
it: it explains why there is no trade with anywhere else, why the depths are the only economy, and why
going down is the civilization's whole project rather than an adventurer's hobby.
---
## 4. Vocabulary
Two words got used for the same thing early on and caused real confusion. Pinned here.
**THE SURFACE / THE CITY** — a hand-authored, ordinary Unreal level. Not voxel terrain, not generated,
not part of VoxelForge. Communal and identical for every player. **It never resets.**
**THE DEPTHS** — everything VoxelForge generates: bounded, subterranean, a stack of strates below the
city's hole. Some strates only *mimic* being outdoors. **This is what is regenerated each season.**
**A SEASON** — one generation of the depths, roughly six to twelve months, plus the settlement tier the
community earns during it.
---
## 5. The city
### Decided
The city is **communal** — the same place for everyone, not instanced — and **permanent**. The season
wipe never touches it.
It **grows across seasons**, one tier at a time: camp, village, town, city, advanced city. Players
gather resources in the depths and donate them to the mayor or equivalent; a global counter rises until
the next tier is reached. A season is the unit that advances it. The game opens at *camp*.
Because groups never meet in the depths, **the city is the entire social surface of the game.** Trade,
the retrieval guild, shared builds, and simply seeing another person all happen there.
### Design rules
**A tier grants access and convenience, never power.** Services, workshops, NPCs, a bank, fast travel,
new quests, better aesthetics — but not stronger starting gear or stat bonuses. Otherwise players
arriving in season eight begin meaningfully stronger than those in season one, the early strates
trivialize, and the difficulty curve erodes a little every season until the top of the world is
scenery. This is the same rule the depth economy already follows: **buy access and time, never
numbers.**
**The city should be a ledger.** Somebody arriving in season eight built none of it. That is either
alienating or the best first impression in the game, depending entirely on whether the city records
*who* built it — names on the aqueduct, a monument per tier listing that season's contributors. New
players then walk through evidence that real people made this place, and long-term players get
something permanent, which pairs with the titles that already survive wipes.
### Open
- Is the tier threshold a fixed number, or does it scale with the active population? A fixed number
stalls forever with a small playerbase and is cleared in a week with a large one. *(My
recommendation: target one tier per season and retune the threshold at each season boundary, which
is a moment that already exists for other reasons.)*
- Where housing sits relative to the city.
---
## 6. The depths
### Decided
Bounded, but **gigantic**. Not infinite — that choice was made deliberately, and it buys a great deal.
**No bottom.** The descent does not end.
**Boss strates roughly every five levels**, and they are **intermediary, not terminal** — gates that
punctuate the descent rather than finish it. A boss is where the transport network's next stop opens.
**Regenerated every season** from a single seed shared by every player.
Some strates are open, cathedral-sized spaces lit from within that read as outdoors. There is no sun
anywhere in the depths.
### What bounding buys
Because the depths are finite, the generator can examine an entire strate rather than sampling it. That
turns the entrance-and-exit guarantee into a **proof**, and it makes "the community has explored 34% of
this season" a real number rather than a slogan.
---
## 7. A strate
### Decided
**The primordial law: every strate has an entrance and an exit, exposed to air, and findable.** This is
the one invariant that may never fail.
**Danger is depth times a per-strate multiplier**, with a rare chance of an easier strate appearing
deep. Danger drives which creatures live there, which environmental hazards exist, and what loot drops.
It does **not** drive what *kind* of place a strate is.
**A strate's identity is unrelated to its depth.** Two seeds differ in everything — not the same
strates spawn, nor the same details. You could meet anything at any depth.
**Anomalous strates are rare.** The example Jahni gave is "dreamcore" — repetitive patterns, a strange
sense of emptiness. They should be rare enough that finding one is *puzzling*, because it does not have
its place there. They deliberately do **not** blend with their neighbours; the wrongness lives in the
seam.
**Size varies enormously** — from a crawlspace to a two-kilometre cathedral.
### Design rules
**Strangeness needs ordinary to be strange against.** If every strate is peculiar, peculiar becomes the
baseline and nothing reads as uncanny. A world should guarantee a share of grounded, plausible strates
so the strange ones land.
**A rare easy strate should be a designed type, not a low roll** — visibly calm, few creatures, a place
a descent exhales. The natural home for a safe camp or a merchant.
**The mirror of that is stronger: a rare danger spike near the surface.** A place at −300 that is
absolutely not for you yet. You find it early, it kills you, and it sits in your head for forty hours.
In a single shared world that becomes season-wide news.
**Every anomaly must be legible.** Unsignalled variance reads as bad tuning, not design. And danger in
particular must be **readable at a strate's entrance, before the player commits** — warned-and-ignored
is the best death in games; unwarned is the worst.
### Open
- Adjacency rules: what may sit next to what. Confirmed as wanted, never specified.
---
## 8. Descending
### Decided
**A party of up to six.** The descent is done together.
**Instanced per group.** Different groups never meet in the depths. Today this runs on a local server —
one player's machine or a dedicated one — fed by an external database for community information.
**Two ways back up.** Walking back through the tunnels is content, not a chore. Alternatively, once a
strate has been visited it opens a passage onward, so transport — an elevator or similar — can carry
you down, and you choose which strate to travel to.
**Transport unlocks are per-player for now.** A world-level unlock, where the first group through opens
the way for everyone, is a possible future — gated on strates being large enough that finding the next
passage is not a ten-minute errand. That is a decision to make from data, not in advance.
### Open
- **How long is a run?** Still unknown, and it constrains a great deal: strate size, how dense the
transport stops need to be, how deep a season can plausibly reach.
- Does danger scale with party size, or are strates tuned for a nominal group?
---
## 9. Progression and the economy
### Decided
**Gear stats have a ceiling — somewhere around depth 30.** Loot found deeper has the *same* stats.
**What depth buys instead:** better natural rolls, so an item costs less material to level up; and
materials, enchantments and effects that exist nowhere else.
**Beyond the ceiling, going deeper is about pride, challenge, and seeing new things.** That is the
intent, not an accident.
**Depth-locked materials are tagged by difficulty tier, not by strate.** Their placement stays random,
so *where* a material is has to be rediscovered every season — which in a one-seed shared world turns
into a community question with a fresh answer each time. A fixed depth would be solved once and stay
solved forever.
**Trading will exist**, lightly at first, and becomes much better once the city is a real social hub.
### Design rules
**Buy access and time, never numbers.** Applied to both depth and city tier, which means the economy has
one principle rather than two competing ones.
**Guarantee what recipes depend on; leave the rest to chance.** A material a progression recipe needs
must be placed within reach, or a season ships a dead end that reads as a bug. A purely optional
material can be absent, and a season lacking one gains an identity.
**Since the depths are gigantic, "guaranteed" must mean a density, not a location.** Somewhere in an
enormous strate is unfindable. Near enough to the spine and common enough to actually meet is not.
### Open
- Where exactly the gear ceiling sits, and how fast danger climbs past it — that single rate is the
entire endgame difficulty curve.
---
## 10. Death
### Decided
Dying in the depths leaves your **corpse, possessed**. You fight it to get your cargo back.
**The corpse copies your weapons, and you keep yours.** It is a mirror match, not a disarming — you
never return to a fight underequipped.
**Only you can claim your loot.** No player can take it.
**A corpse run is a detour, not an evening — ten minutes at worst.**
**An NPC tells you where your corpse was last seen**, for a very small fee.
**Possible later:** dead players appear in other groups' instances, and killing such a corpse earns
gold from a retrieving guild — never that player's loot.
### Design rules
**Place the corpse; do not make it walk to you.** On death it should appear at a landmark near the
nearest passage or transport stop, and wander only within that neighbourhood. That turns the ten-minute
cap from a hope into a guarantee regardless of where you actually died.
**Charge for precision, not for existence.** The general area — "last seen near the Sink" — should be
free. Pay only for the exact position or live tracking. Otherwise the fee is not a decision, and worse,
a broke player after a bad run cannot recover their cargo at all.
**Copied weapons must never be lootable.** If the corpse drops a copy of your sword you have built an
item duplicator and it will be found within a week. Copied gear vanishes with the corpse; only cargo
drops.
**The corpse should be a combat-shaped version of you, not a literal copy.** A support build's literal
mirror heals itself and cannot be beaten, for reasons that have nothing to do with skill.
**Give the player a deliberate edge.** A perfect mirror is a coin flip, and you often arrive having
already spent your consumables. You have potions and can retreat; it does not and cannot. That is what
makes the fight winnable through preparation rather than luck.
**The bounty hunter and the player retrieval guild are one system with two front ends** — players are
the fast, uncertain path; the NPC is the slow, guaranteed one. Either way the cargo returns to you and
the retriever is paid by the guild, not out of your pocket.
### Open
- What happens if you die while fighting your corpse — one corpse that absorbs the last, or do they
stack?
---
## 11. Housing and farming
### Decided
**Housing is an instanced personal level** — your own small world, never wiped, never re-placed.
**Its ground is a snapshot of land you chose** in the depths and claimed. Your home is *from* somewhere.
After the season wipe it is the last surviving fragment of a world that no longer exists.
**One template level populated from save data** — a stored terrain region plus a list of placed
structures. Not one map per player.
**Invites**, because houses can be shared and visited.
**Anything that grows is computed from elapsed real time on entry**, not ticked — the instance is not
loaded while you are away.
### Open
- Whether players can build underground in the depths proper. The idea is alive, undecided.
- Whether the surface offers natural buildable space, or whether terrain-editing tools cover it.
---
## 12. The verbs
### Digging — decided
Digging is for **breaking walls that hide something behind them**, **uncovering half-buried ruins**,
**small shortcuts within a strate**, and **terraforming for builds**. It is a reveal-and-shape verb.
It is **not** a movement verb, and it is not the primary way through the world.
Descending by digging is possible but effortful: each strate's floor and ceiling are sealed, and the
seal must be dug through. Passages and transport are the fast path, by design.
### Combat — decided
MMORPG-like and dynamic: ranged and melee, magical and physical, stuns, roots, mutes, area effects,
targeted area effects, damage over time.
**Party of six. No friendly fire** — an area effect in a tunnel is simply strong, and that is accepted.
**First person must remain possible.**
### Design rules
**Telegraph the source, not the floor.** A circle painted on the ground only works if you can see the
ground, which is exactly what first person removes — you cannot see a marker under your own feet or
behind you. If the enemy visibly winds up instead, the threat is read off the creature. That works in
both perspectives, it survives lumpy voxel terrain where ground decals project badly, and reading an
animation is a better thing to ask of a player than reading a decal.
**Supporting both perspectives means owing both sets of constraints** — full third-person camera
clearance *and* source-readable telegraphs.
**Fights need space, and the generator must guarantee it.** Cramped tunnels are the worst possible
arena: no room to dodge a telegraph, no sightlines, no retreat, and with six players' effects in an
eight-metre corridor nobody can see anything. Rough targets, in the generator's own units of 8 m
chunks: a boss arena wants 3 to 4 chunks across, an ordinary fight space about 2, and roughly 1 chunk
of headroom for the camera.
**Verticality is what caves can offer that a flat arena cannot.** MMO fights are overwhelmingly flat. A
fight across ledges and drops is genuinely different, and it is the reason to fight underground at all.
### Open
- Creatures. Nothing decided. Danger and theme tags will select them, but *what they are* is unwritten,
and they are most of what makes a strate feel like a place rather than a shape.
---
## 13. The season
### Decided
The depths are wiped and regenerated roughly every six to twelve months.
**Survives a wipe:** the city and its tier, account progression, titles, personal blueprints, housing
instances.
**Dies with the wipe:** the depths, the shared build pool, the transport unlock network.
### Why this is good rather than merely tolerable
The world is impermanent and the civilization is not. *We lost our maps, but we built a town.* Season
eight arrives in a place season three made, which gives a season's end a meaning beyond freshness.
It also solves problems that would otherwise be permanent. Every long-lived exploration game eventually
dies of its own wiki — everything is solved, every secret is mapped, nothing is left to find. A wipe
resets that, and the whole community re-explores together. It equally means a datamined map is worthless
one season later, so there is nothing to defend against.
And it frees the generator: because generation is only frozen *within* a season, it can be changed at
every boundary. The system never has to be finished before it meets players.
---
## 14. The community layer
### Decided
**One seed for everyone.** Every player's depths are the same depths, which is what makes shared
knowledge — wikis, guides, "the crystalline lake is in strate four" — possible at all.
**Players share builds**, as defined blueprint structures rather than raw terrain edits. Votes rank
them; well-liked builds appear in more players' worlds; disliked ones fall to the back of the queue and
sufficiently disliked ones are never shown again. **New and unvoted builds must be deliberately rolled
in**, or nothing new is ever seen and the system dies quietly.
**The build pool does not survive a season change** — nothing would be placed correctly. Top
contributors are rewarded with titles, tiered by population.
**Landmarks have names**, generated so that every player sees the same name for the same place before
anyone has ever visited it.
### Design rules
**The community layer must degrade gracefully.** The depths are generated from a seed and need no
database at all. If the database is unreachable, procedural names stand in for community ones, shared
builds simply do not appear, and votes queue locally. That is cheap now and painful to retrofit once a
hundred call sites assume the fetch succeeded.
**A build placed anywhere is yours; a build placed in a spot the world advertised is eligible to
spread.** That keeps building free while keeping automatic distribution safe.
**Names must survive contact with a wiki** — short, pronounceable, typeable. A name nobody can spell
cannot become community knowledge, which is the only reason names exist here.
**Auto-distributing player content needs a report, reject and rollback path**, and shared builds must be
individually removable by the player receiving them.
---
## 15. The opening
### Decided
A cinematic: civilization emerged from the depths. The first artificial strate holds crystals with
humans inside. One of them is un-crystallized — you.
You discover a **base camp**, and are told you could be an adventurer who braves the depths.
Then you descend to **strate 2 — the first generated strate.**
### Why this is worth more than it looks
The first strate is hand-made, and the rest are generated. That is normally a production compromise
players must be prevented from noticing. Here the hand-made strate is **hand-made in the fiction too** —
artificial because someone built it, with the natural world lying beneath. A player who senses that
strate 1 feels different from strate 2 is reading the story correctly rather than spotting the seam.
That is rare, and it is worth protecting in every later decision.
---
## 16. Open questions, collected
Ordered roughly by how much they block other work.
1. **Is the descent fun?** Unverified, and undesignable — it needs a crude build and an evening of
playing it. Everything in this document assumes the answer is yes.
2. **How long is a run?** Constrains strate size, transport density, and how deep a season reaches.
3. **Creatures.** Nothing decided. Blocks content, not the generator.
4. **The backend.** Local server plus an external database, per-group instances, moderation, shared
builds. Entirely unspecified and carrying a lot of weight.
5. **Does danger scale with party size**, or are strates tuned for a nominal group?
6. **The tier threshold** — fixed, or scaled to population?
7. **Adjacency rules** between strates. Wanted, never specified.
8. **Underground building** — undecided.
9. **Where the gear ceiling sits**, and how fast danger climbs past it.
## 17. Deliberately deferred
- **Digging noise attracting creatures.** Liked, parked. Still the cheapest way to price digging in
safety rather than in resources, if it is ever wanted.
- **Naming languages varying by depth** — older, stranger tongues deeper down. Liked, parked as still
being a gradient.
- **World-level transport unlocks**, where the community opens the descent together. Gated on strates
being big enough for the discovery to be worth something.
- **Shards** — more than one seed at a time. Only if the game grows enough to need them.
- **Singleplayer.** Never the intent; may become an option.
---
## Where the rest lives
- **`COMPOSER-NOTES.md`** — the working transcript this was distilled from, including the generator
design (the composer, the world manifest, the measurement pass, stack assembly) and the reasoning
behind everything above.
- **`ARCHITECTURE.md`**, **`CODEMAP.md`** — how VoxelForge actually works.
- **`fable-idea.md`** — the older ranked feature and performance roadmap. Predates most of this.