Worldshaper/docs/refactor/world-and-chunk-semantics.md

World And Chunk Semantics

This document describes the current WorldShaper world/chunk behavior as of Arc 1.

It is a compatibility and refactor aid, not an endorsement of the long-term model.

Scope

These notes summarize the behavior currently implemented in:

• src/worldChunking.ts
• src/components/worldshaperShared.ts
• regression tests in:
  • src/worldChunking.test.ts
  • src/components/worldshaperShared.test.ts

Coordinate Model

Chunk Dimensions

• chunk width and height are normalized with normalizeChunkDimension
• values are floored to integers
• invalid values fall back to DEFAULT_WORLD_CHUNK_SIZE
• normalized dimensions are clamped to a minimum of 1

World To Chunk Coordinates

• chunk coordinates use floor division
• this applies on both positive and negative world coordinates
• examples with chunk size 32:
  • 0 -> chunk 0
  • 31 -> chunk 0
  • 32 -> chunk 1
  • -1 -> chunk -1
  • -33 -> chunk -2

This means negative coordinates behave as mathematical grid cells, not truncation toward zero.

World To Local Coordinates

• local coordinates are derived from the resolved chunk coordinate
• formula: world - (chunk * chunkSize)
• result stays in the half-open range [0, chunkSize)
• examples with chunk size 32:
  • 31 -> local 31
  • 32 -> local 0
  • -1 -> local 31
  • -33 -> local 31

Local To World Coordinates

• formula: (chunkCoord * chunkSize) + localCoord
• examples with chunk size 32:
  • chunk -2, local 31 -> world -33

Address Resolution

resolveWorldChunkAddress returns:

• chunkX
• chunkY
• localX
• localY
• chunkKey in x:y form
• fileName in x_y.json form

Chunk Identity And Storage

• chunk keys use buildChunkKey(chunkX, chunkY)
• chunk filenames use buildChunkFileName(chunkX, chunkY)
• filenames preserve negative signs, for example -3_4.json

Empty Chunk Defaults

createEmptyChunk currently creates:

• schema version 1
• top-level backgroundTileId
• roomLayers[0] filled with . characters
• roomLayers[1] filled with spaces
• empty heightLayers
• empty instances

This establishes the current meaning that:

• . in layer 0 is the default empty background cell encoding
• spaces in non-background layers represent empty overlay cells

Background Tile Behavior

getMapBackgroundTileId currently resolves background tiles in this order:

1. top-level backgroundTileId
2. legacy nested tiles.backgroundTileId
3. empty string fallback

Arc 1 should treat the nested tiles.backgroundTileId shape as compatibility baggage.

Room Layer Semantics

parseRoomLayers currently does the following:

• parses record.roomLayers if present
• ignores malformed entries
• requires a numeric layer
• sorts output by ascending layer
• normalizes row sizes to map bounds
• uses . fill for layer 0
• uses space fill for non-zero layers
• filters blank instanceIds

If no explicit layer 0 exists:

• a synthetic layer 0 is created from top-level record.rows

If there are no usable layers at all:

• a single synthetic layer 0 is returned from top-level record.rows

Current zIndex Behavior

• layer 0 always gets zIndex: 0
• non-zero layers preserve provided zIndex if present
• otherwise non-zero layers default to 0
• non-zero zIndex values are clamped into [0, 5]

This is an important current behavior to preserve during Arc 1, but it looks at least partly accidental because non-zero layers do not derive zIndex from layer number.

Height Patch Semantics

parseHeightLayers currently treats height patches as sparse row-based overlays.

Input Interpretation

• rows are string arrays
• . is interpreted as empty space
• empty margins are trimmed away
• patches are clipped to map bounds

Normalization Rules

• duplicate patch ids are dropped after the first occurrence
• z is clamped to a minimum of 1
• x and y are floored to integers
• rows completely outside bounds become empty
• leading/trailing empty rows are removed
• leading/trailing empty columns are removed by cropping to occupied content
• trailing whitespace inside retained rows is stripped

Resulting Meaning

The current height patch encoding behaves more like a cropped sparse stamp than a fixed-size tile layer.

That is useful to document now because any future redesign needs to decide whether this sparse behavior is intentional or just a side effect of the current editor implementation.

Chunk Instance Semantics

Arc 1 has not redesigned chunk instances yet, but the current shape is:

• id
• optional templateId
• layer
• x
• y
• record

The semantics of templateId + record are still under-specified and should be treated as a known redesign target for later arcs.

Likely Accidental Or Under-Specified Behavior

These behaviors are currently preserved, but should not be treated as settled architecture:

• non-background layers default to zIndex: 0 instead of deriving depth from layer number
• duplicate height patch ids are silently dropped after the first occurrence
• top-level rows still act as a fallback source for synthesized background layers
• nested tiles.backgroundTileId is still accepted
• layer 0 empties use . while non-zero layer empties use spaces
• chunk instance meaning is still implicit rather than explicitly modeled

Arc 2+ Questions

• Should negative-coordinate behavior remain floor-based, or should world addressing be modeled differently at a higher level?
• Should layer depth be derived from layer, zIndex, or a clearer world-space model?
• Should height data remain sparse text rows, or become a more explicit numeric structure?
• Should background tiles stay top-level, or belong to a clearer terrain/base-layer contract?
• What is the correct long-term meaning of chunk instances, templates, and per-instance overrides?