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.