World Model

World Model

ByteBiota organisms inhabit a one-dimensional toroidal "soup" that combines resources, environmental signals, shared storage, and rotating task challenges. This document describes the mechanics implemented in src/bytebiota/environment.py and how the distributed runtime drives them during execution.

Spatial Topology {#spatial-topology}

  • The environment is a ring buffer of length cells (default 4096) configured via EnvironmentConfig.length (src/bytebiota/config.py:61).
  • Addressing wraps automatically using modulo arithmetic so organisms can traverse indefinitely (src/bytebiota/environment.py:46).
  • Each cell stores:
  • Resource units — consumable integers capped at max_resource (src/bytebiota/environment.py:22).
  • Signal intensity — floating-point values used for inter-organism communication (src/bytebiota/environment.py:38).

Resource Field {#resource-field}

  • Initial distribution is either random or gradient-driven depending on enable_gradients (src/bytebiota/environment.py:32).
  • Organisms gather resources through the HARVEST_ENERGY opcode, which calls Environment.harvest() to convert local resources into energy (src/bytebiota/environment.py:59).
  • Worker executors regenerate resources every resource_regen_interval steps by incrementing random cells up to the cap (src/bytebiota/worker/executor.py, src/bytebiota/environment.py:66).
  • Resource scarcity encourages movement and competition; tuning resource_regen_amount adjusts replenishment rate.

Signal Field {#signal-field}

  • Signals accumulate when organisms execute EMIT_SIGNAL; intensities are added at the wrapped address (src/bytebiota/environment.py:52).
  • Global decay applies every signal_decay_interval steps by multiplying values with signal_decay_factor (src/bytebiota/worker/executor.py, src/bytebiota/environment.py:72).
  • Signals can encode pheromone-like trails or coordination cues, especially when gradients are active.

Shared Storage {#shared-storage}

  • Byte-addressable storage array of size storage_slots (default 256) retains values across simulation steps (src/bytebiota/environment.py:42).
  • READ_STORAGE and WRITE_STORAGE opcodes access slots with wraparound indexing and return the previous value on writes (src/bytebiota/environment.py:78).
  • Storage serves as long-lived shared memory for colonies or as a communication scratchpad between species.

Task System {#task-system}

  • Tasks model external challenges that provide bonus energy when solved. Organisms submit values via SUBMIT_TASK, invoking Environment.submit_task() (src/bytebiota/environment.py:108).
  • The task pipeline rotates through:
  • Exact match — match task_value to earn task_reward (default 60).
  • Logic challenges — even numbers, powers of two, or primes when task_value is 0–2 (src/bytebiota/environment.py:137).
  • Pattern challenges — Fibonacci or sequential patterns when task_value is 3–4 (src/bytebiota/environment.py:157).
  • Successful submissions grant energy through the LocalExecutor’s task handling (src/bytebiota/worker/executor.py), and optionally attempt bonuses for failures if configured.
  • After each success the environment rolls a new task, with probabilities 70% match, 20% logic, 10% pattern (src/bytebiota/environment.py:182).

Gradients & Hotspots {#gradients}

  • When gradients are enabled, initial resources follow sine, linear, or hotspot distributions controlled by gradient_type (src/bytebiota/environment.py:204).
  • Hotspot mode seeds multiple localized peaks whose intensity decays with distance (src/bytebiota/environment.py:212).
  • Sine gradients can animate over time: update_gradients() shifts the wave phase based on gradient_period, creating moving resource bands (src/bytebiota/environment.py:224).
  • Parameters exposed through EnvironmentConfig:
  • gradient_amplitude, hotspot_count, hotspot_size, and gradient_period (src/bytebiota/config.py:72).
  • Combined with regeneration and decay settings they shape long-term ecosystem niches.

Integration with the distributed runtime {#environment-integration}

  • The server constructs a shared Environment so every worker operates against the same resource field (src/bytebiota/server/server.py).
  • LocalExecutor.execute_assignment() applies regeneration, decay, and gradient updates on its cadence to keep worker snapshots aligned with server expectations (src/bytebiota/worker/executor.py).
  • Task submissions feed back into organism energy reserves and priority boosts, influencing scheduler dynamics (src/bytebiota/worker/executor.py).
  • Storage utilization metrics and average resource/signal levels surface via the analytics and monitoring APIs exposed by the server services.

Configuration Checklist {#environment-config}

Update .env / configuration to shape the world:
- ENV_LENGTH, ENV_MAX_RESOURCE, ENV_REGEN_INTERVAL, ENV_REGEN_AMOUNT.
- ENV_SIGNAL_DECAY_INTERVAL, ENV_SIGNAL_DECAY_FACTOR.
- ENV_TASK_REWARD, ENV_STORAGE_SLOTS.
- Gradient toggles: ENV_ENABLE_GRADIENTS, ENV_GRADIENT_TYPE, ENV_GRADIENT_AMPLITUDE, ENV_HOTSPOT_COUNT, ENV_HOTSPOT_SIZE, ENV_GRADIENT_PERIOD (env.example).

Adjusting these parameters directly changes selection pressures—use them when designing experiments or crafting scenario playbooks.

Environment API {#environment}

Environment (src/bytebiota/environment.py) exposes sensing, signaling, storage, harvesting, and task submission primitives for organisms. Capture interface changes, new opcodes, or parameter interactions here so simulation code and documentation remain synchronized.