204 lines
5.0 KiB
Markdown
204 lines
5.0 KiB
Markdown
# Tile Registry Schema
|
|
|
|
## Purpose
|
|
|
|
The tile registry is the authoritative operational index for terrain tiles. It
|
|
tracks what tiles exist, where they are, which source data generated them, what
|
|
package version is published, and whether the tile is ready for clients.
|
|
|
|
The first implementation only needs the Ground Zero tile and neighbors. The
|
|
schema is intentionally shaped so it can scale toward hundreds of millions of
|
|
possible 1 km tiles later.
|
|
|
|
## Prototype Grid
|
|
|
|
For the MVP, the tile key uses UTM zone 10N and the lower-left 1 km grid corner.
|
|
|
|
```text
|
|
gz_us_ca_pacifica_utm10n_e544_n4160
|
|
```
|
|
|
|
Fields encoded in the prototype ID:
|
|
|
|
- Location family: `gz_us_ca_pacifica`
|
|
- Projection: `utm10n`
|
|
- Easting kilometer: `e544`
|
|
- Northing kilometer: `n4160`
|
|
|
|
The final global grid is still a design decision. The MVP schema keeps explicit
|
|
projection and metric bounds so tiles can be migrated later if the global index
|
|
changes.
|
|
|
|
## Tile Status
|
|
|
|
Allowed status values:
|
|
|
|
- `unknown`: placeholder exists, no source work started.
|
|
- `queued`: selected for source lookup or generation.
|
|
- `source_data_found`: required source datasets are identified.
|
|
- `generated`: terrain package generated but not validated.
|
|
- `validated`: QA checks passed.
|
|
- `packaged`: client/server package created.
|
|
- `published`: package is available to clients.
|
|
- `deprecated`: superseded by a newer tile version.
|
|
- `blocked`: source or generation issue needs manual review.
|
|
|
|
## Core Tables
|
|
|
|
### `terrain_tiles`
|
|
|
|
Tracks one logical 1 km tile.
|
|
|
|
Required fields:
|
|
|
|
- `tile_id`
|
|
- `grid_scheme`
|
|
- `projection`
|
|
- `utm_zone`
|
|
- `easting_min_m`
|
|
- `northing_min_m`
|
|
- `easting_max_m`
|
|
- `northing_max_m`
|
|
- `tile_size_m`
|
|
- `center_latitude`
|
|
- `center_longitude`
|
|
- `status`
|
|
- `biome_primary`
|
|
- `generation_version`
|
|
- `package_version`
|
|
- `created_at`
|
|
- `updated_at`
|
|
|
|
Optional solar/time fields should be stored only for tiles that have real source
|
|
work or a published package, not for every theoretical 1 km square. The
|
|
Earth-scale registry may eventually contain hundreds of millions of possible
|
|
tiles, so solar metadata is generated on demand for existing/active tiles.
|
|
|
|
Optional growing-zone fields follow the same rule. Crop viability, frost-free
|
|
windows, and growing-season length are generated only for tiles with real source
|
|
work or published packages and explicit growing-zone data.
|
|
|
|
### `terrain_tile_neighbors`
|
|
|
|
Tracks adjacency for stitching and prefetching.
|
|
|
|
Required fields:
|
|
|
|
- `tile_id`
|
|
- `direction`
|
|
- `neighbor_tile_id`
|
|
|
|
### `terrain_tile_sources`
|
|
|
|
Tracks datasets used or intended for each tile.
|
|
|
|
Required fields:
|
|
|
|
- `tile_id`
|
|
- `source_kind`
|
|
- `source_name`
|
|
- `source_uri`
|
|
- `license_name`
|
|
- `source_version`
|
|
- `coverage_status`
|
|
|
|
### `terrain_tile_solar_metadata`
|
|
|
|
Tracks local time-zone and solar lookup metadata for tiles that actually exist
|
|
in the registry as source-backed, generated, validated, packaged, or published
|
|
tiles.
|
|
|
|
Required fields:
|
|
|
|
- `tile_id`
|
|
- `time_zone_id`
|
|
- `standard_utc_offset_hours`
|
|
- `daylight_utc_offset_hours`
|
|
- `solar_model`
|
|
- `generated_at`
|
|
|
|
### `terrain_tile_growing_season_metadata`
|
|
|
|
Tracks the active growing zone and season window for source-backed tiles. Crop
|
|
systems use this table to decide whether a crop with a given maturity time can
|
|
finish before the represented region's growing season closes.
|
|
|
|
Required fields:
|
|
|
|
- `tile_id`
|
|
- `growing_zone_label`
|
|
- `climate_profile`
|
|
- `growing_season_start_day`
|
|
- `growing_season_end_day`
|
|
- `frost_free_days`
|
|
- `min_average_growing_temp_c`
|
|
- `crop_safety_buffer_days`
|
|
- `data_basis`
|
|
- `generated_at`
|
|
|
|
### `terrain_tile_packages`
|
|
|
|
Tracks generated downloadable packages.
|
|
|
|
Required fields:
|
|
|
|
- `package_id`
|
|
- `tile_id`
|
|
- `package_version`
|
|
- `unreal_engine_version`
|
|
- `world_partition_ready`
|
|
- `package_uri`
|
|
- `content_hash`
|
|
- `package_size_bytes`
|
|
- `created_at`
|
|
- `published_at`
|
|
|
|
### `terrain_tile_generation_jobs`
|
|
|
|
Tracks generation pipeline work.
|
|
|
|
Required fields:
|
|
|
|
- `job_id`
|
|
- `tile_id`
|
|
- `job_type`
|
|
- `status`
|
|
- `requested_at`
|
|
- `started_at`
|
|
- `finished_at`
|
|
- `log_uri`
|
|
- `error_summary`
|
|
|
|
## Separation Of Concerns
|
|
|
|
Terrain tile state should be separate from player-made world state.
|
|
|
|
Terrain registry owns:
|
|
|
|
- Source terrain and water data.
|
|
- Generated landscape package.
|
|
- Biome/resource hints.
|
|
- Tile status and package version.
|
|
- Client cache/version compatibility.
|
|
|
|
Player/world persistence owns:
|
|
|
|
- Player inventory, stats, and position.
|
|
- Placed structures.
|
|
- Resource depletion, if needed.
|
|
- Claims, settlements, containers, and ownership.
|
|
- Tile-local gameplay changes.
|
|
|
|
This separation lets us regenerate terrain tiles later without overwriting
|
|
player-built history.
|
|
|
|
## First Validation Rules
|
|
|
|
- Tile bounds must be exactly 1000 m x 1000 m in the projected coordinate system.
|
|
- Center latitude/longitude must fall inside tile bounds.
|
|
- Every published tile must have at least one elevation source.
|
|
- Every published tile must have a generation version and package version.
|
|
- Neighbor records must be reciprocal once adjacent tiles are generated.
|
|
- A tile package cannot be `published` until it is `validated`.
|
|
- Terrain package hash must change when package version changes.
|