Crate tri_grid_sim

Expand description

§tri_grid_sim

A deterministic, tick-based simulation library for 2D grid worlds with directional triangles.

§Overview

tri_grid_sim provides the core simulation engine for games and simulations that use a rectangular grid where each tile is subdivided into four directional triangles (North, East, South, West). This structure enables rich directional gameplay mechanics while maintaining a simple underlying grid topology.

§Key Features

Deterministic simulation: All operations produce identical results given the same inputs, making the engine suitable for replays, networking, and debugging.
Double-buffered state: The simulation uses two state buffers to ensure consistent reads during tick updates.
Fixed-point arithmetic: Uses parts-per-million (PPM) integers instead of floats to guarantee cross-platform determinism.
Extensible entity system: Open ID patterns (GroupKind(u32), StructureKind(u32), etc.) allow users to define their own entity types without modifying the library.
Trait-based behaviors: Custom game logic is injected via behavior traits rather than hardcoded into the engine.

§Architecture

The simulation is organized around these core concepts:

§Grid Topology

┌───────────┬───────────┐
│     N     │     N     │
│  W  ●  E  │  W  ●  E  │  ← Each tile has 4 triangles
│     S     │     S     │    pointing to cardinal directions
├───────────┼───────────┤
│     N     │     N     │
│  W  ●  E  │  W  ●  E  │
│     S     │     S     │
└───────────┴───────────┘
  (0,0)       (1,0)

Grid: Defines the world dimensions and provides coordinate/index conversion.
Direction: The four cardinal directions (North, East, South, West).
Each tile contains 4 triangles, one per direction.

§Terrain Layer

TerrainMap: Stores per-tile terrain data and shared edge data.
TerrainTile: Properties like terrain kind, survivability, and danger modifiers.
TerrainEdge: Shared edges between adjacent tiles with passability and movement cost.
TerrainGenerator: Trait for procedurally generating terrain from a seed.

§Resource Layer

ResourceMap: Sparse storage of resources per triangle.
ResourceKind: Open ID for user-defined resource types.
ResourceGenerator: Trait for procedurally generating initial resources.

§Entity Layer

Group: Mobile entities (units, characters) with position and direction.
Structure: Stationary entities (buildings) with inventory and parameters.
Both use open ID patterns for extensibility.

§Simulation Loop

World: The main simulation container holding all state.
WorldState: Per-tick mutable state (danger values, resources, inventories).
WorldBehavior: Trait for injecting custom logic into the tick loop.

§Quick Start

use tri_grid_sim::{Direction, SimConfig, World};

// Create a 10x10 world with default configuration
let cfg = SimConfig::default();
let mut world = World::new(10, 10, cfg).expect("valid dimensions");

// Set some initial danger in a triangle
world.set_danger(5, 5, Direction::North, 1000);

// Run simulation ticks
for _ in 0..10 {
    world.tick();
}

// Query the resulting state
let danger = world.danger(5, 5, Direction::North);
println!("Danger after 10 ticks: {}", danger);

§Custom Behaviors

Inject game-specific logic by implementing behavior traits:

use tri_grid_sim::{WorldBehavior, WorldCtx, WorldState};

struct MyDangerSource {
    x: u32,
    y: u32,
    amount: i32,
}

impl WorldBehavior for MyDangerSource {
    fn apply(&self, ctx: &WorldCtx<'_>, next: &mut WorldState) {
        // Add danger to the North triangle each tick
        let idx = ctx.grid().idx(self.x, self.y);
        next.danger[idx][0] += self.amount; // 0 = North
    }
}

§Feature Flags

raiders: Enables example RAIDERS group kind and RaidersBehavior.
structures_example: Enables example SETTLEMENT structure kind and SettlementBehavior.

These features demonstrate how to build on the engine but are not required for normal use.

§Coordinate System

The grid uses a top-left origin coordinate system:

(0, 0) is the top-left corner
x increases rightward
y increases downward
Direction offsets: North=(0,-1), East=(1,0), South=(0,1), West=(-1,0)

§Determinism Guarantees

The simulation guarantees determinism through:

Fixed iteration order: Tiles are processed in ascending index order; directions in Direction::ALL order (N, E, S, W).
Integer arithmetic: All calculations use i32/i64 with PPM scaling.
Seeded generation: Terrain and resource generators accept explicit seeds.
No floating-point: Avoids platform-dependent float behavior.

This means: same initial state + same inputs = identical results across platforms.

Re-exports§

pub use entities::group::Group;
pub use entities::group::GroupId;
pub use entities::group::GroupKind;
pub use entities::group::GroupPos;
pub use entities::structure::Structure;
pub use entities::structure::StructureId;
pub use entities::structure::StructureKind;
pub use entities::structure::StructureParam;
pub use entities::structure::StructurePos;
pub use simulation::group_behavior::GroupBehavior;
pub use simulation::group_behavior::GroupBehaviorAdapter;
pub use simulation::group_behavior::NoopGroupBehavior;
pub use simulation::structure_behavior::NoopStructureBehavior;
pub use simulation::structure_behavior::StructureBehavior;
pub use simulation::structure_behavior::StructureBehaviorAdapter;
pub use simulation::world_behavior::NoopWorldBehavior;
pub use simulation::world_behavior::WorldBehavior;
pub use simulation::world_behavior::WorldBehaviorChain2;
pub use simulation::world_behavior::WorldCtx;

Modules§

entities
simulation
util

Structs§

EdgeId: Unique identifier for an edge in the terrain map.
Grid: Defines the dimensions and topology of a rectangular tile grid.
ResourceKind: An open identifier for resource types.
ResourceMap: Sparse storage for resources on individual triangles.
SimConfig: Configuration parameters for the simulation tick loop.
TerrainEdge: Properties of a shared edge between two adjacent tiles.
TerrainKind: An open identifier for terrain types.
TerrainMap: Container for all terrain data in a world.
TerrainTile: Properties of a single terrain tile.
TileSnapshot: A read-only snapshot of a tile’s aggregated state.
TriangleCoord: Coordinates identifying a specific triangle in the world.
TriangleSnapshot: A read-only snapshot of a single triangle’s state.
World: The main simulation container holding all world state.
WorldState: The mutable state that changes each tick.

Enums§

ConfigError: Errors that can occur when validating SimConfig.
Direction: The four cardinal directions used throughout the simulation.
Error: The error type for operations in tri_grid_sim.

Traits§

ResourceGenerator: Trait for procedurally generating resources.
TerrainGenerator: Trait for procedurally generating terrain.

Functions§

deposit_from_inventory_into_triangle: Transfers resources from a structure’s inventory into a triangle.
take_from_triangle_into_inventory: Transfers resources from a triangle into a structure’s inventory.

Type Aliases§

Result: A specialized Result type for tri_grid_sim operations.