Skip to content

Bundled Services

The core Simulation engine bundles five standard services defined in Plantangenet::Runtime::Services, forming the Tier 1 and Tier 2 capabilities natively.

They handle the minimal requirements to define agents, locations, interactions, events, and data flow. You will build highly customized extensions or logic on top of them, or write sibling services interacting with their models.

Tiers and Architecture Strategy

  • Tier 1 Services: The foundational models representing the nouns of the simulation. They manage direct database maps, spatial bounds, and low-level agent actions. They run sequentially early in the Active frame phase.
  • Tier 2 Services: Higher-level services representing the consequences of the simulation. They analyze events from Tier 1, manage rewards, log telemetry, or handle complex cross-cutting routing. These execute sequentially after Tier 1 services or directly inside Aggregation.

Tier 1 Services

Hob Service (hob::HobService)

Hobs are the primary agents within Plantangenet. The HobService handles movement intent, spatial chunk registration, memory graphs, and basic stat pools (stamina, hp).

  • Primary Job: Processes the queue of pending agent intent (moves, interactions) each frame tick.
  • Events Emitted: HobMoved, HobFatigued, HobCreated.
  • Important Constraint: Limits rapid-fire requests via per-Hob cooldowns.

Deformation Service (plant_vrooom::DeformationService)

Tracks alterations, states, and "destructible/mutable" changes to static locations across the world chunk grid natively.

  • Primary Job: Processes environmental stress, changing node states (e.g. "dirt_road" to "mud_road" or "tree" to "stump").
  • Events Emitted: NodeStateChanged, TerrainDeformed.
  • Important Constraint: Handles batch updates for chunks un-loaded from memory to the SQL persistence layer.

Tier 2 Services

Inventory Service (inventory::InventoryService)

Manages the complex graph of Items, Pouches (Containers), and Entities ownership mapping. An InventoryService mutation often requires atomic validation of the source and destination nodes natively.

  • Primary Job: Transfers item instances across agent boundaries or drops items to spatial nodes.
  • Events Emitted: ItemTransferred, ItemDestroyed, ItemCreated.
  • Dependencies: Needs HobService state to confirm item pick-ups.

Road Service (region::RoadService)

A navigation and spatial graph analyzer. The RoadService is less about "creating roads" and more about evaluating the traversal cost and connectivity of regions recursively.

  • Primary Job: Calculating path-finding metrics and maintaining a regional cached routing graph.
  • Events Emitted: RouteCompleted, RegionDiscovered.
  • Dependencies: Observes DeformationService events to invalidate routing caches if terrain changes.

Achievement Service (quest::AchievementService)

Responsible natively for tracking progression flags, completing objectives, and granting rewards asynchronously based on the actions occurring in Tier 1 and other Tier 2 services.

  • Primary Job: Listens to an aggregated stream of HobMoved, ItemTransferred, etc. to increment progression counters.
  • Events Emitted: ObjectiveCompleted, QuestStarted.
  • Dependencies: Subscribes to the global EventBus during its provision() step.

Adding Custom Services

As documented in the ForgeService Trait Reference, building custom mechanics means implementing the ForgeService trait on a struct, registering it to the context, and ensuring it interacts sequentially within this Tiered architecture natively depending on its requirements.