Build Specification

System Requirements

Dependencies

pygame>=2.5.0
Pillow>=10.0.0
numpy>=1.24.0
scipy>=1.10.0  # For quantum calculations
networkx>=3.0  # For mycorrhizal networks

Architecture Overview

Core Modules

acorn/engine.py

The pure simulation engine. Completely headless, GUI-agnostic. Manages world state, entity lifecycle, physics simulation, and deterministic execution.

from acorn.engine import AcornEngine

engine = AcornEngine(seed=12345)
engine.spawn_entity("acorn", position=(50, 50))
engine.tick()  # Advance simulation by one step

acorn/iss/

Internal Simulation Stack with four bounded subsystems:

• Affect: Bounded emotional vectors in [0,1] with decay toward baseline
• Imagination: Counterfactual rollouts (1-3 steps) producing bias vectors
• Dream: Idle-time compression and statistical summaries
• Awareness: Processing states (focused/idle/overloaded/dormant)

acorn/plates.py

Holographic memory system using PNG images with embedded JSON data in LSB channels.

from acorn.plates import save_plate, load_plate

# Save universe state
save_plate(engine.get_state(), "universe_001.png")

# Load universe state
state = load_plate("universe_001.png")
engine.restore_state(state)

acorn/fractal.py

Recursive simulation capabilities. Each layer has bounded computation budget (50% of parent by default).

Web Interface Build

File Structure

AcornEngine_v7_FINAL/
├── index.html          # Landing page
├── simulator.html      # Main simulation interface
├── build-spec.html     # This document
├── future-plan.html    # Roadmap
├── use-cases.html      # Applications
├── rosetta-helix-overview.html
├── acorn/              # Python engine
│   ├── __init__.py
│   ├── engine.py
│   ├── plates.py
│   ├── fractal.py
│   └── iss/
│       ├── affect.py
│       ├── imagination.py
│       ├── dream.py
│       └── awareness.py
└── clients/
    ├── terminal.py
    └── web/            # WebSocket server

Running the Web Client

# Start WebSocket server
python -m clients.web.server --port 8080

# Open simulator.html in browser
# Connect to ws://localhost:8080

Configuration

Edit config/universe.yaml to customize simulation parameters:

world:
  size: [100, 100]
  seed: 12345

iss:
  affect:
    baseline: 0.5
    decay_rate: 0.1
  imagination:
    max_rollouts: 3
    depth: 2
  dream:
    compression_ratio: 0.01
  awareness:
    default_state: "idle"

fractal:
  max_depth: 5
  budget_decay: 0.5

quantum:
  coherence_threshold: 0.3
  decoherence_rate: 0.01
  entanglement_distance: 50

Safety & Ethics

• Bounded Computation: All simulation has hard limits
• Deterministic: Same inputs = same outputs
• Logged: Every change is recorded
• Reversible: Full state history available
• No Autonomy: Engine only responds to proposals