Before detailing the agent-specific components and systems, it’s essential to outline the global simulation constructs and environmental factors that provide the context for agent behavior. These systems are typically managed at a higher level than individual agents but directly impact how agents perceive, interact, and schedule their operations.

Simulation Tick Rate and Event Scheduling

The entire simulation operates on a hard simulation tick rate (target: e.g., 60 Ticks Per Second - TPS). This provides a discrete, consistent heartbeat for all state changes and event processing. All durations, decay rates, and scheduled events within the simulation are ultimately measured in these ticks.

Role of the Universal Top-Level Scheduler

A global, universal scheduler is responsible for managing and dispatching all timed events within the simulation. This system maintains a time-ordered queue of events. Each tick, it:

• Identifies all events scheduled to fire on the current tick.
• Dispatches these events to the relevant systems or entities.
• Handles the registration of new events generated by systems or agents, placing them into the queue according to their designated future tick. This scheduler is critical for the event-driven nature of the agent architecture, enabling deferred processing, scheduled self-updates for agents, and the resolution of actions that span multiple ticks.

For distributed simulations operating across different logical threads or “Points of Interest” (POIs), maintaining determinism during inter-POI communication is paramount. If POI A (on Thread 1) sends a message/event intended for POI B (on Thread 2) that should be processed in the same simulation tick, complex locking or synchronization would be needed to ensure a deterministic order if multiple such messages arrive simultaneously from various sources. To simplify this and guarantee a deterministic outcome, inter-POI messages/events are typically buffered and processed with a minimum 1-tick delay. This means a message sent from POI A during tick T will be queued and made available for processing by POI B at the beginning of tick T+1 (or later, if the message itself specifies a future delivery tick). This delay allows all messages destined for a POI for tick T+1 to be collected, sorted by a deterministic rule (e.g., source POI ID, message type, priority), and then processed in that fixed order, thus preventing race conditions and ensuring deterministic state changes across the distributed simulation. The top-level scheduler may coordinate with or delegate to regional schedulers to manage these message queues and enforce this ordered processing.

Agent-Specific Scheduled Events

Agents heavily rely on the Universal Scheduler to manage their internal state progression and action timing without requiring constant polling. Examples include:

• Need Threshold Events: When a Need component (e.g., SustenanceNeed) projects that its value will cross a critical or goal-triggering threshold at a future tick, an event is scheduled for that agent at that specific tick.
• Action Completion Events: Actions that take time (e.g., movement, crafting, performing an interaction) will schedule an event for their anticipated completion (or failure/blockage) tick.
• Reflection/Maintenance Events: Agents might schedule periodic events for cognitive processes like memory consolidation or belief review.

Spatial Hashing & Perception Basics

Efficiently determining what an agent can perceive is crucial. This is facilitated by a global spatial indexing system.

Position Component

All entities that exist in the game world and can be perceived or interact spatially (including agents, food sources, threats, environmental features) possess a Position component:

• x: float
• y: float
• z: float (if 3D) This component is updated by movement systems and is read by the spatial hashing system.

Implicit/Explicit SensoryCapabilities

Agents possess sensory capabilities that define what they can perceive from their environment. For this initial draft, this might be:

• Implicit: A fixed sensory radius or cone definition used by perception systems when processing a specific agent.
• Explicit (Future): A dedicated SensoryCapabilities component on the agent, detailing ranges, fields of view, and sensitivities for different senses (sight, hearing, smell), potentially also including states like “actively searching” which might modify these parameters. Perception systems use an agent’s Position and its SensoryCapabilities to query the spatial hash.

A SpatialHashUpdateSystem (or equivalent, e.g., Quadtree/Octree manager) runs early in each tick to update the spatial index with the current positions of all relevant entities, making proximity and range queries efficient for perception and other systems.

Environmental Entities & Components (Illustrative)

The world is populated by various entities that agents can interact with or perceive. These entities are defined by their own set of components. For the purpose of our micro-level agent simulation focusing on sustenance and basic reactivity, we’ll consider:

FoodSource Component Attached to entities that can provide sustenance.

• sustenance_value: float (How much it replenishes an agent’s SustenanceNeed)
• (Also possesses a Position component)
• (Optional: quantity, requires_interaction_type)

ThreatSource Component (Illustrative) Attached to entities or environmental features that pose a danger to agents.

• danger_level: float (An abstract measure of the threat)
• threat_type: Enum_ThreatType (e.g., PREDATOR, ENVIRONMENTAL_HAZARD, HOSTILE_AGENT)
• (Also possesses a Position component)
• (Optional: effective_range, attack_capabilities) The presence of a ThreatSource would typically trigger safety-oriented goals and behaviors in perceiving agents.