Agent Simulation Framework #5

New Issue

2025-12-17T01:09:12Z

siennathesane commented

2025-12-17 01:09:12 +00:00

(Migrated from github.com)

Description

In order to create a living, breathing village of 500 NPCs that feel alive and autonomous,
as players exploring the world of Aspen,
we need a comprehensive agent simulation framework that enables emergent behavior from simple generic rules.

Business Value:
This is the core of what makes Aspen unique—a village where every inhabitant has their own life, relationships, and routines that continue whether players are watching or not. The baker wakes before dawn, bakes bread, serves customers, and returns home. When she gets sick, her apprentice covers. When her child starts school, her mornings shift. These aren't scripted events—they emerge from the interaction of simple systems.

Success means Dwarf Fortress depth on iPad hardware, with multiplayer synchronization that "just works."

Scope

In Scope:

Four-layer architecture (Life Arc, Daily Schedule, Behavior Tree, World Substrate)
Entity composition system (Lifecycle, PhysicalPresence, Needs, Instincts, Roles, Autonomy, Relationships, Membership, etc.)
Institution system (workplaces, schools, households coordinating multiple entities)
Relationship system (bonds that enable coordination without real-time negotiation)
Condition system (temporary modifiers like sickness, pregnancy, grief that affect all layers)
Tool and capability system (entities provide capabilities to operators)
Production workflow system (multi-step processes like baking, crafting)
Performance architecture (simulation tiers, discrete event simulation, wake queue)
Networking and synchronization (CRDT-based, spatial ownership, entity ownership)
Wildlife simulation (mode-based behavior for non-sapient entities)

Out of Scope:

Specific content (individual villager personalities, specific recipes, etc.)
Visual representation (animation, rendering)—this is pure simulation
Player character control—agents are NPCs only
Full ecology simulation—wildlife is simplified
Advanced AI/ML techniques—we want simple, understandable, debuggable rules

Success Criteria

Scenario: Village comes alive
  Given 500 entities exist simultaneously with positions, states, and histories
  When players observe the village over multiple in-game days
  Then entities follow believable daily routines
  And relationships form and evolve through interaction
  And institutions coordinate workers without explicit communication
  And emergent behaviors occur from generic rule interactions
  And the simulation runs at stable framerates on iPad hardware

Scenario: Multiplayer synchronization works seamlessly
  Given 2-4 peers connected in a multiplayer session
  When entities are owned by different peers based on proximity
  Then all peers see consistent entity states and behaviors
  And institutions coordinate across peer boundaries
  And no desync or divergence occurs
  And ownership transitions are seamless

Scenario: Performance scales efficiently
  Given 500 entities in various simulation tiers
  When only nearby entities (30-50) run full behavior trees
  And background entities (400) use interpolation with wake events
  Then the simulation runs at 60 FPS on iPad
  And promotion/demotion between tiers is seamless
  And discrete event simulation minimizes unnecessary computation

Metrics:

500 entities simulated simultaneously
60 FPS on iPad Pro with full simulation load
Background entities consume <5% of frame budget
Multiplayer sync latency <100ms for state propagation
Zero desyncs in 1-hour multiplayer sessions

Features & Tasks

Layer 1: Foundation

Entity composition system with component categories
Lifecycle state machine for all entity types
PhysicalPresence component with position and movement
Needs system (biological and psychological drives)
Instincts system (species-typical behaviors)

Layer 2: Life Arc System

Life arc state machines (Child → Adolescent → Adult → Elder)
Autonomy gradient implementation
Life arc transitions and triggers
Schedule authority model

Layer 3: Schedule System

Daily schedule generation from roles and personality
Schedule authority (autonomous, external, partial)
Shared commitments between related entities
Schedule regeneration on condition changes

Layer 4: Behavior Tree System

Behavior tree framework and evaluation
Activity-specific behavior trees (Work, Leisure, etc.)
Need-driven behavior prioritization
Condition modifiers affecting behavior

Layer 5: World Substrate

Substrate layer types (substances, temperature, light, sound, air quality, contagion)
Trigger volume system for spatial events
Generic substance transfer and consumption
Environmental effects on entities

Layer 6: Institutions

Institution entity type with Governance, Resources, Reputation
Shared blackboard state for coordination
Worker schedule template generation
Institution lifecycle (Founded → Struggling → Established → etc.)

Layer 7: Relationships

Relationship state and evolution
Bond types (Romantic, Familial, Friendship, Professional, Caretaking)
Coordination levels (None → AdHoc → Recurring → Cohabiting → Dependent)
Relationship effects on all simulation layers

Layer 8: Conditions

Condition system with severity and duration
Condition effects (need modifiers, capability modifiers, schedule overrides, behavior modifiers)
Contagion system for spreading conditions
Condition progression and recovery

Layer 9: Tools & Capabilities

Capability types (Movement, Communication, Transformation, Force, Storage, etc.)
Tool operator modes (Inhabit, Wield, Station, Wear)
Tools as institutional resources
Tool quality affecting output

Layer 10: Production Workflows

Batch entity system for multi-step processes
Recipe and phase system
Interruptible work with state persistence
Quality accumulation from skill, tool, and materials

Layer 11: Performance Architecture

Simulation tier system (Attached, Nearby, Background, Wildlife)
Tier promotion/demotion based on player proximity
Discrete event simulation and wake queue
Wildlife mode-based behavior

Layer 12: Networking & Sync

CRDT-based state synchronization for slow-changing layers
Behavior tree outcome synchronization
Entity ownership model
Spatial ownership for substrate
Institution state synchronization across peers

Dependencies & Risks

Dependencies:

CRDT sync system (libmarathon) must be robust and performant
Bevy ECS for entity composition
Spatial indexing for proximity queries and trigger volumes
Pathfinding system for entity movement

Risks:

Performance on iPad: 500 entities may exceed hardware limits
- Mitigation: Aggressive tier system, discrete event sim, profiling early
Emergent behavior bugs: Generic systems may combine in unexpected/broken ways
- Mitigation: Extensive testing, clear invariants, ability to disable subsystems
Multiplayer desyncs: Complex state across peers may diverge
- Mitigation: Deterministic schedule generation, outcome-based sync, reconciliation
Complexity explosion: Many interacting systems may become unmaintainable
- Mitigation: Clear layer separation, good documentation, incremental implementation
Content creation burden: System may require massive content investment to feel alive
- Mitigation: Focus on generic rules that recombine, not hand-authored content

Additional Context

See RFC 0006 for full architectural details (will be moved to marathon repo).

This epic represents the largest single feature and will likely span multiple months. The implementation should be incremental—each layer should be validated in isolation before adding the next. Start with foundation, add one layer at a time, and continuously test performance and emergent behavior.

The key insight is temporal scale separation: slow-changing state (life arcs) uses different update strategies than fast-changing state (behavior trees). By layering these concerns, we can update slow things slowly and fast things only when necessary.

Philosophy: Generic composition over special cases. Emergence over authorship. Consequences without failure. Existence is cheap; cognition is expensive.

## Description In order to create a living, breathing village of 500 NPCs that feel alive and autonomous, as players exploring the world of Aspen, we need a comprehensive agent simulation framework that enables emergent behavior from simple generic rules. **Business Value:** This is the core of what makes Aspen unique—a village where every inhabitant has their own life, relationships, and routines that continue whether players are watching or not. The baker wakes before dawn, bakes bread, serves customers, and returns home. When she gets sick, her apprentice covers. When her child starts school, her mornings shift. These aren't scripted events—they emerge from the interaction of simple systems. Success means Dwarf Fortress depth on iPad hardware, with multiplayer synchronization that "just works." ## Scope **In Scope:** - Four-layer architecture (Life Arc, Daily Schedule, Behavior Tree, World Substrate) - Entity composition system (Lifecycle, PhysicalPresence, Needs, Instincts, Roles, Autonomy, Relationships, Membership, etc.) - Institution system (workplaces, schools, households coordinating multiple entities) - Relationship system (bonds that enable coordination without real-time negotiation) - Condition system (temporary modifiers like sickness, pregnancy, grief that affect all layers) - Tool and capability system (entities provide capabilities to operators) - Production workflow system (multi-step processes like baking, crafting) - Performance architecture (simulation tiers, discrete event simulation, wake queue) - Networking and synchronization (CRDT-based, spatial ownership, entity ownership) - Wildlife simulation (mode-based behavior for non-sapient entities) **Out of Scope:** - Specific content (individual villager personalities, specific recipes, etc.) - Visual representation (animation, rendering)—this is pure simulation - Player character control—agents are NPCs only - Full ecology simulation—wildlife is simplified - Advanced AI/ML techniques—we want simple, understandable, debuggable rules ## Success Criteria ```gherkin Scenario: Village comes alive Given 500 entities exist simultaneously with positions, states, and histories When players observe the village over multiple in-game days Then entities follow believable daily routines And relationships form and evolve through interaction And institutions coordinate workers without explicit communication And emergent behaviors occur from generic rule interactions And the simulation runs at stable framerates on iPad hardware Scenario: Multiplayer synchronization works seamlessly Given 2-4 peers connected in a multiplayer session When entities are owned by different peers based on proximity Then all peers see consistent entity states and behaviors And institutions coordinate across peer boundaries And no desync or divergence occurs And ownership transitions are seamless Scenario: Performance scales efficiently Given 500 entities in various simulation tiers When only nearby entities (30-50) run full behavior trees And background entities (400) use interpolation with wake events Then the simulation runs at 60 FPS on iPad And promotion/demotion between tiers is seamless And discrete event simulation minimizes unnecessary computation ``` **Metrics:** - 500 entities simulated simultaneously - 60 FPS on iPad Pro with full simulation load - Background entities consume <5% of frame budget - Multiplayer sync latency <100ms for state propagation - Zero desyncs in 1-hour multiplayer sessions ## Features & Tasks ### Layer 1: Foundation - [ ] Entity composition system with component categories - [ ] Lifecycle state machine for all entity types - [ ] PhysicalPresence component with position and movement - [ ] Needs system (biological and psychological drives) - [ ] Instincts system (species-typical behaviors) ### Layer 2: Life Arc System - [ ] Life arc state machines (Child → Adolescent → Adult → Elder) - [ ] Autonomy gradient implementation - [ ] Life arc transitions and triggers - [ ] Schedule authority model ### Layer 3: Schedule System - [ ] Daily schedule generation from roles and personality - [ ] Schedule authority (autonomous, external, partial) - [ ] Shared commitments between related entities - [ ] Schedule regeneration on condition changes ### Layer 4: Behavior Tree System - [ ] Behavior tree framework and evaluation - [ ] Activity-specific behavior trees (Work, Leisure, etc.) - [ ] Need-driven behavior prioritization - [ ] Condition modifiers affecting behavior ### Layer 5: World Substrate - [ ] Substrate layer types (substances, temperature, light, sound, air quality, contagion) - [ ] Trigger volume system for spatial events - [ ] Generic substance transfer and consumption - [ ] Environmental effects on entities ### Layer 6: Institutions - [ ] Institution entity type with Governance, Resources, Reputation - [ ] Shared blackboard state for coordination - [ ] Worker schedule template generation - [ ] Institution lifecycle (Founded → Struggling → Established → etc.) ### Layer 7: Relationships - [ ] Relationship state and evolution - [ ] Bond types (Romantic, Familial, Friendship, Professional, Caretaking) - [ ] Coordination levels (None → AdHoc → Recurring → Cohabiting → Dependent) - [ ] Relationship effects on all simulation layers ### Layer 8: Conditions - [ ] Condition system with severity and duration - [ ] Condition effects (need modifiers, capability modifiers, schedule overrides, behavior modifiers) - [ ] Contagion system for spreading conditions - [ ] Condition progression and recovery ### Layer 9: Tools & Capabilities - [ ] Capability types (Movement, Communication, Transformation, Force, Storage, etc.) - [ ] Tool operator modes (Inhabit, Wield, Station, Wear) - [ ] Tools as institutional resources - [ ] Tool quality affecting output ### Layer 10: Production Workflows - [ ] Batch entity system for multi-step processes - [ ] Recipe and phase system - [ ] Interruptible work with state persistence - [ ] Quality accumulation from skill, tool, and materials ### Layer 11: Performance Architecture - [ ] Simulation tier system (Attached, Nearby, Background, Wildlife) - [ ] Tier promotion/demotion based on player proximity - [ ] Discrete event simulation and wake queue - [ ] Wildlife mode-based behavior ### Layer 12: Networking & Sync - [ ] CRDT-based state synchronization for slow-changing layers - [ ] Behavior tree outcome synchronization - [ ] Entity ownership model - [ ] Spatial ownership for substrate - [ ] Institution state synchronization across peers ## Dependencies & Risks **Dependencies:** - CRDT sync system (libmarathon) must be robust and performant - Bevy ECS for entity composition - Spatial indexing for proximity queries and trigger volumes - Pathfinding system for entity movement **Risks:** - **Performance on iPad**: 500 entities may exceed hardware limits - Mitigation: Aggressive tier system, discrete event sim, profiling early - **Emergent behavior bugs**: Generic systems may combine in unexpected/broken ways - Mitigation: Extensive testing, clear invariants, ability to disable subsystems - **Multiplayer desyncs**: Complex state across peers may diverge - Mitigation: Deterministic schedule generation, outcome-based sync, reconciliation - **Complexity explosion**: Many interacting systems may become unmaintainable - Mitigation: Clear layer separation, good documentation, incremental implementation - **Content creation burden**: System may require massive content investment to feel alive - Mitigation: Focus on generic rules that recombine, not hand-authored content ## Additional Context See RFC 0006 for full architectural details (will be moved to marathon repo). This epic represents the largest single feature and will likely span multiple months. The implementation should be incremental—each layer should be validated in isolation before adding the next. Start with foundation, add one layer at a time, and continuously test performance and emergent behavior. The key insight is **temporal scale separation**: slow-changing state (life arcs) uses different update strategies than fast-changing state (behavior trees). By layering these concerns, we can update slow things slowly and fast things only when necessary. **Philosophy**: Generic composition over special cases. Emergence over authorship. Consequences without failure. Existence is cheap; cognition is expensive.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: studio/marathon#5