README: World Brand
Profile version: net.plantange/v1
Kind: world
Surface root: world::<world_id>/
Overview
A world brand is the outermost simulation authority. It owns planetary geometry, the seeds that generate all climate and ocean data, the global event stream, the transport corridor network, and the ownership registry that admits regions into the simulation.
Everything else — regions, biologics, producers, games — exists within a world. The world provides the spatial coordinate system every other brand relies on (WorldCoord, WorldCell), and the baseline environmental conditions every region receives at registration.
World signals are deterministic positional pure functions of (seed, WorldCoord, frame). The same seed + the same coordinate + the same frame always produces the same value, on any host. Consumers must not treat world climate/ocean values as mutable simulation state.
Who Produces This Surface
The world brand object is compiled by the environment from a world spec document (spec.json). At startup, the brand validates its spatial claims, emits climate baselines to each registering region, and begins broadcasting the 24-path signal set each frame.
Corresponding Rust type: WorldBrand trait in janet-brand/src/world/brand.rs.
Surface Organisation
world::<world_id>/
identity/
title
description/<lang>
geometry/
model
executor_chunk_cells
climate/
seed
ocean/
terrain_seed
tide_frame
events/
<event_id>/
kind
intensity
impacts/<region_id>/
severity
mobility_pressure
resource_stress
transport/
nodes/<node_id>/
coord/x
coord/y
region_id
segments/<segment_id>/
start_node
end_node
mode
length_km
condition
regions/
<region_id>/
claim/
origin_x origin_y width height
climate_baselines/
<key>
signals/
<region_id>/
climate/ temperature rainfall wind elevation
ocean/ depth salinity sea_temperature current_speed current_bearing tide_height
seasonal/ storm_intensity amplitude
events/
storm/ intensity severity mobility_pressure resource_stress
seasonal_cycle/ intensity severity mobility_pressure resource_stress
migration_wave/ intensity severity mobility_pressure resource_stress
spec/
ref
genome
engine/
name version
view
frame
Key Properties
Geometry (geometry/)
Fixed at compile time from GeometryModel in the spec. Three models:
| Value | Meaning |
|---|---|
flat_grid |
Euclidean 2D grid — simplest option, no wrap |
cylindrical |
Wraps on the x-axis, open on y — suitable for a planet strip |
spherical |
Full spherical wrapping — highest spatial fidelity |
executor_chunk_cells (default 16) controls executor streaming granularity.
Climate Seed (climate/seed)
The climate_seed from the spec. Present so consumers can independently verify deterministic output or replay a specific world state. All climate values at any coordinate are derived from this seed.
Ocean Terrain Seed and Tide Frame
Underwater positional fields (depth, salinity, current) derive from terrain_seed. Tidal height is frame-dependent — tide_frame records the frame at which the snapshot was computed so consumers can replay it.
The tidal model is a two-component superposition:
- Semidiurnal M2: period 744 frames
- Diurnal K1: period 1488 frames
Transport Network (transport/)
Structural — declared in brand code and validated at startup. The transport surface in KNAT is topology only, not live route state. Live routing and traversal is executor responsibility.
Segment condition [0.0, 1.0] represents infrastructure health. Poor condition scales traversal time, energy cost, and risk. Actual traversal computations are performed by the executor via SegmentTraversal.
Registered Regions (regions/)
Populated when regions submit spatial claims via RegionRegistrationInterface. Contains only the world-side receipt: the accepted claim rectangle and the climate baselines delivered at registration.
For full environment detail, join to the corresponding RegionRuntime surface.
Signals (signals/<region_id>/)
The canonical 24-path signal set emitted by WorldSignalEmitter each frame. All 24 values per region are deterministic from seed + frame. Signal paths follow the pattern:
brand::world/<category>/<region_id>/<field>
Four categories and their fields:
| Category | Fields |
|---|---|
climate |
temperature, rainfall, wind, elevation |
ocean |
depth, salinity, sea_temperature, current_speed, current_bearing, tide_height |
seasonal |
storm_intensity, amplitude |
events/storm |
intensity, severity, mobility_pressure, resource_stress |
events/seasonal_cycle |
intensity, severity, mobility_pressure, resource_stress |
events/migration_wave |
intensity, severity, mobility_pressure, resource_stress |
Cross-Domain Joins
| Join | Key | Description |
|---|---|---|
| world → region | region_id |
World delivers climate baselines at region registration; ongoing signals flow each frame via the 24-path set. Region joins back as registered_regions/<region_id>/. |
| world → producer | world_id |
A producer's chem_prefix is world::<world_id>/. The world frame clock is the root tick all producers advance against. |
| world → game | world_id |
Games inscribed in a world reference world_id for spatial claims and climate context. |
| world → biologic | world_id |
Biologics moving across regions receive climate and event pressure from world signals. |
| signals → any consumer | region_id |
Any brand consuming a region should poll world::<world_id>/signals/<region_id>/ for environmental input rather than duplicating the deterministic computation. |
Responsibilities Boundary
The world enforces a three-way responsibility split:
WorldOwned — GlobalGeometry, SpatialArbitration, ClimateBaselines, OceanSystems, PlanetaryEvents
RegionOwned — LocalTerrain, LocalEconomy, LocalEvents, LocalAgents
ExecutorOwned — StreamingChunks, PhysicsStep, AgentScheduling
The world surface in KNAT only exposes WorldOwned outputs. Never write executor or region-owned state into this surface.
MVP Presence
A minimal valid world KNAT snapshot must include:
id,frame,engine,viewidentity.titlegeometry.modelclimate.seedocean.terrain_seed,ocean.tide_frameevents(may be empty array)transport.nodes,transport.segments(may be empty objects)regions(at least one registered region)signals(all 24 paths for each registered region)spec.ref,spec.genome
Example: Toytown World
{
"id": "toytown",
"spec": {
"ref": "file://defs/world/toytown.json",
"genome": "deadbeef01234567"
},
"engine": { "name": "janet-executor", "version": "0.4.0" },
"view": "full",
"frame": 1440,
"identity": {
"title": "Toytown",
"description": {
"en": "A self-sustaining tutorial world with a train economy."
}
},
"geometry": {
"model": "flat_grid",
"executor_chunk_cells": 16
},
"climate": {
"seed": 12345678901234
},
"ocean": {
"terrain_seed": 98765432109876,
"tide_frame": 1440
},
"events": [
{
"event_id": "evt_storm_001",
"kind": "storm",
"intensity": 0.62,
"impacts": {
"downtown": {
"severity": 0.55,
"mobility_pressure": 0.71,
"resource_stress": 0.38
},
"outskirts": {
"severity": 0.29,
"mobility_pressure": 0.44,
"resource_stress": 0.18
}
}
}
],
"transport": {
"nodes": {
"central_station": {
"coord": { "x": 32, "y": 48 },
"region_id": "downtown"
},
"rail_hub_north": {
"coord": { "x": 32, "y": 80 },
"region_id": "outskirts"
}
},
"segments": {
"main_line": {
"start_node": "central_station",
"end_node": "rail_hub_north",
"mode": "road",
"length_km": 14.2,
"condition": 0.85,
"base_time_hours": 0.35,
"energy_cost": 1.2,
"risk": 0.05
}
}
},
"regions": {
"downtown": {
"claim": { "origin_x": 16, "origin_y": 32, "width": 32, "height": 32 },
"climate_baselines": {
"temperature": 12.4,
"rainfall": 0.51,
"wind": 0.33
}
},
"outskirts": {
"claim": { "origin_x": 16, "origin_y": 64, "width": 32, "height": 32 },
"climate_baselines": {
"temperature": 10.8,
"rainfall": 0.47,
"wind": 0.41
}
}
},
"signals": {
"downtown": {
"climate": {
"temperature": 12.4,
"rainfall": 0.51,
"wind": 0.33,
"elevation": 0.22
},
"ocean": {
"depth": 0.0,
"salinity": 0.0,
"sea_temperature": 0.0,
"current_speed": 0.0,
"current_bearing": 0.0,
"tide_height": 0.0
},
"seasonal": { "storm_intensity": 0.62, "amplitude": 0.45 },
"events": {
"storm": {
"intensity": 0.62,
"severity": 0.55,
"mobility_pressure": 0.71,
"resource_stress": 0.38
},
"seasonal_cycle": {
"intensity": 0.0,
"severity": 0.0,
"mobility_pressure": 0.0,
"resource_stress": 0.0
},
"migration_wave": {
"intensity": 0.0,
"severity": 0.0,
"mobility_pressure": 0.0,
"resource_stress": 0.0
}
}
},
"outskirts": {
"climate": {
"temperature": 10.8,
"rainfall": 0.47,
"wind": 0.41,
"elevation": 0.3
},
"ocean": {
"depth": 0.0,
"salinity": 0.0,
"sea_temperature": 0.0,
"current_speed": 0.0,
"current_bearing": 0.0,
"tide_height": 0.0
},
"seasonal": { "storm_intensity": 0.29, "amplitude": 0.38 },
"events": {
"storm": {
"intensity": 0.62,
"severity": 0.29,
"mobility_pressure": 0.44,
"resource_stress": 0.18
},
"seasonal_cycle": {
"intensity": 0.0,
"severity": 0.0,
"mobility_pressure": 0.0,
"resource_stress": 0.0
},
"migration_wave": {
"intensity": 0.0,
"severity": 0.0,
"mobility_pressure": 0.0,
"resource_stress": 0.0
}
}
}
}
}