Skip to content

README: Feature

Profile version: net.plantange/v1 Kind: feature_instance Surface root: region::<region_id>/features/<pattern_id>/<instance_index>/

What is a Feature?

A Feature is an environmental element spawned by the region compiler. It is the primary mechanism by which a region spec produces addressable, interactive world content beyond the procedural field layer.

Where an anchor is singular and deterministically placed (the summit, the harbor mouth, the shoreline), a feature is plural and probabilistic — the compiler spawns between min and max instances per pattern using a genome-derived distribution.

At runtime, every spawned feature instance is:

  • Located — assigned a LocationRef (stable spatial address in the world)
  • Shaped — given a CellGeometry (Point, Circle, or Rectangle) describing its spatial extent
  • Influential — its influence fields are applied to the cells it occupies

Features are the things agents can navigate to, act on, harvest from, or shelter in. They are the bridge between the statistical region spec and addressable world geography.

Three Concepts

Feature pattern  — authoring-time declaration: type, presence, instances, influence
Feature instance — one compiled, placed occurrence of a pattern
LocationRef      — the stable spatial address assigned to each instance

One pattern → N instances. Each instance has its own location_id.

Feature vs Anchor

Property Anchor Feature
Cardinality Singular (0 or 1 per region) Plural (min–max instances)
Placement Deterministic — defined by region topology Probabilistic — genome-distributed within scope
Scope Region-level Region-level or nested under an anchor
Typical examples shoreline, harbor_mouth, summit, river_source peat bogs, marinas, villages, mudflats, headlands
GraphSpec node kind NodeKind::Anchor Compiled into cells; not a graph node
LocationRef? Yes — one stable cell Yes — one per instance

Nested features (features declared inside an anchor) are constrained to the anchor's domain. Their parent_cell_id in the LocationRef points to the anchor's cell. Region-scope features are distributed across the full field.

Surface Organisation

region::<region_id>/features/<pattern_id>/<instance_index>/
  id                    — stable: '<region_id>.<pattern_id>.<instance_index>'
  feature_type          — dot-namespaced type (e.g. feature.infrastructure.harbor)
  pattern_id            — source pattern id from the region spec
  instance_index        — 0-based sibling index
  region_id
  anchor_id             — present if this is a nested (anchor-scoped) feature
  location/
    location_id         — stable spatial address
    coordinate_space    — local | world | named:<space>
    parent_cell_id      — anchor's cell (nested features) or null
  geometry/
    shape               — point | circle{radius} | rectangle{width, height}
    anchor              — optional origin offset {x, y}
  influence/
    <trait_key>         — value: string | number | string[]
  spec/
    ref    genome
  engine/
    name    version
  view
  frame

Key Properties

Feature Type (feature_type)

Dot-namespaced type string that drives compiler dispatch and runtime capability registration:

  • feature.terrain.* — landform elements (peat_bog, granite_headlands, mudflat, boulder_field)
  • feature.infrastructure.* — human-built elements (harbor, marina, mill, road_junction)
  • feature.settlement.* — habitation clusters (village, camp, market, welcome_center, outpost)

The type string determines which runtime systems claim this feature (e.g. navigation, economy, ecology).

Presence and Instances

Presence is sampled first — if the presence check fails, zero instances are spawned for this pattern. If presence passes, instances.min..=instances.max instances are placed using genome-derived noise. A feature without instances is singular (exactly one instance when present).

Location (location/)

The LocationRef assigned at compile time is the stable address used by all downstream systems — agent navigation, economic targeting, quest anchoring. It persists across frames throughout the region's lifetime (it changes only if the region is recompiled with a new genome).

parent_cell_id is set when the feature is nested under an anchor. This constrains the instance to cells within the anchor's influence sphere, not the whole region field.

Geometry (geometry/)

Type-appropriate default shapes:

  • Point — waypoints, spawn markers, resource nodes
  • Circle — harbors, settlements, bogs (radial influence)
  • Rectangle — built structures, mudflats, headlands

The compiler may derive defaults from the feature_type, but the runtime shape is always authoritative.

Influence (influence/)

Active environmental signals emitted into the cell field. These match keys from the region's trait schema. A harbor emits water_access: high, fish_density: reduced, disturbance: high. A peat bog emits moisture: retained, soil: peat, acidity: high. The field radiates outward through the geometry shape.

Lifecycle

Authoring spec
  feature pattern (id, type, presence, instances, influence)
        │
        ▼
Region compiler
  presence roll → N instances
  genome-distributed placement → WorldCoord per instance
  CellGeometry assigned
  LocationRef constructed (location_id, coordinate_space, parent_cell_id)
        │
        ▼
Runtime KNAT surface
  feature_instance per N
  each with stable id, location, geometry, influence
        │
        ▼
Downstream systems
  agent navigation / economic targeting / quest anchoring

MVP Presence

A minimal valid FeatureInstance KNAT snapshot:

  • id, frame, engine, view
  • feature_type, pattern_id, instance_index
  • region_id
  • location.location_id, location.coordinate_space
  • geometry.shape
  • influence (may be empty object)
  • spec.ref, spec.genome

Example: Peat Bog Instance (region-scope, plural)

{
  "id": "pictou.old_peat_bog.3",
  "spec": {
    "ref": "file://defs/regions/pictou/region.yml",
    "genome": "04a2fc988f4dee38"
  },
  "engine": { "name": "janet-executor", "version": "0.4.0" },
  "view": "full",
  "frame": 144,
  "feature_type": "feature.terrain.peat_bog",
  "pattern_id": "old_peat_bog",
  "instance_index": 3,
  "region_id": "pictou",
  "anchor_id": null,
  "location": {
    "location_id": "pictou.old_peat_bog.3",
    "coordinate_space": "local",
    "parent_cell_id": null
  },
  "geometry": {
    "shape": { "circle": { "radius": 0.4 } }
  },
  "influence": {
    "moisture": "retained",
    "soil": ["peat"],
    "acidity": "high",
    "decomposition": "slow"
  }
}

Example: Working Harbor Instance (anchor-nested, plural)

{
  "id": "pictou.working_harbor.1",
  "spec": {
    "ref": "file://defs/regions/pictou/region.yml",
    "genome": "04a2fc988f4dee38"
  },
  "engine": { "name": "janet-executor", "version": "0.4.0" },
  "view": "full",
  "frame": 144,
  "feature_type": "feature.infrastructure.harbor",
  "pattern_id": "working_harbor",
  "instance_index": 1,
  "region_id": "pictou",
  "anchor_id": "harbor_mouth",
  "location": {
    "location_id": "pictou.harbor_mouth.working_harbor.1",
    "coordinate_space": "local",
    "parent_cell_id": "pictou.harbor_mouth"
  },
  "geometry": {
    "shape": { "circle": { "radius": 1.2 } }
  },
  "influence": {
    "water_access": "high",
    "fish_density": "reduced",
    "disturbance": "high"
  }
}