Tinyworld Ghost World Gen

---
name: tinyworld-ghost-world-gen
description: Use when changing ghost board generation, path / road / river continuity, deterministic regen, edge connections, or anything that runs inside makeGhostWorld in tiny-world-builder.html.
---

# Tiny World Ghost World Generation

`makeGhostWorld(boardX, boardZ)` produces the contents of a single
non-editable ghost board. It must be:

- **Deterministic.** Same `(boardX, boardZ)` always yields the same
  cells. Cached in `ghostBoardCells` keyed by `'bx,bz'`. Panning away
  and back must regenerate identically (we rely on this for the
  sticky-reveal jigsaw — if content shifted between regens the
  reveal cache would lie).
- **Connection-aware.** Paths and rivers must line up across board
  edges. The user should be able to walk a road from one ghost board
  into the next.

## The seeded RNG

`ghostHash(a, b, salt)` is a tiny mulberry-style 32-bit mix used for
all board-level decisions. Per-cell randomness goes through the older
`cellRand(x, z, salt)` but always with **global** coords
`(boardX * GRID + x, boardZ * GRID + z, salt)`, never local coords.
That guarantees a given world cell renders identically regardless of
which board it was sourced from.

## Connection rubric

- **Horizontal path Z is a function of `boardZ` only**
  (`pathZForRow(boardZ)`). Every board on that world row either has
  the path at the same Z or has no path on that row.
- **Vertical path X is a function of `boardX` only**
  (`pathXForCol(boardX)`). Every board in the column shares the same
  vertical-path X.
- Where horizontal and vertical paths coincide inside a board you
  get a crossroads "for free".
- **Rivers** are column-shared via `riverXForCol(boardX)` so they
  flow continuously down a column. A river that would collide with
  a vertical path is nudged one column over.
- **Bridges**: where a river crosses a horizontal path, drop a
  `kind: 'bridge'` tile so the path stays walkable.

Rough density knobs (tweak in the helpers themselves):

- ~30 % of world rows have no horizontal path
  (`(h % 100) < 30 → -1`).
- ~35 % of world cols have no vertical path.
- ~88 % of world cols have no river (so ~12 % do).

## Cross-board neighbours

The visual tile renderer needs to know what's on the *other side* of a
board edge — otherwise a path that exits east terminates with a stub
end-piece. The neighbour helpers handle this:

- `ghostCellAt(boardX, boardZ, x, z)` resolves any local coord. If
  `x` / `z` are out of `[0, GRID)` it walks into the adjacent board and
  pulls from its `makeGhostWorld(...)` result. If the wrap lands on
  board `(0, 0)` it reads from the home `world[][]` instead so user
  edits on the home board's edges feed the ghost adjacency too.
- `getGhostNeighbors(cells, x, z, prop, value, boardX, boardZ)` and
  `getGhostTerrainNeighbors(cells, x, z, boardX, boardZ)` use
  `ghostCellAt` so an edge tile sees the real neighbour, not `null`.

Always pass `boardX, boardZ` when calling these from inside
`buildGhostBoard`.

## Cells layout

The cell schema must match the home board so `setCell` /
`renderCellObject` work on ghost cells too. Always include the full
shape:

```
{ terrain, kind, floors, buildingType, fenceSide, extras }
```

Omitting fields (especially `extras: []`) caused subtle bugs in the
old generator when ghost data flowed through helpers that assumed the
full shape.

## Blank ghost boards

The Generate dialog can disable outside auto-fill. That path sets
`ghostBoardsBlank = true`, clears existing ghost boards, and lets
`makeGhostWorld(...)` return deterministic blank grass cells for every
off-home board. Keep this as an early return inside `makeGhostWorld` so
panning remains cheap and no generated scenery appears outside the
current generated board.

## Don't

- Don't make paths or rivers depend on both `boardX` and `boardZ` —
  that breaks edge continuity.
- Don't seed decoration with local coords. A tree at local (3,4) of
  board (1,2) must be identical to that same world cell reached from
  any other angle.
- Don't mutate `ghostBoardCells` from anywhere except
  `makeGhostWorld`. The reveal system relies on stable references.

## User overrides (exceptions)

Anything the user builds / erases on a ghost board is an *override* and
must survive map regeneration:

- The override lives in `world[gx][gz]` at **global** coords. There is
  no separate override map — `world[][]` is the single source of truth
  for user-built cells whether they sit on the home board or far out
  in ghost territory.
- `applyToolToCell` copies the generated ghost cell into
  `world[gx][gz]`, calls `removeGhostCellMesh(boardX, boardZ, lx, lz)`
  to strip the ghost board's mesh for that cell, then runs `applyTool`
  which calls `setCell` to render the home cellMesh at the global
  coord. The home cellMesh and the ghost board never both render at
  the same world position.
- `ghostCellAt(boardX, boardZ, x, z)` prefers `world[gx][gz]` over
  `makeGhostWorld(boardX, boardZ)[x][z]`. That keeps cross-board
  adjacency (paths joining, rivers continuing) correct even when the
  user has edited the joining tile.
- `buildGhostBoard` skips any local cell whose global coord exists in
  `world[][]` — those are owned by `setCell` / `cellMeshes`.

## Persistence

- `saveState` walks `Object.keys(world)` so every populated cell — home
  *and* far-flung overrides — is serialised, regardless of how far the
  user has panned.
- `applyState` restores both home cells (via the staggered drop-in
  loop) and out-of-home overrides (via a second `setCell` pass with
  `animate: false, forceTile: true`). The ghost boards regenerate
  deterministically around them and `ghostCellAt` + `buildGhostBoard`
  ensure overrides paint on top.

The contract: if a user can place / erase it, the world reloads with
that exact change re-applied, anywhere on the map, and the rest of the
ghost world regenerates around it.

## Validation

- Pan east across several boards — horizontal paths should run as a
  continuous strip; vertical paths and rivers should cross perfectly
  perpendicular.
- Pan a known board out of the preload radius then back — the same
  trees / houses / crops / rivers reappear in the same cells.
- A river crossing a horizontal path renders a bridge, not water.
- The home board (0, 0) is not affected — its content is the user's,
  not the generator's, and paths that line up with the generated row
  /col are coincidental.