World — assets/worlds/<name>.vworld

A world is a map too large to write by hand: a seeded generator paints biomes over an integer grid of cells, raises rolling ground and the hills, plains, lakes and seas you name (terrain, features), scatters one-cell prefabs, places sites (villages, cities, ruins) on a jittered grid, and puts the landmarks you name (places) exactly where you say. The game streams the chunks around a focus (the hero, usually), so the world is as large as extent allows (up to ±8192 m from the origin, 268 million cells at the defaults) while only a few chunks exist at a time. Since v1.2.0.

You author rules and a few named places in cells; the engine computes every meter, checks every footprint, and tells you what is where (world_query), shows you the map (world_map) and finds a valid cell for a landmark (world_place). Same seed, same world, on the authoring machine and on the console.

File and name

• Location: assets/worlds/<name>.vworld. The name is the file name without .vworld; render --world, simulate --world, scenarios ("world": …) and ctx.LoadWorld refer to it. A folder under assets/worlds/ works too; names must be unique across the folders.
• Decoding is strict (unknown fields, duplicate keys, wrong types and trailing data are errors located by file:line:col and JSON path; all problems are reported together). Prefab references are checked when the prefab exists: a prefab too large for its cell, its site spacing or the world is an error; a missing prefab is a cook warning and an inspect world error.

Cells and chunks

• A cell is cell meters square; cell [x, z] covers x in [x·cell, (x+1)·cell), z in [z·cell, (z+1)·cell). +X is east, −Z is north (up on a top-down render).
• A vertex [x, z] is the min corner of cell [x, z]: the ground has one height per vertex (whole millimeters, computed with integers so every machine agrees) and each cell is two triangles between its four corners.
• A chunk is chunk × chunk cells; chunk [cx, cz] starts at cell [cx·chunk, cz·chunk].
• The world spans chunks -extent to extent-1 on each axis, so cells -extent·chunk to extent·chunk-1. extent × chunk × cell must not exceed 8192 m: farther out, float32 positions lose the precision a 320×240 frame needs.
• Around the focus, the game keeps the (2·view+1)² chunks loaded, and unloads a chunk only when it is view+1 chunks away (so a hero walking along a border does not reload chunks every tick).

Top-level fields

The start cell is the at of render, simulate, a scenario or ctx.LoadWorld ([0, 0] by default): the camera and the persistent entities are placed relative to its centre, and the focus begins there. render --world w --at 120,-40 therefore shows the world around cell [120, -40] with the hero standing there.

Biomes

Biomes are bands of one smooth noise field (integer arithmetic, so every machine agrees): the range of the noise is split among the biomes in file order in proportion to their weights, so with weights 3 and 1 the first biome covers three quarters of the ground and adjacent biomes in the list are adjacent on the map.

Terrain

The ground's shape. Without terrain (or with relief 0 and no features) the ground is flat at y = 0.

Features

Named changes to the ground, applied in file order on top of the relief: a later feature works on the ground the earlier ones left. world_terrain adds them (it reports the heights before and after and what now stands in water); world_remove removes them.

• A hill adds height at the centre, fading to nothing at the edge.
• A plain levels the ground to its level within radius − falloff, blending out to the edge: flatten a hillside before placing a town, or cut a mesa into a hill.
• A lake or a sea is a bowl: water at its level out to the (wandering) radius, the bottom depth below it at the centre, a dry rim 2 cells wide just above the water (5 cm), then the shore back to the ground. A sea is a big lake: centre it off the coast with a radius that reaches the shore (cell: [-600, 0], radius: 500 makes the west a sea from about x = −100 on).
• With sea_level, any ground below it is sea too, lakes and seas included.

Pads. Every site and place stands on a pad: the vertices of its footprint are levelled to the ground at the footprint's centre (features and relief included), blending into the ground over 2 cells around it. Its entities' y is measured from the pad; a scattered prefab's from the ground at the centre of its cell.

Water. A site whose footprint has a vertex under water is dropped; scatter skips cells whose centre is under water; a place in water is reported (WORLD_PLACE_WATER). Water is drawn as flat quads at its level over every cell with a corner under it: the ground hides the part that lies above it. Nothing collides with water: a game asks WaterAt.

Vegetation

Named rules that plant the world, everywhere or in a round area. world_vegetation adds them (it reports how many plants the area gets and what they cost to draw); world_remove removes them.

• A prefab rule competes for cells with the scatter rules and the prefab rules before it: the first rule that fires owns the cell (scatter rules first, then vegetation rules in file order). It keeps its prefab's min_distance from sites and places.
• A model rule plants at most one plant per cell, somewhere in the middle 60% of the cell, turned by a quarter turn and mirrored by the seed, standing on the ground. Any number of model rules may plant the same cell (grass and flowers together). Flora skips water and the footprints of sites and places.
• A flora model is an ordinary model (model topic): keep it to a handful of triangles (a lathe cone of 3–4 segments is a tuft of grass) and give it a draw_distance, and a lod level or two: flora is thinned with distance (next section).

Scatter

Each rule puts a one-cell prefab (footprint at most cell × cell) on a share of the cells of its biomes, decided cell by cell from the seed. Cells occupied by a site or a place, or too close to one for the prefab's min_distance, are skipped.

Sites

Each rule cuts the world into spacing × spacing cell regions and puts, in a share of them, one of its prefabs at a seeded offset that keeps the footprint inside the region. Sites of one rule therefore never touch and keep their min_distance; a site that would break a rule against a place or a site of an earlier rule is dropped. Sites are not rotated.

Places

Explicit landmarks. A place always wins: sites and scatter inside its footprint or its min_distance are dropped. world_place writes them (it validates or finds the cell); writing one by hand is allowed, and inspect world reports one that overlaps, stands in a wrong biome or breaks a distance rule.

Generated entities

Every entity of a chunk has a deterministic name, the same on every machine and in every run, so scenarios and traces can refer to it:

A negative coordinate is written with n: chunk [-3, 12] is chunk_n3_12. A structure (site or place) is spawned whole as soon as any chunk its footprint touches is loaded and despawned when none is. Streamed spawns do not emit spawn/despawn events; the trace gets one chunk_load ({x, z, entities, first_id}) and chunk_unload ({x, z}) event per chunk, and world_load ({world, at}) when the world is loaded.

Runtime

func (g *Game) Init(ctx *veduta.Context) error {
	// A game started with --world already has it loaded; a scene game can switch:
	if ctx.World() == nil {
		return ctx.LoadWorld("overworld", [2]int32{0, 0})
	}
	return nil
}

func (g *Game) Update(ctx *veduta.Context, in veduta.Input) {
	hero := ctx.Scene.Find("player")
	if w := ctx.World(); w != nil && hero != nil {
		w.Focus(hero.WorldPosition()) // chunks follow the hero from the next tick
		ctx.Scene.Camera = scene.Camera2D(gmath.V2(hero.WorldPosition().X, hero.WorldPosition().Z), 12)
	}
}

ctx.World() is nil until a world is loaded. Focus sets the point the window is kept around; CellOf(pos) returns the cell of a position; Loaded() lists the loaded chunks; HeightAt(pos) returns the height of the ground under a position (exactly on the triangles of the chunk's finest drawn level, so a hero set to it stands on the ground) and WaterAt(pos) the water level over it and whether the ground there is under water:

if w := ctx.World(); w != nil {
	p := hero.Transform.Position
	next := p.Add(step)
	if _, wet := w.WaterAt(next); !wet { // keep out of lakes and seas
		next.Y = w.HeightAt(next)
		hero.Transform.Position = next
	}
}

While a world is loaded the within_bounds invariant uses the world's extent (and the project's Y range) instead of the project's bounds. Snapshots carry the loaded window, so Restore continues the same streaming.

Rendering

A console draws about 1200 triangles a frame at 20 Hz, so a world is drawn with two savings, both automatic:

• Limited view. An entity whose drawn bounds lie wholly outside the camera's view volume costs nothing, and nothing beyond the camera's far plane is drawn: a chunk behind the camera or past far is skipped whole. Keep far (perspective) or size (orthographic) within the loaded chunks (WORLD_VIEW_SHORT).
• Fewer triangles far away. Each chunk's ground has levels of detail on grids of 1, 2, 4, 8 and 16 cells. The finest level a chunk is drawn with is the coarsest grid that passes within 6 cm of every vertex (and keeps its biome edges: flat ground at 1 cell where biomes meet, uneven ground at up to 2), so gentle ground costs few triangles even up close; HeightAt follows that grid. Each coarser level is drawn from lod_distance × 2^(k−1) meters on (k = 1 for the first coarser level); flat runs merge into one quad at every level. Neighbouring chunks drawn with different grids would leave cracks along their shared edge, so each level hangs a skirt below every edge that is not straight, as deep as the edge's height range. Flora follows its model's lod and draw_distance: at the model's level k a chunk draws one plant in 2^k (a seeded half, then a quarter) with that level's geometry, and none beyond the draw distance. Trees and every other entity get the same savings from their own model's lod and draw_distance (model topic).

Distances are measured from the camera to the nearest point of an entity's bounds, as seen through a 60° lens (an orthographic camera counts 0.866 × size for everything). render reports draw: the entities considered, culled, too far, and drawn at a lower level.

Inspection and tools

inspect world <name> reports, ranked by severity:

Sheet: map, the top-down map around the origin (biome colours shaded by the relief, water, features and vegetation areas as labelled circles, footprints, names).

MCP tools (CLI veduta world …), all cell-based:

Authoring loop

1. Write the prefabs (prefab topic) and the flora models (a few triangles each, with a draw_distance); inspect prefab <name> and inspect model <name> until clean.
2. Write the world's biomes, terrain (a gentle relief), scatter and sites; cook; world_map and look.
3. Shape the land with world_terrain: hills and hollows, a plain where a town will stand, lakes, a sea off a coast. Read after and places_in_water; world_map again.
4. Plant it with world_vegetation: groves of trees (prefab), grass on a biome, flowers in a meadow (model, cell, radius). Heed its warnings.
5. Add landmarks with world_place (let it choose the cell with near); world_query to check a cell you care about (its height, water, plants).
6. inspect world <name> until it reports no error; heed WORLD_CHUNK_BUDGET.
7. render { world, at } at a landmark and look (draw in the report says what the view limit and the levels of detail saved); simulate { world, at, ticks } walking across a chunk border, expecting chunk_load events and no invariant violation.
8. Keep that simulation as a scenario:

{
  "veduta": "scenario/1",
  "world": "overworld",
  "at": [0, 0],
  "seed": 1,
  "ticks": 200,
  "inputs": [ { "tick": 0, "press": ["right"] } ],
  "expect": [ { "tick": 200, "trace": "chunk_load", "count_min": 12 } ],
  "invariants": ["no_overlap:player,obstacle", "entity_count_max:2000"]
}

Example

{
  "veduta": "world/1",
  "seed": 7,
  "cell": 1,
  "chunk": 16,
  "extent": 512,
  "view": 1,
  "biome_scale": 64,
  "camera": { "type": "orthographic", "size": 12, "position": [0, 30, 0], "look_at": [0, 0, 0] },
  "light": { "direction": [-0.4, -1, -0.3], "color": "#ffffff", "ambient": "#404040" },
  "background": "#202830",
  "biomes":  [ { "name": "plain",  "ground": "grass", "weight": 3 },
               { "name": "forest", "ground": "moss",  "weight": 2 } ],
  "terrain": { "relief": 1.5, "relief_scale": 48, "lod_distance": 24 },
  "features": [ { "name": "north_hills", "kind": "hill", "cell": [10, -60], "radius": 24, "height": 9 },
                { "name": "town_ground", "kind": "plain", "cell": [126, -34], "radius": 14 },
                { "name": "mirror_lake", "kind": "lake", "cell": [-30, 20], "radius": 9, "depth": 2.5 },
                { "name": "west_sea", "kind": "sea", "cell": [-700, 0], "radius": 560, "height": -0.5 } ],
  "vegetation": [ { "name": "grass", "model": "grass_tuft", "density": 0.3, "biomes": ["plain"] },
                  { "name": "oak_grove", "prefab": "oak", "density": 0.25, "cell": [40, 10], "radius": 12 },
                  { "name": "poppies", "model": "poppy", "density": 0.5, "cell": [-12, 8], "radius": 6, "scale": [0.7, 1.3] } ],
  "scatter": [ { "prefab": "tree", "biomes": ["forest"], "density": 0.06 } ],
  "sites":   [ { "tag": "village", "prefabs": ["village"], "biomes": ["plain"], "spacing": 48, "chance": 0.5 } ],
  "places":  [ { "name": "capital", "prefab": "city", "cell": [120, -40], "rotation": 90 } ],
  "entities": [ { "name": "player", "kind": "player", "model": "hero", "material": "hero", "tags": ["player"] } ]
}