Skip to content

KNAT Application Profile: Area

Purpose

This document defines the authored profile for an Area document (simulation.area). An area declares place semantics: what shape a place has, what is continuously true in that place, what it enables, and who or what can inhabit it.

This profile is intentionally authoring-focused. It is not the runtime KNAT snapshot.

Scope

Area documents are authored inputs consumed by compiler and executor systems.

Included in this profile:

  • spatial envelope hints (space)
  • continuous baseline field conditions (environment)
  • typed activity affordances (affordances)
  • minimal hosting constraints (constraints)

Deferred to runtime KNAT surfaces:

  • occupancy
  • activity state
  • discrete signals
  • entity bindings
  • legibility/readability views

Canonical Envelope

apiVersion: net.plantange/v1
kind: simulation.area
meta: { ... }
space: { ... }
environment: { ... }
affordances: [...]
constraints: { ... }

All sections except meta are optional so legacy/meta-only docs remain valid.

Authored Model

space

Declarative spatial hinting only.

  • shape: point | circle | rectangle
  • scale: small | medium | large | epic
  • orientation (optional): vertical | horizontal

Exact dimensions, coordinate-space bindings, anchors, and adjacency edges are compile-time concerns.

environment

Continuous ambient field baselines, not event state:

  • climate: temperature, humidity, airflow, pressure
  • atmosphere: composition map, particulates, toxicity (0.0 to 1.0)
  • sensory: light_level, visibility, noise_level, odor_profile map

composition and odor_profile are semi-open numeric maps. Consumers should tolerate unknown keys and use reserved conventions where available.

affordances

Typed declarations of what activities are normal/possible in the area.

Required per affordance:

  • type (area.activity.*)
  • class (semantic grouping)

Optional:

  • inputs
  • outputs
  • salience (0.0 to 1.0)

This structure avoids untyped tag-cloud drift and supports planner/executor reasoning.

constraints

Minimal hosting envelope, not full policy logic.

  • capacity (integer | null)
  • content_types (item | agent | data)

Complex admission policy, spawn routing, and world wiring are out of scope here.

8-Surface Layer Split

topology      -> authored as space
environment   -> authored as baseline; runtime as evolving field
affordances   -> authored declarations; runtime capability registration
constraints   -> authored limits; runtime enforcement
occupancy     -> runtime only
activity      -> runtime only
signals       -> runtime only
binding       -> runtime only
legibility    -> runtime only

Relationship To Other Profiles

  • regions/KNAT.md: region-scale terrain/ecology and compiler-produced spatial graph.
  • feature/KNAT.md: compiler-spawned influence-bearing instances.
  • area/KNAT.md (this file): authored place semantics for bounded local spaces.

Examples

  • examples/domestic.yml: multi-document stream (---) with bathroom + bedroom.
  • examples/kitchen.yml: transformation + storage affordance profile.
  • examples/coliseum.yml: high-salience spectacle/combat profile.
  • examples/tunnel.yml: traversal-focused narrow passage profile.