Introduction

MIT licensed and AI-native

Build worlds where intelligent agents are a core system, not an afterthought.

A free, MIT-licensed Rust game engine where AI agents are a first-class runtime system. Deterministic simulation, tool-validated behavior, and Criterion-backed performance — inspectable, reproducible, and open.

Explore the architecture Build the workspace

MIT license Free to use, fork, and modify Built for engine developers

Scope Deterministic ECS, AI planning and validation, replay-safe simulation.

12,700+ agents at 60 FPS 977 Miri tests, 0 undefined behavior 71+ Kani proof harnesses

12,700+ validated agents at 60 FPS on modest consumer hardware

39,000+ workspace tests across 128 packages

977 Miri tests with zero undefined behavior

2.70 ms frame time at 1,000 entities in the current benchmark baseline

71+ Kani proof harnesses across safety-critical crates

Quick navigation

Jump straight to the area you need.

Getting started

Set up the workspace and run your first system.

• Quick startOpen quick start
• InstallationInstall dependencies
• First companionBuild your first AI companion

Architecture

Understand the runtime model.

• OverviewRead architecture overview
• AI-native designInspect AI-native design
• ValidationStudy tool validation

Core systems

Explore the engine subsystems.

• AI systemOpen AI systems
• Physics and fluidsInspect simulation systems
• Terrain and navigationBrowse world systems

Examples and performance

Demos, benchmarks, and optimization.

• ExamplesBrowse examples
• BenchmarksOpen benchmark dashboard
• OptimizationRead optimization guide

Engine development

Contribute and build from source.

• ContributingOpen contribution guide
• BuildingBuild from source
• TestingReview validation workflow

API and reference

Subsystem APIs and crate documentation.

• API overviewOpen API reference
• Crate mapBrowse crate documentation
• CLI and configInspect tools and configuration

Why AstraWeave

Architecture, safety, and performance you can verify.

AI-first architecture

Perception → reasoning → planning → action, built into the runtime.

World snapshots, plan intents, tool validation, behavior trees, GOAP, and LLM-backed planning all plug into a deterministic loop.

Deterministic and safe

Bit-identical replay, validator-gated actions, and formal verification.

Core unsafe paths are exercised under Miri. Kani proofs back critical ECS, math, and SDK invariants. Replay validation is built in, not bolted on.

Benchmarked subsystems

Every performance claim links to a reproducible Criterion measurement.

ECS, AI planning, physics, rendering frame times, and SIMD throughput are all measured with specific numbers, not broad adjectives.

Engine loop

Perception → reasoning → planning → validation → action.

Perception World snapshots from deterministic ECS state.

Reasoning Behavior trees, utility systems, GOAP, or LLM logic.

Planning Action sequences with costs, priorities, and fallbacks.

Validation Cooldowns, LOS, pathing, and sandbox constraints.

Action Approved commands flow into simulation, physics, and rendering.

What ships today

A focused stack for intelligent, simulation-heavy games.

AI orchestration

Six validated modes plus hybrid arbiters.

Classical planners, behavior trees, utility logic, LLM orchestration, ensemble patterns, and hybrid arbiters.

AI-native design AI API

Deterministic ECS

Ordered simulation for replay, tooling, and scale.

Archetype storage, system staging, iteration guarantees, and event channels form a reproducible simulation backbone.

ECS architecture ECS API

Rendering

wgpu-based rendering with real engine workloads.

PBR materials, clustered lighting, GPU skinning, post-processing, and LOD tooling.

Rendering systems Render API

Physics and movement

Character control, spatial hashing, fluids, and more.

Collision, character motion, destructibles, ragdolls, vehicles, gravity zones, and fluid simulation.

Physics Fluids

Navigation and world systems

Navmesh, terrain, scene streaming, and gameplay layers.

Terrain generation, navigation meshes, crafting, quests, dialogue, and procedural content.

Navigation Terrain

Tooling and integration

Example suite, editor tooling, and a C ABI for embedding.

A large example suite, editor workflows, and a stable C SDK layer.

Examples API docs

Evidence-backed metrics

Current measurements from the codebase.

• Agent capacity at 60 FPS12,700+
• AI validation throughput6.48M checks/sec
• Frame time at 1,000 entities2.70 ms
• ECS world creation25.8 ns
• Character move cost114 ns
• SIMD batch over 10k entities9.879 us

Top Benchmarks · Latest Run

Criterion.rs statistical benchmarking · Feb 2026

Stable baseline

Bake 10K Triangles E2E Plan Gen · Cache Miss Cache Latency · 200ms Light Binning · High Bloom Upsample · Mip 0 Light Binning · 5K Cache Latency · 100ms Game Loop · 5K Stress

All measurements are p50 medians from Criterion.rs with ≥100 iterations per benchmark and 95% confidence intervals. criterion · cargo bench

Quality posture

Verification and testing across the stack.

• Weighted line coverage59.3% across measured crates
• High-coverage crates14 crates at 85%+
• Miri validation977 tests, 0 UB
• Kani verification71+ harnesses
• Prompt mutation testing100% adjusted kill rate
• Desktop targetsWindows, Linux, macOS

Developer routes

Pick an entry point.

• System designOpen architecture overview
• Performance dataOpen benchmarks
• Build and runRead quick start
• Examples and demosBrowse examples
• Contributing workflowOpen contribution guide
• Reference implementationInspect Veilweaver

Use cases

Where AstraWeave fits best.

RPGs and immersive sims

Companions, directors, and systemic encounters.

Projects where NPCs need to observe, plan, and react with more depth than state-machine scripting allows.

Server-authoritative multiplayer

Validation and replayability matter.

Deterministic simulation and tool-gated actions for anti-cheat, reproducibility, and replay validation.

Research and prototyping

Benchmarkable AI-native architecture.

Test agent scale, planning strategies, and hybrid AI control under measurable conditions.

Embedded engine teams

Rust core with a C ABI.

Adopt focused subsystems through the modular crate structure instead of committing to the whole stack.

Design lineages

Games this engine could help realize.

Colony and world simulation

In the lineage of Dwarf Fortress or RimWorld.

Agent autonomy, world-state memory, logistics, and emergent story generation.

4X and grand strategy

In the lineage of Civilization or Crusader Kings.

Multi-agent diplomacy, advisor systems, strategic planners, and explainable AI.

Tactical command games

In the lineage of X-COM or Battle Brothers.

Tool validation, cover awareness, action planning, and replay-safe combat loops.

Systemic sandboxes

In the lineage of Kenshi or Mount and Blade.

Large numbers of autonomous actors with persistent world consequences.

Immersive sims and party RPGs

In the lineage of Deus Ex or Dragon Age.

Companion decisions, quest reactivity, systemic encounters, and director-style orchestration.

Rights-holder remakes

Licensed ports or original successors.

Rebuild ambitious systemic designs with modern AI-native architecture.

Next step

Clone, build, and decide from evidence.

AstraWeave is free and MIT licensed. Evaluate, adopt subsystems, or contribute back without platform lock-in.

Install dependencies Read benchmark report Contribute to the engine

Quick Start

Get up and running with AstraWeave in minutes! This guide will help you install the engine, run your first AI companion, and understand the basic concepts.

Prerequisites

• Rust: 1.89.0+ (managed automatically via rust-toolchain.toml)
• Platform: Linux, macOS, or Windows
• GPU: Vulkan-compatible graphics card
• Memory: 4GB+ RAM recommended for AI models

Installation

1. Clone the Repository

git clone https://github.com/lazyxeon/AstraWeave-AI-Native-Gaming-Engine.git
cd AstraWeave-AI-Native-Gaming-Engine

2. System Dependencies (Linux)

If you’re on Linux, install the required system packages:

sudo apt-get update
sudo apt-get install -y build-essential pkg-config cmake ninja-build \
  libx11-dev libxi-dev libxcursor-dev libxrandr-dev libxinerama-dev \
  libxkbcommon-dev libxkbcommon-x11-dev libx11-xcb-dev libxcb1-dev \
  libxcb-randr0-dev libxcb-xfixes0-dev libxcb-shape0-dev libxcb-xkb-dev \
  libgl1-mesa-dev libegl1-mesa-dev wayland-protocols libwayland-dev \
  libasound2-dev libpulse-dev libudev-dev mesa-vulkan-drivers vulkan-tools

3. Build Core Components

Build the stable, working core components:

cargo build -p astraweave-core -p astraweave-ai -p astraweave-physics \
            -p astraweave-nav -p astraweave-render -p hello_companion

This typically takes 8-15 seconds after initial dependency download.

Your First AI Companion

Let’s run the most basic example to see AstraWeave in action:

cargo run -p hello_companion --release

What You’ll See

The demo will show:

1. AI Perception: The companion perceives the world state
2. Planning: AI generates a plan using its understanding
3. Tool Validation: The engine validates what the AI wants to do
4. Expected Panic: The demo will panic with “LosBlocked” - this is expected behavior demonstrating the validation system

Example Output

[INFO] AI Companion initialized
[INFO] Perception snapshot captured: 1 entities
[INFO] Planning phase: generating intent for companion
[INFO] Generated plan: MoveTo(target_position)
[INFO] Validating tool usage: MovementTool
[ERROR] Validation failed: LosBlocked
thread 'main' panicked at 'LOS validation failed'

This panic is intentional! It demonstrates AstraWeave’s core principle: the AI can only do what the engine validates as possible.

Understanding What Happened

The hello_companion example showcases AstraWeave’s fundamental architecture:

1. Fixed-Tick Simulation: The world runs at deterministic 60Hz
2. AI Perception: AI agents receive structured world snapshots
3. Planning Layer: AI generates intentions using LLM-based planning
4. Tool Validation: Engine validates every AI action before execution
5. Safety First: Invalid actions are rejected, maintaining game integrity

Next Steps

Now that you’ve seen the core loop in action:

• Learn the Architecture: Read AI-Native Design
• Build Your First Game: Follow Building Your First Game
• Explore More Examples: Check out Working Examples
• Dive Deeper: Study Core Systems

Troubleshooting

Build Errors

If you encounter build errors:

• Make sure you have the correct Rust version (check rust-toolchain.toml)
• Install system dependencies for your platform
• Some examples have known compilation issues - stick to the working core components listed above

Runtime Issues

• Graphics errors: Ensure you have Vulkan drivers installed
• Audio errors: Install audio system dependencies (ALSA/PulseAudio on Linux)
• Permission errors: Make sure your user can access graphics and audio devices

For more help, see Troubleshooting.

🎉 Congratulations! You’ve successfully run your first AstraWeave AI companion. The engine validated the AI’s actions and maintained world integrity, just as it should.

Installation Guide

This guide covers detailed installation instructions for AstraWeave on different platforms, including all dependencies and troubleshooting common issues.

System Requirements

Minimum Requirements

• CPU: x64 processor with SSE2 support
• Memory: 4GB RAM (8GB+ recommended for AI models)
• GPU: Vulkan 1.0 compatible graphics card
• Storage: 2GB free space (more for AI models)
• Rust: 1.89.0+ (managed via rust-toolchain.toml)

Recommended Requirements

• CPU: Multi-core x64 processor (4+ cores)
• Memory: 16GB+ RAM for development and multiple AI models
• GPU: Modern Vulkan 1.2+ compatible GPU with 2GB+ VRAM
• Storage: SSD with 10GB+ free space

Platform-Specific Installation

Linux

Ubuntu/Debian

# Update package lists
sudo apt-get update

# Install build essentials
sudo apt-get install -y build-essential pkg-config cmake ninja-build

# Install graphics dependencies
sudo apt-get install -y libx11-dev libxi-dev libxcursor-dev libxrandr-dev \
  libxinerama-dev libxkbcommon-dev libxkbcommon-x11-dev libx11-xcb-dev \
  libxcb1-dev libxcb-randr0-dev libxcb-xfixes0-dev libxcb-shape0-dev \
  libxcb-xkb-dev

# Install rendering dependencies
sudo apt-get install -y libgl1-mesa-dev libegl1-mesa-dev wayland-protocols \
  libwayland-dev mesa-vulkan-drivers vulkan-tools

# Install audio dependencies  
sudo apt-get install -y libasound2-dev libpulse-dev

# Install additional system dependencies
sudo apt-get install -y libudev-dev

Arch Linux

# Install base development tools
sudo pacman -S base-devel cmake ninja

# Install graphics and audio
sudo pacman -S vulkan-devel mesa alsa-lib libpulse wayland wayland-protocols

# Install X11 dependencies
sudo pacman -S libx11 libxcb libxrandr libxinerama libxcursor libxi

Fedora/RHEL

# Install development tools
sudo dnf groupinstall "Development Tools"
sudo dnf install cmake ninja-build pkg-config

# Install graphics dependencies
sudo dnf install libX11-devel libXi-devel libXcursor-devel libXrandr-devel \
  libXinerama-devel libxkbcommon-devel libxkbcommon-x11-devel

# Install Vulkan and Mesa
sudo dnf install vulkan-devel mesa-dri-drivers

# Install audio
sudo dnf install alsa-lib-devel pulseaudio-libs-devel

macOS

Prerequisites

First, install Xcode Command Line Tools:

xcode-select --install

Using Homebrew (Recommended)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install cmake ninja pkg-config

# For Intel Macs, ensure MoltenVK is installed
brew install molten-vk

Manual Installation

• Download and install Xcode from the App Store
• Install CMake from cmake.org
• Ensure MoltenVK is available for Vulkan support

Windows

Using Visual Studio (Recommended)

1. Install Visual Studio 2019 or later with C++ build tools
2. Install Git for Windows
3. Install CMake (either standalone or via Visual Studio Installer)

Using MSYS2/MinGW

# Install MSYS2 from https://www.msys2.org/
# Then in MSYS2 terminal:
pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja
pacman -S mingw-w64-x86_64-vulkan-devel

Rust Installation

AstraWeave uses a specific Rust version defined in rust-toolchain.toml. The installation process will automatically use the correct version.

Install Rust

# Install rustup (Rust installer)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the prompts, then restart your terminal or run:
source ~/.cargo/env

# Verify installation
rustc --version
cargo --version

Rust Components

The following components will be installed automatically when needed:

• cargo - Package manager and build tool
• clippy - Linter for catching common mistakes
• rustfmt - Code formatter
• rust-analyzer - Language server for IDE support

Clone and Build

1. Clone the Repository

git clone https://github.com/lazyxeon/AstraWeave-AI-Native-Gaming-Engine.git
cd AstraWeave-AI-Native-Gaming-Engine

2. Verify Rust Toolchain

The correct Rust version will be installed automatically:

# This will show the version from rust-toolchain.toml
rustc --version

3. Build Core Components

Start with the stable, working components:

cargo build -p astraweave-core -p astraweave-ai -p astraweave-physics \
            -p astraweave-nav -p astraweave-render -p hello_companion

4. Run Tests

Verify the installation with tests:

cargo test -p astraweave-input

5. Run Example

Test the installation:

cargo run -p hello_companion --release

Verification

Check GPU Support

# Linux: Check Vulkan
vulkaninfo | grep "deviceName"

# macOS: Check Metal
system_profiler SPDisplaysDataType

# Windows: Use dxdiag or GPU-Z

Check Audio

# Linux: Test audio devices
aplay -l

# macOS: Check audio
system_profiler SPAudioDataType  

# Windows: Check audio devices in Device Manager

Development Environment Setup

IDE Recommendations

VS Code (Recommended)

Install these extensions:

• rust-analyzer - Rust language support
• CodeLLDB - Debugging support
• Even Better TOML - TOML file support
• Error Lens - Inline error display

Other IDEs

• CLion: Has good Rust support with the Rust plugin
• Vim/Neovim: Use with rust-analyzer LSP
• Emacs: Use with rust-analyzer and rustic-mode

Performance Considerations

Release Builds

For better performance during development:

# Always use release mode for examples
cargo run -p hello_companion --release

# Build in release mode
cargo build --release

Parallel Compilation

Speed up builds by using multiple CPU cores:

# Set in ~/.cargo/config.toml
[build]
jobs = 4  # or number of CPU cores

Target Directory

Use a shared target directory to reduce disk usage:

# Set CARGO_TARGET_DIR environment variable
export CARGO_TARGET_DIR=/path/to/shared/target

Troubleshooting

Common Build Errors

“linker not found”

• Linux: Install build-essential or gcc
• macOS: Install Xcode Command Line Tools
• Windows: Install Visual Studio with C++ tools

Vulkan errors

• Linux: Install mesa-vulkan-drivers and vulkan-tools
• macOS: Ensure MoltenVK is installed
• Windows: Update graphics drivers

Audio errors

• Linux: Install libasound2-dev and libpulse-dev
• macOS: Usually works out of the box
• Windows: Ensure Windows Audio service is running

Performance Issues

Slow Compilation

• Use cargo build --release for better runtime performance
• Consider using sccache to cache compilation results
• Increase parallel build jobs in Cargo config

Runtime Performance

• Always use --release flag for examples and demos
• Ensure GPU drivers are up to date
• Check system has adequate RAM (4GB minimum)

Platform-Specific Issues

Linux Wayland vs X11

AstraWeave supports both Wayland and X11:

# Force X11 if needed
export WAYLAND_DISPLAY=""

# Force Wayland if needed  
export DISPLAY=""

macOS Code Signing

For distribution on macOS, you may need to sign binaries:

codesign --force --deep --sign - target/release/hello_companion

Windows Antivirus

Some antivirus software may flag Rust binaries. Add exclusions for:

• The project directory
• ~/.cargo directory
• target/ build directory

Next Steps

With AstraWeave installed:

1. Run through the Quick Start Guide
2. Explore Working Examples
3. Read about Architecture
4. Build Your First Game

For ongoing development, see the Contributing Guide and Building from Source.

Your First AI Companion

This tutorial will guide you through creating your first AI companion in AstraWeave. By the end, you’ll have a companion that can perceive its environment, experience emotions, and exhibit autonomous behaviors.

Table of Contents

• Prerequisites
• Project Setup
• Creating a Basic Companion
• Adding Perception
• Adding Emotions
• Adding Behaviors
• Testing Your Companion
• Next Steps

Prerequisites

Before starting, ensure you have:

• Rust 1.75.0 or later installed
• AstraWeave installed (see Installation)
• A compatible GPU (see System Requirements)
• Basic Rust knowledge

New to Rust? Check out [The Rust Book](https://doc.rust-lang.org/book/) for a comprehensive introduction.

Project Setup

Create a New Project

# Create a new Rust project
cargo new my_first_companion
cd my_first_companion

Add AstraWeave Dependencies

Edit Cargo.toml to add AstraWeave dependencies:

[package]
name = "my_first_companion"
version = "0.1.0"
edition = "2021"

[dependencies]
# Core AstraWeave crates
astraweave-ai = "0.1.0"
astraweave-render = "0.1.0"
bevy = "0.12"

# Utilities
anyhow = "1.0"

Version numbers may change. Check [crates.io](https://crates.io) for the latest versions.

Verify Setup

# Build to ensure dependencies are resolved
cargo build

Creating a Basic Companion

Let’s start with a simple companion that just exists in the world.

Basic Structure

Edit src/main.rs:

use bevy::prelude::*;
use astraweave_ai::prelude::*;
use anyhow::Result;

fn main() -> Result<()> {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AstraWeaveAIPlugin)
        .add_systems(Startup, setup_companion)
        .add_systems(Update, update_companion)
        .run();
    
    Ok(())
}

fn setup_companion(mut commands: Commands) {
    // Create a basic companion
    let companion = CompanionBuilder::new()
        .with_name("Buddy")
        .build();
    
    commands.spawn(companion);
    
    info!("Spawned companion: Buddy");
}

fn update_companion(
    mut companions: Query<&mut Companion>,
    time: Res<Time>,
) {
    for mut companion in companions.iter_mut() {
        companion.update(time.delta_seconds());
    }
}

Run Your First Companion

cargo run

You should see log output indicating your companion was spawned!

Congratulations! You've created your first AI companion. Now let's make it more interesting.

Adding Perception

Companions need to perceive their environment to interact meaningfully.

Visual Perception

Add visual perception to detect nearby entities:

#![allow(unused)]
fn main() {
use astraweave_ai::perception::*;

fn setup_companion(mut commands: Commands) {
    let companion = CompanionBuilder::new()
        .with_name("Buddy")
        .with_perception(PerceptionConfig {
            visual_range: 10.0,
            visual_fov: 120.0,      // 120-degree field of view
            update_rate: 10.0,       // 10 updates per second
            ..default()
        })
        .build();
    
    commands.spawn(companion);
}
}

Adding Stimuli

Create entities that the companion can perceive:

#![allow(unused)]
fn main() {
fn setup_companion(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // Spawn the companion
    let companion = CompanionBuilder::new()
        .with_name("Buddy")
        .with_perception(PerceptionConfig {
            visual_range: 10.0,
            visual_fov: 120.0,
            update_rate: 10.0,
            ..default()
        })
        .build();
    
    commands.spawn((
        companion,
        Transform::from_xyz(0.0, 0.0, 0.0),
    ));
    
    // Spawn a ball that the companion can see
    commands.spawn((
        PbrBundle {
            mesh: meshes.add(Sphere::new(0.5)),
            material: materials.add(Color::rgb(0.8, 0.2, 0.2)),
            transform: Transform::from_xyz(3.0, 0.5, 0.0),
            ..default()
        },
        Stimulus::new(StimulusType::Visual, 1.0),
    ));
    
    // Add camera
    commands.spawn(Camera3dBundle {
        transform: Transform::from_xyz(0.0, 5.0, 10.0)
            .looking_at(Vec3::ZERO, Vec3::Y),
        ..default()
    });
    
    // Add light
    commands.spawn(PointLightBundle {
        point_light: PointLight {
            intensity: 1500.0,
            shadows_enabled: true,
            ..default()
        },
        transform: Transform::from_xyz(4.0, 8.0, 4.0),
        ..default()
    });
}
}

Reacting to Perception

Add a system to log what the companion perceives:

#![allow(unused)]
fn main() {
fn update_companion(
    mut companions: Query<(&mut Companion, &Transform)>,
    stimuli: Query<(&Stimulus, &Transform)>,
    time: Res<Time>,
) {
    for (mut companion, companion_transform) in companions.iter_mut() {
        companion.update(time.delta_seconds());
        
        // Check what the companion can see
        if let Some(perception) = companion.perception() {
            for (stimulus, stimulus_transform) in stimuli.iter() {
                let distance = companion_transform
                    .translation
                    .distance(stimulus_transform.translation);
                
                if distance <= perception.visual_range {
                    info!(
                        "{} sees {} stimulus at distance {:.2}",
                        companion.name(),
                        stimulus.stimulus_type,
                        distance
                    );
                }
            }
        }
    }
}
}

Adding Emotions

Emotions make companions feel alive and responsive.

Emotion System

Add emotion processing to your companion:

#![allow(unused)]
fn main() {
use astraweave_ai::emotion::*;

fn setup_companion(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    let companion = CompanionBuilder::new()
        .with_name("Buddy")
        .with_perception(PerceptionConfig {
            visual_range: 10.0,
            visual_fov: 120.0,
            update_rate: 10.0,
            ..default()
        })
        .with_emotions(vec![
            EmotionConfig::new("joy", 0.5, 0.95),
            EmotionConfig::new("curiosity", 0.3, 0.98),
            EmotionConfig::new("calm", 0.7, 0.99),
        ])
        .build();
    
    commands.spawn((
        companion,
        Transform::from_xyz(0.0, 0.0, 0.0),
    ));
    
    // ... spawn stimuli and camera as before
}
}

Emotion Responses

Make emotions respond to stimuli:

fn process_emotions(
    mut companions: Query<&mut Companion>,
    stimuli: Query<(&Stimulus, &Transform)>,
) {
    for mut companion in companions.iter_mut() {
        if let Some(emotion_system) = companion.emotion_system_mut() {
            // Process nearby stimuli
            for (stimulus, _) in stimuli.iter() {
                match stimulus.stimulus_type {
                    StimulusType::Visual => {
                        emotion_system.increase_emotion("curiosity", 0.1);
                    }
                    StimulusType::Positive => {
                        emotion_system.increase_emotion("joy", 0.2);
                    }
                    StimulusType::Negative => {
                        emotion_system.decrease_emotion("calm", 0.15);
                    }
                    _ => {}
                }
            }
            
            // Log dominant emotion
            if let Some(dominant) = emotion_system.dominant_emotion() {
                info!(
                    "{} feels {} (intensity: {:.2})",
                    companion.name(),
                    dominant.name,
                    dominant.intensity
                );
            }
        }
    }
}

// Add this system to your app
fn main() -> Result<()> {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AstraWeaveAIPlugin)
        .add_systems(Startup, setup_companion)
        .add_systems(Update, (update_companion, process_emotions))
        .run();
    
    Ok(())
}

Adding Behaviors

Behaviors allow companions to act autonomously based on their internal state.

Basic Movement Behavior

Add a simple behavior that makes the companion wander:

#![allow(unused)]
fn main() {
use astraweave_ai::behavior::*;

fn setup_companion(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    let companion = CompanionBuilder::new()
        .with_name("Buddy")
        .with_perception(PerceptionConfig::default())
        .with_emotions(vec![
            EmotionConfig::new("joy", 0.5, 0.95),
            EmotionConfig::new("curiosity", 0.3, 0.98),
            EmotionConfig::new("calm", 0.7, 0.99),
        ])
        .with_behavior(BehaviorConfig {
            wander_speed: 2.0,
            wander_radius: 5.0,
            ..default()
        })
        .build();
    
    commands.spawn((
        companion,
        PbrBundle {
            mesh: meshes.add(Capsule3d::new(0.5, 1.0)),
            material: materials.add(Color::rgb(0.3, 0.5, 0.8)),
            transform: Transform::from_xyz(0.0, 0.5, 0.0),
            ..default()
        },
    ));
    
    // ... rest of scene setup
}
}

Emotion-Driven Behavior

Make behavior change based on emotions:

fn emotion_driven_behavior(
    mut companions: Query<(&mut Companion, &mut Transform)>,
    time: Res<Time>,
) {
    for (mut companion, mut transform) in companions.iter_mut() {
        if let Some(emotion_system) = companion.emotion_system() {
            let curiosity = emotion_system
                .get_emotion("curiosity")
                .map(|e| e.intensity)
                .unwrap_or(0.0);
            
            let calm = emotion_system
                .get_emotion("calm")
                .map(|e| e.intensity)
                .unwrap_or(0.0);
            
            // High curiosity = move around more
            if curiosity > 0.6 {
                let speed = 2.0 * curiosity;
                let direction = Vec3::new(
                    (time.elapsed_seconds() * 0.5).sin(),
                    0.0,
                    (time.elapsed_seconds() * 0.5).cos(),
                );
                
                transform.translation += direction * speed * time.delta_seconds();
                
                info!("{} is exploring curiously!", companion.name());
            }
            // High calm = stay still
            else if calm > 0.7 {
                info!("{} is resting calmly.", companion.name());
            }
        }
    }
}

// Update main to include the behavior system
fn main() -> Result<()> {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AstraWeaveAIPlugin)
        .add_systems(Startup, setup_companion)
        .add_systems(Update, (
            update_companion,
            process_emotions,
            emotion_driven_behavior,
        ))
        .run();
    
    Ok(())
}

Testing Your Companion

Complete Example

Here’s the full code with all features:

use bevy::prelude::*;
use astraweave_ai::prelude::*;
use anyhow::Result;

fn main() -> Result<()> {
    App::new()
        .add_plugins(DefaultPlugins.set(WindowPlugin {
            primary_window: Some(Window {
                title: "My First Companion".to_string(),
                resolution: (1280.0, 720.0).into(),
                ..default()
            }),
            ..default()
        }))
        .add_plugins(AstraWeaveAIPlugin)
        .add_systems(Startup, setup_companion)
        .add_systems(Update, (
            update_companion,
            process_emotions,
            emotion_driven_behavior,
        ))
        .run();
    
    Ok(())
}

fn setup_companion(
    mut commands: Commands,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<StandardMaterial>>,
) {
    // Create companion
    let companion = CompanionBuilder::new()
        .with_name("Buddy")
        .with_perception(PerceptionConfig {
            visual_range: 10.0,
            visual_fov: 120.0,
            update_rate: 10.0,
            ..default()
        })
        .with_emotions(vec![
            EmotionConfig::new("joy", 0.5, 0.95),
            EmotionConfig::new("curiosity", 0.3, 0.98),
            EmotionConfig::new("calm", 0.7, 0.99),
        ])
        .with_behavior(BehaviorConfig::default())
        .build();
    
    commands.spawn((
        companion,
        PbrBundle {
            mesh: meshes.add(Capsule3d::new(0.5, 1.0)),
            material: materials.add(Color::rgb(0.3, 0.5, 0.8)),
            transform: Transform::from_xyz(0.0, 0.5, 0.0),
            ..default()
        },
    ));
    
    // Add ground plane
    commands.spawn(PbrBundle {
        mesh: meshes.add(Plane3d::new(Vec3::Y, Vec2::new(20.0, 20.0))),
        material: materials.add(Color::rgb(0.3, 0.5, 0.3)),
        ..default()
    });
    
    // Add interactive objects
    for i in 0..5 {
        let angle = (i as f32 / 5.0) * std::f32::consts::TAU;
        let pos = Vec3::new(angle.cos() * 4.0, 0.5, angle.sin() * 4.0);
        
        commands.spawn((
            PbrBundle {
                mesh: meshes.add(Sphere::new(0.5)),
                material: materials.add(Color::rgb(0.8, 0.2, 0.2)),
                transform: Transform::from_translation(pos),
                ..default()
            },
            Stimulus::new(StimulusType::Visual, 1.0),
        ));
    }
    
    // Add camera
    commands.spawn(Camera3dBundle {
        transform: Transform::from_xyz(0.0, 8.0, 12.0)
            .looking_at(Vec3::ZERO, Vec3::Y),
        ..default()
    });
    
    // Add light
    commands.spawn(PointLightBundle {
        point_light: PointLight {
            intensity: 1500.0,
            shadows_enabled: true,
            ..default()
        },
        transform: Transform::from_xyz(4.0, 8.0, 4.0),
        ..default()
    });
}

fn update_companion(
    mut companions: Query<&mut Companion>,
    time: Res<Time>,
) {
    for mut companion in companions.iter_mut() {
        companion.update(time.delta_seconds());
    }
}

fn process_emotions(
    mut companions: Query<(&mut Companion, &Transform)>,
    stimuli: Query<(&Stimulus, &Transform)>,
) {
    for (mut companion, companion_transform) in companions.iter_mut() {
        if let Some(emotion_system) = companion.emotion_system_mut() {
            for (stimulus, stimulus_transform) in stimuli.iter() {
                let distance = companion_transform
                    .translation
                    .distance(stimulus_transform.translation);
                
                if distance <= 5.0 {
                    emotion_system.increase_emotion("curiosity", 0.05);
                    emotion_system.increase_emotion("joy", 0.02);
                }
            }
        }
    }
}

fn emotion_driven_behavior(
    mut companions: Query<(&mut Companion, &mut Transform)>,
    time: Res<Time>,
) {
    for (companion, mut transform) in companions.iter_mut() {
        if let Some(emotion_system) = companion.emotion_system() {
            let curiosity = emotion_system
                .get_emotion("curiosity")
                .map(|e| e.intensity)
                .unwrap_or(0.0);
            
            if curiosity > 0.4 {
                let speed = 1.5 * curiosity;
                let direction = Vec3::new(
                    (time.elapsed_seconds() * 0.8).sin(),
                    0.0,
                    (time.elapsed_seconds() * 0.8).cos(),
                );
                
                transform.translation += direction * speed * time.delta_seconds();
                transform.translation.y = 0.5; // Keep on ground
            }
        }
    }
}

Run and Observe

cargo run --release

Watch your companion:

• Wander around the scene
• React to nearby objects
• Show emotional responses
• Exhibit autonomous behavior

You've created a fully functional AI companion with perception, emotions, and behaviors!

Next Steps

Now that you have a working companion, try:

1. Add more emotions: Experiment with fear, excitement, anger
2. Complex behaviors: Implement approach/avoid behaviors based on emotions
3. Social interactions: Add multiple companions that interact
4. Save/Load: Persist companion state between runs
5. Visual feedback: Change companion color based on dominant emotion

Advanced Topics

• Behavior Trees
• Emotion Blending
• Multi-Agent Systems
• Performance Optimization

Example Projects

Check out more examples in the repository:

# Clone AstraWeave
git clone https://github.com/verdentlabs/astraweave.git
cd astraweave

# Run advanced examples
cargo run --release --example companion_emotions
cargo run --release --example multi_companion
cargo run --release --example behavior_showcase

Join the Community

• Discord: Join our server
• GitHub: Open issues or discussions
• Forum: Community forums

Share your companion creations in our Discord showcase channel!

Happy companion building!

System Requirements

This page outlines the hardware and software requirements for developing and running AstraWeave applications.

Table of Contents

• Minimum Requirements
• Recommended Requirements
• GPU Requirements
• Software Dependencies
• Platform-Specific Notes

Minimum Requirements

These are the bare minimum specifications to run AstraWeave applications:

Hardware

Minimum requirements may result in reduced performance. For optimal experience, see recommended specifications.

Operating System

• Windows: Windows 10 (64-bit) version 1909 or later
• Linux: Any modern distribution with kernel 5.4+ (Ubuntu 20.04, Fedora 33, etc.)
• macOS: macOS 10.15 (Catalina) or later

Recommended Requirements

For optimal performance and development experience:

Hardware

Operating System

• Windows: Windows 11 (64-bit)
• Linux: Ubuntu 22.04 LTS / Fedora 38 or later
• macOS: macOS 13 (Ventura) or later

More RAM and VRAM allow for larger scenes, more AI companions, and higher-quality assets.

GPU Requirements

AstraWeave is GPU-accelerated and requires modern graphics hardware with compute shader support.

Graphics API Support

Your GPU must support one of the following:

Supported GPUs

NVIDIA

Minimum:

• GTX 1060 (6GB)
• GTX 1070
• GTX 1660 Ti

Recommended:

• RTX 3060 or better
• RTX 4060 or better
• RTX A2000 or better (workstation)

Optimal:

• RTX 4070 Ti or better
• RTX 4080 / 4090
• RTX A4000 or better (workstation)

AMD

Minimum:

• RX 580 (8GB)
• RX 5500 XT (8GB)
• RX 6600

Recommended:

• RX 6700 XT or better
• RX 7600 XT or better

Optimal:

• RX 7800 XT or better
• RX 7900 XTX
• Radeon Pro W6800 or better (workstation)

Intel

Minimum:

• Arc A380

Recommended:

• Arc A750 or better
• Arc A770

Optimal:

• Arc A770 (16GB)

Intel Arc GPUs require the latest drivers for optimal performance. Visit [Intel's driver page](https://www.intel.com/content/www/us/en/download/726609/intel-arc-graphics-windows-dch-driver.html) for updates.

Integrated Graphics

Integrated GPUs are not recommended but may work for basic development:

• Intel Iris Xe (11th gen or later)
• AMD Radeon Graphics (Ryzen 5000 series or later)

Integrated graphics will have significant performance limitations. Dedicated GPU strongly recommended.

Verifying GPU Support

Windows

# Check DirectX version
dxdiag

# Check GPU with PowerShell
Get-WmiObject Win32_VideoController | Select-Object Name, DriverVersion

Linux

# Check Vulkan support
vulkaninfo | grep "deviceName"

# Check GPU details
lspci | grep -i vga
nvidia-smi  # For NVIDIA GPUs

macOS

# Check Metal support
system_profiler SPDisplaysDataType

Software Dependencies

Development Dependencies

Required

• Rust: Version 1.75.0 or later

  • Install via rustup
  • Verify: rustc --version

• Git: Any recent version

  • Install from git-scm.com
  • Verify: git --version

Platform-Specific

Windows

• Visual Studio Build Tools 2022 or Visual Studio 2022

  • Required for MSVC linker
  • Download: Visual Studio Downloads
  • Select “Desktop development with C++” workload

• Vulkan SDK (optional, for Vulkan backend)

  • Download: LunarG Vulkan SDK

Linux

Debian/Ubuntu:

sudo apt install -y \
  build-essential \
  pkg-config \
  libx11-dev \
  libxcursor-dev \
  libxrandr-dev \
  libxi-dev \
  libasound2-dev \
  libudev-dev \
  vulkan-tools \
  libvulkan-dev

Fedora/RHEL:

sudo dnf install -y \
  gcc gcc-c++ \
  pkg-config \
  libX11-devel \
  libXcursor-devel \
  libXrandr-devel \
  libXi-devel \
  alsa-lib-devel \
  systemd-devel \
  vulkan-tools \
  vulkan-loader-devel

Arch Linux:

sudo pacman -S --needed \
  base-devel \
  libx11 \
  libxcursor \
  libxrandr \
  libxi \
  alsa-lib \
  vulkan-tools \
  vulkan-headers

macOS

• Xcode Command Line Tools

  xcode-select --install
  

• Homebrew (recommended for package management)

  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
  

GPU Drivers

Always use the latest drivers for optimal performance:

NVIDIA

• Download from NVIDIA Driver Downloads
• Linux: Use distribution’s package manager or NVIDIA’s .run installer
• Minimum driver version: 525.60.11 (Linux) / 528.24 (Windows)

AMD

• Windows: AMD Software Adrenalin Edition
• Linux: Mesa drivers (usually pre-installed)

  # Ubuntu/Debian
  sudo apt install mesa-vulkan-drivers
  
  # Fedora
  sudo dnf install mesa-vulkan-drivers
  

Intel

• Intel Graphics Drivers
• Linux: Mesa drivers (usually pre-installed)

Platform-Specific Notes

Windows

• Windows Defender: May slow initial builds. Add exclusion for project directory:

  Settings > Windows Security > Virus & threat protection > Exclusion settings
  

• Long Path Support: Enable for deep project structures:

  # Run as Administrator
  New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
    -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
  

• Power Settings: Use “High Performance” or “Ultimate Performance” power plan for best results

Linux

• GPU Permissions: Ensure user is in the video group:

  sudo usermod -a -G video $USER
  # Log out and back in
  

• Wayland: Some features work better with X11. Switch if experiencing issues:

  # Edit /etc/gdm3/custom.conf (Ubuntu/Debian)
  # Uncomment: WaylandEnable=false
  

• Memory Limits: Increase limits for large projects:

  # Add to ~/.bashrc
  ulimit -n 4096
  

macOS

• Metal Support: Requires macOS 10.15+ and Metal-compatible GPU

  • Check: system_profiler SPDisplaysDataType | grep Metal

• Apple Silicon (M1/M2/M3): Fully supported with native ARM builds

  # Verify ARM toolchain
  rustc --version --verbose | grep host
  # Should show: aarch64-apple-darwin
  

• Rosetta 2: Not required for M1/M2/M3 Macs (native ARM support)

• Security Settings: May need to allow apps in System Preferences on first run

Performance Expectations

Development Workloads

Runtime Performance

Example scene: 10 AI companions with full perception and emotion systems

Performance varies based on scene complexity, AI behavior count, and graphics settings.

Checking Your System

Run this command to verify your setup:

# Clone and run the system check example
git clone https://github.com/verdentlabs/astraweave.git
cd astraweave
cargo run --example system_check

The system check will report:

• Rust version
• GPU capabilities
• Graphics API support
• Available memory
• Recommended settings

If all checks pass, your system is ready for AstraWeave development!

Upgrading Your System

If your system doesn’t meet requirements:

Priority Upgrades

1. GPU: Biggest impact on runtime performance
2. RAM: Enables larger scenes and faster compilation
3. SSD: Dramatically reduces build times
4. CPU: Improves compilation speed and AI performance

Budget Recommendations

• Entry Level ($300-500): Used RTX 3060 or RX 6700 XT + 16GB RAM
• Mid Range ($800-1200): RTX 4060 Ti or RX 7700 XT + 32GB RAM + NVMe SSD
• High End ($2000+): RTX 4080 or RX 7900 XTX + 64GB RAM + Fast CPU

Next Steps

Once your system meets the requirements:

1. Install AstraWeave
2. Build from source
3. Create your first companion

If you have questions about requirements, join our Discord community.

Architecture Overview

AstraWeave represents a fundamental shift in game engine design: instead of treating AI as an afterthought, it places intelligent agents at the core of the architecture. This document explains the key architectural decisions and how they enable truly AI-native gameplay.

Core Philosophy: AI-First Design

Traditional game engines follow this pattern:

Game Logic → AI System → Scripted Behaviors

AstraWeave inverts this relationship:

AI Agents ← Tool Validation ← Engine Authority

Why This Matters

1. No Cheating AI: AI can only act through validated game systems
2. Emergent Behavior: Complex interactions emerge from simple, validated tools
3. Multiplayer Ready: Same validation works for human players and AI
4. Predictable Performance: Deterministic simulation enables reliable testing

High-Level Architecture

graph TB
    subgraph "Fixed-Tick Simulation (60Hz)"
        ECS[ECS World]
        Physics[Physics System]
        Audio[Audio System]
        Render[Render System]
    end
    
    subgraph "AI Pipeline"
        Perception[Perception Bus]
        Planning[AI Planning]
        Tools[Tool Sandbox]
        Validation[Engine Validation]
    end
    
    subgraph "Game Layer"
        Gameplay[Gameplay Systems]
        Content[Content Systems]
        UI[UI Systems]
    end
    
    ECS --> Perception
    Perception --> Planning
    Planning --> Tools
    Tools --> Validation
    Validation --> ECS
    
    ECS --> Physics
    ECS --> Audio
    ECS --> Render
    
    Gameplay --> ECS
    Content --> ECS
    UI --> ECS

The Deterministic Core

Fixed-Tick Simulation

AstraWeave runs the simulation at exactly 60Hz, regardless of rendering framerate:

#![allow(unused)]
fn main() {
const TICK_RATE: f64 = 60.0;
const TICK_DURATION: Duration = Duration::from_nanos(16_666_667); // 1/60 second

// Simulation always advances by exactly this amount
fn tick_simulation(&mut self) {
    self.world.step(TICK_DURATION);
}
}

Benefits:

• Deterministic physics and AI behavior
• Consistent timing across different hardware
• Reliable networking and replay systems
• Predictable performance testing

Entity-Component-System (ECS)

AstraWeave uses an archetype-based ECS for cache-friendly performance:

#![allow(unused)]
fn main() {
// Components are pure data
#[derive(Component)]
struct Position(Vec3);

#[derive(Component)]  
struct AIAgent {
    perception_range: f32,
    planning_cooldown: Duration,
}

// Systems operate on component combinations
fn ai_perception_system(
    query: Query<(&Position, &AIAgent, &mut PerceptionState)>
) {
    for (pos, agent, mut perception) in query.iter_mut() {
        // Update agent perception based on world state
    }
}
}

Key Benefits:

• Cache-friendly data layout
• Parallel system execution
• Clean separation of data and logic
• Easy to reason about and test

The AI Pipeline

1. Perception Bus

AI agents receive structured snapshots of the world state:

#![allow(unused)]
fn main() {
#[derive(Serialize, Deserialize)]
pub struct PerceptionSnapshot {
    pub timestamp: u64,
    pub agent_id: EntityId,
    pub visible_entities: Vec<EntityData>,
    pub audio_events: Vec<AudioEvent>,
    pub world_state: WorldState,
}
}

Design Principles:

• Filtered Information: Agents only perceive what they should be able to see/hear
• Structured Data: JSON-serializable for easy AI model consumption
• Temporal Consistency: Snapshots include timing information
• Bandwidth Efficient: Only relevant changes are included

2. Planning Layer

AI models generate plans using the perception data:

#![allow(unused)]
fn main() {
pub struct AIPlan {
    pub agent_id: EntityId,
    pub intent: Intent,
    pub tools: Vec<ToolUsage>,
    pub confidence: f32,
    pub reasoning: String, // For debugging and learning
}

pub enum Intent {
    MoveTo { target: Vec3, urgency: f32 },
    AttackTarget { target: EntityId, weapon: Option<EntityId> },
    Interact { target: EntityId, interaction_type: String },
    Communicate { target: EntityId, message: String },
}
}

Key Features:

• High-Level Intents: AI thinks in terms of goals, not implementation
• Tool-Based Actions: All actions go through validated tools
• Confidence Scoring: Enables dynamic difficulty and behavior tuning
• Explainable Reasoning: For debugging and player understanding

3. Tool Validation

Every AI action must be validated by the engine:

#![allow(unused)]
fn main() {
pub trait Tool {
    fn validate(&self, world: &World, usage: &ToolUsage) -> ValidationResult;
    fn execute(&self, world: &mut World, usage: &ToolUsage) -> ExecutionResult;
}

// Example: Movement tool
impl Tool for MovementTool {
    fn validate(&self, world: &World, usage: &ToolUsage) -> ValidationResult {
        let agent = world.get::<Position>(usage.agent_id)?;
        let target = usage.target_position;
        
        // Check line of sight
        if !world.line_of_sight(agent.0, target) {
            return ValidationResult::Blocked(BlockReason::LineOfSight);
        }
        
        // Check movement cooldown
        if !self.cooldown_ready(usage.agent_id) {
            return ValidationResult::Blocked(BlockReason::Cooldown);
        }
        
        ValidationResult::Valid
    }
    
    fn execute(&self, world: &mut World, usage: &ToolUsage) -> ExecutionResult {
        // Actually perform the movement
        world.get_mut::<Position>(usage.agent_id)?.0 = usage.target_position;
        ExecutionResult::Success
    }
}
}

Validation Categories:

• Physics Constraints: Can the action physically happen?
• Resource Requirements: Does the agent have what’s needed?
• Cooldowns: Is the action available now?
• Line of Sight: Can the agent see the target?
• Game Rules: Does this follow the game’s rules?

Networking Architecture

Server Authority

AstraWeave uses server-authoritative validation for multiplayer:

Client AI → Intent → Server Validation → World Update → State Broadcast

Benefits:

• No client-side cheating possible
• Consistent world state across all clients
• AI agents validated same as human players
• Deterministic simulation enables easy rollback

Intent Replication

Instead of replicating low-level actions, AstraWeave replicates high-level intents:

#![allow(unused)]
fn main() {
#[derive(Serialize, Deserialize)]
pub struct NetworkIntent {
    pub player_id: PlayerId,
    pub intent: Intent,
    pub timestamp: u64,
    pub predicted_outcome: Option<PredictedResult>,
}
}

Advantages:

• Lower bandwidth than action replication
• Natural lag compensation through prediction
• AI and human intents handled identically
• Easy to implement anti-cheat

Performance Architecture

CPU Performance

• ECS Archetype Iteration: Cache-friendly component access
• Parallel Systems: Independent systems run in parallel
• Incremental Updates: Only changed data is processed
• Fixed Timestep: Predictable CPU load

Memory Management

• Pool Allocation: Entities and components use object pools
• Streaming: World chunks loaded/unloaded based on relevance
• Compression: Perception data compressed before AI processing
• Garbage Collection: Minimal allocations in hot paths

GPU Utilization

• Deferred Rendering: Efficient handling of many lights
• Instanced Rendering: Batch similar objects
• Compute Shaders: Physics and AI calculations on GPU
• Temporal Upsampling: Maintain quality at lower resolution

Modularity and Extensibility

Crate Organization

astraweave-core/     # ECS, validation, core types
astraweave-ai/       # AI planning and perception
astraweave-physics/  # Physics integration
astraweave-render/   # Rendering pipeline
astraweave-audio/    # Audio system
astraweave-nav/      # Navigation and pathfinding
astraweave-net/      # Networking layer

Plugin System

#![allow(unused)]
fn main() {
pub trait EnginePlugin {
    fn build(&self, app: &mut App);
}

pub struct CustomGamePlugin;

impl EnginePlugin for CustomGamePlugin {
    fn build(&self, app: &mut App) {
        app.add_system(custom_ai_behavior_system)
           .add_tool(CustomInteractionTool)
           .register_component::<CustomComponent>();
    }
}
}

Security Model

AI Sandboxing

AI agents cannot:

• Access arbitrary memory
• Execute arbitrary code
• Bypass tool validation
• Affect systems outside their permissions

AI agents can only:

• Receive perception data
• Generate high-level intents
• Use validated tools
• Learn from feedback

Deterministic Security

The deterministic simulation enables:

• Replay Verification: Detect desync and cheating
• Formal Verification: Mathematical proof of certain properties
• Predictable Testing: Reliable automated testing
• Audit Trails: Complete history of all decisions

Development Philosophy

Composition Over Inheritance

#![allow(unused)]
fn main() {
// Instead of inheritance hierarchies
class AIAgent extends Entity { ... }

// Use component composition
struct Entity {
    components: HashMap<ComponentId, Box<dyn Component>>
}
}

Data-Driven Design

#![allow(unused)]
fn main() {
// Behavior configured through data
#[derive(Deserialize)]
struct AIProfile {
    aggression: f32,
    curiosity: f32,
    risk_tolerance: f32,
    preferred_tools: Vec<String>,
}
}

Testable Architecture

#![allow(unused)]
fn main() {
// Every system is pure and testable
fn ai_planning_system(
    world: &World, 
    perceptions: &[PerceptionSnapshot]
) -> Vec<AIPlan> {
    // Pure function - easy to test
}
}

Comparison with Traditional Engines

Next Steps

To understand specific systems:

• AI-Native Design - Deep dive into AI architecture
• ECS Architecture - Entity-Component-System details
• Deterministic Simulation - Fixed-tick simulation
• Tool Validation System - How AI actions are validated

To start building:

• Building Your First Game
• Core Systems
• Working Examples

AI-Native Design

AstraWeave’s AI-native design represents a fundamental shift in how game engines approach artificial intelligence. Instead of treating AI as an add-on feature, we’ve built the entire engine around the principle that AI agents are first-class citizens.

The Traditional Approach (And Why It Fails)

Most game engines follow this pattern:

Game Engine → Game Logic → AI Scripting Layer → NPC Behaviors

Problems with this approach:

• AI is disconnected from core game systems
• AI agents can cheat (access hidden information, ignore physics)
• Difficult to create consistent multiplayer behavior
• AI behavior is scripted, not emergent
• Hard to test and debug AI interactions

AstraWeave’s AI-Native Approach

AstraWeave inverts this relationship:

AI Agents ← Tool Validation ← Engine Core ← Game Logic

Benefits of this approach:

• AI and human players use identical systems
• No AI cheating possible
• Emergent behavior from simple rules
• Natural multiplayer compatibility
• Testable and debuggable AI behavior

Core Principles

1. Perception-Based Decision Making

AI agents only know what they can perceive:

#![allow(unused)]
fn main() {
#[derive(Serialize, Deserialize)]
pub struct PerceptionSnapshot {
    // Only information the AI should have access to
    pub visible_entities: Vec<EntityData>,
    pub audible_events: Vec<AudioEvent>,
    pub remembered_information: Vec<MemoryItem>,
    pub world_constraints: Vec<Constraint>,
}
}

No omniscience: AI cannot access:

• Hidden game state
• Other agents’ thoughts
• Perfect world information
• Player UI state
• Debug information

Realistic limitations: AI must work within:

• Line of sight restrictions
• Hearing range limitations
• Memory capacity constraints
• Processing time limits

2. Intent-Based Actions

AI generates high-level intents, not low-level commands:

#![allow(unused)]
fn main() {
pub enum Intent {
    // High-level goals
    ExploreArea { target_region: Region, curiosity: f32 },
    SeekCover { threat_direction: Vec3, urgency: f32 },
    ProtectAlly { ally_id: EntityId, commitment: f32 },
    
    // Not low-level commands like "move left 3 pixels"
}
}

Benefits:

• AI thinks strategically, not tactically
• Natural language mapping for LLMs
• Easy to understand and debug
• Platform and implementation independent

3. Tool-Based Execution

All AI actions go through validated tools:

#![allow(unused)]
fn main() {
pub trait Tool {
    // Every action must be validated first
    fn validate(&self, world: &World, usage: &ToolUsage) -> ValidationResult;
    
    // Only valid actions are executed
    fn execute(&self, world: &mut World, usage: &ToolUsage) -> ExecutionResult;
    
    // Tools have constraints and cooldowns
    fn get_constraints(&self) -> ToolConstraints;
}
}

No direct world manipulation: AI cannot:

• Teleport entities
• Spawn infinite resources
• Ignore physics constraints
• Break game rules

The AI Pipeline Architecture

Phase 1: Perception

#![allow(unused)]
fn main() {
fn perception_system(
    mut agents: Query<(&Position, &AIAgent, &mut PerceptionState)>,
    world_entities: Query<&Position, &EntityType>,
    audio_events: Res<AudioEventBuffer>,
) {
    for (pos, agent, mut perception) in agents.iter_mut() {
        let mut snapshot = PerceptionSnapshot::new();
        
        // Gather visible entities (line of sight)
        for (other_pos, entity_type) in world_entities.iter() {
            if world.line_of_sight(pos.0, other_pos.0) {
                let distance = pos.0.distance(other_pos.0);
                if distance <= agent.vision_range {
                    snapshot.visible_entities.push(EntityData {
                        position: other_pos.0,
                        entity_type: entity_type.clone(),
                        distance,
                    });
                }
            }
        }
        
        // Gather audible events
        for event in audio_events.iter() {
            let distance = pos.0.distance(event.position);
            let volume = event.calculate_volume_at_distance(distance);
            if volume > agent.hearing_threshold {
                snapshot.audible_events.push(event.clone());
            }
        }
        
        // Include relevant memories
        snapshot.remembered_information = agent.memory.query_relevant(
            &snapshot, 
            agent.memory_capacity
        );
        
        perception.current_snapshot = Some(snapshot);
    }
}
}

Phase 2: Planning

#![allow(unused)]
fn main() {
fn ai_planning_system(
    mut agents: Query<(&AIAgent, &PerceptionState, &mut PlanningState)>,
    ai_service: Res<AIService>,
) {
    for (agent, perception, mut planning) in agents.iter_mut() {
        if let Some(snapshot) = &perception.current_snapshot {
            // Prepare input for AI model
            let planning_request = PlanningRequest {
                agent_profile: agent.profile.clone(),
                perception_data: snapshot.clone(),
                available_tools: tool_registry.get_available_tools(agent.id),
                current_goals: agent.goal_stack.clone(),
                recent_memory: agent.memory.get_recent(10),
            };
            
            // Generate plan using LLM
            match ai_service.generate_plan(planning_request) {
                Ok(plan) => {
                    info!("AI generated plan: {:?}", plan);
                    planning.current_plan = Some(plan);
                },
                Err(e) => {
                    warn!("AI planning failed: {}", e);
                    // Fallback to simple behaviors
                    planning.current_plan = Some(generate_fallback_plan(agent));
                }
            }
        }
    }
}
}

Phase 3: Validation

#![allow(unused)]
fn main() {
fn tool_validation_system(
    mut agents: Query<(&PlanningState, &mut ActionQueue)>,
    tool_registry: Res<ToolRegistry>,
    world: &World,
) {
    for (planning, mut actions) in agents.iter_mut() {
        if let Some(plan) = &planning.current_plan {
            for tool_usage in &plan.tool_usages {
                let tool = tool_registry.get_tool(&tool_usage.tool_name)?;
                
                match tool.validate(world, tool_usage) {
                    ValidationResult::Valid => {
                        actions.push(ValidatedAction {
                            tool_usage: tool_usage.clone(),
                            validation_timestamp: world.current_tick(),
                        });
                    },
                    ValidationResult::Blocked(reason) => {
                        warn!("Tool validation failed: {:?}", reason);
                        // AI learns from failure
                        agent.memory.record_failure(tool_usage, reason);
                    },
                    ValidationResult::Delayed(wait_time) => {
                        actions.push_delayed(tool_usage.clone(), wait_time);
                    }
                }
            }
        }
    }
}
}

Phase 4: Execution

#![allow(unused)]
fn main() {
fn action_execution_system(
    mut agents: Query<&mut ActionQueue>,
    tool_registry: Res<ToolRegistry>,
    mut world: ResMut<World>,
) {
    for mut actions in agents.iter_mut() {
        while let Some(action) = actions.pop_ready() {
            let tool = tool_registry.get_tool(&action.tool_usage.tool_name)?;
            
            match tool.execute(&mut world, &action.tool_usage) {
                ExecutionResult::Success => {
                    // AI learns from success
                    agent.memory.record_success(&action.tool_usage);
                },
                ExecutionResult::Failed(reason) => {
                    // Even validated actions can fail during execution
                    warn!("Action execution failed: {:?}", reason);
                    agent.memory.record_execution_failure(&action.tool_usage, reason);
                }
            }
        }
    }
}
}

Tool Design Philosophy

Tools as Affordances

In AstraWeave, tools represent what an agent can do, not what it will do:

#![allow(unused)]
fn main() {
pub struct MovementTool {
    max_speed: f32,
    acceleration: f32,
    valid_surfaces: Vec<SurfaceType>,
}

impl Tool for MovementTool {
    fn validate(&self, world: &World, usage: &ToolUsage) -> ValidationResult {
        // Check if movement is physically possible
        let agent_pos = world.get::<Position>(usage.agent_id)?;
        let target_pos = usage.parameters.get_vec3("target")?;
        
        // Line of sight check
        if !world.line_of_sight(agent_pos.0, target_pos) {
            return ValidationResult::Blocked(BlockReason::ObstructedPath);
        }
        
        // Surface validity check
        let surface_type = world.get_surface_type(target_pos);
        if !self.valid_surfaces.contains(&surface_type) {
            return ValidationResult::Blocked(BlockReason::InvalidSurface);
        }
        
        // Speed limit check
        let distance = agent_pos.0.distance(target_pos);
        let time_required = distance / self.max_speed;
        if time_required > usage.max_execution_time {
            return ValidationResult::Blocked(BlockReason::TooSlow);
        }
        
        ValidationResult::Valid
    }
}
}

Tool Composition

Complex behaviors emerge from combining simple tools:

#![allow(unused)]
fn main() {
// AI plans using multiple tools in sequence
let complex_plan = AIPlan {
    steps: vec![
        ToolUsage {
            tool_name: "MovementTool",
            parameters: movement_params,
        },
        ToolUsage {
            tool_name: "InteractionTool", 
            parameters: interaction_params,
        },
        ToolUsage {
            tool_name: "CommunicationTool",
            parameters: communication_params,
        },
    ],
};
}

Learning and Adaptation

Memory System Integration

#![allow(unused)]
fn main() {
pub struct AIMemory {
    // Short-term working memory
    working_memory: VecDeque<MemoryItem>,
    
    // Long-term episodic memory
    episodic_memory: Vec<Episode>,
    
    // Learned patterns and strategies
    strategy_memory: HashMap<Situation, Strategy>,
    
    // Failed actions and why they failed
    failure_memory: Vec<FailureRecord>,
}

impl AIMemory {
    pub fn record_success(&mut self, action: &ToolUsage, outcome: &ExecutionResult) {
        // Reinforce successful strategies
        let situation = self.extract_situation_features(action);
        let strategy = self.extract_strategy_features(action);
        self.strategy_memory.entry(situation)
            .or_default()
            .reinforce(strategy, outcome.success_metric());
    }
    
    pub fn record_failure(&mut self, action: &ToolUsage, reason: &BlockReason) {
        // Learn from failures to avoid them
        self.failure_memory.push(FailureRecord {
            action: action.clone(),
            reason: reason.clone(),
            context: self.current_context.clone(),
            timestamp: Instant::now(),
        });
    }
}
}

Dynamic Behavior Adaptation

#![allow(unused)]
fn main() {
fn adaptation_system(
    mut agents: Query<(&mut AIAgent, &AIMemory)>,
) {
    for (mut agent, memory) in agents.iter_mut() {
        // Adjust behavior based on recent experiences
        let recent_failures = memory.get_recent_failures(Duration::from_secs(300));
        
        if recent_failures.iter().any(|f| matches!(f.reason, BlockReason::TooAggressive)) {
            agent.profile.aggression *= 0.9; // Become less aggressive
        }
        
        if recent_failures.iter().any(|f| matches!(f.reason, BlockReason::TooSlow)) {
            agent.profile.urgency *= 1.1; // Become more urgent
        }
        
        // Adapt strategy preferences
        let successful_strategies = memory.get_successful_strategies();
        for (situation, strategy) in successful_strategies {
            agent.strategy_preferences.insert(situation, strategy);
        }
    }
}
}

Emergent Behavior Examples

Cooperative Pathfinding

When multiple AI agents need to navigate through a narrow passage:

#![allow(unused)]
fn main() {
// No explicit coordination code needed
// Emergent behavior arises from:
// 1. Each agent perceives others as obstacles
// 2. Movement tool validates non-collision
// 3. Agents naturally take turns or find alternate routes
}

Dynamic Alliance Formation

#![allow(unused)]
fn main() {
// Agents can form alliances based on shared threats
fn threat_response_planning(
    agent: &AIAgent,
    perception: &PerceptionSnapshot,
) -> Intent {
    let threats = perception.identify_threats();
    let potential_allies = perception.identify_potential_allies();
    
    if threats.is_empty() {
        return Intent::Explore { target: random_area() };
    }
    
    if potential_allies.is_empty() {
        return Intent::Flee { threat_direction: threats[0].position };
    }
    
    // Emergent alliance formation
    Intent::CoordinateDefense {
        allies: potential_allies,
        threat: threats[0],
        strategy: choose_defensive_strategy(threats, potential_allies),
    }
}
}

Adaptive Combat Tactics

#![allow(unused)]
fn main() {
// AI learns and counters player strategies
fn combat_planning(
    agent: &AIAgent,
    perception: &PerceptionSnapshot,
    memory: &AIMemory,
) -> Intent {
    let player = perception.find_player()?;
    
    // Analyze player's recent tactics
    let player_patterns = memory.analyze_player_behavior(&player);
    
    // Choose counter-strategy
    let counter_strategy = match player_patterns.primary_tactic {
        PlayerTactic::RushAttack => CombatStrategy::DefensiveCounter,
        PlayerTactic::RangedKiting => CombatStrategy::ClosingPincer,
        PlayerTactic::DefensiveTurtle => CombatStrategy::AreaDenial,
        PlayerTactic::Unpredictable => CombatStrategy::AdaptiveReactive,
    };
    
    Intent::ExecuteCombatStrategy {
        target: player.entity_id,
        strategy: counter_strategy,
        commitment: calculate_commitment(player_patterns.skill_level),
    }
}
}

Performance Considerations

Computational Efficiency

#![allow(unused)]
fn main() {
// AI planning can be expensive, so we use various optimizations:

pub struct AIService {
    // LLM inference can be slow
    model_cache: LRUCache<PlanningRequest, AIPlan>,
    
    // Batch multiple planning requests
    batch_processor: BatchProcessor<PlanningRequest>,
    
    // Use cheaper models for simple decisions
    model_hierarchy: Vec<AIModel>, // Fast → Accurate
}

impl AIService {
    pub fn generate_plan(&self, request: PlanningRequest) -> Result<AIPlan> {
        // Check cache first
        if let Some(cached_plan) = self.model_cache.get(&request) {
            return Ok(cached_plan.clone());
        }
        
        // Use appropriate model based on complexity
        let model = self.select_model(request.complexity());
        
        // Generate plan
        let plan = model.generate_plan(request)?;
        
        // Cache result
        self.model_cache.insert(request, plan.clone());
        
        Ok(plan)
    }
}
}

Memory Management

#![allow(unused)]
fn main() {
// AI memory systems need careful management
impl AIMemory {
    pub fn cleanup_old_memories(&mut self) {
        // Remove memories older than threshold
        let cutoff = Instant::now() - Duration::from_secs(3600); // 1 hour
        self.episodic_memory.retain(|episode| episode.timestamp > cutoff);
        
        // Compress similar memories
        self.compress_similar_episodes();
        
        // Keep only the most important failures
        self.failure_memory.sort_by_key(|f| f.importance_score());
        self.failure_memory.truncate(100); // Keep top 100
    }
}
}

Debugging AI Behavior

Explainable AI

#![allow(unused)]
fn main() {
#[derive(Debug, Serialize)]
pub struct AIPlan {
    pub intent: Intent,
    pub reasoning: String, // Natural language explanation
    pub confidence: f32,
    pub alternative_plans: Vec<AlternativePlan>,
    pub decision_factors: Vec<DecisionFactor>,
}

// Example reasoning output:
"I can see an enemy at position (10, 5) who appears to be low on health. 
My ally is engaged in combat nearby and could use support. I have a clear 
line of sight and my weapon is ready. I'm choosing to attack rather than 
flank because the enemy seems focused on my ally and won't see me coming."
}

Debug Visualization

#![allow(unused)]
fn main() {
// In development builds, expose AI decision making
#[cfg(debug_assertions)]
impl AIAgent {
    pub fn get_debug_info(&self) -> AIDebugInfo {
        AIDebugInfo {
            current_perception: self.perception.clone(),
            active_plan: self.planning.current_plan.clone(),
            recent_decisions: self.memory.get_recent_decisions(10),
            personality_state: self.profile.clone(),
            tool_availability: self.get_available_tools(),
        }
    }
}
}

Integration with Traditional Game Systems

Physics Integration

#![allow(unused)]
fn main() {
// AI respects physics constraints
impl Tool for MovementTool {
    fn validate(&self, world: &World, usage: &ToolUsage) -> ValidationResult {
        let physics_world = world.resource::<PhysicsWorld>();
        let agent_body = physics_world.get_body(usage.agent_id)?;
        
        // Check if movement would cause collision
        let proposed_movement = usage.parameters.get_vec3("target")?;
        if physics_world.would_collide(agent_body, proposed_movement) {
            return ValidationResult::Blocked(BlockReason::PhysicsCollision);
        }
        
        ValidationResult::Valid
    }
}
}

Animation Integration

#![allow(unused)]
fn main() {
// AI actions trigger appropriate animations
impl Tool for CombatTool {
    fn execute(&self, world: &mut World, usage: &ToolUsage) -> ExecutionResult {
        let attack_type = usage.parameters.get_string("attack_type")?;
        
        // Trigger combat animation
        world.get_mut::<AnimationController>(usage.agent_id)?
             .play_animation(format!("attack_{}", attack_type));
        
        // Execute combat logic
        self.resolve_combat(world, usage)
    }
}
}

Comparison: Traditional vs AI-Native

Best Practices for AI-Native Development

1. Design Affordances, Not Behaviors

#![allow(unused)]
fn main() {
// Good: Define what an agent CAN do
pub struct InteractionTool {
    pub interaction_range: f32,
    pub valid_targets: Vec<EntityType>,
    pub cooldown: Duration,
}

// Avoid: Scripting what an agent WILL do
// pub fn npc_behavior_script() { ... }
}

2. Embrace Failure as Learning

#![allow(unused)]
fn main() {
// AI failures are features, not bugs
if let Err(validation_error) = tool.validate(world, usage) {
    // Don't just log the error - let the AI learn from it
    agent.memory.record_lesson(validation_error, current_context);
    
    // AI will avoid this mistake in similar situations
}
}

3. Provide Rich Perception

#![allow(unused)]
fn main() {
// Give AI agents the information they need to make good decisions
pub struct PerceptionSnapshot {
    // Not just positions, but meaningful context
    pub entities: Vec<EntityPerception>,
    pub environmental_cues: Vec<EnvironmentalCue>,
    pub social_context: SocialContext,
    pub recent_events: Vec<GameEvent>,
}
}

4. Use Hierarchical Planning

#![allow(unused)]
fn main() {
// Break complex goals into manageable sub-goals
pub enum Intent {
    // High-level strategic goals
    DefendTerritory { area: Region },
    
    // Mid-level tactical goals  
    EstablishDefensivePosition { chokepoint: Vec3 },
    
    // Low-level operational goals
    MoveToCover { cover_position: Vec3 },
}
}

Future Directions

Advanced AI Architectures

• Multi-Agent Planning: Coordinated group decision making
• Hierarchical Temporal Memory: Better long-term memory systems
• Causal Reasoning: Understanding cause-and-effect relationships
• Meta-Learning: AI that learns how to learn better

Performance Optimizations

• Neural Network Compression: Smaller, faster AI models
• Predictive Caching: Pre-compute likely AI decisions
• Distributed Processing: AI planning across multiple cores/machines
• Hybrid Approaches: Combine neural networks with symbolic reasoning

AI-native design is not just about making NPCs smarter - it’s about creating fundamentally new types of interactive experiences where AI agents are true participants in the game world, subject to the same rules and constraints as human players.

ECS Architecture

AstraWeave uses an archetype-based Entity Component System (ECS) designed for deterministic, AI-native game development. The architecture provides cache-friendly iteration, deterministic execution ordering, and efficient event propagation for AI perception.

Core Concepts

Entity

An Entity is a unique identifier representing a game object. Internally, entities use a 32-bit ID and 32-bit generation counter for safe recycling:

#![allow(unused)]
fn main() {
use astraweave_ecs::*;

let mut world = World::new();

// Spawn returns a unique Entity handle
let player = world.spawn();
let enemy = world.spawn();

// Check if entity is alive (generation-safe)
assert!(world.is_alive(player));

// Despawn removes entity and all components
world.despawn(enemy);
assert!(!world.is_alive(enemy));
}

The generation counter prevents “dangling entity” bugs—if you hold a stale entity handle after despawn, operations silently fail rather than affecting the recycled entity.

Component

A Component is data attached to an entity. Any 'static + Send + Sync type automatically implements Component:

#![allow(unused)]
fn main() {
// Components are just plain structs
#[derive(Clone, Copy)]
struct Position { x: f32, y: f32 }

#[derive(Clone, Copy)]
struct Velocity { x: f32, y: f32 }

struct Health(i32);

// Insert components
let mut world = World::new();
let e = world.spawn();
world.insert(e, Position { x: 0.0, y: 0.0 });
world.insert(e, Velocity { x: 1.0, y: 0.0 });
world.insert(e, Health(100));

// Query components
if let Some(pos) = world.get::<Position>(e) {
    println!("Entity at ({}, {})", pos.x, pos.y);
}

// Mutate components
if let Some(health) = world.get_mut::<Health>(e) {
    health.0 -= 10;
}
}

Resource

A Resource is a singleton value accessible across systems—perfect for shared state like input, time, or game configuration:

#![allow(unused)]
fn main() {
struct DeltaTime(f32);
struct InputState {
    move_direction: (f32, f32),
    attack_pressed: bool,
}

let mut world = World::new();

// Insert resources
world.insert_resource(DeltaTime(1.0 / 60.0));
world.insert_resource(InputState {
    move_direction: (0.0, 0.0),
    attack_pressed: false,
});

// Query resources
let dt = world.get_resource::<DeltaTime>().unwrap();
let input = world.get_resource::<InputState>().unwrap();
}

Archetype Storage

What is an Archetype?

An Archetype groups all entities with the same set of component types. When you add or remove components, the entity moves to a different archetype.

Archetype 0: [Position]
├── Entity(1): Position(0,0)
└── Entity(4): Position(5,3)

Archetype 1: [Position, Velocity]
├── Entity(2): Position(1,1), Velocity(1,0)
└── Entity(3): Position(2,2), Velocity(0,1)

Archetype 2: [Position, Velocity, Health]
└── Entity(5): Position(3,3), Velocity(1,1), Health(100)

This design provides:

• Cache-friendly iteration: Components of the same type are stored contiguously
• Efficient queries: Filter by archetype signature, not per-entity checks
• Predictable memory layout: Improves CPU prefetching

Storage Modes

AstraWeave supports two storage backends:

Box Mode (Legacy): Components stored as Box<dyn Any>. Works for any component type but has heap indirection overhead.

BlobVec Mode (Optimized): Components stored in contiguous byte arrays. Requires component registration but provides 2-10× faster iteration:

#![allow(unused)]
fn main() {
let mut world = World::new();

// Register component for optimized storage
world.register_component::<Position>();
world.register_component::<Velocity>();

// Now Position and Velocity use BlobVec storage
}

SparseSet Entity Lookup

Entity-to-archetype mapping uses a SparseSet for O(1) lookup:

Memory Layout:
sparse: [None, Some(0), None, Some(1), None, Some(2), ...]
             ↓              ↓              ↓
dense:  [Entity(1), Entity(3), Entity(5), ...]

This replaced the previous BTreeMap approach, providing 12-57× faster entity lookups.

System Architecture

System Stages

AstraWeave uses fixed stages for deterministic execution—critical for AI agents that must produce identical behavior across game sessions:

#![allow(unused)]
fn main() {
use astraweave_ecs::*;

// System stages execute in order
pub struct SystemStage;

impl SystemStage {
    pub const PRE_SIMULATION: &'static str = "pre_simulation";
    pub const PERCEPTION: &'static str = "perception";      // Build AI snapshots
    pub const SIMULATION: &'static str = "simulation";      // Game logic
    pub const AI_PLANNING: &'static str = "ai_planning";    // Generate plans
    pub const PHYSICS: &'static str = "physics";            // Apply forces
    pub const POST_SIMULATION: &'static str = "post_simulation";
    pub const PRESENTATION: &'static str = "presentation";  // Render, audio
}
}

The AI-native game loop follows: Perception → Reasoning → Planning → Action

┌───────────────────────────────────────────────────────────────────────┐
│                         Frame N                                       │
├─────────────┬─────────────┬──────────────┬─────────────┬─────────────┤
│ pre_sim     │ perception  │  simulation  │ ai_planning │  physics    │
│ (setup)     │ (sensors)   │ (game logic) │ (decide)    │ (movement)  │
├─────────────┴─────────────┴──────────────┴─────────────┴─────────────┤
│                       post_sim → presentation                         │
└───────────────────────────────────────────────────────────────────────┘

Registering Systems

Systems are functions that operate on the World:

#![allow(unused)]
fn main() {
fn movement_system(world: &mut World) {
    world.each_mut::<Position>(|entity, pos| {
        if let Some(vel) = world.get::<Velocity>(entity) {
            pos.x += vel.x;
            pos.y += vel.y;
        }
    });
}

fn ai_perception_system(world: &mut World) {
    // Build WorldSnapshot for AI agents
    // (see AI documentation for details)
}

let mut app = App::new();
app.add_system("simulation", movement_system);
app.add_system("perception", ai_perception_system);
}

Query Types

AstraWeave provides ergonomic query iterators:

#![allow(unused)]
fn main() {
// Single-component read-only query
let query = Query::<Position>::new(&world);
for (entity, pos) in query {
    println!("Entity {:?} at ({}, {})", entity, pos.x, pos.y);
}

// Two-component query
let query2 = Query2::<Position, Velocity>::new(&world);
for (entity, pos, vel) in query2 {
    println!("Entity {:?} moving at ({}, {})", entity, vel.x, vel.y);
}

// Mutable queries
let mut query = Query2Mut::<Position, Velocity>::new(&mut world);
for (entity, pos, vel) in query.iter_mut() {
    pos.x += vel.x;
    pos.y += vel.y;
}
}

Event System

Events enable reactive AI behaviors and decoupled communication between systems.

Sending Events

#![allow(unused)]
fn main() {
use astraweave_ecs::*;

// Define custom events
#[derive(Clone)]
struct DamageEvent {
    target: Entity,
    amount: i32,
    source: Option<Entity>,
}

impl Event for DamageEvent {}

// Send events via Events resource
let mut events = Events::new();
events.send(DamageEvent {
    target: player,
    amount: 25,
    source: Some(enemy),
});
}

Reading Events

#![allow(unused)]
fn main() {
// Systems read events via EventReader
fn damage_system(world: &mut World) {
    let mut events = world.get_resource_mut::<Events>().unwrap();
    
    for event in events.drain::<DamageEvent>() {
        if let Some(health) = world.get_mut::<Health>(event.target) {
            health.0 -= event.amount;
        }
    }
}
}

Built-in Events

AstraWeave provides common events for AI perception:

App Builder Pattern

The App struct provides a Bevy-like builder pattern:

use astraweave_ecs::*;

#[derive(Clone, Copy)]
struct Position { x: f32, y: f32 }

#[derive(Clone, Copy)]
struct Velocity { x: f32, y: f32 }

fn movement_system(world: &mut World) {
    world.each_mut::<Position>(|entity, pos| {
        if let Some(vel) = world.get::<Velocity>(entity) {
            pos.x += vel.x;
            pos.y += vel.y;
        }
    });
}

fn main() {
    let mut app = App::new();
    app.add_system("simulation", movement_system);
    
    // Spawn entities
    let e = app.world.spawn();
    app.world.insert(e, Position { x: 0.0, y: 0.0 });
    app.world.insert(e, Velocity { x: 1.0, y: 0.0 });
    
    // Run 100 simulation ticks
    app = app.run_fixed(100);
    
    // Entity moved 100 units
    let pos = app.world.get::<Position>(e).unwrap();
    assert_eq!(pos.x, 100.0);
}

Plugin Architecture

Plugins encapsulate related systems and resources:

#![allow(unused)]
fn main() {
pub trait Plugin {
    fn build(&self, app: &mut App);
}

struct PhysicsPlugin;

impl Plugin for PhysicsPlugin {
    fn build(&self, app: &mut App) {
        app.add_system("physics", physics_tick);
        app.world.insert_resource(PhysicsConfig::default());
    }
}

// Add plugins to app
let app = App::new().add_plugin(PhysicsPlugin);
}

Command Buffer

For deferred operations (avoiding borrow conflicts), use CommandBuffer:

#![allow(unused)]
fn main() {
use astraweave_ecs::*;

// Register components first
let mut world = World::new();
world.register_component::<Position>();
world.register_component::<Velocity>();

// Queue commands
let mut cmd = CommandBuffer::new();
cmd.spawn()
    .insert(Position { x: 0.0, y: 0.0 })
    .insert(Velocity { x: 1.0, y: 0.0 });

cmd.entity(existing_entity)
    .remove::<Velocity>();

// Apply all commands at once
cmd.apply(&mut world);
}

Determinism

AstraWeave ECS is designed for deterministic replay and multiplayer synchronization:

Ordered Iteration

Entities within an archetype iterate in spawn order (using packed arrays), ensuring consistent system behavior.

Seeded RNG

Use the built-in deterministic RNG:

#![allow(unused)]
fn main() {
use astraweave_ecs::Rng;

let mut rng = Rng::from_seed(42);
let damage = rng.next_f32() * 10.0;  // Same value every time with seed 42
}

Event Ordering

Events are stored in order-of-send, with frame tracking for cleanup:

#![allow(unused)]
fn main() {
let events = Events::new()
    .with_keep_frames(2);  // Keep events for 2 frames
}

Performance Characteristics

Benchmarked on the AstraWeave test suite (Week 10):

60 FPS Budget

With 16.67 ms per frame, current performance provides:

• 1,000 entities: 1.14 ms frame time (93% headroom)
• 10,000 entities: ~11 ms frame time (34% headroom)
• Movement system: 106 µs for 1,000 entities (9.4× faster post-optimization)

Advanced Topics

Custom Component Storage

For specialized use cases, you can interact with archetype storage directly:

#![allow(unused)]
fn main() {
// Access archetypes for low-level iteration
for archetype in world.archetypes().iter() {
    println!("Archetype {} has {} entities", 
             archetype.id, archetype.len());
    
    for &entity in archetype.entities_vec() {
        // Direct entity access
    }
}
}

Profiling Integration

Enable the profiling feature for Tracy integration:

[dependencies]
astraweave-ecs = { version = "0.4", features = ["profiling"] }

Key spans are automatically instrumented: ECS::World::spawn, ECS::World::get, ECS::Schedule::run.

See Also

• API Reference: ECS — Full API documentation
• Core Systems: AI — AI integration with ECS
• Patterns — Common ECS design patterns
• First Companion Tutorial — Hands-on ECS usage

Deterministic Simulation

AstraWeave provides bit-identical deterministic simulation across all core systems. This enables reproducible AI behavior, lockstep multiplayer, replay systems, and reliable regression testing.

Why Determinism Matters

For AI-native gameplay, determinism is critical:

#![allow(unused)]
fn main() {
// Without determinism (BAD):
// Run 1: Entity 42 attacks first (random HashMap iteration)
// Run 2: Entity 17 attacks first (different outcome!)
// Multiplayer: Host and client see different results

// With determinism (GOOD):
// Run 1, 2, 3...: Same entity order, same decisions, same outcome
// Multiplayer: All clients see identical simulation
// Replays: Record inputs, reproduce exact gameplay
}

Use Cases:

• Reproducible AI: Same world state → same AI decisions
• Lockstep Multiplayer: Only sync inputs, not full game state
• Replay Systems: Record/playback for debugging and spectating
• Regression Testing: Validate AI changes don’t break behavior
• Competitive Gaming: Provably fair gameplay

Determinism Guarantees

What IS Guaranteed

What is NOT Guaranteed

• Spawn order across archetypes: Entity order changes when components added/removed
• Floating-point across platforms: Different CPUs may produce slightly different results
• Non-deterministic RNG: Must use seeded RNG explicitly

Fixed-Tick Simulation

AstraWeave runs physics and AI at exactly 60Hz:

#![allow(unused)]
fn main() {
const TICK_RATE: f64 = 60.0;
const TICK_DURATION: Duration = Duration::from_nanos(16_666_667);

// Every simulation step advances by exactly this amount
pub fn step(world: &mut World, cfg: &SimConfig) {
    world.tick(cfg.dt);  // cfg.dt = 1/60 second
}
}

Benefits:

• Consistent timing across different hardware
• Decoupled from render frame rate
• Predictable performance testing
• Reliable networking

ECS Determinism

BTreeMap Storage

The ECS uses BTreeMap instead of HashMap for archetype storage:

#![allow(unused)]
fn main() {
/// CRITICAL: BTreeMap for deterministic iteration by ID
pub struct ArchetypeSet {
    archetypes: BTreeMap<ArchetypeId, Archetype>,
    // NOT HashMap - iteration order would be non-deterministic!
}
}

Why this matters:

• HashMap iteration order depends on hash function and memory layout
• BTreeMap iteration order is sorted by key (deterministic)
• AI agents iterate entities in identical order every run

Entity Iteration Order

#![allow(unused)]
fn main() {
// Entities are stored per-archetype
let e1 = world.spawn();  // Empty archetype (ID 0)
let e2 = world.spawn();  // Empty archetype (ID 0)
world.insert(e1, Position::new(1.0, 1.0));  // Moves e1 to Position archetype (ID 1)

// Iteration order: [e2, e1]
// - Archetype 0 (empty) visited first: contains e2
// - Archetype 1 (Position) visited second: contains e1
// NOT spawn order [e1, e2] - but IS deterministic!
}

Preserving Spawn Order

If spawn order is critical, track it explicitly:

#![allow(unused)]
fn main() {
#[derive(Component, Clone, Copy)]
struct SpawnOrder(u64);

// When spawning:
let e = world.spawn();
world.insert(e, SpawnOrder(world.entity_count() as u64));

// When iterating in spawn order:
let mut entities = world.entities_with::<SpawnOrder>();
entities.sort_by_key(|&e| world.get::<SpawnOrder>(e).unwrap().0);
}

Capture & Replay

AstraWeave provides state capture for debugging and determinism validation:

#![allow(unused)]
fn main() {
use astraweave_core::{capture_state, replay_state, SimConfig};

// Capture world state at tick 100
capture_state(100, "save.json", &world)?;

// Later: Replay from saved state
let cfg = SimConfig { dt: 1.0 / 60.0 };
let world = replay_state("save.json", 100, &cfg)?;  // Run 100 ticks
}

Snapshot Format

{
  "tick": 100,
  "world": {
    "t": 1.6666,
    "next_id": 42,
    "obstacles": [[5, 10], [0, 0], [15, 20]]
  }
}

Stability guarantees:

• Obstacles sorted for consistent serialization
• JSON format for human readability
• Minimal state for fast save/load

Physics Determinism

Parallel Processing

Physics uses Rayon with deterministic iteration:

#![allow(unused)]
fn main() {
/// Parallel iterator helpers for deterministic physics
impl PhysicsParallelOps {
    /// Process rigid bodies in parallel (deterministic order)
    pub fn par_process_bodies<F>(&self, bodies: &mut [RigidBody], f: F)
    where
        F: Fn(&mut RigidBody) + Sync,
    {
        // Rayon's par_iter preserves element order
        bodies.par_iter_mut().for_each(f);
    }
}
}

Fixed Timestep

Physics simulation uses fixed timesteps:

#![allow(unused)]
fn main() {
// Physics world with deterministic gravity
let physics = PhysicsWorld::new(Vec3::new(0.0, -9.81, 0.0));

// Fixed step (not variable dt!)
physics.step(1.0 / 60.0);  // Always 16.67ms
}

Testing Determinism

Validation Tests

The ECS includes comprehensive determinism tests:

#![allow(unused)]
fn main() {
#[test]
fn test_query_iteration_deterministic() {
    let mut world = World::new();
    
    // Spawn entities with components
    for i in 0..100 {
        let e = world.spawn();
        world.insert(e, Position { x: i as f32, y: 0.0 });
    }
    
    // First iteration
    let order1: Vec<Entity> = world.entities_with::<Position>().collect();
    
    // Second iteration - must be identical
    let order2: Vec<Entity> = world.entities_with::<Position>().collect();
    
    assert_eq!(order1, order2, "Iteration order must be deterministic");
}
}

Multi-Run Verification

#![allow(unused)]
fn main() {
#[test]
fn test_determinism_across_runs() {
    let results: Vec<Vec<Entity>> = (0..5)
        .map(|_| {
            let mut world = World::new();
            // Same operations each run
            setup_world(&mut world);
            world.entities_with::<AIAgent>().collect()
        })
        .collect();
    
    // All runs must produce identical results
    for run in &results[1..] {
        assert_eq!(&results[0], run);
    }
}
}

Best Practices

DO

#![allow(unused)]
fn main() {
// ✅ Use fixed timestep
world.step(FIXED_DT);

// ✅ Use seeded RNG
let mut rng = StdRng::seed_from_u64(12345);

// ✅ Use BTreeMap for deterministic iteration
let entities: BTreeMap<EntityId, Entity> = ...;

// ✅ Sort before iteration if order matters
let mut entities = query.iter().collect::<Vec<_>>();
entities.sort_by_key(|e| e.id());
}

DON’T

#![allow(unused)]
fn main() {
// ❌ Variable timestep
world.step(delta_time);

// ❌ Unseeded RNG
let mut rng = rand::thread_rng();

// ❌ HashMap for gameplay-critical iteration
let entities: HashMap<EntityId, Entity> = ...;

// ❌ Rely on spawn order across archetype changes
let first = world.entities().next();  // Order may change!
}

Performance Impact

Determinism adds minimal overhead:

In practice: For typical games (<10,000 entities), the overhead is negligible (<1% of frame budget).

Related Documentation

• ECS Architecture - Entity-Component-System details
• AI-Native Design - How determinism enables AI
• Performance Optimization - Frame budget analysis

See Also

• astraweave-ecs/src/determinism_tests.rs - 763 lines of determinism validation
• astraweave-core/src/capture_replay.rs - State capture/replay implementation
• astraweave-physics/src/async_scheduler.rs - Deterministic parallel physics

Tool Validation System

The AstraWeave LLM integration includes a comprehensive tool validation system that ensures LLM-generated plans are safe and comply with the game’s allowed actions.

Overview

The tool validation system works in three layers:

1. Schema Validation: Ensures JSON structure matches expected format
2. Tool Registry Validation: Verifies all actions are in the allowed tool set
3. Engine Validation: Runtime checks for cooldowns, line-of-sight, and other constraints

Components

ToolRegistry

The ToolRegistry defines which tools are available to the LLM:

#![allow(unused)]
fn main() {
pub struct ToolRegistry {
    pub tools: Vec<ToolSpec>,
    pub constraints: Constraints,
}

pub struct ToolSpec {
    pub name: String,
    pub args: BTreeMap<String, String>, // argument name -> type
}
}

Validation Process

1. LLM Response Parsing: Parse the JSON response into a PlanIntent
2. Tool Allowlist Check: Verify each action is in the registry
3. Type Validation: Ensure arguments match expected types (future enhancement)
4. Runtime Validation: Engine checks constraints during execution

Supported Actions

• MoveTo: Move companion to specified coordinates
• Throw: Throw items (smoke, grenade) at target location
• CoverFire: Provide covering fire at target for duration
• Revive: Revive allied units

Error Handling

The system provides clear error messages for validation failures:

• Invalid JSON format
• Disallowed tools used by LLM
• Missing required arguments
• Type mismatches (future)

Security Features

• Allowlist-only: Only pre-approved actions can be executed
• No dynamic code execution: All actions are statically defined
• Input sanitization: JSON parsing prevents injection attacks
• Constraint enforcement: Runtime validation prevents illegal moves

Usage Example

#![allow(unused)]
fn main() {
use astraweave_llm::{parse_llm_plan, MockLlm, plan_from_llm};

// Create tool registry
let registry = ToolRegistry {
    tools: vec![
        ToolSpec {
            name: "move_to".into(),
            args: [("x", "i32"), ("y", "i32")].into_iter().collect(),
        }
    ],
    constraints: Constraints::default(),
};

// Parse and validate LLM response
let plan = parse_llm_plan(llm_response, &registry)?;

// Full end-to-end validation
let plan = plan_from_llm(&client, &world_snapshot, &registry).await?;
}

Testing

The validation system includes comprehensive tests covering:

• Valid plan parsing
• Invalid JSON handling
• Disallowed tool detection
• Empty plan handling
• All action types
• Error message verification

Run tests with:

cargo test -p astraweave-llm

Future Enhancements

• Argument type validation
• Parameter range checking
• Cost/resource validation
• Complex constraint evaluation
• Custom validation plugins

AI System

AstraWeave’s AI system is the core differentiator of the engine. Unlike traditional game engines where AI is an afterthought, AstraWeave treats AI agents as first-class citizens that interact with the game world through validated tools.

In AstraWeave, AI agents cannot cheat. They must use the same validated game systems as players, ensuring fair and emergent gameplay.

Architecture Overview

graph TB
    subgraph "AI Pipeline"
        Perception[Perception Bus]
        Memory[Agent Memory]
        Planning[Planning Layer]
        Tools[Tool Sandbox]
        Validation[Engine Validation]
    end
    
    subgraph "Game World"
        ECS[ECS World State]
        Physics[Physics System]
        Nav[Navigation]
    end
    
    ECS --> Perception
    Perception --> Memory
    Memory --> Planning
    Planning --> Tools
    Tools --> Validation
    Validation --> ECS

Core Components

Perception Bus

The perception system provides AI agents with a filtered view of the world:

#![allow(unused)]
fn main() {
use astraweave_ai::perception::*;

#[derive(Component)]
struct AiAgent {
    perception_radius: f32,
    perception_filter: PerceptionFilter,
}

fn perception_system(
    agents: Query<(Entity, &Transform, &AiAgent)>,
    percievables: Query<(Entity, &Transform, &Percievable)>,
    mut perception_bus: ResMut<PerceptionBus>,
) {
    for (agent_entity, agent_transform, agent) in agents.iter() {
        let mut percepts = Vec::new();
        
        for (target, target_transform, percievable) in percievables.iter() {
            let distance = agent_transform.translation
                .distance(target_transform.translation);
            
            if distance <= agent.perception_radius {
                percepts.push(Percept {
                    entity: target,
                    position: target_transform.translation,
                    category: percievable.category,
                    properties: percievable.properties.clone(),
                });
            }
        }
        
        perception_bus.update(agent_entity, percepts);
    }
}
}

See Perception Bus for details.

Planning Layer

AI agents use LLM-based planning to decide actions:

#![allow(unused)]
fn main() {
use astraweave_ai::planning::*;

fn planning_system(
    mut agents: Query<(&mut AiPlanner, &PerceptionState)>,
    llm: Res<LlmClient>,
) {
    for (mut planner, perception) in agents.iter_mut() {
        if planner.needs_replan() {
            let context = build_context(perception);
            
            match llm.plan(&context, &planner.available_tools) {
                Ok(plan) => planner.set_plan(plan),
                Err(e) => planner.fallback_behavior(),
            }
        }
    }
}
}

See Planning Layer for details.

Tool Sandbox

All AI actions go through the tool sandbox for validation:

#![allow(unused)]
fn main() {
use astraweave_ai::tools::*;

fn execute_tool_system(
    mut agents: Query<&mut AiPlanner>,
    mut tool_executor: ResMut<ToolExecutor>,
    validator: Res<ToolValidator>,
) {
    for mut planner in agents.iter_mut() {
        if let Some(tool_call) = planner.next_action() {
            match validator.validate(&tool_call) {
                ValidationResult::Valid => {
                    tool_executor.execute(tool_call);
                }
                ValidationResult::Invalid(reason) => {
                    planner.action_failed(reason);
                }
            }
        }
    }
}
}

See Tool Sandbox for details.

Behavior Trees

For deterministic, reactive behaviors:

#![allow(unused)]
fn main() {
use astraweave_behavior::*;

let patrol_tree = BehaviorTree::new(
    Selector::new(vec![
        Sequence::new(vec![
            Condition::new(|ctx| ctx.enemy_visible()),
            Action::new(|ctx| ctx.engage_combat()),
        ]),
        Sequence::new(vec![
            Condition::new(|ctx| ctx.at_patrol_point()),
            Action::new(|ctx| ctx.next_patrol_point()),
        ]),
        Action::new(|ctx| ctx.move_to_patrol_point()),
    ])
);
}

See Behavior Trees for details.

AI Agent Configuration

Basic Agent Setup

#![allow(unused)]
fn main() {
fn spawn_companion(world: &mut World) -> Entity {
    world.spawn((
        Transform::default(),
        AiAgent::new()
            .with_personality("friendly and helpful")
            .with_perception_radius(15.0)
            .with_tick_budget(Duration::from_millis(8)),
        
        PerceptionState::default(),
        AiPlanner::new(vec![
            Tool::move_to(),
            Tool::attack(),
            Tool::use_item(),
            Tool::speak(),
        ]),
        
        NavAgent::default(),
        DialogueCapable::default(),
    ))
}
}

Tick Budget

AI has a strict time budget per simulation tick:

#![allow(unused)]
fn main() {
let config = AiConfig {
    tick_budget_ms: 8,
    max_concurrent_plans: 4,
    plan_cache_duration: Duration::from_secs(1),
    fallback_on_timeout: true,
};
}

If planning exceeds the budget, agents use cached plans or fallback behaviors.

LLM Integration

Ollama Setup

AstraWeave uses Ollama for local LLM inference:

ollama serve
ollama pull hermes2-pro-mistral

Configuration

#![allow(unused)]
fn main() {
let llm_config = LlmConfig {
    endpoint: "http://localhost:11434".into(),
    model: "hermes2-pro-mistral".into(),
    temperature: 0.7,
    max_tokens: 256,
    timeout: Duration::from_millis(100),
};
}

Tool Calling

AstraWeave uses structured tool calling:

#![allow(unused)]
fn main() {
let tools = vec![
    ToolDefinition {
        name: "move_to",
        description: "Move to a target location",
        parameters: json!({
            "type": "object",
            "properties": {
                "target": { "type": "array", "items": { "type": "number" } }
            }
        }),
    },
];

let response = llm.generate_with_tools(prompt, &tools).await?;
}

Performance Considerations

Batching

Group AI queries for efficiency:

#![allow(unused)]
fn main() {
let batch = agents.iter()
    .filter(|a| a.needs_replan())
    .take(4)
    .collect::<Vec<_>>();

let results = llm.batch_plan(&batch).await;
}

Caching

Cache plans to reduce LLM calls:

#![allow(unused)]
fn main() {
let planner = AiPlanner::new(tools)
    .with_plan_cache(Duration::from_secs(2))
    .with_context_hash(true);
}

Fallback Behaviors

Always define fallbacks:

#![allow(unused)]
fn main() {
impl AiAgent {
    fn fallback_behavior(&self) -> Action {
        match self.role {
            Role::Companion => Action::FollowPlayer,
            Role::Guard => Action::Patrol,
            Role::Merchant => Action::Idle,
        }
    }
}
}

Subsections

• Perception Bus - How AI perceives the world
• Planning Layer - LLM-based decision making
• Tool Sandbox - Validated action execution
• Behavior Trees - Deterministic reactive behaviors

Perception Bus

Planning Layer

Tool Sandbox

Behavior Trees

AI Arbiter System

Status: Production Ready
Crate: astraweave-ai (requires llm_orchestrator feature)
Documentation: See also Complete Implementation Guide

The AIArbiter is a hybrid AI control system that combines instant tactical decisions (GOAP) with deep strategic reasoning (LLM), achieving zero user-facing latency while maintaining LLM-level intelligence.

The Problem

Traditional game AI faces a dilemma:

Players either wait 20 seconds for smart AI or get immediate but shallow responses.

The Solution

The arbiter provides zero user-facing latency by:

1. Instant GOAP control - Returns tactical actions in 101.7 ns
2. Background LLM planning - Generates strategic plans asynchronously
3. Seamless transitions - Switches to LLM plans when ready
4. Non-blocking polling - Checks LLM completion in 104.7 ns

Performance

Scalability

Quick Start

#![allow(unused)]
fn main() {
use astraweave_ai::{AIArbiter, LlmExecutor, GoapOrchestrator, RuleOrchestrator};
use std::sync::Arc;

// Create arbiter
let llm_orch = Arc::new(LlmOrchestrator::new(/* config */));
let runtime = tokio::runtime::Handle::current();
let llm_executor = LlmExecutor::new(llm_orch, runtime);

let goap = Box::new(GoapOrchestrator::new());
let bt = Box::new(RuleOrchestrator);

let mut arbiter = AIArbiter::new(llm_executor, goap, bt);

// Game loop
loop {
    let snapshot = build_world_snapshot(/* ... */);
    let action = arbiter.update(&snapshot);  // 101.7 ns
    execute_action(action);
}
}

Architecture

Three-Tier Control System

┌─────────────────────────────────────────────────────┐
│                   AIArbiter                         │
│  (Orchestration Layer - 101.7 ns overhead)          │
└────┬────────────────────┬────────────────────┬──────┘
     │                    │                    │
     ▼                    ▼                    ▼
┌──────────┐      ┌──────────────┐     ┌──────────┐
│   GOAP   │      │   Qwen3-8B    │     │    BT    │
│ (3-5 ns) │      │ (13-21s async)│     │ Fallback │
└──────────┘      └──────────────┘     └──────────┘

Mode State Machine

        ┌──────────────┐
        │     GOAP     │ ◄─────────┐
        │ (Instant AI) │           │
        └───────┬──────┘           │
                │                  │
                │ LLM ready        │ Plan exhausted
                │                  │
        ┌───────▼──────────┐       │
        │   ExecutingLLM   │───────┘
        │  (Step-by-step)  │
        └──────────────────┘
                │
                │ Empty plan
                ▼
        ┌──────────────┐
        │ BehaviorTree │
        │  (Fallback)  │
        └──────────────┘

API Reference

AIArbiter

#![allow(unused)]
fn main() {
pub struct AIArbiter { /* ... */ }

impl AIArbiter {
    /// Create new arbiter in GOAP mode
    pub fn new(
        llm_executor: LlmExecutor,
        goap: Box<dyn Orchestrator>,
        bt: Box<dyn Orchestrator>,
    ) -> Self;
    
    /// Set LLM request cooldown (default: 15s)
    pub fn with_llm_cooldown(self, cooldown: f32) -> Self;
    
    /// Main control loop - call every frame
    pub fn update(&mut self, snap: &WorldSnapshot) -> ActionStep;
    
    /// Get current mode
    pub fn mode(&self) -> AIControlMode;
    
    /// Check if LLM task is active
    pub fn is_llm_active(&self) -> bool;
    
    /// Get performance metrics
    pub fn metrics(&self) -> (
        usize,  // mode_transitions
        usize,  // llm_requests
        usize,  // llm_successes
        usize,  // llm_failures
        usize,  // goap_actions
        usize,  // llm_steps_executed
    );
}
}

AIControlMode

#![allow(unused)]
fn main() {
pub enum AIControlMode {
    GOAP,                              // Fast tactical mode
    ExecutingLLM { step_index: usize }, // Executing LLM plan
    BehaviorTree,                      // Emergency fallback
}
}

Common Patterns

Pattern 1: Basic Agent

#![allow(unused)]
fn main() {
pub struct AIAgent {
    arbiter: AIArbiter,
}

impl AIAgent {
    pub fn update(&mut self, snap: &WorldSnapshot) -> ActionStep {
        self.arbiter.update(snap)
    }
}
}

Pattern 2: Shared LLM Executor

#![allow(unused)]
fn main() {
// Create once, clone for each agent
let base_executor = LlmExecutor::new(llm_orch, runtime);

let agents: Vec<AIAgent> = (0..100)
    .map(|_| AIAgent::new(base_executor.clone()))
    .collect();
}

Pattern 3: Custom Cooldown

#![allow(unused)]
fn main() {
// Aggressive (more LLM requests)
let arbiter = AIArbiter::new(executor, goap, bt)
    .with_llm_cooldown(5.0);

// Passive (fewer LLM requests)
let arbiter = AIArbiter::new(executor, goap, bt)
    .with_llm_cooldown(30.0);
}

Pattern 4: Metrics Monitoring

#![allow(unused)]
fn main() {
let (transitions, requests, successes, failures, goap_actions, llm_steps) = 
    arbiter.metrics();

let success_rate = 100.0 * successes as f64 / requests as f64;
if success_rate < 50.0 {
    warn!("LLM success rate low: {:.1}%", success_rate);
}
}

Pattern 5: Mode-Specific Logic

#![allow(unused)]
fn main() {
match arbiter.mode() {
    AIControlMode::GOAP => {
        ui.show_status("Tactical Mode");
    }
    AIControlMode::ExecutingLLM { step_index } => {
        ui.show_status(&format!("Strategic Step {}", step_index));
        ui.show_indicator("LLM Active");
    }
    AIControlMode::BehaviorTree => {
        ui.show_warning("Fallback Mode");
    }
}
}

Cooldown Configuration

The LLM cooldown controls how frequently the arbiter requests new strategic plans:

#![allow(unused)]
fn main() {
let arbiter = AIArbiter::new(executor, goap, bt)
    .with_llm_cooldown(15.0);  // Default
}

Troubleshooting

LLM Never Completes

Symptoms: is_llm_active() always true, never transitions to ExecutingLLM

Causes:

1. Ollama not running
2. Model not loaded
3. Network issues

Fix:

# Verify Ollama is running
ollama list

# Test model directly
ollama run qwen3:8b

High Failure Rate

Symptoms: llm_failures > 50% of requests

Causes:

1. Model quality issues
2. Bad prompts
3. Timeout too short

Fix:

#![allow(unused)]
fn main() {
// Increase cooldown to reduce impact
let arbiter = AIArbiter::new(executor, goap, bt)
    .with_llm_cooldown(30.0);
}

Stuck in ExecutingLLM

Symptoms: Same action repeated, step_index doesn’t advance

Causes:

1. Plan has duplicate steps
2. Plan too long

Fix: Validate plan length before execution:

#![allow(unused)]
fn main() {
if plan.steps.len() > 50 {
    warn!("LLM plan too long: {} steps", plan.steps.len());
}
}

Running the Demo

# GOAP-only mode
cargo run -p hello_companion --release

# Arbiter mode (GOAP + Qwen3-8B)
cargo run -p hello_companion --release --features llm_orchestrator -- --arbiter

Expected output:

Frame 0: MoveTo { x: 5, y: 5 } (GOAP)
Frame 1: TakeCover { position: Some((3, 2)) } (GOAP)
[INFO] LLM plan ready: 3 steps
Frame 3: MoveTo { x: 4, y: 0 } (ExecutingLLM[step 1])
Frame 4: TakeCover { position: Some((4, 1)) } (ExecutingLLM[step 2])
Frame 5: Attack { target: 1 } (ExecutingLLM[step 3])
[INFO] Plan exhausted, returning to GOAP
Frame 6: MoveTo { x: 5, y: 5 } (GOAP)

See Also

• Complete Implementation Guide - 8,000+ word deep dive
• Quick Reference - 5-minute API guide
• AI Core Loop - Perception-Reasoning-Planning-Action
• GOAP System - Goal-oriented action planning
• Behavior Trees - Behavior tree integration

Physics System

The AstraWeave physics system provides comprehensive 3D physics simulation through integration with Rapier, a high-performance physics engine written in Rust.

Overview

The physics system runs at a fixed 60Hz tick rate to ensure deterministic simulation.

Key features:

• Rigid Body Dynamics - Full 3D rigid body simulation
• Character Controllers - Player and NPC movement with collision
• Collision Detection - Broad and narrow phase collision
• Spatial Queries - Raycasting, shape casting, overlap tests
• Joints & Constraints - Connect bodies with various joint types
• Continuous Collision Detection - Prevents tunneling for fast objects

Architecture

graph TB
    subgraph Physics Pipeline
        A[Collect Inputs] --> B[Broad Phase]
        B --> C[Narrow Phase]
        C --> D[Constraint Solver]
        D --> E[Position Integration]
        E --> F[Sync to ECS]
    end
    
    G[ECS World] --> A
    F --> G

Core Components

RigidBody

Represents a physics-simulated body:

#![allow(unused)]
fn main() {
use astraweave_physics::{RigidBody, RigidBodyType};

let body = RigidBody {
    body_type: RigidBodyType::Dynamic,
    mass: 1.0,
    linear_damping: 0.1,
    angular_damping: 0.1,
    gravity_scale: 1.0,
    ..Default::default()
};
}

Body types:

• Dynamic - Fully simulated, responds to forces
• Static - Immovable, used for environment
• Kinematic - Moved by code, pushes dynamic bodies

Collider

Defines collision shapes:

#![allow(unused)]
fn main() {
use astraweave_physics::{Collider, ColliderShape};

let collider = Collider {
    shape: ColliderShape::Box { half_extents: Vec3::new(1.0, 1.0, 1.0) },
    friction: 0.5,
    restitution: 0.3,
    sensor: false,
    ..Default::default()
};
}

Available shapes:

• Box - Axis-aligned box
• Sphere - Perfect sphere
• Capsule - Cylinder with spherical caps
• Cylinder - Circular cylinder
• ConvexHull - Convex mesh
• TriMesh - Triangle mesh (static only)
• HeightField - Terrain heightmap

CharacterController

Handles player/NPC movement:

#![allow(unused)]
fn main() {
use astraweave_physics::CharacterController;

let controller = CharacterController {
    height: 1.8,
    radius: 0.3,
    step_height: 0.3,
    max_slope: 45.0_f32.to_radians(),
    ..Default::default()
};
}

Spatial Queries

Raycasting

#![allow(unused)]
fn main() {
use astraweave_physics::{RaycastQuery, RaycastHit};

let query = RaycastQuery {
    origin: Vec3::new(0.0, 5.0, 0.0),
    direction: Vec3::NEG_Y,
    max_distance: 100.0,
    filter: CollisionFilter::default(),
};

if let Some(hit) = physics.raycast(&query) {
    println!("Hit entity {:?} at distance {}", hit.entity, hit.distance);
}
}

Shape Casting

#![allow(unused)]
fn main() {
use astraweave_physics::{ShapeCastQuery, ColliderShape};

let query = ShapeCastQuery {
    shape: ColliderShape::Sphere { radius: 0.5 },
    origin: start_pos,
    direction: velocity.normalize(),
    max_distance: velocity.length(),
};

let hits = physics.shape_cast(&query);
}

Overlap Tests

#![allow(unused)]
fn main() {
use astraweave_physics::OverlapQuery;

let query = OverlapQuery {
    shape: ColliderShape::Sphere { radius: 5.0 },
    position: explosion_center,
    filter: CollisionFilter::default(),
};

for entity in physics.overlap(&query) {
    apply_explosion_damage(entity);
}
}

Collision Filtering

Control which objects can collide:

#![allow(unused)]
fn main() {
use astraweave_physics::{CollisionFilter, CollisionGroup};

let player_filter = CollisionFilter {
    membership: CollisionGroup::PLAYER,
    filter: CollisionGroup::WORLD | CollisionGroup::ENEMY | CollisionGroup::PROJECTILE,
};
}

Performance Optimization

Spatial Hash

The physics system uses a spatial hash for broad-phase acceleration:

#![allow(unused)]
fn main() {
use astraweave_physics::SpatialHash;

let spatial = SpatialHash::new(10.0);
spatial.insert(entity, aabb);

let nearby = spatial.query_aabb(&query_aabb);
}

Async Scheduling

For large simulations, physics can run asynchronously:

#![allow(unused)]
fn main() {
use astraweave_physics::AsyncPhysicsScheduler;

let scheduler = AsyncPhysicsScheduler::new(4);
scheduler.step(&mut physics_world, delta_time).await;
}

Integration with ECS

Physics components sync automatically with ECS transforms:

#![allow(unused)]
fn main() {
fn physics_sync_system(
    query: Query<(&mut Transform, &RigidBodyHandle)>,
    physics: Res<PhysicsWorld>,
) {
    for (mut transform, handle) in query.iter_mut() {
        if let Some(body) = physics.get_body(*handle) {
            transform.translation = body.position();
            transform.rotation = body.rotation();
        }
    }
}
}

See Also

• API Documentation - astraweave_physics API
• Character Controller Tutorial
• Navigation System - Pathfinding integration
• Deterministic Simulation

Rendering System

AstraWeave’s rendering system is built on top of WGPU, providing a modern, high-performance graphics pipeline with support for physically-based rendering (PBR), advanced lighting techniques, and post-processing effects.

Architecture Overview

The rendering system follows a modular architecture with clear separation of concerns:

graph TD
    A[Render Graph] --> B[Material System]
    A --> C[Lighting System]
    A --> D[Post-Processing]
    B --> E[Texture Streaming]
    C --> F[Clustered Forward]
    D --> G[Bloom/Tonemap]
    E --> H[GPU Upload]
    F --> I[Light Culling]

Key Components

• Render Graph: Declarative frame composition with automatic resource barriers
• Material System: PBR materials with metallic-roughness workflow
• Lighting: Clustered forward rendering supporting thousands of dynamic lights
• Texture Streaming: Virtual texture system with priority-based loading
• Post-Processing: Modular effects stack (bloom, tonemap, FXAA, etc.)

The rendering system is designed to scale from integrated graphics to high-end GPUs, with automatic quality adaptation based on detected hardware capabilities.

WGPU-Based Renderer

AstraWeave uses WGPU as its graphics abstraction layer, providing cross-platform support for Vulkan, Metal, DirectX 12, and WebGPU.

Initialization

#![allow(unused)]
fn main() {
use astraweave_render::{RenderContext, RenderConfig};

// Initialize the renderer
let config = RenderConfig {
    width: 1920,
    height: 1080,
    vsync: true,
    msaa_samples: 4,
    ..Default::default()
};

let render_ctx = RenderContext::new(&window, config).await?;
}

Device and Queue Management

The render context manages the WGPU device and queue lifecycle:

#![allow(unused)]
fn main() {
// Access device for resource creation
let device = render_ctx.device();
let queue = render_ctx.queue();

// Create a texture
let texture = device.create_texture(&wgpu::TextureDescriptor {
    label: Some("game_texture"),
    size: wgpu::Extent3d {
        width: 1024,
        height: 1024,
        depth_or_array_layers: 1,
    },
    mip_level_count: 1,
    sample_count: 1,
    dimension: wgpu::TextureDimension::D2,
    format: wgpu::TextureFormat::Rgba8UnormSrgb,
    usage: wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST,
    view_formats: &[],
});
}

PBR Materials and Lighting

AstraWeave implements a complete PBR pipeline based on the metallic-roughness workflow, closely following theglTF 2.0 specification.

Material Definition

#![allow(unused)]
fn main() {
use astraweave_render::material::{Material, PbrMaterial};

let material = PbrMaterial {
    base_color: [1.0, 1.0, 1.0, 1.0],
    base_color_texture: Some(texture_handle),
    metallic: 0.0,
    roughness: 0.5,
    metallic_roughness_texture: Some(mr_texture),
    normal_texture: Some(normal_map),
    emissive: [0.0, 0.0, 0.0],
    emissive_texture: None,
    occlusion_texture: Some(ao_map),
    alpha_mode: AlphaMode::Opaque,
    double_sided: false,
};

// Register material with renderer
let material_id = render_ctx.register_material(material);
}

Material Properties

Use texture packing to reduce memory bandwidth: combine metallic (B channel), roughness (G channel), and occlusion (R channel) into a single texture.

Lighting Model

The PBR shader implements a Cook-Torrance BRDF with:

• Diffuse: Lambertian diffuse term
• Specular: GGX/Trowbridge-Reitz normal distribution
• Fresnel: Schlick’s approximation
• Geometry: Smith’s shadowing-masking function

#![allow(unused)]
fn main() {
// BRDF calculation (shader pseudo-code)
fn pbr_brdf(
    N: vec3<f32>,  // Normal
    V: vec3<f32>,  // View direction
    L: vec3<f32>,  // Light direction
    F0: vec3<f32>, // Fresnel reflectance at 0°
    roughness: f32,
    metallic: f32,
) -> vec3<f32> {
    let H = normalize(V + L);
    let NdotH = max(dot(N, H), 0.0);
    let NdotV = max(dot(N, V), 0.0);
    let NdotL = max(dot(N, L), 0.0);
    
    // Distribution term (GGX)
    let D = distribution_ggx(NdotH, roughness);
    
    // Geometry term (Smith)
    let G = geometry_smith(NdotV, NdotL, roughness);
    
    // Fresnel term (Schlick)
    let F = fresnel_schlick(max(dot(H, V), 0.0), F0);
    
    // Cook-Torrance BRDF
    let specular = (D * G * F) / (4.0 * NdotV * NdotL + 0.0001);
    
    let kD = (vec3(1.0) - F) * (1.0 - metallic);
    let diffuse = kD * base_color.rgb / PI;
    
    return (diffuse + specular) * radiance * NdotL;
}
}

Clustered Forward Rendering

Clustered forward rendering divides the view frustum into a 3D grid of clusters, assigning lights to clusters for efficient culling.

Cluster Configuration

#![allow(unused)]
fn main() {
use astraweave_render::lighting::{ClusteredLightingConfig, LightCluster};

let cluster_config = ClusteredLightingConfig {
    tile_size_x: 16,
    tile_size_y: 16,
    z_slices: 24,
    max_lights_per_cluster: 256,
};

render_ctx.configure_clustered_lighting(cluster_config);
}

Cluster Grid

graph LR
    A[View Frustum] --> B[XY Tiling]
    B --> C[Z Slicing]
    C --> D[Cluster Grid]
    D --> E[Light Assignment]
    E --> F[Per-Cluster Light Lists]

The frustum is divided into:

• XY tiles: Screen-space subdivision (typically 16x16 pixels)
• Z slices: Exponential depth slices for better near-field distribution

Adding Lights

#![allow(unused)]
fn main() {
use astraweave_render::lighting::{PointLight, SpotLight, DirectionalLight};

// Point light
let point_light = PointLight {
    position: [0.0, 5.0, 0.0],
    color: [1.0, 0.9, 0.8],
    intensity: 100.0,
    radius: 10.0,
    falloff: 2.0, // Inverse square falloff
};

render_ctx.add_light(point_light);

// Directional light (sun)
let sun = DirectionalLight {
    direction: [-0.3, -1.0, -0.5],
    color: [1.0, 0.95, 0.9],
    intensity: 5.0,
    cast_shadows: true,
    shadow_cascade_count: 4,
};

render_ctx.set_directional_light(sun);
}

Light Culling

The system performs GPU-based light culling using a compute shader:

#![allow(unused)]
fn main() {
// Compute shader for light culling (WGSL)
@compute @workgroup_size(16, 16, 1)
fn cull_lights(
    @builtin(global_invocation_id) global_id: vec3<u32>,
) {
    let cluster_id = compute_cluster_id(global_id);
    let cluster_aabb = get_cluster_bounds(cluster_id);
    
    var light_count: u32 = 0u;
    for (var i = 0u; i < light_buffer.count; i++) {
        let light = light_buffer.lights[i];
        if (sphere_aabb_intersection(light.position, light.radius, cluster_aabb)) {
            light_indices[cluster_id * MAX_LIGHTS + light_count] = i;
            light_count++;
        }
    }
    
    cluster_light_counts[cluster_id] = light_count;
}
}

Clustered forward rendering requires compute shader support. Fallback to traditional forward rendering is provided for older hardware.

Post-Processing Effects

AstraWeave provides a flexible post-processing stack with composable effects.

Effect Pipeline

#![allow(unused)]
fn main() {
use astraweave_render::post::{PostProcessStack, BloomEffect, TonemapEffect, FxaaEffect};

let mut post_stack = PostProcessStack::new();

// Add bloom
post_stack.add_effect(BloomEffect {
    threshold: 1.0,
    intensity: 0.5,
    blur_passes: 5,
});

// Add tonemapping
post_stack.add_effect(TonemapEffect {
    exposure: 1.0,
    operator: TonemapOperator::AcesFilmic,
});

// Add anti-aliasing
post_stack.add_effect(FxaaEffect {
    quality: FxaaQuality::High,
});

render_ctx.set_post_processing(post_stack);
}

Available Effects

Custom Post-Processing Effects

#![allow(unused)]
fn main() {
use astraweave_render::post::{PostEffect, PostEffectContext};

struct CustomVignetteEffect {
    intensity: f32,
    radius: f32,
}

impl PostEffect for CustomVignetteEffect {
    fn apply(&self, ctx: &mut PostEffectContext) -> Result<()> {
        let shader = ctx.load_shader("vignette.wgsl")?;
        
        ctx.bind_uniform("intensity", &self.intensity);
        ctx.bind_uniform("radius", &self.radius);
        ctx.bind_texture(0, ctx.input_texture());
        
        ctx.dispatch_fullscreen(shader)?;
        
        Ok(())
    }
}
}

Texture Streaming

The texture streaming system manages GPU memory efficiently by loading textures on-demand with priority-based eviction.

Virtual Texture System

#![allow(unused)]
fn main() {
use astraweave_render::texture::{TextureStreamingConfig, VirtualTexture};

let streaming_config = TextureStreamingConfig {
    budget_mb: 512,
    min_mip_level: 0,
    max_mip_level: 12,
    load_bias: 0.0,
    anisotropy: 16,
};

render_ctx.configure_texture_streaming(streaming_config);
}

Loading Textures

#![allow(unused)]
fn main() {
use astraweave_render::texture::TextureLoader;

// Load texture with streaming
let texture = TextureLoader::new()
    .with_streaming(true)
    .with_mip_levels(8)
    .with_compression(TextureCompression::BC7)
    .load("assets/textures/ground_albedo.png")?;

// Set priority (higher = load sooner)
texture.set_priority(1.0);
}

Mip Streaming

The system automatically selects mip levels based on:

• Distance to camera
• Screen coverage
• Available GPU memory
• User-defined priority

graph TD
    A[Texture Request] --> B{In Budget?}
    B -->|Yes| C[Load Full Resolution]
    B -->|No| D[Calculate Required Mip]
    D --> E[Load Mip Level]
    E --> F{Budget Exceeded?}
    F -->|Yes| G[Evict Low Priority]
    F -->|No| H[Complete]
    G --> H
    C --> H

Pre-generate mip chains offline and compress textures to reduce load times. AstraWeave supports BC1-BC7, ASTC, and ETC2 compression formats.

Performance Optimization

GPU Profiling

#![allow(unused)]
fn main() {
use astraweave_render::profiling::GpuProfiler;

let profiler = GpuProfiler::new(&render_ctx);

profiler.begin_frame();
{
    profiler.begin_scope("Shadow Pass");
    render_shadows(&mut render_ctx);
    profiler.end_scope();
    
    profiler.begin_scope("Main Pass");
    render_main_scene(&mut render_ctx);
    profiler.end_scope();
    
    profiler.begin_scope("Post Processing");
    apply_post_effects(&mut render_ctx);
    profiler.end_scope();
}
profiler.end_frame();

// Print timing report
println!("{}", profiler.report());
}

Instancing

Use GPU instancing for rendering many identical meshes:

#![allow(unused)]
fn main() {
use astraweave_render::mesh::InstancedMesh;

let instances: Vec<InstanceData> = trees
    .iter()
    .map(|tree| InstanceData {
        transform: tree.transform.matrix(),
        color: tree.color,
    })
    .collect();

render_ctx.draw_instanced(tree_mesh, &instances);
}

Occlusion Culling

#![allow(unused)]
fn main() {
use astraweave_render::culling::OcclusionCulling;

let mut occlusion = OcclusionCulling::new(&render_ctx);

// First pass: render occluders
occlusion.render_occluders(&occluder_meshes);

// Second pass: test visibility
let visible_objects = occlusion.test_visibility(&all_objects);

// Third pass: render only visible objects
render_objects(&visible_objects);
}

Code Examples

Complete Rendering Loop

use astraweave_render::{RenderContext, Camera, Scene};
use winit::event_loop::EventLoop;

fn main() -> Result<()> {
    let event_loop = EventLoop::new();
    let window = Window::new(&event_loop)?;
    
    let mut render_ctx = RenderContext::new(&window, Default::default()).await?;
    let mut scene = Scene::new();
    let mut camera = Camera::perspective(60.0, 16.0 / 9.0, 0.1, 1000.0);
    
    event_loop.run(move |event, _, control_flow| {
        match event {
            Event::RedrawRequested(_) => {
                // Update camera
                camera.update(&input_state);
                
                // Begin frame
                let mut frame = render_ctx.begin_frame().unwrap();
                
                // Render scene
                frame.render_scene(&scene, &camera);
                
                // Present
                frame.present();
            }
            _ => {}
        }
    });
}

Dynamic Material Updates

#![allow(unused)]
fn main() {
// Update material properties at runtime
let material = render_ctx.get_material_mut(material_id)?;
material.base_color = [1.0, 0.0, 0.0, 1.0]; // Change to red
material.roughness = 0.8; // Make rougher
render_ctx.mark_material_dirty(material_id);
}

Related Documentation

• Asset Pipeline - Asset loading and preprocessing
• Scene Graph - Scene organization and transforms
• Editor Integration - Editor viewport rendering
• Performance Guide - Advanced optimization techniques

API Reference

For complete API documentation, see:

• astraweave_render API docs
• WGPU documentation

Audio System

AstraWeave’s audio system provides comprehensive spatial audio, dialogue management, and music/SFX playback capabilities using modern Rust audio libraries (kira/rodio).

Architecture Overview

The audio system is designed for real-time game audio with low latency, spatial positioning, and dynamic mixing.

graph TD
    A[Audio Engine] --> B[Spatial Audio]
    A --> C[Dialogue Runtime]
    A --> D[Music Manager]
    A --> E[SFX Manager]
    B --> F[3D Positioning]
    B --> G[Attenuation]
    C --> H[Voice System]
    D --> I[Adaptive Music]
    E --> J[Sound Pool]

Key Components

• Audio Engine: Core audio processing and device management
• Spatial Audio: 3D positional audio with HRTF and distance attenuation
• Dialogue Runtime: Conversation system with voice line playback
• Music Manager: Adaptive music with crossfading and layering
• SFX Manager: Sound effect pooling and priority management

The audio system supports multiple backends (WASAPI, ALSA, CoreAudio) and automatically selects the best available option for the platform.

Audio Engine Initialization

Basic Setup

#![allow(unused)]
fn main() {
use astraweave_audio::{AudioEngine, AudioConfig};

let config = AudioConfig {
    sample_rate: 48000,
    buffer_size: 512,
    num_channels: 2,
    enable_spatial_audio: true,
    max_voices: 64,
    ..Default::default()
};

let mut audio_engine = AudioEngine::new(config)?;
}

Backend Selection

#![allow(unused)]
fn main() {
use astraweave_audio::backend::{AudioBackend, BackendType};

// Explicitly select backend
let backend = AudioBackend::new(BackendType::WASAPI)?;
let audio_engine = AudioEngine::with_backend(backend, config)?;

// Or use automatic selection
let audio_engine = AudioEngine::auto_detect(config)?;
}

For lowest latency on Windows, use WASAPI in exclusive mode. For compatibility, use the automatic backend selection.

Spatial Audio

AstraWeave’s spatial audio system provides realistic 3D sound positioning with distance attenuation, obstruction, and HRTF (Head-Related Transfer Function) support.

3D Audio Listener

#![allow(unused)]
fn main() {
use astraweave_audio::spatial::{AudioListener, ListenerOrientation};

// Create listener (typically attached to camera/player)
let mut listener = AudioListener::new();

// Update listener position and orientation each frame
listener.set_position([player_pos.x, player_pos.y, player_pos.z]);
listener.set_orientation(ListenerOrientation {
    forward: [forward.x, forward.y, forward.z],
    up: [up.x, up.y, up.z],
});

audio_engine.set_listener(listener);
}

Spatial Sound Sources

#![allow(unused)]
fn main() {
use astraweave_audio::spatial::{SpatialSound, AttenuationModel};

// Load and play spatial sound
let sound = audio_engine.load_sound("assets/audio/footstep.ogg")?;

let spatial_sound = SpatialSound::new(sound)
    .with_position([10.0, 0.0, 5.0])
    .with_velocity([0.0, 0.0, 0.0]) // For Doppler effect
    .with_attenuation(AttenuationModel::InverseDistance {
        reference_distance: 1.0,
        max_distance: 50.0,
        rolloff_factor: 1.0,
    })
    .with_cone(90.0, 180.0, 0.5) // Directional sound
    .with_volume(0.8);

let handle = audio_engine.play_spatial(spatial_sound)?;
}

Attenuation Models

AstraWeave supports multiple distance attenuation models:

#![allow(unused)]
fn main() {
use astraweave_audio::spatial::AttenuationModel;

// Custom attenuation curve
let custom_attenuation = AttenuationModel::Custom(Box::new(|distance| {
    if distance < 5.0 {
        1.0
    } else if distance < 20.0 {
        1.0 - ((distance - 5.0) / 15.0).powi(2)
    } else {
        0.0
    }
}));
}

Doppler Effect

#![allow(unused)]
fn main() {
// Enable Doppler shift based on velocity
spatial_sound.set_doppler_factor(1.0); // 1.0 = realistic, 0.0 = disabled
spatial_sound.set_velocity([velocity.x, velocity.y, velocity.z]);
}

Obstruction and Occlusion

#![allow(unused)]
fn main() {
use astraweave_audio::spatial::Obstruction;

// Simple obstruction (lowpass filter based on raycast)
if raycast_to_listener_blocked {
    spatial_sound.set_obstruction(Obstruction {
        direct_gain: 0.3,      // Reduce direct sound
        lowpass_cutoff: 1000.0, // Apply lowpass filter
    });
} else {
    spatial_sound.clear_obstruction();
}
}

graph LR
    A[Sound Source] --> B{Line of Sight?}
    B -->|Clear| C[Direct Sound]
    B -->|Blocked| D[Obstructed Sound]
    D --> E[Apply Lowpass]
    D --> F[Reduce Gain]
    E --> G[Audio Output]
    F --> G
    C --> G

Dialogue Runtime

The dialogue runtime manages conversation playback with support for branching, voice lines, and subtitles.

Dialogue Graph

#![allow(unused)]
fn main() {
use astraweave_audio::dialogue::{DialogueGraph, DialogueNode, DialogueChoice};

let mut dialogue = DialogueGraph::new();

// Add dialogue nodes
let node1 = dialogue.add_node(DialogueNode {
    id: "greeting",
    speaker: "NPC_Guard",
    text: "Halt! What's your business here?",
    voice_line: Some("assets/voice/guard_greeting.ogg"),
    duration: 3.0,
});

let node2 = dialogue.add_node(DialogueNode {
    id: "response_friendly",
    speaker: "Player",
    text: "Just passing through, friend.",
    voice_line: Some("assets/voice/player_friendly.ogg"),
    duration: 2.5,
});

let node3 = dialogue.add_node(DialogueNode {
    id: "response_hostile",
    speaker: "Player",
    text: "None of your concern.",
    voice_line: Some("assets/voice/player_hostile.ogg"),
    duration: 2.0,
});

// Add choices
dialogue.add_choice(node1, DialogueChoice {
    text: "Be friendly",
    next_node: node2,
    condition: None,
});

dialogue.add_choice(node1, DialogueChoice {
    text: "Be hostile",
    next_node: node3,
    condition: None,
});
}

Playing Dialogue

#![allow(unused)]
fn main() {
use astraweave_audio::dialogue::DialoguePlayer;

let mut player = DialoguePlayer::new(&audio_engine);

// Start dialogue
player.start_dialogue(dialogue, "greeting")?;

// Update each frame
loop {
    player.update(delta_time)?;
    
    if let Some(current_node) = player.current_node() {
        println!("Speaker: {}", current_node.speaker);
        println!("Text: {}", current_node.text);
        
        // Display choices when node finishes
        if player.is_waiting_for_choice() {
            let choices = player.available_choices();
            for (idx, choice) in choices.iter().enumerate() {
                println!("{}: {}", idx, choice.text);
            }
        }
    }
    
    if player.is_finished() {
        break;
    }
}

// Handle player input
player.select_choice(0)?; // Select first choice
}

Voice System

#![allow(unused)]
fn main() {
use astraweave_audio::voice::{VoiceConfig, VoiceEffect};

// Configure voice processing
let voice_config = VoiceConfig {
    normalize: true,
    compress: true,      // Dynamic range compression
    eq_preset: Some(VoiceEffect::RadioFilter), // Apply effects
    ducking: true,       // Duck music/sfx during dialogue
};

player.set_voice_config(voice_config);
}

Subtitle Synchronization

#![allow(unused)]
fn main() {
use astraweave_audio::dialogue::SubtitleTrack;

// Load subtitle track
let subtitles = SubtitleTrack::load("assets/dialogue/quest1.srt")?;
player.set_subtitles(subtitles);

// Get current subtitle
if let Some(subtitle) = player.current_subtitle() {
    ui.draw_subtitle(subtitle.text, subtitle.speaker);
}
}

Ensure voice line durations match actual audio file lengths. Use the `analyze_duration()` function to automatically detect durations from audio files.

Music Manager

The music manager provides adaptive music with layering, crossfading, and dynamic transitions.

Music Tracks

#![allow(unused)]
fn main() {
use astraweave_audio::music::{MusicManager, MusicTrack, MusicLayer};

let mut music_manager = MusicManager::new(&audio_engine);

// Load music track with layers
let mut combat_music = MusicTrack::new("combat");
combat_music.add_layer(MusicLayer {
    name: "percussion",
    file: "assets/music/combat_percussion.ogg",
    volume: 1.0,
    loop_start: 0.0,
    loop_end: 32.0, // Loop point in seconds
});
combat_music.add_layer(MusicLayer {
    name: "strings",
    file: "assets/music/combat_strings.ogg",
    volume: 0.8,
    loop_start: 0.0,
    loop_end: 32.0,
});
combat_music.add_layer(MusicLayer {
    name: "brass",
    file: "assets/music/combat_brass.ogg",
    volume: 0.6,
    loop_start: 0.0,
    loop_end: 32.0,
});

music_manager.register_track(combat_music);
}

Adaptive Music System

#![allow(unused)]
fn main() {
// Play music with intensity control
music_manager.play("combat")?;

// Dynamically adjust layers based on game state
match combat_intensity {
    CombatIntensity::Low => {
        music_manager.set_layer_volume("combat", "percussion", 1.0);
        music_manager.set_layer_volume("combat", "strings", 0.3);
        music_manager.set_layer_volume("combat", "brass", 0.0);
    }
    CombatIntensity::Medium => {
        music_manager.set_layer_volume("combat", "percussion", 1.0);
        music_manager.set_layer_volume("combat", "strings", 0.8);
        music_manager.set_layer_volume("combat", "brass", 0.4);
    }
    CombatIntensity::High => {
        music_manager.set_layer_volume("combat", "percussion", 1.0);
        music_manager.set_layer_volume("combat", "strings", 1.0);
        music_manager.set_layer_volume("combat", "brass", 1.0);
    }
}
}

Crossfading and Transitions

#![allow(unused)]
fn main() {
use astraweave_audio::music::TransitionType;

// Immediate transition
music_manager.transition_to("exploration", TransitionType::Immediate)?;

// Crossfade over 2 seconds
music_manager.transition_to("exploration", TransitionType::Crossfade(2.0))?;

// Wait for musical bar/beat
music_manager.transition_to("exploration", TransitionType::OnBeat {
    bars: 1,  // Wait for next bar
    fade_duration: 1.0,
})?;

// Sequential (finish current, then play next)
music_manager.transition_to("victory", TransitionType::Sequential)?;
}

Music States

#![allow(unused)]
fn main() {
use astraweave_audio::music::MusicState;

// Create music state machine
let mut music_states = MusicState::new();
music_states.add_state("explore", "exploration_music");
music_states.add_state("combat", "combat_music");
music_states.add_state("boss", "boss_music");

// Define transitions
music_states.add_transition("explore", "combat", TransitionType::Crossfade(1.5));
music_states.add_transition("combat", "explore", TransitionType::OnBeat {
    bars: 2,
    fade_duration: 2.0,
});

// Trigger state changes
music_states.change_state("combat")?;
}

stateDiagram-v2
    [*] --> Exploration
    Exploration --> Combat: Enemy Detected
    Combat --> Exploration: Combat Ended
    Combat --> Boss: Boss Appears
    Boss --> Victory: Boss Defeated
    Victory --> Exploration: Return

SFX Manager

The SFX manager handles sound effect pooling, priority management, and one-shot sounds.

Sound Pool

#![allow(unused)]
fn main() {
use astraweave_audio::sfx::{SfxManager, SoundPool};

let mut sfx_manager = SfxManager::new(&audio_engine);

// Create sound pool for common effects
let footstep_pool = SoundPool::new()
    .add_variant("assets/sfx/footstep_01.ogg")
    .add_variant("assets/sfx/footstep_02.ogg")
    .add_variant("assets/sfx/footstep_03.ogg")
    .add_variant("assets/sfx/footstep_04.ogg")
    .with_random_pitch(0.95, 1.05)
    .with_max_instances(4); // Limit concurrent sounds

sfx_manager.register_pool("footstep", footstep_pool);
}

Playing Sound Effects

#![allow(unused)]
fn main() {
// Play from pool (automatically selects variant)
sfx_manager.play("footstep")?;

// Play with position
sfx_manager.play_at("footstep", player_position)?;

// Play with custom parameters
sfx_manager.play_with("explosion", SfxParams {
    position: Some(explosion_pos),
    volume: 1.0,
    pitch: 1.0,
    priority: SoundPriority::High,
})?;
}

Priority System

#![allow(unused)]
fn main() {
use astraweave_audio::sfx::SoundPriority;

// Define sound priorities
pub enum SoundPriority {
    Critical = 100,  // UI, dialogue
    High = 75,       // Explosions, important events
    Medium = 50,     // Gunfire, abilities
    Low = 25,        // Footsteps, ambient
    VeryLow = 10,    // Background details
}

// Priority-based voice stealing
sfx_manager.set_max_voices(32);
sfx_manager.set_voice_stealing(true); // Steal low priority when full
}

Sound Categories

#![allow(unused)]
fn main() {
use astraweave_audio::sfx::SoundCategory;

// Create categories for volume control
sfx_manager.create_category("master", 1.0);
sfx_manager.create_category("sfx", 0.8);
sfx_manager.create_category("ui", 1.0);
sfx_manager.create_category("ambient", 0.6);

// Assign sounds to categories
sfx_manager.set_category("footstep", "sfx");
sfx_manager.set_category("button_click", "ui");

// Adjust category volumes
sfx_manager.set_category_volume("sfx", 0.5);
}

Audio Effects and Processing

Built-in Effects

#![allow(unused)]
fn main() {
use astraweave_audio::effects::{Effect, Reverb, LowPassFilter, HighPassFilter};

// Add reverb to spatial sound
let reverb = Reverb {
    room_size: 0.7,
    damping: 0.5,
    wet: 0.3,
    dry: 0.7,
};
spatial_sound.add_effect(Effect::Reverb(reverb));

// Lowpass filter for underwater effect
let underwater_filter = LowPassFilter {
    cutoff: 800.0,
    resonance: 1.0,
};
audio_engine.add_global_effect(Effect::LowPass(underwater_filter));
}

Custom DSP

#![allow(unused)]
fn main() {
use astraweave_audio::dsp::{AudioProcessor, AudioBuffer};

struct CustomDistortion {
    gain: f32,
    threshold: f32,
}

impl AudioProcessor for CustomDistortion {
    fn process(&mut self, buffer: &mut AudioBuffer) {
        for sample in buffer.samples_mut() {
            *sample *= self.gain;
            *sample = sample.clamp(-self.threshold, self.threshold);
        }
    }
}

// Apply custom processor
let distortion = CustomDistortion {
    gain: 2.0,
    threshold: 0.8,
};
sfx_manager.add_processor("distortion", Box::new(distortion));
}

Performance Optimization

Voice Limiting

#![allow(unused)]
fn main() {
// Limit total active voices
audio_engine.set_max_voices(64);

// Per-pool limiting
let gunshot_pool = SoundPool::new()
    .add_variant("gunshot.ogg")
    .with_max_instances(8); // Max 8 simultaneous gunshots
}

Streaming vs. Loaded

#![allow(unused)]
fn main() {
// Load small sounds into memory
let ui_click = audio_engine.load_sound_static("click.ogg")?;

// Stream large files (music, ambience)
let music = audio_engine.load_sound_streaming("music.ogg")?;
}

Audio Budget

#![allow(unused)]
fn main() {
use astraweave_audio::budget::AudioBudget;

let budget = AudioBudget {
    max_memory_mb: 256,
    max_streaming_sources: 4,
    max_static_sources: 60,
};

audio_engine.set_budget(budget);
}

Complete Example

Game Audio System

#![allow(unused)]
fn main() {
use astraweave_audio::*;

pub struct GameAudio {
    engine: AudioEngine,
    music: MusicManager,
    sfx: SfxManager,
    dialogue: DialoguePlayer,
}

impl GameAudio {
    pub fn new() -> Result<Self> {
        let mut engine = AudioEngine::new(AudioConfig::default())?;
        let music = MusicManager::new(&engine);
        let sfx = SfxManager::new(&engine);
        let dialogue = DialoguePlayer::new(&engine);
        
        Ok(Self { engine, music, sfx, dialogue })
    }
    
    pub fn update(&mut self, delta_time: f32, listener_pos: Vec3, listener_forward: Vec3) {
        // Update listener
        let mut listener = AudioListener::new();
        listener.set_position([listener_pos.x, listener_pos.y, listener_pos.z]);
        listener.set_orientation(ListenerOrientation {
            forward: [listener_forward.x, listener_forward.y, listener_forward.z],
            up: [0.0, 1.0, 0.0],
        });
        self.engine.set_listener(listener);
        
        // Update managers
        self.music.update(delta_time);
        self.dialogue.update(delta_time).ok();
    }
    
    pub fn play_footstep(&mut self, position: Vec3) {
        self.sfx.play_at("footstep", [position.x, position.y, position.z]).ok();
    }
    
    pub fn start_combat_music(&mut self) {
        self.music.transition_to("combat", TransitionType::Crossfade(1.5)).ok();
    }
}
}

Related Documentation

• Asset Pipeline - Audio asset loading and processing
• ECS Integration - Audio components and systems
• Editor Tools - Audio editing and preview
• Performance Guide - Audio optimization techniques

API Reference

For complete API documentation, see:

• astraweave_audio API docs
• kira documentation
• rodio documentation

Navigation System

AstraWeave’s navigation system provides robust pathfinding and agent movement with support for dynamic navmesh generation, A* pathfinding, local steering, and obstacle avoidance.

Architecture Overview

The navigation system consists of multiple layers working together to enable intelligent agent movement.

graph TD
    A[Navigation System] --> B[Navmesh Generation]
    A --> C[Pathfinding]
    A --> D[Steering]
    B --> E[Voxelization]
    B --> F[Region Building]
    C --> G[A* Search]
    D --> H[Obstacle Avoidance]
    D --> I[Local Movement]

Key Components

• Navmesh Generation: Automatic navigation mesh creation from level geometry
• Pathfinding: A* algorithm with hierarchical path optimization
• Steering: Local navigation with obstacle avoidance and crowd simulation
• Dynamic Updates: Runtime navmesh modification for destructible environments
• Off-Mesh Links: Manual connections for jumps, ladders, and teleports

The navigation system is based on Recast & Detour algorithms, providing industry-standard navmesh generation and pathfinding.

Navmesh Generation

Basic Navmesh Creation

#![allow(unused)]
fn main() {
use astraweave_nav::{NavmeshBuilder, NavmeshConfig};

let config = NavmeshConfig {
    cell_size: 0.3,           // XZ plane cell size
    cell_height: 0.2,         // Y axis cell size
    agent_height: 2.0,        // Agent height in meters
    agent_radius: 0.6,        // Agent radius in meters
    agent_max_climb: 0.9,     // Max step height
    agent_max_slope: 45.0,    // Max walkable slope in degrees
    region_min_size: 8.0,     // Min region area
    region_merge_size: 20.0,  // Region merge threshold
    edge_max_len: 12.0,       // Max edge length
    edge_max_error: 1.3,      // Edge simplification error
    verts_per_poly: 6,        // Vertices per polygon
    detail_sample_dist: 6.0,  // Detail mesh sample distance
    detail_sample_max_error: 1.0, // Detail mesh error
};

let mut builder = NavmeshBuilder::new(config);
}

Building from Geometry

#![allow(unused)]
fn main() {
use astraweave_nav::geometry::InputGeometry;

// Collect level geometry
let mut geometry = InputGeometry::new();

// Add static meshes
for mesh in level.static_meshes() {
    geometry.add_mesh(mesh.vertices(), mesh.indices());
}

// Mark areas (walkable, non-walkable, water, etc.)
geometry.mark_area(
    bounding_box,
    AreaType::NonWalkable,
);

// Build navmesh
let navmesh = builder.build(&geometry)?;
}

Navmesh Configuration Presets

#![allow(unused)]
fn main() {
use astraweave_nav::NavmeshConfig;

// Humanoid character (default)
let human_config = NavmeshConfig::humanoid();

// Small creature (rat, dog)
let small_config = NavmeshConfig::small_creature();

// Large creature (ogre, vehicle)
let large_config = NavmeshConfig::large_creature();

// Flying unit
let flying_config = NavmeshConfig::flying();

// Custom configuration
let custom_config = NavmeshConfig {
    agent_height: 1.5,
    agent_radius: 0.4,
    agent_max_climb: 0.5,
    agent_max_slope: 60.0,
    ..NavmeshConfig::humanoid()
};
}

Use smaller cell sizes for more detailed navmeshes, but be aware of increased memory usage and build times. A cell size of 0.3m works well for humanoid characters.

Navmesh Layers

#![allow(unused)]
fn main() {
use astraweave_nav::NavmeshLayer;

// Create separate navmeshes for different agent types
let mut nav_system = NavigationSystem::new();

// Layer 0: Infantry
nav_system.add_layer(
    NavmeshLayer::new("infantry")
        .with_config(NavmeshConfig::humanoid())
        .with_geometry(&level_geometry)
);

// Layer 1: Vehicles
nav_system.add_layer(
    NavmeshLayer::new("vehicles")
        .with_config(NavmeshConfig::large_creature())
        .with_geometry(&vehicle_geometry)
);

// Layer 2: Flying
nav_system.add_layer(
    NavmeshLayer::new("flying")
        .with_config(NavmeshConfig::flying())
        .with_geometry(&flying_geometry)
);
}

A* Pathfinding

Basic Pathfinding

#![allow(unused)]
fn main() {
use astraweave_nav::{Pathfinder, PathQuery};

let pathfinder = Pathfinder::new(&navmesh);

// Find path from start to end
let query = PathQuery {
    start: [10.0, 0.0, 5.0],
    end: [50.0, 0.0, 30.0],
    extents: [2.0, 4.0, 2.0], // Search extents for nearest poly
    filter: None,
};

let path = pathfinder.find_path(query)?;

// Path is a Vec<[f32; 3]> of waypoints
for waypoint in path.waypoints() {
    println!("Waypoint: {:?}", waypoint);
}
}

Path Smoothing

#![allow(unused)]
fn main() {
use astraweave_nav::PathSmoothingOptions;

let smoothing = PathSmoothingOptions {
    max_iterations: 100,
    max_smooth_distance: 0.5,
};

let smooth_path = pathfinder.smooth_path(&path, smoothing)?;
}

Path Filtering

#![allow(unused)]
fn main() {
use astraweave_nav::filter::{PathFilter, AreaFlags};

// Create filter for specific area types
let mut filter = PathFilter::new();
filter.set_area_cost(AreaType::Road, 1.0);      // Prefer roads
filter.set_area_cost(AreaType::Grass, 2.0);     // Neutral
filter.set_area_cost(AreaType::Water, 10.0);    // Avoid water
filter.set_area_cost(AreaType::Lava, f32::MAX); // Never path through lava

filter.exclude_flags(AreaFlags::DISABLED);

let query = PathQuery {
    start: start_pos,
    end: end_pos,
    extents: [2.0, 4.0, 2.0],
    filter: Some(filter),
};

let path = pathfinder.find_path(query)?;
}

Hierarchical Pathfinding

#![allow(unused)]
fn main() {
use astraweave_nav::hierarchical::HierarchicalPathfinder;

// Create hierarchical graph for long-distance paths
let hpa_pathfinder = HierarchicalPathfinder::new(&navmesh, 32.0); // 32m clusters

// Fast long-distance pathfinding
let long_path = hpa_pathfinder.find_path(query)?;
}

graph TD
    A[Start] --> B[Find Nearest Poly]
    B --> C[A* Search]
    C --> D{Path Found?}
    D -->|Yes| E[Smooth Path]
    D -->|No| F[Partial Path]
    E --> G[String Pulling]
    G --> H[Return Waypoints]
    F --> H

Partial Paths

#![allow(unused)]
fn main() {
// Allow partial paths when destination unreachable
let query = PathQuery {
    start: start_pos,
    end: unreachable_pos,
    extents: [2.0, 4.0, 2.0],
    filter: None,
};

let result = pathfinder.find_path(query)?;

if result.is_partial() {
    println!("Couldn't reach destination, got {} waypoints", result.waypoints().len());
    // Path goes as close as possible to target
} else {
    println!("Complete path found!");
}
}

Agent Movement

Navigation Agent

#![allow(unused)]
fn main() {
use astraweave_nav::agent::{NavAgent, AgentParams};

// Create navigation agent
let agent_params = AgentParams {
    radius: 0.6,
    height: 2.0,
    max_acceleration: 8.0,
    max_speed: 5.5,
    collision_query_range: 2.0,
    path_optimization_range: 5.0,
    separation_weight: 2.0,
    ..Default::default()
};

let mut agent = NavAgent::new(agent_params);

// Set destination
agent.set_destination([50.0, 0.0, 30.0]);

// Update each frame
let delta_time = 0.016; // 60 FPS
agent.update(delta_time, &pathfinder);

// Get current velocity and position
let velocity = agent.velocity();
let position = agent.position();

// Apply to entity transform
entity.position = position;
entity.rotation = Quat::from_rotation_y(velocity.x.atan2(velocity.z));
}

Agent States

#![allow(unused)]
fn main() {
use astraweave_nav::agent::AgentState;

match agent.state() {
    AgentState::Idle => {
        // Agent has no destination
    }
    AgentState::Moving => {
        // Agent is moving toward destination
    }
    AgentState::Arrived => {
        // Agent reached destination
        agent.stop();
    }
    AgentState::Stuck => {
        // Agent couldn't make progress
        agent.set_destination(fallback_position);
    }
}
}

Speed Modulation

#![allow(unused)]
fn main() {
// Dynamic speed based on terrain
let current_area = navmesh.get_area_at(agent.position());
let speed_multiplier = match current_area {
    AreaType::Road => 1.2,
    AreaType::Grass => 1.0,
    AreaType::Water => 0.5,
    _ => 1.0,
};

agent.set_max_speed(5.5 * speed_multiplier);
}

Obstacle Avoidance

Local Steering

#![allow(unused)]
fn main() {
use astraweave_nav::steering::{SteeringBehavior, AvoidanceParams};

let avoidance = AvoidanceParams {
    horizon_time: 2.5,        // Look-ahead time
    obstacle_margin: 0.3,      // Extra clearance
    max_neighbors: 10,         // Max agents to consider
    neighbor_dist: 10.0,       // Neighbor search radius
    separation_weight: 2.0,    // Separation strength
    alignment_weight: 1.0,     // Velocity alignment
    cohesion_weight: 1.0,      // Group cohesion
};

agent.set_avoidance_params(avoidance);
}

Dynamic Obstacles

#![allow(unused)]
fn main() {
use astraweave_nav::obstacle::DynamicObstacle;

// Add temporary obstacles
let obstacle = DynamicObstacle::cylinder(
    position,
    1.5,  // radius
    2.0,  // height
);

nav_system.add_obstacle(obstacle);

// Agents will automatically avoid the obstacle

// Remove when no longer needed
nav_system.remove_obstacle(obstacle.id());
}

Crowd Simulation

#![allow(unused)]
fn main() {
use astraweave_nav::crowd::{CrowdManager, CrowdAgent};

let mut crowd = CrowdManager::new(&navmesh, 100); // Max 100 agents

// Add agents to crowd
let agent_id = crowd.add_agent(CrowdAgent {
    position: start_pos,
    params: agent_params,
});

// Set target
crowd.set_target(agent_id, end_pos);

// Update all agents efficiently
crowd.update(delta_time);

// Get agent state
let agent = crowd.get_agent(agent_id);
println!("Position: {:?}, Velocity: {:?}", agent.position, agent.velocity);
}

CrowdManager uses spatial hashing and optimized neighbor queries to efficiently simulate hundreds of agents with local avoidance.

Off-Mesh Links

Off-mesh links enable navigation across gaps, jumps, ladders, and teleporters.

Creating Links

#![allow(unused)]
fn main() {
use astraweave_nav::offmesh::{OffMeshLink, OffMeshLinkType};

// Jump down
let jump_link = OffMeshLink {
    start: [10.0, 5.0, 0.0],
    end: [15.0, 0.0, 0.0],
    radius: 0.5,
    bidirectional: false, // One-way
    link_type: OffMeshLinkType::Jump,
    cost: 2.0, // Path cost
};

navmesh.add_offmesh_link(jump_link);

// Ladder (bidirectional)
let ladder_link = OffMeshLink {
    start: [20.0, 0.0, 0.0],
    end: [20.0, 5.0, 0.0],
    radius: 0.5,
    bidirectional: true,
    link_type: OffMeshLinkType::Climb,
    cost: 5.0,
};

navmesh.add_offmesh_link(ladder_link);
}

Traversing Links

#![allow(unused)]
fn main() {
// Agent detects off-mesh link during pathfinding
if let Some(link) = agent.current_offmesh_link() {
    match link.link_type {
        OffMeshLinkType::Jump => {
            // Play jump animation
            animation.play("jump");
            
            // Arc trajectory
            let t = link.traversal_progress();
            let height = 2.0 * t * (1.0 - t); // Parabolic arc
            agent.position.y += height;
        }
        OffMeshLinkType::Climb => {
            // Play climb animation
            animation.play("climb_ladder");
        }
        OffMeshLinkType::Teleport => {
            // Instant teleport
            agent.position = link.end;
        }
    }
}
}

Dynamic Navmesh Updates

Runtime Modifications

#![allow(unused)]
fn main() {
use astraweave_nav::dynamic::{NavmeshModifier, TileCache};

// Create tile cache for dynamic updates
let mut tile_cache = TileCache::new(&navmesh, config);

// Add obstacle (e.g., fallen tree)
let obstacle_id = tile_cache.add_obstacle(
    position,
    bounding_box,
);

// Rebuild affected tiles
tile_cache.update()?;

// Remove obstacle when destroyed
tile_cache.remove_obstacle(obstacle_id);
tile_cache.update()?;
}

Temporary Blocking

#![allow(unused)]
fn main() {
// Block area temporarily
let blocker_id = nav_system.block_area(
    center,
    radius,
    duration_seconds,
);

// Automatically unblocks after duration
}

Performance Optimization

Async Pathfinding

#![allow(unused)]
fn main() {
use astraweave_nav::async_pathfinding::AsyncPathfinder;

let async_pathfinder = AsyncPathfinder::new(&navmesh);

// Request path asynchronously
let path_future = async_pathfinder.find_path_async(query);

// Continue gameplay, path calculated in background

// Check if ready
if let Some(path) = path_future.try_get() {
    agent.set_path(path);
}
}

Path Caching

#![allow(unused)]
fn main() {
use astraweave_nav::cache::PathCache;

let mut path_cache = PathCache::new(1000); // Cache 1000 paths

// Check cache before pathfinding
let cache_key = PathCache::key(start, end);
if let Some(cached_path) = path_cache.get(&cache_key) {
    return cached_path.clone();
}

// Calculate and cache
let path = pathfinder.find_path(query)?;
path_cache.insert(cache_key, path.clone());
}

LOD for Distant Agents

#![allow(unused)]
fn main() {
// Reduce update frequency for distant agents
let distance_to_player = (agent.position - player.position).length();

let update_interval = if distance_to_player < 20.0 {
    0.0 // Every frame
} else if distance_to_player < 50.0 {
    0.1 // 10 times per second
} else {
    0.5 // 2 times per second
};

if agent.time_since_update() >= update_interval {
    agent.update(delta_time, &pathfinder);
}
}

Complete Example

AI Character with Navigation

use astraweave_nav::*;

pub struct AICharacter {
    agent: NavAgent,
    current_path: Option<Path>,
    destination: Option<Vec3>,
}

impl AICharacter {
    pub fn new(start_position: Vec3) -> Self {
        let params = AgentParams {
            radius: 0.6,
            height: 2.0,
            max_speed: 5.0,
            max_acceleration: 10.0,
            ..Default::default()
        };
        
        let mut agent = NavAgent::new(params);
        agent.set_position([start_position.x, start_position.y, start_position.z]);
        
        Self {
            agent,
            current_path: None,
            destination: None,
        }
    }
    
    pub fn move_to(&mut self, destination: Vec3, pathfinder: &Pathfinder) -> Result<()> {
        let query = PathQuery {
            start: self.agent.position(),
            end: [destination.x, destination.y, destination.z],
            extents: [2.0, 4.0, 2.0],
            filter: None,
        };
        
        let path = pathfinder.find_path(query)?;
        self.current_path = Some(path);
        self.destination = Some(destination);
        self.agent.set_destination([destination.x, destination.y, destination.z]);
        
        Ok(())
    }
    
    pub fn update(&mut self, delta_time: f32, pathfinder: &Pathfinder) {
        self.agent.update(delta_time, pathfinder);
        
        // Check if arrived
        if self.agent.state() == AgentState::Arrived {
            self.current_path = None;
            self.destination = None;
        }
    }
    
    pub fn position(&self) -> Vec3 {
        let pos = self.agent.position();
        Vec3::new(pos[0], pos[1], pos[2])
    }
    
    pub fn velocity(&self) -> Vec3 {
        let vel = self.agent.velocity();
        Vec3::new(vel[0], vel[1], vel[2])
    }
}

// Usage
fn main() -> Result<()> {
    let navmesh = build_navmesh()?;
    let pathfinder = Pathfinder::new(&navmesh);
    
    let mut character = AICharacter::new(Vec3::new(0.0, 0.0, 0.0));
    character.move_to(Vec3::new(50.0, 0.0, 30.0), &pathfinder)?;
    
    loop {
        let delta_time = 0.016;
        character.update(delta_time, &pathfinder);
        
        println!("Position: {:?}", character.position());
        
        std::thread::sleep(std::time::Duration::from_millis(16));
    }
}

Debugging and Visualization

Debug Rendering

#![allow(unused)]
fn main() {
use astraweave_nav::debug::NavmeshDebugRenderer;

let mut debug_renderer = NavmeshDebugRenderer::new();

// Render navmesh
debug_renderer.draw_navmesh(&navmesh, Color::GREEN);

// Render path
if let Some(path) = &agent.current_path {
    debug_renderer.draw_path(path, Color::YELLOW);
}

// Render agent
debug_renderer.draw_agent(&agent, Color::RED);

// Render off-mesh links
debug_renderer.draw_offmesh_links(&navmesh, Color::CYAN);
}

Related Documentation

• AI System - Behavior trees and decision making
• Physics Integration - Character controllers
• Level Design - Navigation editing tools
• Performance Guide - Navigation optimization

API Reference

For complete API documentation, see:

• astraweave_nav API docs
• Recast & Detour

Input System

AstraWeave’s input system provides comprehensive input handling with action mapping, binding system, controller support, input replay, and cross-platform abstraction.

Architecture Overview

The input system is designed to decouple raw input events from gameplay actions, enabling flexible control schemes and remapping.

graph TD
    A[Raw Input] --> B[Input Devices]
    B --> C[Keyboard]
    B --> D[Mouse]
    B --> E[Gamepad]
    B --> F[Touch]
    C --> G[Input Mapper]
    D --> G
    E --> G
    F --> G
    G --> H[Action System]
    H --> I[Gameplay Actions]
    H --> J[UI Actions]

Key Components

• Input Devices: Cross-platform abstraction for keyboard, mouse, gamepad, and touch
• Action Mapping: Map raw inputs to high-level gameplay actions
• Binding System: Customizable control schemes with conflict detection
• Input Context: Hierarchical input contexts for different game states
• Input Replay: Record and playback input sequences for testing and demos

The input system uses winit for window events and gilrs for gamepad support, providing consistent cross-platform input handling.

Input System Initialization

Basic Setup

#![allow(unused)]
fn main() {
use astraweave_input::{InputSystem, InputConfig};

let config = InputConfig {
    deadzone: 0.15,              // Gamepad deadzone
    mouse_sensitivity: 1.0,
    enable_raw_mouse_input: true, // For FPS games
    double_click_time_ms: 300,
    key_repeat_delay_ms: 500,
    key_repeat_rate_ms: 50,
    ..Default::default()
};

let mut input_system = InputSystem::new(config);
}

Processing Window Events

#![allow(unused)]
fn main() {
use winit::event::{Event, WindowEvent};

event_loop.run(move |event, _, control_flow| {
    // Feed events to input system
    input_system.handle_event(&event);
    
    match event {
        Event::WindowEvent { event, .. } => {
            match event {
                WindowEvent::Focused(false) => {
                    input_system.clear_input_state();
                }
                _ => {}
            }
        }
        Event::MainEventsCleared => {
            // Update input system
            input_system.update(delta_time);
            
            // Process actions
            update_game(&input_system);
        }
        _ => {}
    }
});
}

Action Mapping

Defining Actions

#![allow(unused)]
fn main() {
use astraweave_input::action::{Action, ActionType};

#[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
pub enum GameAction {
    // Movement
    MoveForward,
    MoveBackward,
    MoveLeft,
    MoveRight,
    Jump,
    Crouch,
    Sprint,
    
    // Camera
    LookHorizontal,
    LookVertical,
    
    // Combat
    Fire,
    AimDownSights,
    Reload,
    SwitchWeapon,
    
    // Interaction
    Interact,
    UseItem,
    
    // UI
    OpenMenu,
    Inventory,
}

impl Action for GameAction {
    fn action_type(&self) -> ActionType {
        match self {
            // Button actions (pressed/released)
            GameAction::Jump | GameAction::Fire | GameAction::Interact => {
                ActionType::Button
            }
            // Axis actions (continuous values)
            GameAction::MoveForward | GameAction::LookHorizontal => {
                ActionType::Axis
            }
        }
    }
}
}

Creating Action Maps

#![allow(unused)]
fn main() {
use astraweave_input::mapping::{ActionMap, InputBinding};
use astraweave_input::device::{Key, MouseButton, GamepadButton, GamepadAxis};

let mut action_map = ActionMap::new("default");

// Keyboard bindings
action_map.bind(GameAction::MoveForward, InputBinding::Key(Key::W));
action_map.bind(GameAction::MoveBackward, InputBinding::Key(Key::S));
action_map.bind(GameAction::MoveLeft, InputBinding::Key(Key::A));
action_map.bind(GameAction::MoveRight, InputBinding::Key(Key::D));
action_map.bind(GameAction::Jump, InputBinding::Key(Key::Space));
action_map.bind(GameAction::Crouch, InputBinding::Key(Key::ControlLeft));
action_map.bind(GameAction::Sprint, InputBinding::Key(Key::ShiftLeft));

// Mouse bindings
action_map.bind(GameAction::Fire, InputBinding::MouseButton(MouseButton::Left));
action_map.bind(GameAction::AimDownSights, InputBinding::MouseButton(MouseButton::Right));
action_map.bind(GameAction::LookHorizontal, InputBinding::MouseAxisX);
action_map.bind(GameAction::LookVertical, InputBinding::MouseAxisY);

// Gamepad bindings
action_map.bind(GameAction::Jump, InputBinding::GamepadButton(GamepadButton::South));
action_map.bind(GameAction::Fire, InputBinding::GamepadButton(GamepadButton::RightTrigger2));
action_map.bind(GameAction::MoveForward, InputBinding::GamepadAxis {
    axis: GamepadAxis::LeftStickY,
    threshold: 0.0,
    inverted: false,
});
action_map.bind(GameAction::LookHorizontal, InputBinding::GamepadAxis {
    axis: GamepadAxis::RightStickX,
    threshold: 0.0,
    inverted: false,
});

// Register action map
input_system.register_action_map(action_map);
}

Multiple Bindings

#![allow(unused)]
fn main() {
// Bind multiple inputs to the same action
action_map.bind(GameAction::MoveForward, InputBinding::Key(Key::W));
action_map.bind(GameAction::MoveForward, InputBinding::Key(Key::ArrowUp));
action_map.bind(GameAction::MoveForward, InputBinding::GamepadAxis {
    axis: GamepadAxis::LeftStickY,
    threshold: 0.2,
    inverted: false,
});
}

Input Modifiers

#![allow(unused)]
fn main() {
use astraweave_input::modifier::{InputModifier, ModifierKey};

// Bind with modifier keys (e.g., Shift+E for fast interaction)
action_map.bind_with_modifiers(
    GameAction::Interact,
    InputBinding::Key(Key::E),
    &[ModifierKey::Shift],
);

// Input modifiers for axis scaling
action_map.bind_with_modifier_fn(
    GameAction::LookHorizontal,
    InputBinding::MouseAxisX,
    |value| value * mouse_sensitivity,
);
}

Querying Input State

Button State

#![allow(unused)]
fn main() {
// Check if action is currently pressed
if input_system.is_action_pressed(GameAction::Jump) {
    player.jump();
}

// Check if action was just pressed this frame
if input_system.is_action_just_pressed(GameAction::Fire) {
    weapon.fire();
}

// Check if action was just released this frame
if input_system.is_action_just_released(GameAction::AimDownSights) {
    player.stop_aiming();
}

// Get how long action has been held
let sprint_duration = input_system.action_duration(GameAction::Sprint);
if sprint_duration > 2.0 {
    player.start_breathing_heavily();
}
}

Axis Values

#![allow(unused)]
fn main() {
// Get axis value (-1.0 to 1.0)
let move_forward = input_system.action_value(GameAction::MoveForward);
let move_right = input_system.action_value(GameAction::MoveRight);

// Create movement vector
let movement = Vec3::new(move_right, 0.0, move_forward).normalize_or_zero();
player.move_direction(movement);

// Get raw axis value (before deadzone)
let raw_look = input_system.raw_action_value(GameAction::LookHorizontal);

// Get axis delta (change since last frame)
let look_delta = input_system.action_delta(GameAction::LookHorizontal);
camera.rotate_yaw(look_delta * sensitivity);
}

Composite Inputs

#![allow(unused)]
fn main() {
use astraweave_input::composite::Vec2Input;

// Create 2D input from multiple actions
let movement_input = Vec2Input::new(
    GameAction::MoveRight,   // X axis
    GameAction::MoveForward, // Y axis
);

let movement = movement_input.get_value(&input_system);
player.move_direction(Vec3::new(movement.x, 0.0, movement.y));
}

Binding System

Runtime Rebinding

#![allow(unused)]
fn main() {
use astraweave_input::rebinding::BindingRecorder;

// Start recording new binding
let mut recorder = BindingRecorder::new();
recorder.start_recording(GameAction::Jump);

// Wait for user input
loop {
    input_system.update(delta_time);
    
    if let Some(binding) = recorder.check_input(&input_system) {
        // User pressed a key/button
        println!("New binding: {:?}", binding);
        
        // Check for conflicts
        if let Some(conflict) = action_map.find_conflict(GameAction::Jump, &binding) {
            println!("Warning: {} already bound to {:?}", conflict, binding);
            
            // Optionally swap or clear conflict
            action_map.unbind(conflict, &binding);
        }
        
        // Apply new binding
        action_map.bind(GameAction::Jump, binding);
        break;
    }
}
}

Saving and Loading Bindings

#![allow(unused)]
fn main() {
use astraweave_input::persistence::BindingProfile;

// Save bindings
let profile = BindingProfile::from_action_map(&action_map);
profile.save_to_file("user_bindings.json")?;

// Load bindings
let profile = BindingProfile::load_from_file("user_bindings.json")?;
let action_map = profile.to_action_map();
input_system.register_action_map(action_map);
}

Preset Binding Schemes

#![allow(unused)]
fn main() {
// Create multiple preset schemes
let keyboard_mouse = ActionMap::keyboard_mouse_preset();
let gamepad = ActionMap::gamepad_preset();
let left_handed = ActionMap::left_handed_preset();

// Switch schemes
input_system.set_active_action_map("keyboard_mouse");
}

Input Contexts

Input contexts allow different parts of the game to handle input differently (e.g., gameplay vs. menu).

Creating Contexts

#![allow(unused)]
fn main() {
use astraweave_input::context::{InputContext, ContextPriority};

// Gameplay context
let mut gameplay_context = InputContext::new("gameplay", ContextPriority::Normal);
gameplay_context.set_action_map(gameplay_action_map);

// UI context (higher priority)
let mut ui_context = InputContext::new("ui", ContextPriority::High);
ui_context.set_action_map(ui_action_map);

// Add contexts to system
input_system.add_context(gameplay_context);
input_system.add_context(ui_context);
}

Context Activation

#![allow(unused)]
fn main() {
// Activate/deactivate contexts
input_system.activate_context("gameplay");
input_system.deactivate_context("ui");

// Push/pop context stack
input_system.push_context("menu"); // Menu now receives input
// ... menu is open ...
input_system.pop_context(); // Back to previous context

// Query which contexts are active
if input_system.is_context_active("gameplay") {
    // Process gameplay input
}
}

Input Consumption

#![allow(unused)]
fn main() {
// Higher priority contexts can consume input
ui_context.set_consumes_input(true); // UI blocks input from reaching gameplay

// Check if input was consumed
if !input_system.was_action_consumed(GameAction::Fire) {
    weapon.fire();
}
}

Controller Support

Gamepad Detection

#![allow(unused)]
fn main() {
use astraweave_input::gamepad::{Gamepad, GamepadEvent};

// List connected gamepads
for gamepad in input_system.gamepads() {
    println!("Gamepad {}: {}", gamepad.id(), gamepad.name());
}

// Handle gamepad events
while let Some(event) = input_system.poll_gamepad_event() {
    match event {
        GamepadEvent::Connected(id) => {
            println!("Gamepad {} connected", id);
        }
        GamepadEvent::Disconnected(id) => {
            println!("Gamepad {} disconnected", id);
        }
        GamepadEvent::ButtonPressed(id, button) => {
            println!("Gamepad {} button {:?} pressed", id, button);
        }
        _ => {}
    }
}
}

Vibration/Haptics

#![allow(unused)]
fn main() {
use astraweave_input::gamepad::{VibrationEffect, VibrationDuration};

// Simple vibration
input_system.vibrate_gamepad(
    gamepad_id,
    0.5, // Weak motor (0.0 - 1.0)
    0.8, // Strong motor (0.0 - 1.0)
    VibrationDuration::Milliseconds(200),
);

// Complex effect
let effect = VibrationEffect::explosion()
    .with_intensity(1.0)
    .with_duration_ms(500);

input_system.play_vibration_effect(gamepad_id, effect);
}

Per-Player Input

#![allow(unused)]
fn main() {
use astraweave_input::player::PlayerInput;

// Assign gamepads to players
let player1_input = PlayerInput::new()
    .with_gamepad(0)
    .with_keyboard_mouse();

let player2_input = PlayerInput::new()
    .with_gamepad(1);

// Query player-specific input
if player1_input.is_action_pressed(&input_system, GameAction::Jump) {
    player1.jump();
}

if player2_input.is_action_pressed(&input_system, GameAction::Jump) {
    player2.jump();
}
}

For split-screen games, use separate PlayerInput instances to isolate input between players.

Input Replay

Input replay enables testing, demo playback, and replay systems.

Recording Input

#![allow(unused)]
fn main() {
use astraweave_input::replay::{InputRecorder, InputRecording};

// Start recording
let mut recorder = InputRecorder::new();
recorder.start();

// Update each frame (automatically records input)
loop {
    input_system.update(delta_time);
    recorder.record_frame(&input_system);
    
    // ... game logic ...
}

// Stop and save
recorder.stop();
let recording = recorder.finalize();
recording.save_to_file("replay.bin")?;
}

Playback

#![allow(unused)]
fn main() {
use astraweave_input::replay::InputPlayer;

// Load recording
let recording = InputRecording::load_from_file("replay.bin")?;
let mut player = InputPlayer::new(recording);

// Playback loop
loop {
    // Apply recorded input to system
    player.update(delta_time, &mut input_system);
    
    // Game state will be driven by recorded input
    update_game(&input_system);
    
    if player.is_finished() {
        break;
    }
}
}

Replay Controls

#![allow(unused)]
fn main() {
// Pause/resume
player.pause();
player.resume();

// Seek
player.seek_to_time(10.0); // Seek to 10 seconds
player.seek_to_frame(600); // Seek to frame 600

// Playback speed
player.set_playback_speed(0.5); // Half speed
player.set_playback_speed(2.0); // Double speed

// Loop
player.set_loop(true);
}

Advanced Features

Input Buffering

#![allow(unused)]
fn main() {
use astraweave_input::buffer::InputBuffer;

// Create input buffer for fighting game-style combo inputs
let mut buffer = InputBuffer::new()
    .with_buffer_duration(0.3) // 300ms window
    .with_max_inputs(8);

// Add inputs to buffer
buffer.record_input(&input_system);

// Check for sequences
if buffer.matches_sequence(&[
    GameAction::MoveForward,
    GameAction::MoveDown,
    GameAction::MoveForward,
    GameAction::Fire,
]) {
    character.perform_special_move("Hadouken");
    buffer.clear();
}
}

Input Prediction (Networking)

#![allow(unused)]
fn main() {
use astraweave_input::prediction::InputPredictor;

// For networked games, predict input during lag
let mut predictor = InputPredictor::new();

// Record recent inputs
predictor.record(&input_system);

// Predict future input (e.g., during packet loss)
let predicted_input = predictor.predict_next_frame();

// Use predicted input until real input arrives
if network.has_input() {
    apply_input(network.get_input());
} else {
    apply_input(predicted_input);
}
}

Touch Input

#![allow(unused)]
fn main() {
use astraweave_input::touch::{TouchEvent, TouchPhase};

// Handle touch events (mobile/tablet)
while let Some(event) = input_system.poll_touch_event() {
    match event.phase {
        TouchPhase::Started => {
            println!("Touch started at {:?}", event.position);
        }
        TouchPhase::Moved => {
            let delta = event.position - event.previous_position;
            camera.rotate(delta);
        }
        TouchPhase::Ended => {
            println!("Touch ended");
        }
        TouchPhase::Cancelled => {
            println!("Touch cancelled");
        }
    }
}

// Multi-touch gestures
if let Some(pinch) = input_system.get_pinch_gesture() {
    camera.zoom(pinch.scale);
}

if let Some(swipe) = input_system.get_swipe_gesture() {
    player.dodge(swipe.direction);
}
}

Complete Example

FPS Input System

#![allow(unused)]
fn main() {
use astraweave_input::*;

pub struct FPSInput {
    input_system: InputSystem,
    gameplay_context: ContextId,
    menu_context: ContextId,
}

impl FPSInput {
    pub fn new() -> Self {
        let mut input_system = InputSystem::new(InputConfig::default());
        
        // Create gameplay action map
        let mut gameplay_map = ActionMap::new("gameplay");
        gameplay_map.bind(GameAction::MoveForward, InputBinding::Key(Key::W));
        gameplay_map.bind(GameAction::MoveBackward, InputBinding::Key(Key::S));
        gameplay_map.bind(GameAction::MoveLeft, InputBinding::Key(Key::A));
        gameplay_map.bind(GameAction::MoveRight, InputBinding::Key(Key::D));
        gameplay_map.bind(GameAction::Jump, InputBinding::Key(Key::Space));
        gameplay_map.bind(GameAction::Fire, InputBinding::MouseButton(MouseButton::Left));
        gameplay_map.bind(GameAction::LookHorizontal, InputBinding::MouseAxisX);
        gameplay_map.bind(GameAction::LookVertical, InputBinding::MouseAxisY);
        
        // Create menu action map
        let mut menu_map = ActionMap::new("menu");
        menu_map.bind(GameAction::OpenMenu, InputBinding::Key(Key::Escape));
        
        // Register contexts
        let gameplay_context = input_system.add_context(
            InputContext::new("gameplay", ContextPriority::Normal)
                .with_action_map(gameplay_map)
        );
        
        let menu_context = input_system.add_context(
            InputContext::new("menu", ContextPriority::High)
                .with_action_map(menu_map)
                .with_consumes_input(true)
        );
        
        // Start with gameplay active
        input_system.activate_context(gameplay_context);
        
        Self {
            input_system,
            gameplay_context,
            menu_context,
        }
    }
    
    pub fn update(&mut self, delta_time: f32, player: &mut Player, camera: &mut Camera) {
        self.input_system.update(delta_time);
        
        // Handle menu toggle
        if self.input_system.is_action_just_pressed(GameAction::OpenMenu) {
            self.toggle_menu();
        }
        
        // Process gameplay input if not in menu
        if self.input_system.is_context_active(self.gameplay_context) {
            self.process_gameplay_input(player, camera);
        }
    }
    
    fn process_gameplay_input(&self, player: &mut Player, camera: &mut Camera) {
        // Movement
        let move_forward = self.input_system.action_value(GameAction::MoveForward);
        let move_right = self.input_system.action_value(GameAction::MoveRight);
        let movement = Vec3::new(move_right, 0.0, move_forward);
        player.set_movement(movement);
        
        // Jump
        if self.input_system.is_action_just_pressed(GameAction::Jump) {
            player.jump();
        }
        
        // Camera look
        let look_x = self.input_system.action_delta(GameAction::LookHorizontal);
        let look_y = self.input_system.action_delta(GameAction::LookVertical);
        camera.rotate(look_x, look_y);
        
        // Fire weapon
        if self.input_system.is_action_pressed(GameAction::Fire) {
            player.fire_weapon();
        }
    }
    
    fn toggle_menu(&mut self) {
        if self.input_system.is_context_active(self.menu_context) {
            self.input_system.deactivate_context(self.menu_context);
            self.input_system.activate_context(self.gameplay_context);
        } else {
            self.input_system.deactivate_context(self.gameplay_context);
            self.input_system.activate_context(self.menu_context);
        }
    }
    
    pub fn handle_event(&mut self, event: &Event<()>) {
        self.input_system.handle_event(event);
    }
}
}

Related Documentation

• Player Controller - Character movement and control
• UI System - UI interaction and focus
• Networking - Network input synchronization
• Accessibility - Accessible input options

API Reference

For complete API documentation, see:

• astraweave_input API docs
• winit documentation
• gilrs documentation

Networking System

AstraWeave’s networking system provides robust client-server architecture with state synchronization, delta encoding, lag compensation, and prediction for responsive multiplayer gameplay.

Architecture Overview

The networking system is built on a client-server model with authoritative server and client-side prediction.

graph TD
    A[Server] --> B[State Authority]
    A --> C[Physics Simulation]
    A --> D[Game Logic]
    B --> E[Delta Encoding]
    E --> F[Network Transport]
    F --> G[Client 1]
    F --> H[Client 2]
    F --> I[Client N]
    G --> J[Prediction]
    G --> K[Interpolation]
    J --> L[Reconciliation]

Key Components

• Transport Layer: UDP-based reliable/unreliable messaging with Quinn (QUIC)
• State Synchronization: Efficient delta compression and entity replication
• Client Prediction: Responsive input with server reconciliation
• Lag Compensation: Server-side hit detection with rewind
• Network Relevancy: Bandwidth optimization through spatial partitioning

AstraWeave uses QUIC (via Quinn) for modern, secure, and multiplexed networking with built-in congestion control and 0-RTT connection establishment.

Server Setup

Creating a Server

#![allow(unused)]
fn main() {
use astraweave_net::{Server, ServerConfig};

let config = ServerConfig {
    bind_address: "0.0.0.0:7777".parse()?,
    max_clients: 64,
    tick_rate: 60,              // Server updates per second
    timeout_seconds: 10.0,
    enable_encryption: true,
    max_bandwidth_kbps: 1024,
    ..Default::default()
};

let mut server = Server::new(config)?;
}

Server Loop

#![allow(unused)]
fn main() {
use astraweave_net::{ServerEvent, ClientId};

loop {
    let delta_time = 1.0 / 60.0; // 60 Hz tick rate
    
    // Process incoming events
    while let Some(event) = server.poll_event() {
        match event {
            ServerEvent::ClientConnected { client_id, address } => {
                println!("Client {} connected from {}", client_id, address);
                spawn_player(client_id);
            }
            ServerEvent::ClientDisconnected { client_id, reason } => {
                println!("Client {} disconnected: {:?}", client_id, reason);
                despawn_player(client_id);
            }
            ServerEvent::MessageReceived { client_id, message } => {
                handle_client_message(client_id, message);
            }
        }
    }
    
    // Update game state
    update_game_state(delta_time);
    
    // Send state updates to clients
    server.broadcast_state_update(&world_state)?;
    
    // Tick network
    server.tick(delta_time)?;
    
    std::thread::sleep(std::time::Duration::from_secs_f32(delta_time));
}
}

Client Setup

Connecting to Server

#![allow(unused)]
fn main() {
use astraweave_net::{Client, ClientConfig};

let config = ClientConfig {
    server_address: "127.0.0.1:7777".parse()?,
    timeout_seconds: 10.0,
    enable_prediction: true,
    interpolation_delay_ms: 100,
    ..Default::default()
};

let mut client = Client::connect(config).await?;
}

Client Loop

#![allow(unused)]
fn main() {
use astraweave_net::ClientEvent;

loop {
    let delta_time = 1.0 / 60.0;
    
    // Process server events
    while let Some(event) = client.poll_event() {
        match event {
            ClientEvent::Connected => {
                println!("Connected to server");
            }
            ClientEvent::Disconnected { reason } => {
                println!("Disconnected: {:?}", reason);
                break;
            }
            ClientEvent::StateUpdate { state } => {
                apply_state_update(state);
            }
            ClientEvent::MessageReceived { message } => {
                handle_server_message(message);
            }
        }
    }
    
    // Get local input
    let input = gather_input();
    
    // Send input to server
    client.send_input(input)?;
    
    // Client-side prediction
    if config.enable_prediction {
        simulate_local_player(input, delta_time);
    }
    
    // Interpolate remote entities
    interpolate_entities(delta_time);
    
    // Tick network
    client.tick(delta_time)?;
    
    std::thread::sleep(std::time::Duration::from_secs_f32(delta_time));
}
}

State Synchronization

Entity Replication

#![allow(unused)]
fn main() {
use astraweave_net::replication::{NetEntity, ReplicationMode};

#[derive(NetEntity)]
pub struct Player {
    #[replicate(mode = ReplicationMode::Always)]
    pub entity_id: u64,
    
    #[replicate(mode = ReplicationMode::OnChange, priority = 10)]
    pub position: Vec3,
    
    #[replicate(mode = ReplicationMode::OnChange, priority = 10)]
    pub rotation: Quat,
    
    #[replicate(mode = ReplicationMode::OnChange, priority = 5)]
    pub velocity: Vec3,
    
    #[replicate(mode = ReplicationMode::OnChange, priority = 2)]
    pub health: f32,
    
    #[replicate(mode = ReplicationMode::OnChange, priority = 1)]
    pub ammo: u32,
    
    // Not replicated
    #[replicate(mode = ReplicationMode::Never)]
    local_animation_state: AnimationState,
}
}

Replication Modes

World State Updates

#![allow(unused)]
fn main() {
use astraweave_net::state::{WorldState, EntityState};

// Server: Build world state
let mut world_state = WorldState::new();

for player in players.iter() {
    world_state.add_entity(player.entity_id, EntityState {
        position: player.position,
        rotation: player.rotation,
        velocity: player.velocity,
        custom_data: serialize_player_data(player),
    });
}

// Send to all clients
server.broadcast_state_update(&world_state)?;

// Client: Apply state update
fn apply_state_update(state: WorldState) {
    for (entity_id, entity_state) in state.entities() {
        if let Some(entity) = world.get_entity_mut(entity_id) {
            entity.position = entity_state.position;
            entity.rotation = entity_state.rotation;
            entity.velocity = entity_state.velocity;
        }
    }
}
}

Delta Encoding

Delta encoding dramatically reduces bandwidth by only sending changed values.

Automatic Delta Compression

#![allow(unused)]
fn main() {
use astraweave_net::delta::{DeltaEncoder, DeltaDecoder};

// Server: Encode state changes
let mut encoder = DeltaEncoder::new();

// First frame: full state
let full_state = encoder.encode_full(&world_state)?;
server.broadcast(full_state)?;

// Subsequent frames: only deltas
loop {
    let new_state = get_current_world_state();
    let delta = encoder.encode_delta(&new_state)?;
    
    if delta.size_bytes() < full_state.size_bytes() * 0.8 {
        server.broadcast(delta)?;
    } else {
        // Send full state if delta is too large
        server.broadcast(encoder.encode_full(&new_state)?)?;
    }
}

// Client: Decode deltas
let mut decoder = DeltaDecoder::new();

match received_message {
    NetworkMessage::FullState(state) => {
        decoder.apply_full_state(state);
    }
    NetworkMessage::DeltaState(delta) => {
        decoder.apply_delta(delta);
    }
}

let current_state = decoder.get_state();
}

Custom Delta Serialization

#![allow(unused)]
fn main() {
use astraweave_net::serialization::{BitWriter, BitReader};

impl Player {
    pub fn write_delta(&self, previous: &Player, writer: &mut BitWriter) {
        // Position (quantized)
        if self.position != previous.position {
            writer.write_bit(true);
            writer.write_vec3_quantized(self.position, -1000.0, 1000.0, 0.01);
        } else {
            writer.write_bit(false);
        }
        
        // Rotation (quaternion compression)
        if self.rotation != previous.rotation {
            writer.write_bit(true);
            writer.write_quaternion_compressed(self.rotation);
        } else {
            writer.write_bit(false);
        }
        
        // Health (8-bit)
        if self.health != previous.health {
            writer.write_bit(true);
            writer.write_u8((self.health * 255.0) as u8);
        } else {
            writer.write_bit(false);
        }
    }
    
    pub fn read_delta(&mut self, reader: &mut BitReader) {
        if reader.read_bit() {
            self.position = reader.read_vec3_quantized(-1000.0, 1000.0, 0.01);
        }
        if reader.read_bit() {
            self.rotation = reader.read_quaternion_compressed();
        }
        if reader.read_bit() {
            self.health = reader.read_u8() as f32 / 255.0;
        }
    }
}
}

Quantize floating-point values to reduce precision and save bandwidth. For example, position precision of 1cm (0.01m) is sufficient for most games.

Client Prediction

Client-side prediction makes the game feel responsive despite network latency.

Input Prediction

#![allow(unused)]
fn main() {
use astraweave_net::prediction::{PredictionSystem, InputBuffer};

pub struct PredictedPlayer {
    // Authoritative state from server
    server_position: Vec3,
    server_velocity: Vec3,
    server_tick: u64,
    
    // Predicted state
    predicted_position: Vec3,
    predicted_velocity: Vec3,
    
    // Input history
    input_buffer: InputBuffer,
}

impl PredictedPlayer {
    pub fn send_input(&mut self, input: PlayerInput, client: &mut Client) {
        // Store input locally
        self.input_buffer.push(input.clone());
        
        // Send to server
        client.send_input(input)?;
        
        // Predict movement
        self.simulate_movement(input, TICK_DELTA);
    }
    
    pub fn reconcile(&mut self, server_state: PlayerState) {
        self.server_position = server_state.position;
        self.server_velocity = server_state.velocity;
        self.server_tick = server_state.tick;
        
        // Start from server state
        self.predicted_position = server_state.position;
        self.predicted_velocity = server_state.velocity;
        
        // Re-simulate inputs after server tick
        for input in self.input_buffer.after_tick(server_state.tick) {
            self.simulate_movement(input, TICK_DELTA);
        }
        
        // Clear old inputs
        self.input_buffer.clear_before_tick(server_state.tick);
    }
    
    fn simulate_movement(&mut self, input: PlayerInput, delta_time: f32) {
        // Same movement code as server
        let acceleration = input.move_direction * MOVE_SPEED;
        self.predicted_velocity += acceleration * delta_time;
        self.predicted_velocity *= 0.9; // Friction
        self.predicted_position += self.predicted_velocity * delta_time;
    }
}
}

Prediction Error Correction

#![allow(unused)]
fn main() {
// Smooth correction of prediction errors
pub fn correct_prediction_error(&mut self, delta_time: f32) {
    let error = self.server_position - self.predicted_position;
    let error_magnitude = error.length();
    
    if error_magnitude > 0.01 {
        // Smooth correction over time
        let correction_speed = 10.0; // Adjust for smoothness
        let correction = error * correction_speed * delta_time;
        
        self.predicted_position += correction;
    } else {
        // Snap if very close
        self.predicted_position = self.server_position;
    }
}
}

sequenceDiagram
    participant Client
    participant Server
    
    Client->>Client: Input (frame 1)
    Client->>Client: Predict movement
    Client->>Server: Send input (frame 1)
    
    Client->>Client: Input (frame 2)
    Client->>Client: Predict movement
    Client->>Server: Send input (frame 2)
    
    Server->>Server: Process input (frame 1)
    Server->>Client: State update (frame 1)
    
    Client->>Client: Reconcile with server
    Client->>Client: Re-simulate frames 2+

Entity Interpolation

Remote entities are interpolated between snapshots for smooth movement.

Snapshot Interpolation

#![allow(unused)]
fn main() {
use astraweave_net::interpolation::{SnapshotBuffer, InterpolationTarget};

pub struct InterpolatedEntity {
    snapshots: SnapshotBuffer<EntitySnapshot>,
    interpolation_delay: f32, // 100ms
}

#[derive(Clone)]
pub struct EntitySnapshot {
    timestamp: f32,
    position: Vec3,
    rotation: Quat,
    velocity: Vec3,
}

impl InterpolatedEntity {
    pub fn add_snapshot(&mut self, snapshot: EntitySnapshot) {
        self.snapshots.push(snapshot);
    }
    
    pub fn interpolate(&self, current_time: f32) -> InterpolationTarget {
        // Render time is current time minus interpolation delay
        let render_time = current_time - self.interpolation_delay;
        
        // Find bracketing snapshots
        let (before, after) = self.snapshots.get_bracketing(render_time);
        
        // Calculate interpolation factor
        let t = (render_time - before.timestamp) / (after.timestamp - before.timestamp);
        let t = t.clamp(0.0, 1.0);
        
        InterpolationTarget {
            position: before.position.lerp(after.position, t),
            rotation: before.rotation.slerp(after.rotation, t),
            velocity: before.velocity.lerp(after.velocity, t),
        }
    }
}
}

Extrapolation for Missing Snapshots

#![allow(unused)]
fn main() {
pub fn extrapolate(&self, current_time: f32) -> InterpolationTarget {
    let latest = self.snapshots.latest();
    let time_diff = current_time - latest.timestamp;
    
    if time_diff > 0.2 {
        // Too old, don't extrapolate
        return InterpolationTarget {
            position: latest.position,
            rotation: latest.rotation,
            velocity: latest.velocity,
        };
    }
    
    // Linear extrapolation using velocity
    InterpolationTarget {
        position: latest.position + latest.velocity * time_diff,
        rotation: latest.rotation,
        velocity: latest.velocity,
    }
}
}

Lag Compensation

Server-side lag compensation ensures fair hit detection.

Rewinding Game State

#![allow(unused)]
fn main() {
use astraweave_net::lag_compensation::{HistoryBuffer, HistoricalState};

pub struct LagCompensationSystem {
    history: HistoryBuffer<WorldSnapshot>,
    max_rewind_ms: u64,
}

impl LagCompensationSystem {
    pub fn record_snapshot(&mut self, world: &World, timestamp: u64) {
        let snapshot = WorldSnapshot {
            timestamp,
            entities: world.entities().map(|e| e.clone()).collect(),
        };
        
        self.history.push(snapshot);
        self.history.prune_older_than(timestamp - self.max_rewind_ms);
    }
    
    pub fn rewind_and_test(&self, client_latency_ms: u64, raycast: Ray) -> Option<Hit> {
        let rewind_time = current_time() - client_latency_ms;
        let snapshot = self.history.get_at_time(rewind_time)?;
        
        // Test hit detection against historical state
        for entity in &snapshot.entities {
            if let Some(hit) = raycast.intersect(&entity.hitbox) {
                return Some(Hit {
                    entity_id: entity.id,
                    position: hit.point,
                    distance: hit.distance,
                });
            }
        }
        
        None
    }
}
}

Server-Side Hit Validation

#![allow(unused)]
fn main() {
pub fn process_shot(
    &mut self,
    client_id: ClientId,
    shot_data: ShotData,
) -> Result<Option<Hit>> {
    let client = self.clients.get(client_id)?;
    let latency_ms = client.round_trip_time() / 2;
    
    // Rewind to client's view of the world
    let hit = self.lag_compensation.rewind_and_test(
        latency_ms,
        shot_data.raycast,
    );
    
    if let Some(hit) = hit {
        // Validate hit (anti-cheat)
        if validate_shot(&shot_data, &hit) {
            apply_damage(hit.entity_id, shot_data.damage);
            return Ok(Some(hit));
        }
    }
    
    Ok(None)
}
}

Limit maximum rewind time (typically 200-250ms) to prevent abuse and reduce server memory usage.

Network Relevancy

Only send relevant entities to each client to save bandwidth.

Spatial Partitioning

#![allow(unused)]
fn main() {
use astraweave_net::relevancy::{RelevancySystem, SpatialGrid};

pub struct RelevancySystem {
    grid: SpatialGrid,
    relevancy_range: f32,
}

impl RelevancySystem {
    pub fn update_relevancy(&mut self, clients: &[Client], entities: &[Entity]) {
        self.grid.clear();
        
        // Insert entities into spatial grid
        for entity in entities {
            self.grid.insert(entity.id, entity.position);
        }
        
        // Calculate relevant entities for each client
        for client in clients {
            let player_pos = client.player_position();
            let relevant = self.grid.query_radius(player_pos, self.relevancy_range);
            client.set_relevant_entities(relevant);
        }
    }
    
    pub fn should_replicate(&self, client_id: ClientId, entity_id: EntityId) -> bool {
        let client = self.clients.get(client_id);
        client.relevant_entities.contains(&entity_id)
    }
}
}

Priority-Based Updates

#![allow(unused)]
fn main() {
pub struct ReplicationPriority {
    pub distance_factor: f32,
    pub importance: f32,
    pub update_frequency: f32,
}

impl ReplicationPriority {
    pub fn calculate(client_pos: Vec3, entity: &Entity) -> f32 {
        let distance = (entity.position - client_pos).length();
        let distance_priority = 1.0 / (1.0 + distance * 0.1);
        
        let importance_priority = match entity.entity_type {
            EntityType::Player => 1.0,
            EntityType::Projectile => 0.8,
            EntityType::Enemy => 0.6,
            EntityType::Pickup => 0.4,
            EntityType::Decoration => 0.1,
        };
        
        distance_priority * importance_priority
    }
}

// Send high-priority entities every frame, low-priority less often
pub fn send_updates(&mut self, delta_time: f32) {
    for client in &mut self.clients {
        let mut updates = Vec::new();
        
        for entity_id in &client.relevant_entities {
            let entity = self.world.get_entity(*entity_id);
            let priority = ReplicationPriority::calculate(client.position(), entity);
            
            // Update frequency based on priority
            let update_interval = 1.0 / (60.0 * priority);
            
            if entity.time_since_update(client.id) >= update_interval {
                updates.push(entity.create_update());
                entity.mark_updated(client.id);
            }
        }
        
        client.send_updates(updates)?;
    }
}
}

Complete Example

Multiplayer FPS Game

#![allow(unused)]
fn main() {
use astraweave_net::*;

// Server
pub struct GameServer {
    server: Server,
    world: World,
    lag_compensation: LagCompensationSystem,
    relevancy: RelevancySystem,
}

impl GameServer {
    pub fn run(&mut self) {
        loop {
            let delta_time = 1.0 / 60.0;
            
            // Process events
            while let Some(event) = self.server.poll_event() {
                match event {
                    ServerEvent::MessageReceived { client_id, message } => {
                        self.handle_message(client_id, message);
                    }
                    _ => {}
                }
            }
            
            // Update game logic
            self.world.update(delta_time);
            
            // Record for lag compensation
            self.lag_compensation.record_snapshot(&self.world, current_time());
            
            // Update relevancy
            self.relevancy.update_relevancy(&self.server.clients(), &self.world.entities());
            
            // Send state updates
            self.send_state_updates();
            
            self.server.tick(delta_time).unwrap();
            std::thread::sleep(std::time::Duration::from_secs_f32(delta_time));
        }
    }
    
    fn handle_message(&mut self, client_id: ClientId, message: ClientMessage) {
        match message {
            ClientMessage::Input(input) => {
                self.process_input(client_id, input);
            }
            ClientMessage::Shot(shot_data) => {
                if let Some(hit) = self.process_shot(client_id, shot_data) {
                    self.broadcast_hit(hit);
                }
            }
        }
    }
}

// Client
pub struct GameClient {
    client: Client,
    local_player: PredictedPlayer,
    remote_players: HashMap<EntityId, InterpolatedEntity>,
}

impl GameClient {
    pub fn run(&mut self) {
        loop {
            let delta_time = 1.0 / 60.0;
            
            // Process server messages
            while let Some(event) = self.client.poll_event() {
                match event {
                    ClientEvent::StateUpdate { state } => {
                        self.apply_state_update(state);
                    }
                    _ => {}
                }
            }
            
            // Gather input
            let input = self.gather_input();
            self.local_player.send_input(input, &mut self.client);
            
            // Interpolate remote entities
            let current_time = current_time();
            for entity in self.remote_players.values_mut() {
                let target = entity.interpolate(current_time);
                // Apply to visual representation
            }
            
            self.client.tick(delta_time).unwrap();
            std::thread::sleep(std::time::Duration::from_secs_f32(delta_time));
        }
    }
}
}

Related Documentation

• Physics System - Server-side physics simulation
• ECS Integration - Network-replicated components
• Security - Anti-cheat and validation
• Performance Guide - Network optimization

API Reference

For complete API documentation, see:

• astraweave_net API docs
• Quinn (QUIC) documentation

Fluids System

Status: Production Ready (A+ Grade)
Coverage: 94.2% (2,404 tests)
Crate: astraweave-fluids

AstraWeave’s fluid simulation system provides production-quality water effects for games, featuring Position-Based Dynamics (PBD) particle simulation, volumetric grids, and comprehensive visual effects.

Overview

Core Systems

Visual Effects

Quick Start

#![allow(unused)]
fn main() {
use astraweave_fluids::{WaterEffectsManager, WaterQualityPreset};

// Create water effects manager with quality preset
let manager = WaterEffectsManager::from_preset(WaterQualityPreset::High)?;

// Game loop
loop {
    // Update water simulation
    manager.update(delta_time, camera_pos, water_height);
    
    // Render water
    manager.render(&render_context);
}
}

Architecture

Module Overview

astraweave-fluids/
├── Core Simulation
│   ├── pcisph_system.rs      # PCISPH pressure solver
│   ├── unified_solver.rs     # Combined solver
│   ├── viscosity.rs          # Viscosity handling
│   ├── boundary.rs           # Domain boundaries
│   └── simd_ops.rs           # SIMD optimizations
├── Visual Effects
│   ├── caustics.rs           # Light caustics
│   ├── god_rays.rs           # Volumetric rays
│   ├── foam.rs               # Foam generation
│   ├── water_reflections.rs  # Reflection system
│   └── underwater.rs         # Underwater effects
├── Terrain Integration
│   ├── terrain_integration.rs
│   ├── volume_grid.rs
│   └── waterfall.rs
└── Editor/Tools
    ├── editor.rs             # Editor integration
    ├── profiling.rs          # Performance stats
    └── serialization.rs      # Save/load

SPH Simulation

Kernel Functions

AstraWeave implements standard SPH kernels:

#![allow(unused)]
fn main() {
// Poly6 kernel for density calculation
fn poly6_kernel(r_sq: f32, h: f32) -> f32 {
    let h2 = h * h;
    if r_sq > h2 { return 0.0; }
    let diff = h2 - r_sq;
    POLY6_FACTOR / h.powi(9) * diff * diff * diff
}

// Spiky kernel for pressure gradient
fn spiky_gradient(r: Vec3, r_len: f32, h: f32) -> Vec3 {
    if r_len > h || r_len < 1e-6 { return Vec3::ZERO; }
    let diff = h - r_len;
    SPIKY_FACTOR / h.powi(6) * diff * diff * (-r / r_len)
}

// Viscosity kernel for velocity diffusion
fn viscosity_laplacian(r_len: f32, h: f32) -> f32 {
    if r_len > h { return 0.0; }
    VISCOSITY_FACTOR / h.powi(3) * (h - r_len)
}
}

Performance

Volume Grid

For voxel-based water simulation:

#![allow(unused)]
fn main() {
use astraweave_fluids::{VolumeGrid, FlowDirection};

// Create volume grid
let mut grid = VolumeGrid::new(
    dimensions: (64, 32, 64),  // Grid size
    cell_size: 0.5,            // World units per cell
);

// Fill cells
grid.set_water_level(x, y, z, 1.0);

// Simulate flow
grid.simulate_step(delta_time);

// Query water at position
let water_level = grid.sample_at(world_pos);
}

Water Effects Manager

The WaterEffectsManager coordinates all water visual effects:

#![allow(unused)]
fn main() {
use astraweave_fluids::{
    WaterEffectsManager,
    WaterQualityPreset,
    CausticsConfig,
    GodRaysConfig,
    FoamConfig,
};

// Create with custom configuration
let manager = WaterEffectsManager::new()
    .with_caustics(CausticsConfig {
        intensity: 0.8,
        scale: 2.0,
        speed: 0.5,
    })
    .with_god_rays(GodRaysConfig {
        density: 0.3,
        decay: 0.95,
        samples: 64,
    })
    .with_foam(FoamConfig {
        threshold: 0.7,
        persistence: 2.0,
    });
}

Quality Presets

Terrain Integration

Automatic water body detection:

#![allow(unused)]
fn main() {
use astraweave_fluids::{TerrainWaterIntegration, WaterBodyType};

let integration = TerrainWaterIntegration::new(&terrain);

// Detect water bodies
let water_bodies = integration.detect_water_bodies();

for body in water_bodies {
    match body.body_type {
        WaterBodyType::Lake { depth, .. } => {
            println!("Lake detected: depth = {}", depth);
        }
        WaterBodyType::River { flow_speed, .. } => {
            println!("River detected: flow = {}", flow_speed);
        }
        WaterBodyType::Waterfall { height, .. } => {
            println!("Waterfall detected: height = {}", height);
        }
    }
}
}

Building Integration

Interactive water elements for building systems:

#![allow(unused)]
fn main() {
use astraweave_fluids::{
    WaterBuildingManager,
    WaterDispenser,
    WaterDrain,
    WaterGate,
    WaterWheel,
};

let mut water_manager = WaterBuildingManager::new(&volume_grid);

// Water source
let dispenser = WaterDispenser::new(position, flow_rate: 5.0);
water_manager.add_dispenser(dispenser);

// Water sink
let drain = WaterDrain::new(position, capacity: 10.0);
water_manager.add_drain(drain);

// Player-controlled gate
let gate = WaterGate::new(position, width: 2.0);
water_manager.add_gate(gate);

// Power generator
let wheel = WaterWheel::new(position, radius: 1.5);
water_manager.add_wheel(wheel);

// Query power generation
let power = water_manager.get_wheel_power(&wheel);
}

Editor Integration

Full editor support with undo/redo:

#![allow(unused)]
fn main() {
use astraweave_fluids::editor::{
    FluidEditorConfig,
    ConfigHistory,
    ValidationIssue,
};

let mut config = FluidEditorConfig::default();
let mut history = ConfigHistory::new();

// Make changes with history tracking
history.push(config.clone());
config.physics.viscosity = 0.5;

// Undo
if let Some(prev) = history.undo() {
    config = prev;
}

// Validate configuration
let issues: Vec<ValidationIssue> = config.validate();
for issue in issues {
    eprintln!("{}: {}", issue.severity, issue.message);
}
}

Serialization

Save and load fluid state:

#![allow(unused)]
fn main() {
use astraweave_fluids::serialization::{FluidSnapshot, save_snapshot, load_snapshot};

// Save current state
let snapshot = FluidSnapshot::capture(&simulation);
save_snapshot(&snapshot, "saves/water_state.bin")?;

// Load state
let loaded = load_snapshot("saves/water_state.bin")?;
simulation.restore(&loaded);
}

Performance Optimization

SIMD Operations

The fluids system uses SIMD for critical operations:

#![allow(unused)]
fn main() {
use astraweave_fluids::simd_ops;

// Batch particle updates (SIMD accelerated)
simd_ops::update_positions_batch(&mut particles, delta_time);
simd_ops::compute_densities_batch(&particles, &neighbors, kernel_h);
}

LOD System

Distance-based quality reduction:

#![allow(unused)]
fn main() {
use astraweave_fluids::lod::{FluidLodConfig, LodLevel};

let lod_config = FluidLodConfig {
    levels: vec![
        LodLevel { distance: 0.0, particle_skip: 1 },   // Full detail
        LodLevel { distance: 50.0, particle_skip: 2 },  // 50% particles
        LodLevel { distance: 100.0, particle_skip: 4 }, // 25% particles
    ],
    cull_distance: 200.0,
};
}

Profiling

Built-in performance monitoring:

#![allow(unused)]
fn main() {
use astraweave_fluids::profiling::FluidProfiler;

let profiler = FluidProfiler::new();

// Wrap simulation step
profiler.begin("simulation_step");
simulation.step(dt);
profiler.end("simulation_step");

// Get statistics
let stats = profiler.get_stats();
println!("Avg step time: {:?}", stats.avg_step_time);
println!("Particle count: {}", stats.active_particles);
}

Benchmarks

From Master Benchmark Report:

Examples

Basic Water Pool

cargo run --example fluids_demo -- --preset pool

Interactive Waterfall

cargo run --example fluids_demo -- --preset waterfall

Building Water System

cargo run --example fluids_demo -- --preset building

See Also

• API Reference - Detailed API documentation
• Benchmarks - Performance data
• Physics System - Physics integration
• Terrain System - Terrain integration

Terrain System

Status: Production Ready
Coverage: 71.5%
Crate: astraweave-terrain

AstraWeave’s terrain system provides procedural terrain generation using noise functions, voxel data, and biome classification with full LOD support and async streaming.

Overview

Core Features

Performance

Quick Start

#![allow(unused)]
fn main() {
use astraweave_terrain::{
    ChunkManager, TerrainChunk, ChunkId,
    Heightmap, HeightmapConfig,
    Biome, BiomeType,
};

// Create heightmap generator
let heightmap = Heightmap::new(HeightmapConfig {
    seed: 12345,
    octaves: 6,
    frequency: 0.01,
    amplitude: 100.0,
});

// Generate chunk
let chunk_id = ChunkId::new(0, 0);
let chunk = TerrainChunk::generate(&heightmap, chunk_id);

// Get height at world position
let height = heightmap.sample(world_x, world_z);
}

Architecture

Module Overview

astraweave-terrain/
├── Generation
│   ├── noise_gen.rs          # Noise generation
│   ├── noise_simd.rs         # SIMD-optimized noise
│   ├── heightmap.rs          # Heightmap generation
│   └── structures.rs         # Structure placement
├── Voxel System
│   ├── voxel_data.rs         # Voxel grid & chunks
│   ├── chunk.rs              # Chunk management
│   └── terrain_modifier.rs   # Runtime modification
├── Meshing
│   ├── meshing.rs            # Mesh generation
│   ├── marching_cubes_tables.rs  # MC lookup tables
│   └── lod_blending.rs       # LOD mesh morphing
├── Biomes
│   ├── biome.rs              # Biome types
│   ├── biome_blending.rs     # Smooth transitions
│   ├── climate.rs            # Climate simulation
│   └── scatter.rs            # Vegetation placement
├── Erosion
│   ├── erosion.rs            # Basic erosion
│   └── advanced_erosion.rs   # Multi-type erosion
├── Streaming
│   ├── background_loader.rs  # Async loading
│   ├── lod_manager.rs        # LOD control
│   └── streaming_diagnostics.rs  # Debug info
└── Integration
    ├── partition_integration.rs  # World streaming
    ├── texture_splatting.rs      # Material blending
    └── terrain_persistence.rs    # Save/load

Voxel System

Voxel Data Structure

#![allow(unused)]
fn main() {
use astraweave_terrain::{Voxel, Density, MaterialId, VoxelChunk, CHUNK_SIZE};

// Voxel with density and material
let voxel = Voxel {
    density: Density::new(0.7),  // 0.0 = air, 1.0 = solid
    material: MaterialId::STONE,
};

// Create empty chunk
let mut chunk = VoxelChunk::new();

// Set voxel at local position
chunk.set(x, y, z, voxel);

// Get voxel
let v = chunk.get(x, y, z);
}

Chunk Coordinates

#![allow(unused)]
fn main() {
use astraweave_terrain::{ChunkCoord, ChunkId, CHUNK_SIZE};

// World position to chunk
let chunk_coord = ChunkCoord::from_world_pos(world_pos);

// Chunk ID for manager
let chunk_id = ChunkId::new(chunk_coord.x, chunk_coord.z);

// Local position within chunk
let local_pos = chunk_coord.to_local(world_pos);
}

Heightmap Generation

Basic Heightmap

#![allow(unused)]
fn main() {
use astraweave_terrain::{Heightmap, HeightmapConfig};

let config = HeightmapConfig {
    seed: 42,
    octaves: 6,           // Detail levels
    frequency: 0.01,      // Base frequency
    amplitude: 100.0,     // Height range
    persistence: 0.5,     // Octave decay
    lacunarity: 2.0,      // Octave frequency multiplier
};

let heightmap = Heightmap::new(config);

// Sample height at position
let height = heightmap.sample(x, z);

// Get normal at position
let normal = heightmap.normal(x, z);
}

SIMD-Optimized Generation

For bulk generation (2-3× faster):

#![allow(unused)]
fn main() {
use astraweave_terrain::SimdHeightmapGenerator;

let generator = SimdHeightmapGenerator::new(config);

// Generate entire chunk heightmap
let heights: Vec<f32> = generator.generate_chunk(chunk_coord);
}

Biome System

Biome Types

#![allow(unused)]
fn main() {
use astraweave_terrain::{BiomeType, Biome, BiomeConfig};

pub enum BiomeType {
    Ocean,
    Beach,
    Plains,
    Forest,
    Taiga,
    Desert,
    Savanna,
    Jungle,
    Swamp,
    Mountain,
    SnowyMountain,
    Tundra,
}

// Biome configuration
let forest = BiomeConfig {
    biome_type: BiomeType::Forest,
    temperature_range: (0.3, 0.7),
    humidity_range: (0.5, 0.8),
    height_modifier: 1.0,
    vegetation_density: 0.8,
};
}

Climate-Based Distribution

#![allow(unused)]
fn main() {
use astraweave_terrain::{ClimateMap, ClimateConfig};

let climate = ClimateMap::new(ClimateConfig {
    seed: 12345,
    temperature_scale: 0.001,
    humidity_scale: 0.002,
});

// Get biome at position
let biome = climate.get_biome_at(x, z);

// Get climate values
let (temp, humidity) = climate.sample(x, z);
}

Biome Blending

#![allow(unused)]
fn main() {
use astraweave_terrain::{BiomeBlender, BiomeBlendConfig};

let blender = BiomeBlender::new(BiomeBlendConfig {
    blend_distance: 16.0,  // Transition width
    noise_strength: 0.2,   // Edge noise
});

// Get blended biome weights at position
let weights: Vec<BiomeWeight> = blender.get_weights(x, z);

// Apply to terrain materials
for weight in weights {
    material.blend(weight.biome, weight.strength);
}
}

Mesh Generation

Marching Cubes

#![allow(unused)]
fn main() {
use astraweave_terrain::meshing::{ChunkMesh, MeshVertex};

// Generate mesh from voxel chunk
let mesh = ChunkMesh::from_voxels(&chunk, &heightmap);

// Access mesh data
for vertex in mesh.vertices() {
    let pos = vertex.position;
    let normal = vertex.normal;
    let uv = vertex.uv;
}
}

Dual Contouring

For sharper edges:

#![allow(unused)]
fn main() {
use astraweave_terrain::meshing::DualContouring;

let dc = DualContouring::new();
let mesh = dc.generate(&chunk, edge_sharpness: 0.8);
}

LOD Mesh Generation

#![allow(unused)]
fn main() {
use astraweave_terrain::meshing::{LodMeshGenerator, LodConfig};

let generator = LodMeshGenerator::new(LodConfig {
    levels: vec![
        LodLevel { distance: 0.0, subdivisions: 8 },
        LodLevel { distance: 100.0, subdivisions: 4 },
        LodLevel { distance: 300.0, subdivisions: 2 },
        LodLevel { distance: 500.0, subdivisions: 1 },
    ],
});

// Generate LOD mesh for distance
let mesh = generator.generate(&chunk, camera_distance);
}

Erosion Simulation

Hydraulic Erosion

#![allow(unused)]
fn main() {
use astraweave_terrain::{
    AdvancedErosionSimulator,
    HydraulicErosionConfig,
    ErosionPreset,
};

let erosion = AdvancedErosionSimulator::new();

// Apply preset
let config = ErosionPreset::MountainRivers.into_config();
erosion.simulate_hydraulic(&mut heightmap, config, iterations: 50000);

// Or custom config
let custom = HydraulicErosionConfig {
    rain_amount: 0.01,
    erosion_rate: 0.3,
    deposition_rate: 0.3,
    evaporation_rate: 0.02,
    min_slope: 0.01,
};
}

Thermal Erosion

#![allow(unused)]
fn main() {
use astraweave_terrain::ThermalErosionConfig;

let thermal_config = ThermalErosionConfig {
    talus_angle: 0.5,  // Max stable slope
    erosion_rate: 0.1,
};

erosion.simulate_thermal(&mut heightmap, thermal_config, iterations: 1000);
}

Wind Erosion

#![allow(unused)]
fn main() {
use astraweave_terrain::WindErosionConfig;

let wind_config = WindErosionConfig {
    wind_direction: Vec3::new(1.0, 0.0, 0.5).normalize(),
    wind_strength: 0.5,
    particle_count: 10000,
};

erosion.simulate_wind(&mut heightmap, wind_config, iterations: 5000);
}

Async Streaming

Background Loader

#![allow(unused)]
fn main() {
use astraweave_terrain::{
    BackgroundChunkLoader,
    StreamingConfig,
    StreamingStats,
};

let loader = BackgroundChunkLoader::new(StreamingConfig {
    load_radius: 8,           // Chunks to keep loaded
    unload_radius: 12,        // Distance to unload
    max_concurrent_loads: 4,  // Parallel chunk loading
    priority_distance: 2,     // High-priority radius
});

// Update from camera position
loader.update(camera_pos);

// Poll for completed chunks
while let Some(chunk) = loader.poll_completed() {
    chunk_manager.insert(chunk);
}

// Get statistics
let stats: StreamingStats = loader.stats();
println!("Chunks loaded: {}", stats.chunks_loaded);
println!("Load queue: {}", stats.queue_length);
}

LOD Manager

#![allow(unused)]
fn main() {
use astraweave_terrain::{LodManager, LodConfig, LodStats};

let lod_manager = LodManager::new(LodConfig {
    hysteresis: 0.1,  // Prevent LOD flickering
    update_interval: 0.5,  // Seconds between LOD updates
});

// Update LOD states
lod_manager.update(camera_pos, delta_time);

// Get current LOD for chunk
let lod_level = lod_manager.get_lod(chunk_id);
}

Streaming Diagnostics

#![allow(unused)]
fn main() {
use astraweave_terrain::StreamingDiagnostics;

let diagnostics = StreamingDiagnostics::new();

// Record frame data
diagnostics.record_frame(frame_time, chunks_loaded, chunks_visible);

// Detect hitches
if let Some(hitch) = diagnostics.detect_hitch() {
    warn!("Streaming hitch: {:?}", hitch);
}

// Generate report
let report = diagnostics.generate_report();
}

Runtime Modification

Terrain Modifier

#![allow(unused)]
fn main() {
use astraweave_terrain::{TerrainModifier, VoxelOp, VoxelOpType};

let mut modifier = TerrainModifier::new(&mut chunk_manager);

// Dig sphere
modifier.apply(VoxelOp {
    op_type: VoxelOpType::Subtract,
    center: world_pos,
    radius: 5.0,
    material: None,
});

// Add material
modifier.apply(VoxelOp {
    op_type: VoxelOpType::Add,
    center: world_pos,
    radius: 3.0,
    material: Some(MaterialId::STONE),
});

// Smooth area
modifier.apply(VoxelOp {
    op_type: VoxelOpType::Smooth,
    center: world_pos,
    radius: 4.0,
    material: None,
});

// Batch operations for efficiency
modifier.begin_batch();
for op in operations {
    modifier.apply(op);
}
modifier.end_batch();  // Regenerates affected meshes once
}

Texture Splatting

Material Blending

#![allow(unused)]
fn main() {
use astraweave_terrain::{
    SplatMapGenerator,
    SplatConfig,
    SplatRule,
    TerrainMaterial,
};

let generator = SplatMapGenerator::new(SplatConfig {
    resolution: 512,
    rules: vec![
        SplatRule::height_based(TerrainMaterial::Grass, 0.0, 50.0),
        SplatRule::height_based(TerrainMaterial::Rock, 50.0, 100.0),
        SplatRule::height_based(TerrainMaterial::Snow, 100.0, 200.0),
        SplatRule::slope_based(TerrainMaterial::Cliff, 0.7, 1.0),
    ],
});

let splat_map = generator.generate(&heightmap);
}

Triplanar Mapping

#![allow(unused)]
fn main() {
use astraweave_terrain::TriplanarWeights;

// Calculate triplanar weights from normal
let weights = TriplanarWeights::from_normal(vertex_normal);

// Sample texture with triplanar projection
let color = 
    sample_xz(uv_xz) * weights.y +
    sample_xy(uv_xy) * weights.z +
    sample_zy(uv_zy) * weights.x;
}

Persistence

Save/Load Terrain

#![allow(unused)]
fn main() {
use astraweave_terrain::terrain_persistence::{save_terrain, load_terrain};

// Save modified terrain
save_terrain(&chunk_manager, "saves/terrain.bin")?;

// Load terrain
let loaded = load_terrain("saves/terrain.bin")?;
chunk_manager.restore(&loaded);
}

AI Integration

Terrain Solver

For AI-driven terrain queries:

#![allow(unused)]
fn main() {
use astraweave_terrain::{TerrainSolver, ResolvedLocation};

let solver = TerrainSolver::new(&chunk_manager);

// Find valid location for AI agent
let result: ResolvedLocation = solver.find_valid_location(
    search_center,
    radius: 10.0,
    constraints: &[
        Constraint::MinHeight(5.0),
        Constraint::MaxSlope(0.3),
        Constraint::RequireBiome(BiomeType::Forest),
    ],
)?;

println!("Found location: {:?}", result.position);
}

Blueprint Zone System

The Blueprint Zone system enables polygon-based spatial control over vegetation generation and heightmap injection, bridging .blend scene imports with the terrain scatter pipeline.

Overview

Editor Canvas → BlueprintZone → ZoneScatterGenerator → ZoneGenerationResult
     ↓               ↓                ↓                      ↓
Polygon drawing   ZoneRegistry    Replica/Inspired      placements + patches
                  (save/load)      mode dispatch         ↓
                                                    apply_heightmap_patches()
                                                         ↓
                                                    TerrainChunk updates

Zone Data Model

#![allow(unused)]
fn main() {
use astraweave_terrain::blueprint_zone::*;

// Define a zone with polygon vertices
let zone = BlueprintZone {
    id: ZoneId(1),
    name: "Forest Clearing".into(),
    vertices: vec![[0.0, 0.0], [100.0, 0.0], [100.0, 100.0], [0.0, 100.0]],
    source: ZoneSource::BlendScene {
        pack_path: "assets/pine_forest.biomepack".into(),
        placement_mode: PlacementMode::Replica,
    },
    priority: 0,
    enabled: true,
};

// ZoneRegistry — CRUD, spatial queries, persistence
let mut registry = ZoneRegistry::new();
registry.add_zone(zone);
let zones = registry.zones_containing_point(50.0, 50.0);
registry.save(&Path::new("zones.json"))?;
let loaded = ZoneRegistry::load(&Path::new("zones.json"))?;
}

Placement Modes

Zone-Scoped Generation

#![allow(unused)]
fn main() {
use astraweave_terrain::zone_scatter::*;

let gen = ZoneScatterGenerator::new(256.0, 128); // chunk_size, heightmap_resolution
let result = gen.generate_zone_scatter(&zone, &biome_pack)?;

// result.placements — Vec<VegetationInstance> (position, rotation, scale, model_path)
// result.heightmap_patches — Vec<HeightmapPatch> (per-chunk height modifications)

// Apply heightmap patches to terrain chunks
let results = vec![result];
apply_heightmap_patches(&mut chunk_map, &results);
}

Adaptive Scaling

When zone area differs from source scene footprint, density and scale adjust automatically:

#![allow(unused)]
fn main() {
let params = AdaptiveScaleParams::compute(reference_area, zone_area);
// density_multiplier = sqrt(zone_area / reference_area)
// scale_multiplier   = (zone_area / reference_area)^0.25
// position_scale     = sqrt(zone_area / reference_area)
}

Boundary Blending

apply_boundary_blending() uses smoothstep falloff at zone edges:

• Vegetation: density fades via BlendMask::sample(x, z) → 0.0–1.0
• Heightmap: height delta scaled by mask value at each sample point
• Manual: BrushMode::ZoneBlend for blend-weight painting in-editor

Heightmap Rasterization

Terrain meshes from .blend decomposition are rasterized into heightmaps:

#![allow(unused)]
fn main() {
use astraweave_blend::heightmap_raster::*;

let heightmap = rasterize_terrain_meshes(&terrain_meshes, resolution)?;
let height = heightmap.sample_bilinear(u, v); // Normalized [0,1] coords
let area = heightmap.footprint_area();         // World-space area in m²
}

Editor Integration

The BlueprintPanel provides a 2D canvas for polygon zone editing:

• Tools: Select, DrawPolygon, MoveVertex, DeleteZone
• Zone inspector with name, source selection, placement mode toggle
• Undo/redo via command stack
• Save/Load zones as .zones.json

The BlueprintOverlay projects zone polygons as wireframe outlines into the 3D viewport, integrated with the physics renderer debug line pass.

Test Coverage

See Also

• API Reference - Detailed API documentation
• Fluids System - Water integration
• Physics System - Collision terrain
• Navigation - Navmesh from terrain

Blueprint Zone Editor

Status: Production Ready
Tests: 125+
Crates: astraweave-terrain, astraweave-blend, aw_editor

The Blueprint Zone system provides polygon-based spatial control for vegetation generation and heightmap injection. It bridges .blend scene imports with AstraWeave’s terrain scatter pipeline, enabling both exact 1:1 reproduction (Replica mode) and procedural variation (Inspired mode) of imported environments.

Overview

Pipeline

.blend Scene → Decomposition → BiomePack → BlueprintZone → ZoneScatterGenerator
                    ↓                           ↓                    ↓
              heightmap_raster           ZoneRegistry          VegetationInstance
              (terrain mesh →            (polygon CRUD,        + HeightmapPatch
               heightmap + fixed          spatial queries,          ↓
               placements)                JSON persistence)   apply_heightmap_patches()
                                                                    ↓
                                                              TerrainChunk updates

Key Features

Quick Start

#![allow(unused)]
fn main() {
use astraweave_terrain::blueprint_zone::*;
use astraweave_terrain::zone_scatter::*;
use std::path::Path;

// 1. Define a zone
let zone = BlueprintZone {
    id: ZoneId(1),
    name: "Pine Forest".into(),
    vertices: vec![
        [0.0, 0.0], [200.0, 0.0],
        [200.0, 150.0], [0.0, 150.0],
    ],
    source: ZoneSource::BlendScene {
        pack_path: "assets/pine_forest.biomepack".into(),
        placement_mode: PlacementMode::Replica,
    },
    priority: 0,
    enabled: true,
};

// 2. Register it
let mut registry = ZoneRegistry::new();
registry.add_zone(zone.clone());

// 3. Generate scatter
let gen = ZoneScatterGenerator::new(256.0, 128);
let result = gen.generate_zone_scatter(&zone, &biome_pack)?;

println!("{} placements", result.placement_count());
println!("{} height modifications", result.modified_height_count());

// 4. Apply heightmap patches to terrain
let mut chunks = HashMap::new();
// ... populate with TerrainChunks ...
apply_heightmap_patches(&mut chunks, &[result]);

// 5. Persist zones
registry.save(Path::new("assets/zones.json"))?;
}

Zone Data Model

BlueprintZone

A BlueprintZone represents a polygon region with a vegetation/terrain source:

#![allow(unused)]
fn main() {
pub struct BlueprintZone {
    pub id: ZoneId,                    // Unique identifier
    pub name: String,                  // Display name
    pub vertices: Vec<[f32; 2]>,       // Polygon vertices (XZ plane)
    pub source: ZoneSource,            // What to generate
    pub priority: u32,                 // Overlap resolution (higher wins)
    pub enabled: bool,                 // Toggle generation
}
}

ZoneSource

#![allow(unused)]
fn main() {
pub enum ZoneSource {
    BiomePreset(BiomeType),            // Built-in biome scatter
    BlendScene {
        pack_path: String,             // Path to .biomepack
        placement_mode: PlacementMode, // Replica or Inspired
    },
}
}

PlacementMode

ZoneRegistry

#![allow(unused)]
fn main() {
let mut registry = ZoneRegistry::new();

// CRUD operations
registry.add_zone(zone);
registry.remove_zone(zone_id);
let zone = registry.get_zone(zone_id);
let zone_mut = registry.get_zone_mut(zone_id);

// Spatial queries
let zones = registry.zones_containing_point(x, z);
let overlaps = registry.zones_overlapping_rect(min_x, min_z, max_x, max_z);

// Persistence
registry.save(Path::new("zones.json"))?;
let loaded = ZoneRegistry::load(Path::new("zones.json"))?;
}

Zone-Scoped Generation

ZoneScatterGenerator

#![allow(unused)]
fn main() {
use astraweave_terrain::zone_scatter::*;

// Create generator with chunk size and heightmap resolution
let gen = ZoneScatterGenerator::new(256.0, 128);

// Generate for a single zone
let result: ZoneGenerationResult = gen.generate_zone_scatter(&zone, &biome_pack)?;
}

ZoneGenerationResult

#![allow(unused)]
fn main() {
pub struct ZoneGenerationResult {
    pub placements: Vec<VegetationInstance>,     // What to place
    pub heightmap_patches: Vec<HeightmapPatch>,  // Height modifications
}

// VegetationInstance fields:
// - position: Vec3
// - rotation: f32
// - scale: f32
// - vegetation_type: String
// - model_path: String
// - terrain_normal: Vec3
}

Multi-Zone Generation

#![allow(unused)]
fn main() {
// Generate scatter for all zones with overlap priority resolution
let results = generate_multi_zone_scatter(&zones, &gen, &biome_packs)?;

// Apply all heightmap patches at once
apply_heightmap_patches(&mut chunk_map, &results);
}

Adaptive Scaling

When a zone’s area differs from the source scene’s footprint, scaling parameters adjust automatically:

#![allow(unused)]
fn main() {
let params = AdaptiveScaleParams::compute(reference_area, zone_area);
}

Example: A zone 4× larger than the source scene would have:

• density_multiplier = 2.0 (double the objects)
• scale_multiplier ≈ 1.41 (slightly larger objects)
• position_scale = 2.0 (spread positions wider)

Boundary Blending

Smoothstep Falloff

Zone edges use smoothstep interpolation to prevent hard vegetation/height cutoffs:

#![allow(unused)]
fn main() {
// BlendMask provides per-point blending weights
let mask = BlendMask::new(resolution, world_bounds);
let weight = mask.sample(x, z); // 0.0 at edge → 1.0 at center
}

Manual Painting

The editor provides BrushMode::ZoneBlend for manually painting blend weights at zone boundaries, giving artists fine control over transition regions.

Heightmap Rasterization

Terrain meshes extracted from .blend files are rasterized into heightmaps:

#![allow(unused)]
fn main() {
use astraweave_blend::heightmap_raster::*;

let heightmap = rasterize_terrain_meshes(&terrain_meshes, 128)?;

// Query rasterized data
let height = heightmap.sample_bilinear(0.5, 0.5); // Normalized UV coords
let area = heightmap.footprint_area();              // m² world-space

// Fixed placements (exact object positions from scene)
let placements: Vec<FixedPlacement> = extract_fixed_placements(&scene_objects);
}

The rasterizer uses ray-triangle intersection with:

• Seam averaging for multi-tile terrain boundaries
• Hole filling via neighbor interpolation for missing samples

Editor Integration

Blueprint Panel

The BlueprintPanel (panel type: Blueprint) provides:

• 2D Canvas: Pan/zoom view for polygon zone drawing
• Tools: Select, DrawPolygon, MoveVertex, DeleteZone
• Zone Inspector: Name, source selection (biome preset or blend scene), placement mode toggle
• Undo/Redo: Full BlueprintCommand stack with Ctrl+Z/Ctrl+Shift+Z
• Persistence: Save/Load zones as .zones.json files

Viewport Overlay

BlueprintOverlay projects zone polygons as colored wireframe outlines in the 3D viewport. Zone boundaries are rendered alongside component gizmos and brush cursors in the physics renderer debug line pass.

Asset Browser

The BlendAssetScanner adds .blend file discovery to the asset browser with:

• Automatic directory scanning for .blend files
• Decomposition status detection (checking for manifest.json)
• Quick actions: Import Blend Scene, Use as Zone Source

System Wiring

The editor’s update loop dispatches BlueprintAction events:

After each action, sync_zone_overlay() pushes updated zone data to the viewport.

Test Coverage

See Also

• Terrain System - Core terrain generation and streaming
• Rendering - Renderer debug line pass for overlays
• Physics - DebugLine integration

Cinematics System

Status: Production Ready
Crate: astraweave-cinematics
Coverage: ~85%

The cinematics system provides a timeline-based sequencer for creating cutscenes, scripted events, and cinematic sequences with synchronized camera, animation, audio, and visual effects tracks.

Core Types

Quick Start

#![allow(unused)]
fn main() {
use astraweave_cinematics::{Time, Timeline, Track, CameraKey, Sequencer};

// Create a 10-second timeline
let mut timeline = Timeline::new("intro_cutscene", 10.0);

// Add camera keyframes
let keyframes = vec![
    CameraKey::new(Time::zero(), [0.0, 5.0, -10.0], [0.0, 0.0, 0.0], 60.0),
    CameraKey::new(Time::from_secs(5.0), [10.0, 8.0, -5.0], [0.0, 45.0, 0.0], 55.0),
    CameraKey::new(Time::from_secs(10.0), [0.0, 3.0, 0.0], [0.0, 90.0, 0.0], 70.0),
];
timeline.add_camera_track(keyframes);

// Add audio
timeline.add_audio_track("music/intro.ogg", Time::zero(), 0.8);

// Add animation trigger
timeline.add_track(Track::animation(1, "character_wave", Time::from_secs(2.0)));

// Add FX
timeline.add_track(Track::fx("explosion", Time::from_secs(8.0), serde_json::json!({
    "scale": 2.0,
    "particles": 500
})));

// Playback
let mut sequencer = Sequencer::new();
let dt = 1.0 / 60.0; // 60 FPS

loop {
    match sequencer.step(dt, &timeline) {
        Ok(events) => {
            for event in events {
                handle_event(event);
            }
        }
        Err(_) => break, // End of timeline
    }
}
}

Architecture

Timeline Structure

Timeline "intro_cutscene" (10.0s)
├── Track::Camera
│   ├── Keyframe @ 0.0s (pos, rot, fov)
│   ├── Keyframe @ 5.0s
│   └── Keyframe @ 10.0s
├── Track::Audio "music/intro.ogg" @ 0.0s
├── Track::Animation target=1 "character_wave" @ 2.0s
└── Track::Fx "explosion" @ 8.0s

Playback Flow

┌───────────────────────────────────────────────────┐
│                    Sequencer                       │
│  ┌─────────┐    ┌───────────┐    ┌─────────────┐  │
│  │  seek() │ →  │  step(dt) │ →  │   events    │  │
│  └─────────┘    └───────────┘    └─────────────┘  │
│                        │                           │
│                        ▼                           │
│  ┌─────────────────────────────────────────────┐  │
│  │ For each track, emit events where           │  │
│  │ start_time > previous_t && start_time <= t  │  │
│  └─────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────┘

Time API

The Time type provides precision time handling:

#![allow(unused)]
fn main() {
use astraweave_cinematics::Time;

// Construction
let t1 = Time::zero();                  // 0.0s
let t2 = Time::from_secs(5.0);          // 5.0s
let t3 = Time::from_millis(1500.0);     // 1.5s

// Access
println!("Seconds: {}", t2.as_secs());   // 5.0
println!("Millis: {}", t2.as_millis());  // 5000.0

// Arithmetic
let sum = t2 + t3;                       // 6.5s
let diff = t2 - t3;                      // 3.5s
let added = t2.add_secs(2.5);            // 7.5s

// Utilities
let clamped = t2.clamp(Time::zero(), Time::from_secs(4.0)); // 4.0s
let lerped = Time::zero().lerp(Time::from_secs(10.0), 0.3); // 3.0s

// Display
println!("{}", Time::from_secs(2.5));    // "2.50s"
println!("{}", Time::from_millis(500.0)); // "500ms"
}

Track Types

Camera Track

Controls camera position, rotation, and field of view:

#![allow(unused)]
fn main() {
use astraweave_cinematics::{Track, CameraKey, Time};

let track = Track::camera(vec![
    CameraKey {
        t: Time::zero(),
        pos: [0.0, 5.0, -10.0],
        rot: [0.0, 0.0, 0.0],      // Euler angles (degrees)
        fov: 60.0,                  // Field of view
    },
    CameraKey {
        t: Time::from_secs(5.0),
        pos: [10.0, 8.0, -5.0],
        rot: [0.0, 45.0, 0.0],
        fov: 55.0,
    },
]);

assert!(track.is_camera());
assert_eq!(track.keyframe_count(), Some(2));
}

Animation Track

Triggers character/object animations:

#![allow(unused)]
fn main() {
let track = Track::animation(
    42,                        // Target entity ID
    "run_forward",             // Animation clip name
    Time::from_secs(1.5),      // Start time
);

assert!(track.is_animation());
assert_eq!(track.start_time(), Some(Time::from_secs(1.5)));
}

Audio Track

Plays sound effects or music:

#![allow(unused)]
fn main() {
let track = Track::audio(
    "sfx/explosion.wav",       // Audio clip path
    Time::from_secs(3.0),      // Start time
    0.8,                       // Volume (0.0 - 1.0)
);

assert!(track.is_audio());
}

FX Track

Triggers visual effects with parameters:

#![allow(unused)]
fn main() {
use serde_json::json;

let track = Track::fx(
    "particle_burst",          // Effect name
    Time::from_secs(2.0),      // Start time
    json!({
        "count": 100,
        "color": [1.0, 0.5, 0.0],
        "lifetime": 2.0
    }),
);

assert!(track.is_fx());
}

Timeline API

Creating Timelines

#![allow(unused)]
fn main() {
use astraweave_cinematics::Timeline;

// Named timeline with duration
let mut timeline = Timeline::new("boss_intro", 30.0);

// Empty timeline
let empty = Timeline::empty();
assert!(empty.is_empty());
}

Building Timelines

#![allow(unused)]
fn main() {
let mut timeline = Timeline::new("action_sequence", 15.0);

// Add tracks
timeline.add_camera_track(camera_keyframes);
timeline.add_audio_track("music/action.ogg", Time::zero(), 1.0);
timeline.add_track(Track::animation(1, "attack", Time::from_secs(5.0)));

// Track counts
println!("Camera tracks: {}", timeline.camera_track_count());
println!("Audio tracks: {}", timeline.audio_track_count());
println!("Animation tracks: {}", timeline.animation_track_count());
println!("FX tracks: {}", timeline.fx_track_count());
println!("Total tracks: {}", timeline.track_count());
println!("Total keyframes: {}", timeline.total_keyframes());
}

Timeline Properties

#![allow(unused)]
fn main() {
let timeline = Timeline::new("example", 10.0);

println!("Name: {}", timeline.name);
println!("Duration: {}s", timeline.duration_secs());
println!("Empty: {}", timeline.is_empty());

// Display
println!("{}", timeline); // Timeline("example", duration=10.00s, 0 tracks)
}

Sequencer API

Basic Playback

#![allow(unused)]
fn main() {
use astraweave_cinematics::Sequencer;

let mut seq = Sequencer::new();
let dt = 1.0 / 60.0;  // 60 FPS

// Step through timeline
loop {
    match seq.step(dt, &timeline) {
        Ok(events) => {
            for event in events {
                process_event(event);
            }
        }
        Err(SeqError::Range(_)) => {
            println!("Timeline complete");
            break;
        }
    }
}
}

Seeking

#![allow(unused)]
fn main() {
let mut seq = Sequencer::new();

// Jump to specific time
seq.seek(Time::from_secs(5.0));

// Current time
println!("Current: {}", seq.t);
}

Event Handling

#![allow(unused)]
fn main() {
use astraweave_cinematics::SequencerEvent;

fn handle_event(event: SequencerEvent) {
    match event {
        SequencerEvent::CameraKey(key) => {
            camera.set_position(key.pos);
            camera.set_rotation(key.rot);
            camera.set_fov(key.fov);
        }
        SequencerEvent::AnimStart { target, clip } => {
            if let Some(entity) = world.get_entity(target) {
                animator.play(entity, &clip);
            }
        }
        SequencerEvent::AudioPlay { clip, volume } => {
            audio.play(&clip, volume);
        }
        SequencerEvent::FxTrigger { name, params } => {
            fx_system.trigger(&name, params);
        }
    }
}
}

Serialization

Timelines are fully serializable with Serde:

#![allow(unused)]
fn main() {
use astraweave_cinematics::Timeline;

// Save to JSON
let json = serde_json::to_string_pretty(&timeline)?;
std::fs::write("cutscene.json", &json)?;

// Load from JSON
let loaded: Timeline = serde_json::from_str(&json)?;

// Save to RON (common in game dev)
let ron = ron::to_string(&timeline)?;
}

Example JSON:

{
  "name": "intro",
  "duration": 10.0,
  "tracks": [
    {
      "Camera": {
        "keyframes": [
          { "t": 0.0, "pos": [0, 5, -10], "rot": [0, 0, 0], "fov": 60 },
          { "t": 5.0, "pos": [10, 8, -5], "rot": [0, 45, 0], "fov": 55 }
        ]
      }
    },
    {
      "Audio": {
        "clip": "music/intro.ogg",
        "start": 0.0,
        "volume": 0.8
      }
    }
  ]
}

Integration Examples

With ECS

#![allow(unused)]
fn main() {
use astraweave_ecs::World;
use astraweave_cinematics::{Sequencer, Timeline};

fn cinematics_system(world: &mut World, timeline: &Timeline, seq: &mut Sequencer, dt: f32) {
    if let Ok(events) = seq.step(dt, timeline) {
        for event in events {
            match event {
                SequencerEvent::CameraKey(key) => {
                    // Update camera component
                    if let Some(camera) = world.query_mut::<CameraComponent>().next() {
                        camera.position = key.pos.into();
                        camera.rotation = key.rot.into();
                        camera.fov = key.fov;
                    }
                }
                SequencerEvent::AnimStart { target, clip } => {
                    // Trigger animation on entity
                    if let Some(anim) = world.get_component_mut::<Animator>(target) {
                        anim.play(&clip);
                    }
                }
                // ... handle other events
            }
        }
    }
}
}

With Game State

#![allow(unused)]
fn main() {
enum GameState {
    Playing,
    Cutscene { timeline: Timeline, sequencer: Sequencer },
}

impl GameState {
    fn update(&mut self, dt: f32) -> Option<SequencerEvent> {
        match self {
            GameState::Cutscene { timeline, sequencer } => {
                match sequencer.step(dt, timeline) {
                    Ok(events) => {
                        for event in events {
                            // Handle events
                        }
                        None
                    }
                    Err(_) => {
                        // Cutscene complete, return to gameplay
                        *self = GameState::Playing;
                        None
                    }
                }
            }
            _ => None,
        }
    }
}
}

Performance

Optimization Tips

1. Pre-sort tracks by start time for faster event lookup
2. Reuse sequencers instead of creating new ones
3. Batch event handling when multiple events fire simultaneously
4. Use seek() sparingly - stepping is more efficient

Common Patterns

Looping Cutscenes

#![allow(unused)]
fn main() {
let mut seq = Sequencer::new();

loop {
    match seq.step(dt, &timeline) {
        Ok(events) => handle_events(events),
        Err(_) => {
            // Loop back to start
            seq.seek(Time::zero());
        }
    }
}
}

Skippable Cutscenes

#![allow(unused)]
fn main() {
fn update_cutscene(seq: &mut Sequencer, timeline: &Timeline, dt: f32, skip_pressed: bool) {
    if skip_pressed {
        // Jump to end
        seq.seek(timeline.duration);
        return;
    }
    
    if let Ok(events) = seq.step(dt, timeline) {
        handle_events(events);
    }
}
}

Branching Cutscenes

#![allow(unused)]
fn main() {
struct BranchingCutscene {
    timelines: HashMap<String, Timeline>,
    current: String,
    sequencer: Sequencer,
}

impl BranchingCutscene {
    fn switch_to(&mut self, name: &str) {
        self.current = name.to_string();
        self.sequencer.seek(Time::zero());
    }
    
    fn update(&mut self, dt: f32) -> Vec<SequencerEvent> {
        let timeline = &self.timelines[&self.current];
        self.sequencer.step(dt, timeline).unwrap_or_default()
    }
}
}

See Also

• API Reference: Cinematics
• Audio System - Audio integration
• Animation System - Character animation
• Camera System - Camera controls

Building Your First Game

This guide walks you through building a complete game with AstraWeave, from project setup to a playable demo featuring AI companions, physics, and navigation.

Before starting, ensure you have:
- Rust 1.75+ installed
- AstraWeave cloned and building successfully
- Ollama running with a compatible model (see [Installation Guide](../getting-started/installation.md))

Project Overview

We’ll build “Companion Quest” - a small adventure where an AI companion helps the player navigate a dungeon, solve puzzles, and defeat enemies. This showcases:

• AI companion with LLM-powered dialogue
• Physics-based puzzles
• Navigation and pathfinding
• Combat with adaptive enemies
• Save/load functionality

Step 1: Project Setup

Create a New Example

Create a new directory in examples/:

mkdir -p examples/companion_quest/src

Create examples/companion_quest/Cargo.toml:

[package]
name = "companion_quest"
version = "0.1.0"
edition = "2021"

[dependencies]
astraweave-core = { path = "../../astraweave-core" }
astraweave-ecs = { path = "../../astraweave-ecs" }
astraweave-ai = { path = "../../astraweave-ai" }
astraweave-physics = { path = "../../astraweave-physics" }
astraweave-nav = { path = "../../astraweave-nav" }
astraweave-render = { path = "../../astraweave-render" }
astraweave-audio = { path = "../../astraweave-audio" }
astraweave-input = { path = "../../astraweave-input" }
astraweave-llm = { path = "../../astraweave-llm" }
astraweave-gameplay = { path = "../../astraweave-gameplay" }
tokio = { version = "1.0", features = ["rt-multi-thread", "macros"] }

Main Entry Point

Create examples/companion_quest/src/main.rs:

use astraweave_core::prelude::*;
use astraweave_ecs::prelude::*;
use astraweave_ai::prelude::*;
use astraweave_physics::prelude::*;
use astraweave_nav::prelude::*;

fn main() {
    let mut world = World::new();
    
    setup_world(&mut world);
    setup_player(&mut world);
    setup_companion(&mut world);
    setup_dungeon(&mut world);
    
    run_game_loop(&mut world);
}

fn setup_world(world: &mut World) {
    world.insert_resource(PhysicsConfig::default());
    world.insert_resource(NavigationConfig::default());
    world.insert_resource(AiConfig {
        tick_budget_ms: 8,
        max_concurrent_plans: 4,
        ..Default::default()
    });
}

Step 2: Creating the Player

The player entity needs transform, physics, and input components:

#![allow(unused)]
fn main() {
fn setup_player(world: &mut World) {
    let player = world.spawn((
        Transform::from_xyz(0.0, 1.0, 0.0),
        RigidBody::Dynamic,
        Collider::capsule(0.5, 1.8),
        Player {
            health: 100.0,
            max_health: 100.0,
            stamina: 100.0,
        },
        InputReceiver::default(),
        CharacterController {
            speed: 5.0,
            jump_force: 8.0,
            ..Default::default()
        },
    ));
    
    world.insert_resource(PlayerEntity(player));
}

#[derive(Component)]
struct Player {
    health: f32,
    max_health: f32,
    stamina: f32,
}
}

Step 3: Creating the AI Companion

The companion uses AstraWeave’s AI-native architecture:

#![allow(unused)]
fn main() {
fn setup_companion(world: &mut World) {
    let companion = world.spawn((
        Transform::from_xyz(2.0, 1.0, 0.0),
        RigidBody::Dynamic,
        Collider::capsule(0.4, 1.6),
        
        AiAgent {
            personality: "helpful and curious".into(),
            knowledge_base: vec![
                "I am Spark, a magical companion".into(),
                "I can help solve puzzles and fight enemies".into(),
            ],
        },
        
        PerceptionRadius(15.0),
        
        NavAgent {
            speed: 4.0,
            acceleration: 10.0,
            avoidance_radius: 0.5,
        },
        
        Companion {
            following: true,
            follow_distance: 3.0,
        },
        
        DialogueCapable::default(),
    ));
    
    world.insert_resource(CompanionEntity(companion));
}

#[derive(Component)]
struct Companion {
    following: bool,
    follow_distance: f32,
}
}

Step 4: Building the Dungeon

Create a simple dungeon with rooms and corridors:

#![allow(unused)]
fn main() {
fn setup_dungeon(world: &mut World) {
    let floor = world.spawn((
        Transform::from_xyz(0.0, 0.0, 0.0),
        RigidBody::Static,
        Collider::cuboid(50.0, 0.5, 50.0),
        Floor,
    ));
    
    spawn_walls(world);
    spawn_doors(world);
    spawn_puzzles(world);
    spawn_enemies(world);
    
    generate_navmesh(world);
}

fn generate_navmesh(world: &mut World) {
    let navmesh = NavMeshBuilder::new()
        .cell_size(0.3)
        .cell_height(0.2)
        .agent_radius(0.5)
        .agent_height(1.8)
        .max_slope(45.0)
        .build_from_world(world);
    
    world.insert_resource(navmesh);
}
}

Step 5: The Game Loop

AstraWeave uses a fixed-tick simulation for determinism:

#![allow(unused)]
fn main() {
fn run_game_loop(world: &mut World) {
    let mut scheduler = Scheduler::new();
    
    scheduler.add_system(input_system);
    scheduler.add_system(player_movement_system);
    scheduler.add_system(ai_perception_system);
    scheduler.add_system(ai_planning_system);
    scheduler.add_system(companion_follow_system);
    scheduler.add_system(navigation_system);
    scheduler.add_system(physics_system);
    scheduler.add_system(combat_system);
    scheduler.add_system(dialogue_system);
    scheduler.add_system(render_system);
    
    let tick_rate = Duration::from_secs_f64(1.0 / 60.0);
    let mut accumulator = Duration::ZERO;
    let mut last_time = Instant::now();
    
    loop {
        let now = Instant::now();
        let delta = now - last_time;
        last_time = now;
        accumulator += delta;
        
        while accumulator >= tick_rate {
            scheduler.run(world);
            accumulator -= tick_rate;
        }
        
        if should_quit(world) {
            break;
        }
    }
}
}

Step 6: AI Companion Behavior

The companion uses perception and planning:

#![allow(unused)]
fn main() {
fn companion_follow_system(
    player_query: Query<&Transform, With<Player>>,
    mut companion_query: Query<(&mut NavAgent, &Companion, &Transform)>,
    navmesh: Res<NavMesh>,
) {
    let player_pos = player_query.single().translation;
    
    for (mut nav_agent, companion, transform) in companion_query.iter_mut() {
        if !companion.following {
            continue;
        }
        
        let distance = transform.translation.distance(player_pos);
        
        if distance > companion.follow_distance {
            let target = player_pos - (player_pos - transform.translation)
                .normalize() * companion.follow_distance;
            
            if let Some(path) = navmesh.find_path(transform.translation, target) {
                nav_agent.set_path(path);
            }
        }
    }
}
}

Step 7: Dialogue Integration

Enable LLM-powered dialogue with the companion:

#![allow(unused)]
fn main() {
fn dialogue_system(
    mut dialogue_events: EventReader<DialogueEvent>,
    mut llm_client: ResMut<LlmClient>,
    companion_query: Query<&AiAgent, With<Companion>>,
    mut dialogue_responses: EventWriter<DialogueResponse>,
) {
    for event in dialogue_events.read() {
        let agent = companion_query.single();
        
        let prompt = format!(
            "You are {}. The player says: '{}'. Respond in character.",
            agent.personality,
            event.message
        );
        
        match llm_client.generate_blocking(&prompt) {
            Ok(response) => {
                dialogue_responses.send(DialogueResponse {
                    speaker: "Spark".into(),
                    text: response,
                });
            }
            Err(e) => {
                dialogue_responses.send(DialogueResponse {
                    speaker: "Spark".into(),
                    text: "Hmm, I'm not sure what to say...".into(),
                });
            }
        }
    }
}
}

Step 8: Combat System

Add combat with tool validation:

#![allow(unused)]
fn main() {
fn combat_system(
    mut combat_events: EventReader<CombatEvent>,
    mut health_query: Query<&mut Health>,
    tool_validator: Res<ToolValidator>,
) {
    for event in combat_events.read() {
        let validation = tool_validator.validate(&ToolCall {
            tool: "attack".into(),
            params: json!({
                "attacker": event.attacker,
                "target": event.target,
                "damage": event.damage,
            }),
        });
        
        match validation {
            ToolResult::Success => {
                if let Ok(mut health) = health_query.get_mut(event.target) {
                    health.current -= event.damage;
                }
            }
            ToolResult::Blocked(reason) => {
                println!("Attack blocked: {}", reason);
            }
        }
    }
}
}

Step 9: Running Your Game

Build and run:

cargo run -p companion_quest --release

Expected Output

[INFO] AstraWeave v0.1.0 starting...
[INFO] Physics initialized: Rapier 0.17
[INFO] Navigation: NavMesh built (2,450 polygons)
[INFO] AI: Connected to Ollama (hermes2-pro)
[INFO] Companion "Spark" spawned at (2.0, 1.0, 0.0)
[INFO] Game loop started at 60 Hz

Complete Example

See the full working example at examples/companion_quest/ or explore these related examples:

Next Steps

• AI Companions - Deep dive into companion AI
• Adaptive Bosses - Creating intelligent enemies
• Dialogue Systems - LLM-powered conversations
• Physics - Physics system details

Enable release mode (`--release`) for LLM inference. Debug builds can be 10-50x slower for AI operations.

AI Companions

AI companions are a signature feature of AstraWeave. Unlike scripted NPCs in traditional engines, companions in AstraWeave use LLM-powered planning to make intelligent decisions while respecting game rules through tool validation.

Companions cannot cheat - they perceive the world, plan actions, and execute through the same validated systems as players.

Companion Architecture

graph LR
    subgraph Companion
        Perception[Perception]
        Memory[Memory]
        Personality[Personality]
        Planning[LLM Planning]
        Actions[Action Queue]
    end
    
    World[World State] --> Perception
    Perception --> Memory
    Memory --> Planning
    Personality --> Planning
    Planning --> Actions
    Actions --> World

Creating a Companion

Basic Companion Setup

#![allow(unused)]
fn main() {
use astraweave_ai::prelude::*;
use astraweave_ecs::prelude::*;

fn spawn_companion(world: &mut World, name: &str, personality: &str) -> Entity {
    world.spawn((
        Name::new(name),
        Transform::from_xyz(0.0, 0.0, 0.0),
        
        AiAgent::new()
            .with_personality(personality)
            .with_perception_radius(20.0)
            .with_memory_capacity(100),
        
        CompanionBehavior {
            follow_distance: 3.0,
            engage_distance: 10.0,
            flee_health_threshold: 0.2,
        },
        
        AvailableTools::new(vec![
            Tool::move_to(),
            Tool::follow(),
            Tool::attack(),
            Tool::defend(),
            Tool::use_item(),
            Tool::speak(),
            Tool::investigate(),
        ]),
        
        PerceptionState::default(),
        NavAgent::default(),
        DialogueCapable::default(),
        Health::new(100.0),
    ))
}
}

Personality Configuration

Companions have distinct personalities that influence their decisions:

#![allow(unused)]
fn main() {
let warrior_companion = AiAgent::new()
    .with_personality("brave and protective warrior who prioritizes the player's safety")
    .with_traits(vec![
        Trait::Brave,
        Trait::Protective,
        Trait::DirectCommunicator,
    ])
    .with_knowledge(vec![
        "I am a seasoned warrior".into(),
        "I protect my allies at all costs".into(),
        "I prefer melee combat".into(),
    ]);

let scholar_companion = AiAgent::new()
    .with_personality("curious scholar who loves discovering secrets and solving puzzles")
    .with_traits(vec![
        Trait::Curious,
        Trait::Analytical,
        Trait::Cautious,
    ])
    .with_knowledge(vec![
        "I study ancient texts and artifacts".into(),
        "I prefer avoiding combat when possible".into(),
        "I excel at puzzle-solving".into(),
    ]);
}

Companion Behaviors

Following the Player

#![allow(unused)]
fn main() {
fn companion_follow_system(
    player: Query<&Transform, With<Player>>,
    mut companions: Query<(&mut NavAgent, &CompanionBehavior, &Transform), With<AiAgent>>,
    navmesh: Res<NavMesh>,
) {
    let player_pos = player.single().translation;
    
    for (mut nav, behavior, transform) in companions.iter_mut() {
        let distance = transform.translation.distance(player_pos);
        
        if distance > behavior.follow_distance {
            let target = calculate_follow_position(player_pos, transform.translation, behavior.follow_distance);
            
            if let Some(path) = navmesh.find_path(transform.translation, target) {
                nav.set_path(path);
            }
        } else {
            nav.stop();
        }
    }
}
}

Combat Assistance

#![allow(unused)]
fn main() {
fn companion_combat_system(
    mut companions: Query<(&AiAgent, &mut ActionQueue, &Transform, &Health)>,
    enemies: Query<(Entity, &Transform, &Health), With<Enemy>>,
    player: Query<&Transform, With<Player>>,
) {
    let player_pos = player.single().translation;
    
    for (agent, mut actions, companion_pos, health) in companions.iter_mut() {
        if health.percentage() < agent.flee_threshold {
            actions.push(Action::Flee);
            continue;
        }
        
        let nearest_enemy = enemies.iter()
            .filter(|(_, t, h)| h.current > 0.0)
            .min_by_key(|(_, t, _)| {
                (t.translation.distance(player_pos) * 100.0) as i32
            });
        
        if let Some((enemy_entity, enemy_pos, _)) = nearest_enemy {
            let distance = companion_pos.translation.distance(enemy_pos.translation);
            
            if distance < agent.engage_distance {
                actions.push(Action::Attack(enemy_entity));
            } else {
                actions.push(Action::MoveTo(enemy_pos.translation));
            }
        }
    }
}
}

Dialogue Interaction

#![allow(unused)]
fn main() {
fn companion_dialogue_system(
    mut events: EventReader<DialogueRequest>,
    mut companions: Query<(&AiAgent, &PerceptionState, &mut DialogueState)>,
    llm: Res<LlmClient>,
    mut responses: EventWriter<DialogueResponse>,
) {
    for request in events.read() {
        if let Ok((agent, perception, mut dialogue)) = companions.get_mut(request.target) {
            let context = build_dialogue_context(agent, perception, &dialogue.history);
            
            let prompt = format!(
                "{}\n\nThe player says: '{}'\n\nRespond in character:",
                context,
                request.message
            );
            
            match llm.generate(&prompt) {
                Ok(response) => {
                    dialogue.history.push(DialogueEntry {
                        speaker: "Player".into(),
                        text: request.message.clone(),
                    });
                    dialogue.history.push(DialogueEntry {
                        speaker: agent.name.clone(),
                        text: response.clone(),
                    });
                    
                    responses.send(DialogueResponse {
                        speaker: agent.name.clone(),
                        text: response,
                    });
                }
                Err(_) => {
                    responses.send(DialogueResponse {
                        speaker: agent.name.clone(),
                        text: "Hmm, let me think about that...".into(),
                    });
                }
            }
        }
    }
}
}

Memory System

Companions remember past events and use them in decision-making:

#![allow(unused)]
fn main() {
#[derive(Component)]
struct CompanionMemory {
    short_term: VecDeque<MemoryEntry>,
    long_term: Vec<MemoryEntry>,
    capacity: usize,
}

impl CompanionMemory {
    fn remember(&mut self, event: MemoryEntry) {
        self.short_term.push_back(event);
        
        if self.short_term.len() > self.capacity {
            if let Some(old) = self.short_term.pop_front() {
                if old.importance >= 0.7 {
                    self.long_term.push(old);
                }
            }
        }
    }
    
    fn recall(&self, query: &str, limit: usize) -> Vec<&MemoryEntry> {
        self.long_term.iter()
            .chain(self.short_term.iter())
            .filter(|m| m.matches(query))
            .take(limit)
            .collect()
    }
}

#[derive(Clone)]
struct MemoryEntry {
    timestamp: GameTime,
    event_type: EventType,
    description: String,
    importance: f32,
    entities: Vec<Entity>,
    location: Vec3,
}
}

Companion Commands

Players can issue commands to companions:

#![allow(unused)]
fn main() {
#[derive(Event)]
enum CompanionCommand {
    Follow,
    Stay,
    Attack(Entity),
    Investigate(Vec3),
    UseAbility(AbilityId),
    ToggleAggressive,
}

fn handle_companion_commands(
    mut commands: EventReader<CompanionCommand>,
    mut companions: Query<(&mut CompanionBehavior, &mut ActionQueue)>,
) {
    for command in commands.read() {
        for (mut behavior, mut actions) in companions.iter_mut() {
            match command {
                CompanionCommand::Follow => {
                    behavior.mode = CompanionMode::Follow;
                    actions.clear();
                }
                CompanionCommand::Stay => {
                    behavior.mode = CompanionMode::Stay;
                    actions.clear();
                }
                CompanionCommand::Attack(target) => {
                    actions.push(Action::Attack(*target));
                }
                CompanionCommand::Investigate(pos) => {
                    actions.push(Action::MoveTo(*pos));
                    actions.push(Action::Investigate);
                }
                CompanionCommand::UseAbility(ability) => {
                    actions.push(Action::UseAbility(*ability));
                }
                CompanionCommand::ToggleAggressive => {
                    behavior.aggressive = !behavior.aggressive;
                }
            }
        }
    }
}
}

Configuration

Companion Presets

#![allow(unused)]
fn main() {
pub fn create_healer_companion(world: &mut World) -> Entity {
    spawn_companion(world, "Luna", "compassionate healer who prioritizes keeping allies alive")
        .with(AvailableTools::new(vec![
            Tool::heal(),
            Tool::cure_status(),
            Tool::buff(),
            Tool::follow(),
            Tool::flee(),
        ]))
        .with(CompanionBehavior {
            follow_distance: 5.0,
            engage_distance: 15.0,
            flee_health_threshold: 0.3,
            mode: CompanionMode::Support,
        })
}

pub fn create_tank_companion(world: &mut World) -> Entity {
    spawn_companion(world, "Grimjaw", "fearless guardian who draws enemy attention")
        .with(AvailableTools::new(vec![
            Tool::taunt(),
            Tool::block(),
            Tool::attack(),
            Tool::charge(),
            Tool::protect_ally(),
        ]))
        .with(CompanionBehavior {
            follow_distance: 2.0,
            engage_distance: 8.0,
            flee_health_threshold: 0.1,
            mode: CompanionMode::Aggressive,
        })
}
}

Best Practices

- Limit perception radius for better performance
- Use plan caching to reduce LLM calls
- Batch companion updates in the scheduler

- Don't give companions tools they shouldn't have
- Always define fallback behaviors for LLM timeouts
- Test personality prompts for consistent behavior

See Also

• AI System - Core AI architecture
• Adaptive Bosses - Enemy AI patterns
• Dialogue Systems - Conversation implementation
• Tool Validation - How actions are validated

Adaptive Bosses

Adaptive bosses in AstraWeave learn from player behavior and adjust their strategies in real-time. Unlike scripted boss encounters, these AI-driven enemies create unique, memorable fights that evolve with each attempt.

Bosses use the same AI architecture as companions - perception, planning, and validated tools - but with combat-focused behaviors and learning capabilities.

Boss Architecture

graph TB
    subgraph "Boss AI"
        Perception[Player Analysis]
        Memory[Pattern Memory]
        Strategy[Strategy Selection]
        Phase[Phase Management]
        Actions[Action Execution]
    end
    
    Player[Player Behavior] --> Perception
    Perception --> Memory
    Memory --> Strategy
    Strategy --> Phase
    Phase --> Actions
    Actions --> Player

Creating an Adaptive Boss

Basic Boss Setup

#![allow(unused)]
fn main() {
use astraweave_ai::prelude::*;
use astraweave_gameplay::boss::*;

fn spawn_adaptive_boss(world: &mut World) -> Entity {
    world.spawn((
        Name::new("The Hollow Knight"),
        Transform::from_xyz(0.0, 2.0, 0.0),
        
        BossAi::new()
            .with_phases(3)
            .with_adaptation_rate(0.3)
            .with_pattern_memory(50),
        
        BossHealth {
            current: 10000.0,
            max: 10000.0,
            phase_thresholds: vec![0.7, 0.4, 0.15],
        },
        
        AvailableTools::new(vec![
            Tool::melee_combo(),
            Tool::ranged_attack(),
            Tool::area_attack(),
            Tool::summon_minions(),
            Tool::teleport(),
            Tool::enrage(),
        ]),
        
        PlayerAnalyzer::default(),
        StrategySelector::default(),
        
        RigidBody::Dynamic,
        Collider::capsule(1.0, 4.0),
        NavAgent::default(),
    ))
}
}

Phase Configuration

#![allow(unused)]
fn main() {
#[derive(Component)]
struct BossPhaseConfig {
    phases: Vec<BossPhase>,
    current_phase: usize,
}

struct BossPhase {
    name: String,
    health_threshold: f32,
    available_attacks: Vec<AttackPattern>,
    behavior_modifiers: BehaviorModifiers,
    transition_animation: Option<AnimationId>,
}

let phase_config = BossPhaseConfig {
    phases: vec![
        BossPhase {
            name: "Cautious".into(),
            health_threshold: 1.0,
            available_attacks: vec![
                AttackPattern::SingleSlash,
                AttackPattern::Thrust,
                AttackPattern::Sidestep,
            ],
            behavior_modifiers: BehaviorModifiers {
                aggression: 0.3,
                defense: 0.7,
                patience: 0.8,
            },
            transition_animation: None,
        },
        BossPhase {
            name: "Aggressive".into(),
            health_threshold: 0.6,
            available_attacks: vec![
                AttackPattern::TripleCombo,
                AttackPattern::SpinAttack,
                AttackPattern::LeapSlam,
                AttackPattern::Thrust,
            ],
            behavior_modifiers: BehaviorModifiers {
                aggression: 0.7,
                defense: 0.3,
                patience: 0.4,
            },
            transition_animation: Some(AnimationId::Enrage),
        },
        BossPhase {
            name: "Desperate".into(),
            health_threshold: 0.25,
            available_attacks: vec![
                AttackPattern::FuryCombo,
                AttackPattern::ShadowClones,
                AttackPattern::AreaDenial,
                AttackPattern::GrabAttack,
            ],
            behavior_modifiers: BehaviorModifiers {
                aggression: 1.0,
                defense: 0.1,
                patience: 0.1,
            },
            transition_animation: Some(AnimationId::Transform),
        },
    ],
    current_phase: 0,
};
}

Player Analysis

Bosses track player behavior to counter their strategies:

#![allow(unused)]
fn main() {
#[derive(Component, Default)]
struct PlayerAnalyzer {
    dodge_pattern: DodgePattern,
    attack_timing: AttackTiming,
    positioning_preference: PositioningStyle,
    heal_threshold: f32,
    aggression_level: f32,
    pattern_history: VecDeque<PlayerAction>,
}

#[derive(Default)]
struct DodgePattern {
    left_count: u32,
    right_count: u32,
    back_count: u32,
    roll_timing: Vec<f32>,
}

fn analyze_player_system(
    mut analyzers: Query<&mut PlayerAnalyzer, With<BossAi>>,
    player_actions: EventReader<PlayerActionEvent>,
) {
    for action in player_actions.read() {
        for mut analyzer in analyzers.iter_mut() {
            analyzer.pattern_history.push_back(action.clone());
            
            if analyzer.pattern_history.len() > 100 {
                analyzer.pattern_history.pop_front();
            }
            
            match action {
                PlayerActionEvent::Dodge(direction) => {
                    match direction {
                        Direction::Left => analyzer.dodge_pattern.left_count += 1,
                        Direction::Right => analyzer.dodge_pattern.right_count += 1,
                        Direction::Back => analyzer.dodge_pattern.back_count += 1,
                        _ => {}
                    }
                }
                PlayerActionEvent::Attack(timing) => {
                    analyzer.attack_timing.record(*timing);
                }
                PlayerActionEvent::Heal => {
                    analyzer.heal_threshold = calculate_heal_threshold(&analyzer);
                }
                _ => {}
            }
        }
    }
}
}

Strategy Adaptation

#![allow(unused)]
fn main() {
#[derive(Component)]
struct StrategySelector {
    current_strategy: BossStrategy,
    strategy_effectiveness: HashMap<BossStrategy, f32>,
    adaptation_cooldown: Timer,
}

#[derive(Clone, Copy, Hash, Eq, PartialEq)]
enum BossStrategy {
    Aggressive,
    Defensive,
    Counter,
    Pressure,
    Bait,
    Mixed,
}

fn adapt_strategy_system(
    mut bosses: Query<(&PlayerAnalyzer, &mut StrategySelector, &BossHealth)>,
    time: Res<Time>,
) {
    for (analyzer, mut selector, health) in bosses.iter_mut() {
        selector.adaptation_cooldown.tick(time.delta());
        
        if selector.adaptation_cooldown.finished() {
            let new_strategy = select_counter_strategy(analyzer);
            
            if new_strategy != selector.current_strategy {
                let old_effectiveness = selector.strategy_effectiveness
                    .get(&selector.current_strategy)
                    .copied()
                    .unwrap_or(0.5);
                
                selector.strategy_effectiveness
                    .insert(selector.current_strategy, old_effectiveness * 0.9);
                
                selector.current_strategy = new_strategy;
                selector.adaptation_cooldown.reset();
            }
        }
    }
}

fn select_counter_strategy(analyzer: &PlayerAnalyzer) -> BossStrategy {
    if analyzer.aggression_level > 0.7 {
        BossStrategy::Counter
    } else if analyzer.dodge_pattern.is_predictable() {
        BossStrategy::Bait
    } else if analyzer.heal_threshold > 0.5 {
        BossStrategy::Pressure
    } else {
        BossStrategy::Mixed
    }
}
}

Attack Patterns

#![allow(unused)]
fn main() {
fn boss_attack_system(
    mut bosses: Query<(
        &BossAi,
        &StrategySelector,
        &PlayerAnalyzer,
        &Transform,
        &mut ActionQueue,
    )>,
    player: Query<&Transform, With<Player>>,
) {
    let player_pos = player.single().translation;
    
    for (boss, strategy, analyzer, transform, mut actions) in bosses.iter_mut() {
        let distance = transform.translation.distance(player_pos);
        
        let attack = match strategy.current_strategy {
            BossStrategy::Aggressive => {
                select_aggressive_attack(distance, boss.current_phase)
            }
            BossStrategy::Counter => {
                if analyzer.is_player_attacking() {
                    Some(AttackPattern::Parry)
                } else {
                    Some(AttackPattern::Wait)
                }
            }
            BossStrategy::Bait => {
                let predicted_dodge = analyzer.predict_dodge_direction();
                Some(AttackPattern::DelayedStrike(predicted_dodge.opposite()))
            }
            BossStrategy::Pressure => {
                Some(AttackPattern::RelentlessCombo)
            }
            _ => {
                select_random_attack(boss.current_phase)
            }
        };
        
        if let Some(pattern) = attack {
            actions.push(Action::ExecutePattern(pattern));
        }
    }
}
}

Learning Between Attempts

Bosses can remember strategies across player deaths:

#![allow(unused)]
fn main() {
#[derive(Resource)]
struct BossMemory {
    player_deaths: u32,
    successful_attacks: HashMap<AttackPattern, u32>,
    failed_attacks: HashMap<AttackPattern, u32>,
    player_weaknesses: Vec<Weakness>,
}

impl BossMemory {
    fn record_attack_result(&mut self, pattern: AttackPattern, hit: bool) {
        if hit {
            *self.successful_attacks.entry(pattern).or_default() += 1;
        } else {
            *self.failed_attacks.entry(pattern).or_default() += 1;
        }
    }
    
    fn get_attack_priority(&self, pattern: AttackPattern) -> f32 {
        let successes = self.successful_attacks.get(&pattern).copied().unwrap_or(0) as f32;
        let failures = self.failed_attacks.get(&pattern).copied().unwrap_or(0) as f32;
        
        if successes + failures < 3.0 {
            return 0.5;
        }
        
        successes / (successes + failures)
    }
}
}

Example: The Hollow Knight

A complete adaptive boss implementation:

#![allow(unused)]
fn main() {
pub fn spawn_hollow_knight(world: &mut World) -> Entity {
    let boss = world.spawn((
        Name::new("The Hollow Knight"),
        Transform::from_xyz(0.0, 2.0, -20.0),
        
        BossAi::new()
            .with_phases(4)
            .with_adaptation_rate(0.25),
        
        BossHealth::new(15000.0)
            .with_phases(vec![0.75, 0.5, 0.25]),
        
        PlayerAnalyzer::default(),
        StrategySelector::new(BossStrategy::Defensive),
        
        AttackPatterns::new(vec![
            ("slash", AttackPattern::Slash { damage: 80.0, range: 3.0 }),
            ("thrust", AttackPattern::Thrust { damage: 100.0, range: 5.0 }),
            ("spin", AttackPattern::Spin { damage: 60.0, radius: 4.0 }),
            ("leap", AttackPattern::LeapSlam { damage: 120.0, radius: 6.0 }),
            ("shadow", AttackPattern::ShadowDash { damage: 50.0, distance: 10.0 }),
        ]),
        
        RigidBody::Dynamic,
        Collider::capsule(1.2, 3.5),
        NavAgent::default(),
    ));
    
    world.send_event(BossSpawnedEvent { boss });
    boss
}
}

Best Practices

- Start with simpler patterns, add complexity in later phases
- Ensure all attacks are telegraphed and fair
- Test adaptation rates - too fast feels unfair, too slow feels scripted
- Provide recovery windows between attack chains

- Adaptation should challenge, not frustrate
- Preserve attack patterns that players can learn
- Don't punish the same mistake indefinitely
- Allow multiple valid strategies

See Also

• AI System - Core AI architecture
• AI Companions - Friendly AI patterns
• Combat System - Combat mechanics

Crafting & Combat Systems

AstraWeave provides a unified crafting and combat framework that integrates with the AI systems for dynamic, adaptive gameplay. This guide covers implementing both systems with physics integration, AI-driven balancing, and procedural content generation.

Architecture Overview

graph TB
    subgraph Combat["Combat System"]
        CS[Combat State] --> DM[Damage Model]
        DM --> HR[Hit Resolution]
        HR --> EF[Effects Pipeline]
        EF --> FB[Feedback System]
    end
    
    subgraph Crafting["Crafting System"]
        IV[Inventory] --> RC[Recipe Check]
        RC --> CR[Craft Resolution]
        CR --> QR[Quality Roll]
        QR --> IT[Item Creation]
    end
    
    subgraph Integration["AI Integration"]
        AI[AI Director] --> CB[Combat Balancing]
        AI --> CG[Craft Guidance]
        CB --> CS
        CG --> RC
    end
    
    Physics[Physics Engine] --> HR
    Physics --> EF

Combat System

Combat Components

Define the core components for combat entities:

#![allow(unused)]
fn main() {
use astraweave_ecs::prelude::*;
use astraweave_physics::prelude::*;

#[derive(Component, Debug, Clone)]
pub struct CombatStats {
    pub health: f32,
    pub max_health: f32,
    pub stamina: f32,
    pub max_stamina: f32,
    pub poise: f32,
    pub max_poise: f32,
}

impl Default for CombatStats {
    fn default() -> Self {
        Self {
            health: 100.0,
            max_health: 100.0,
            stamina: 100.0,
            max_stamina: 100.0,
            poise: 50.0,
            max_poise: 50.0,
        }
    }
}

#[derive(Component, Debug, Clone)]
pub struct DamageResistances {
    pub physical: f32,
    pub fire: f32,
    pub ice: f32,
    pub lightning: f32,
    pub poison: f32,
}

#[derive(Component, Debug, Clone)]
pub struct WeaponStats {
    pub base_damage: f32,
    pub damage_type: DamageType,
    pub attack_speed: f32,
    pub reach: f32,
    pub stamina_cost: f32,
    pub poise_damage: f32,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum DamageType {
    Physical,
    Fire,
    Ice,
    Lightning,
    Poison,
}

#[derive(Component, Debug)]
pub struct CombatState {
    pub stance: CombatStance,
    pub combo_count: u32,
    pub combo_timer: f32,
    pub stagger_timer: f32,
    pub invincibility_frames: f32,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum CombatStance {
    Neutral,
    Attacking,
    Blocking,
    Dodging,
    Staggered,
    Recovering,
}
}

Attack System

Implement the attack resolution with physics-based hit detection:

#![allow(unused)]
fn main() {
use astraweave_physics::collision::*;

#[derive(Debug, Clone)]
pub struct AttackEvent {
    pub attacker: Entity,
    pub weapon: Entity,
    pub attack_type: AttackType,
    pub direction: Vec3,
}

#[derive(Debug, Clone, Copy)]
pub enum AttackType {
    Light,
    Heavy,
    Special,
    Charged { charge_time: f32 },
}

pub fn attack_system(
    mut commands: Commands,
    mut attack_events: EventReader<AttackEvent>,
    mut combat_query: Query<(&mut CombatState, &mut CombatStats, &Transform)>,
    weapon_query: Query<&WeaponStats>,
    physics: Res<PhysicsWorld>,
) {
    for event in attack_events.iter() {
        let Ok((mut state, mut stats, transform)) = combat_query.get_mut(event.attacker) else {
            continue;
        };
        
        if stats.stamina < get_stamina_cost(&event.attack_type) {
            continue;
        }
        
        let Ok(weapon) = weapon_query.get(event.weapon) else {
            continue;
        };
        
        stats.stamina -= weapon.stamina_cost * get_attack_multiplier(&event.attack_type);
        state.stance = CombatStance::Attacking;
        
        let hitbox = create_attack_hitbox(transform, weapon, &event.attack_type);
        
        commands.spawn((
            hitbox,
            AttackHitbox {
                owner: event.attacker,
                damage: calculate_attack_damage(weapon, &event.attack_type, state.combo_count),
                damage_type: weapon.damage_type,
                poise_damage: weapon.poise_damage,
                knockback: event.direction * 5.0,
            },
            Lifetime { remaining: 0.2 },
        ));
        
        state.combo_count = (state.combo_count + 1).min(5);
        state.combo_timer = 1.5;
    }
}

fn calculate_attack_damage(weapon: &WeaponStats, attack_type: &AttackType, combo: u32) -> f32 {
    let base = weapon.base_damage;
    let type_mult = match attack_type {
        AttackType::Light => 1.0,
        AttackType::Heavy => 1.8,
        AttackType::Special => 2.5,
        AttackType::Charged { charge_time } => 1.0 + (charge_time * 0.5).min(2.0),
    };
    let combo_mult = 1.0 + (combo as f32 * 0.1);
    
    base * type_mult * combo_mult
}

fn create_attack_hitbox(
    transform: &Transform,
    weapon: &WeaponStats,
    attack_type: &AttackType,
) -> Collider {
    let size = match attack_type {
        AttackType::Light => Vec3::new(weapon.reach * 0.8, 1.0, weapon.reach * 0.8),
        AttackType::Heavy => Vec3::new(weapon.reach * 1.2, 1.5, weapon.reach * 1.2),
        AttackType::Special => Vec3::new(weapon.reach * 2.0, 2.0, weapon.reach * 2.0),
        AttackType::Charged { .. } => Vec3::new(weapon.reach * 1.5, 1.2, weapon.reach * 1.5),
    };
    
    Collider::cuboid(size.x, size.y, size.z)
        .with_offset(transform.forward() * (weapon.reach * 0.5))
}
}

Damage Resolution

Process hits and apply damage with resistance calculations:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct AttackHitbox {
    pub owner: Entity,
    pub damage: f32,
    pub damage_type: DamageType,
    pub poise_damage: f32,
    pub knockback: Vec3,
}

pub fn damage_resolution_system(
    mut commands: Commands,
    hitbox_query: Query<(Entity, &AttackHitbox, &CollidingEntities)>,
    mut target_query: Query<(
        &mut CombatStats,
        &mut CombatState,
        &DamageResistances,
        &mut Transform,
    )>,
    mut damage_events: EventWriter<DamageEvent>,
) {
    for (hitbox_entity, hitbox, colliding) in hitbox_query.iter() {
        for &target in colliding.iter() {
            if target == hitbox.owner {
                continue;
            }
            
            let Ok((mut stats, mut state, resistances, mut transform)) = 
                target_query.get_mut(target) else {
                continue;
            };
            
            if state.invincibility_frames > 0.0 {
                continue;
            }
            
            let resistance = get_resistance(resistances, hitbox.damage_type);
            let final_damage = hitbox.damage * (1.0 - resistance);
            
            stats.health = (stats.health - final_damage).max(0.0);
            stats.poise -= hitbox.poise_damage;
            
            if stats.poise <= 0.0 {
                state.stance = CombatStance::Staggered;
                state.stagger_timer = 1.5;
                stats.poise = stats.max_poise * 0.5;
            }
            
            transform.translation += hitbox.knockback * 0.1;
            
            damage_events.send(DamageEvent {
                target,
                attacker: hitbox.owner,
                damage: final_damage,
                damage_type: hitbox.damage_type,
                was_critical: false,
            });
            
            state.invincibility_frames = 0.15;
        }
        
        commands.entity(hitbox_entity).despawn();
    }
}

fn get_resistance(resistances: &DamageResistances, damage_type: DamageType) -> f32 {
    match damage_type {
        DamageType::Physical => resistances.physical,
        DamageType::Fire => resistances.fire,
        DamageType::Ice => resistances.ice,
        DamageType::Lightning => resistances.lightning,
        DamageType::Poison => resistances.poison,
    }.clamp(0.0, 0.9)
}
}

Combat AI Integration

Leverage the AI system for dynamic combat behavior:

#![allow(unused)]
fn main() {
use astraweave_ai::prelude::*;

#[derive(Component)]
pub struct CombatAI {
    pub aggression: f32,
    pub patience: f32,
    pub preferred_range: f32,
    pub combo_tendency: f32,
}

pub fn ai_combat_decision_system(
    mut ai_query: Query<(
        Entity,
        &CombatAI,
        &CombatStats,
        &CombatState,
        &Transform,
        &mut AiPlanner,
    )>,
    target_query: Query<(&CombatStats, &CombatState, &Transform), Without<CombatAI>>,
    mut attack_events: EventWriter<AttackEvent>,
) {
    for (entity, ai, stats, state, transform, mut planner) in ai_query.iter_mut() {
        if state.stance != CombatStance::Neutral {
            continue;
        }
        
        let Some(target) = find_nearest_target(transform, &target_query) else {
            continue;
        };
        
        let (target_stats, target_state, target_transform) = target_query.get(target).unwrap();
        let distance = transform.translation.distance(target_transform.translation);
        let direction = (target_transform.translation - transform.translation).normalize();
        
        let decision = evaluate_combat_options(
            ai,
            stats,
            target_stats,
            target_state,
            distance,
        );
        
        match decision {
            CombatDecision::Attack(attack_type) => {
                attack_events.send(AttackEvent {
                    attacker: entity,
                    weapon: entity,
                    attack_type,
                    direction,
                });
            }
            CombatDecision::Reposition(target_distance) => {
                let goal_pos = target_transform.translation - direction * target_distance;
                planner.set_goal(AiGoal::MoveTo { position: goal_pos });
            }
            CombatDecision::Defend => {
                planner.set_goal(AiGoal::Custom("block".into()));
            }
            CombatDecision::Wait => {}
        }
    }
}

#[derive(Debug)]
enum CombatDecision {
    Attack(AttackType),
    Reposition(f32),
    Defend,
    Wait,
}

fn evaluate_combat_options(
    ai: &CombatAI,
    stats: &CombatStats,
    target_stats: &CombatStats,
    target_state: &CombatState,
    distance: f32,
) -> CombatDecision {
    let health_ratio = stats.health / stats.max_health;
    let stamina_ratio = stats.stamina / stats.max_stamina;
    let target_health_ratio = target_stats.health / target_stats.max_health;
    
    if target_state.stance == CombatStance::Staggered && distance < 3.0 {
        return CombatDecision::Attack(AttackType::Heavy);
    }
    
    if health_ratio < 0.3 && ai.patience > 0.5 {
        return CombatDecision::Reposition(ai.preferred_range * 1.5);
    }
    
    if distance > ai.preferred_range * 1.2 {
        return CombatDecision::Reposition(ai.preferred_range);
    }
    
    if target_state.stance == CombatStance::Attacking && ai.patience > 0.7 {
        return CombatDecision::Defend;
    }
    
    if stamina_ratio > 0.3 && distance < ai.preferred_range {
        let attack_type = if ai.aggression > 0.7 && stamina_ratio > 0.6 {
            AttackType::Heavy
        } else {
            AttackType::Light
        };
        return CombatDecision::Attack(attack_type);
    }
    
    CombatDecision::Wait
}
}

Crafting System

Inventory and Items

Define the item and inventory structures:

#![allow(unused)]
fn main() {
#[derive(Component, Debug, Clone)]
pub struct Item {
    pub id: ItemId,
    pub name: String,
    pub item_type: ItemType,
    pub rarity: ItemRarity,
    pub stack_size: u32,
    pub max_stack: u32,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ItemId(pub u64);

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ItemType {
    Material,
    Consumable,
    Weapon,
    Armor,
    Accessory,
    Tool,
    QuestItem,
}

#[derive(Debug, Clone, Copy, PartialEq, Ord, PartialOrd, Eq)]
pub enum ItemRarity {
    Common,
    Uncommon,
    Rare,
    Epic,
    Legendary,
}

#[derive(Component, Debug)]
pub struct Inventory {
    pub slots: Vec<Option<InventorySlot>>,
    pub max_slots: usize,
    pub weight_limit: f32,
    pub current_weight: f32,
}

#[derive(Debug, Clone)]
pub struct InventorySlot {
    pub item: Item,
    pub quantity: u32,
}

impl Inventory {
    pub fn new(max_slots: usize, weight_limit: f32) -> Self {
        Self {
            slots: vec![None; max_slots],
            max_slots,
            weight_limit,
            current_weight: 0.0,
        }
    }
    
    pub fn add_item(&mut self, item: Item, quantity: u32) -> Result<(), InventoryError> {
        for slot in self.slots.iter_mut() {
            if let Some(ref mut existing) = slot {
                if existing.item.id == item.id && existing.quantity < item.max_stack {
                    let space = item.max_stack - existing.quantity;
                    let add = quantity.min(space);
                    existing.quantity += add;
                    if add == quantity {
                        return Ok(());
                    }
                }
            }
        }
        
        for slot in self.slots.iter_mut() {
            if slot.is_none() {
                *slot = Some(InventorySlot {
                    item: item.clone(),
                    quantity: quantity.min(item.max_stack),
                });
                return Ok(());
            }
        }
        
        Err(InventoryError::Full)
    }
    
    pub fn remove_item(&mut self, item_id: ItemId, quantity: u32) -> Result<u32, InventoryError> {
        let mut remaining = quantity;
        
        for slot in self.slots.iter_mut() {
            if remaining == 0 {
                break;
            }
            
            if let Some(ref mut existing) = slot {
                if existing.item.id == item_id {
                    let remove = remaining.min(existing.quantity);
                    existing.quantity -= remove;
                    remaining -= remove;
                    
                    if existing.quantity == 0 {
                        *slot = None;
                    }
                }
            }
        }
        
        if remaining > 0 {
            Err(InventoryError::InsufficientItems)
        } else {
            Ok(quantity)
        }
    }
    
    pub fn count_item(&self, item_id: ItemId) -> u32 {
        self.slots
            .iter()
            .filter_map(|s| s.as_ref())
            .filter(|s| s.item.id == item_id)
            .map(|s| s.quantity)
            .sum()
    }
}

#[derive(Debug)]
pub enum InventoryError {
    Full,
    InsufficientItems,
    WeightExceeded,
}
}

Recipe System

Define recipes and crafting requirements:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct Recipe {
    pub id: RecipeId,
    pub name: String,
    pub ingredients: Vec<RecipeIngredient>,
    pub outputs: Vec<RecipeOutput>,
    pub crafting_time: f32,
    pub required_station: Option<CraftingStation>,
    pub required_skill: Option<(SkillType, u32)>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct RecipeId(pub u64);

#[derive(Debug, Clone)]
pub struct RecipeIngredient {
    pub item_id: ItemId,
    pub quantity: u32,
    pub consumed: bool,
}

#[derive(Debug, Clone)]
pub struct RecipeOutput {
    pub item_id: ItemId,
    pub base_quantity: u32,
    pub quality_scaling: bool,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum CraftingStation {
    Workbench,
    Forge,
    Alchemy,
    Enchanting,
    Cooking,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum SkillType {
    Smithing,
    Alchemy,
    Enchanting,
    Cooking,
    Woodworking,
}

#[derive(Resource)]
pub struct RecipeRegistry {
    recipes: HashMap<RecipeId, Recipe>,
    by_station: HashMap<Option<CraftingStation>, Vec<RecipeId>>,
    by_output: HashMap<ItemId, Vec<RecipeId>>,
}

impl RecipeRegistry {
    pub fn new() -> Self {
        Self {
            recipes: HashMap::new(),
            by_station: HashMap::new(),
            by_output: HashMap::new(),
        }
    }
    
    pub fn register(&mut self, recipe: Recipe) {
        let id = recipe.id;
        
        self.by_station
            .entry(recipe.required_station)
            .or_default()
            .push(id);
        
        for output in &recipe.outputs {
            self.by_output
                .entry(output.item_id)
                .or_default()
                .push(id);
        }
        
        self.recipes.insert(id, recipe);
    }
    
    pub fn get(&self, id: RecipeId) -> Option<&Recipe> {
        self.recipes.get(&id)
    }
    
    pub fn available_at_station(&self, station: Option<CraftingStation>) -> &[RecipeId] {
        self.by_station.get(&station).map(|v| v.as_slice()).unwrap_or(&[])
    }
    
    pub fn recipes_for_item(&self, item_id: ItemId) -> &[RecipeId] {
        self.by_output.get(&item_id).map(|v| v.as_slice()).unwrap_or(&[])
    }
}
}

Crafting Execution

Process crafting with quality calculations:

#![allow(unused)]
fn main() {
#[derive(Debug)]
pub struct CraftRequest {
    pub crafter: Entity,
    pub recipe_id: RecipeId,
    pub station: Option<Entity>,
}

#[derive(Debug)]
pub struct CraftResult {
    pub success: bool,
    pub items: Vec<(ItemId, u32, ItemRarity)>,
    pub experience: u32,
}

pub fn crafting_system(
    mut craft_requests: EventReader<CraftRequest>,
    mut craft_results: EventWriter<CraftResult>,
    registry: Res<RecipeRegistry>,
    mut crafter_query: Query<(&mut Inventory, Option<&CrafterSkills>)>,
    station_query: Query<&CraftingStationComponent>,
    item_registry: Res<ItemRegistry>,
) {
    for request in craft_requests.iter() {
        let Some(recipe) = registry.get(request.recipe_id) else {
            continue;
        };
        
        let Ok((mut inventory, skills)) = crafter_query.get_mut(request.crafter) else {
            continue;
        };
        
        if let Some(station_entity) = request.station {
            if let Ok(station) = station_query.get(station_entity) {
                if Some(station.station_type) != recipe.required_station {
                    continue;
                }
            }
        } else if recipe.required_station.is_some() {
            continue;
        }
        
        if !can_craft(&inventory, recipe) {
            continue;
        }
        
        if let Some((skill_type, level)) = recipe.required_skill {
            let crafter_level = skills
                .map(|s| s.get_level(skill_type))
                .unwrap_or(0);
            if crafter_level < level {
                continue;
            }
        }
        
        for ingredient in &recipe.ingredients {
            if ingredient.consumed {
                let _ = inventory.remove_item(ingredient.item_id, ingredient.quantity);
            }
        }
        
        let quality = calculate_craft_quality(skills, recipe);
        let rarity = quality_to_rarity(quality);
        
        let mut crafted_items = Vec::new();
        for output in &recipe.outputs {
            let quantity = if output.quality_scaling {
                (output.base_quantity as f32 * (1.0 + quality * 0.5)) as u32
            } else {
                output.base_quantity
            };
            
            if let Some(base_item) = item_registry.get(output.item_id) {
                let mut item = base_item.clone();
                item.rarity = rarity;
                let _ = inventory.add_item(item, quantity);
                crafted_items.push((output.item_id, quantity, rarity));
            }
        }
        
        craft_results.send(CraftResult {
            success: true,
            items: crafted_items,
            experience: calculate_craft_xp(recipe, quality),
        });
    }
}

fn can_craft(inventory: &Inventory, recipe: &Recipe) -> bool {
    recipe.ingredients.iter().all(|ing| {
        inventory.count_item(ing.item_id) >= ing.quantity
    })
}

fn calculate_craft_quality(skills: Option<&CrafterSkills>, recipe: &Recipe) -> f32 {
    let base_quality = 0.5;
    
    let skill_bonus = if let (Some(skills), Some((skill_type, required))) = (skills, recipe.required_skill) {
        let level = skills.get_level(skill_type) as f32;
        let excess = (level - required as f32).max(0.0);
        excess * 0.05
    } else {
        0.0
    };
    
    let random_factor = rand::random::<f32>() * 0.2;
    
    (base_quality + skill_bonus + random_factor).clamp(0.0, 1.0)
}

fn quality_to_rarity(quality: f32) -> ItemRarity {
    match quality {
        q if q >= 0.95 => ItemRarity::Legendary,
        q if q >= 0.8 => ItemRarity::Epic,
        q if q >= 0.6 => ItemRarity::Rare,
        q if q >= 0.4 => ItemRarity::Uncommon,
        _ => ItemRarity::Common,
    }
}
}

AI-Assisted Crafting

Use AI to suggest recipes and optimize crafting:

#![allow(unused)]
fn main() {
use astraweave_llm::prelude::*;

pub struct CraftingAdvisor {
    llm: LlmClient,
}

impl CraftingAdvisor {
    pub async fn suggest_recipes(
        &self,
        inventory: &Inventory,
        goal: &str,
        registry: &RecipeRegistry,
    ) -> Vec<RecipeSuggestion> {
        let available_items: Vec<_> = inventory.slots
            .iter()
            .filter_map(|s| s.as_ref())
            .map(|s| format!("{} x{}", s.item.name, s.quantity))
            .collect();
        
        let prompt = format!(
            r#"Given these materials: {}
            
Player goal: {}

Suggest the best crafting recipes to achieve this goal.
Return as JSON array of recipe suggestions."#,
            available_items.join(", "),
            goal
        );
        
        let response = self.llm.complete(&prompt).await;
        parse_suggestions(&response, registry)
    }
    
    pub async fn optimize_craft_order(
        &self,
        target_item: ItemId,
        inventory: &Inventory,
        registry: &RecipeRegistry,
    ) -> Vec<RecipeId> {
        let mut order = Vec::new();
        let mut simulated_inventory = inventory.clone();
        
        self.build_craft_tree(target_item, &mut simulated_inventory, registry, &mut order);
        
        order
    }
    
    fn build_craft_tree(
        &self,
        target: ItemId,
        inventory: &mut Inventory,
        registry: &RecipeRegistry,
        order: &mut Vec<RecipeId>,
    ) {
        let recipes = registry.recipes_for_item(target);
        
        for &recipe_id in recipes {
            if let Some(recipe) = registry.get(recipe_id) {
                let mut can_craft = true;
                
                for ingredient in &recipe.ingredients {
                    let have = inventory.count_item(ingredient.item_id);
                    if have < ingredient.quantity {
                        self.build_craft_tree(
                            ingredient.item_id,
                            inventory,
                            registry,
                            order,
                        );
                        
                        if inventory.count_item(ingredient.item_id) < ingredient.quantity {
                            can_craft = false;
                            break;
                        }
                    }
                }
                
                if can_craft {
                    order.push(recipe_id);
                    return;
                }
            }
        }
    }
}

#[derive(Debug)]
pub struct RecipeSuggestion {
    pub recipe_id: RecipeId,
    pub reason: String,
    pub priority: u32,
}
}

Combat-Crafting Integration

Weapon Modification

Allow runtime weapon customization:

#![allow(unused)]
fn main() {
#[derive(Component, Debug)]
pub struct ModifiableWeapon {
    pub base: WeaponStats,
    pub modifications: Vec<WeaponMod>,
    pub max_mods: usize,
}

#[derive(Debug, Clone)]
pub struct WeaponMod {
    pub mod_type: WeaponModType,
    pub value: f32,
    pub item_source: ItemId,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum WeaponModType {
    DamageBonus,
    ElementalDamage(DamageType),
    AttackSpeed,
    CriticalChance,
    CriticalDamage,
    LifeSteal,
    PoiseDamage,
}

impl ModifiableWeapon {
    pub fn calculate_stats(&self) -> WeaponStats {
        let mut stats = self.base.clone();
        
        for modification in &self.modifications {
            match modification.mod_type {
                WeaponModType::DamageBonus => {
                    stats.base_damage *= 1.0 + modification.value;
                }
                WeaponModType::AttackSpeed => {
                    stats.attack_speed *= 1.0 + modification.value;
                }
                WeaponModType::PoiseDamage => {
                    stats.poise_damage *= 1.0 + modification.value;
                }
                _ => {}
            }
        }
        
        stats
    }
    
    pub fn add_mod(&mut self, modification: WeaponMod) -> Result<(), &'static str> {
        if self.modifications.len() >= self.max_mods {
            return Err("Maximum modifications reached");
        }
        
        let same_type_count = self.modifications
            .iter()
            .filter(|m| std::mem::discriminant(&m.mod_type) == std::mem::discriminant(&modification.mod_type))
            .count();
        
        if same_type_count >= 2 {
            return Err("Cannot stack more than 2 of the same mod type");
        }
        
        self.modifications.push(modification);
        Ok(())
    }
}

pub fn apply_weapon_mods_system(
    mut weapons: Query<(&ModifiableWeapon, &mut WeaponStats), Changed<ModifiableWeapon>>,
) {
    for (modifiable, mut stats) in weapons.iter_mut() {
        *stats = modifiable.calculate_stats();
    }
}
}

Combat Loot System

Generate loot based on combat performance:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct LootTable {
    pub entries: Vec<LootEntry>,
    pub guaranteed: Vec<ItemId>,
}

#[derive(Debug, Clone)]
pub struct LootEntry {
    pub item_id: ItemId,
    pub weight: f32,
    pub min_quantity: u32,
    pub max_quantity: u32,
    pub min_rarity: ItemRarity,
}

pub fn combat_loot_system(
    mut death_events: EventReader<EntityDeathEvent>,
    loot_query: Query<&LootTable>,
    combat_log: Res<CombatLog>,
    mut loot_events: EventWriter<LootDropEvent>,
) {
    for event in death_events.iter() {
        let Ok(loot_table) = loot_query.get(event.entity) else {
            continue;
        };
        
        let performance = combat_log.get_performance(event.killer, event.entity);
        let luck_bonus = calculate_luck_bonus(&performance);
        
        let mut drops = Vec::new();
        
        for item_id in &loot_table.guaranteed {
            drops.push((*item_id, 1, ItemRarity::Common));
        }
        
        let roll_count = 1 + (luck_bonus * 2.0) as usize;
        for _ in 0..roll_count {
            if let Some(entry) = roll_loot(loot_table, luck_bonus) {
                let quantity = rand::thread_rng()
                    .gen_range(entry.min_quantity..=entry.max_quantity);
                let rarity = roll_rarity(entry.min_rarity, luck_bonus);
                drops.push((entry.item_id, quantity, rarity));
            }
        }
        
        loot_events.send(LootDropEvent {
            position: event.position,
            drops,
        });
    }
}

fn calculate_luck_bonus(performance: &CombatPerformance) -> f32 {
    let mut bonus = 0.0;
    
    if performance.no_damage_taken {
        bonus += 0.3;
    }
    
    if performance.time_to_kill < 30.0 {
        bonus += 0.2;
    }
    
    if performance.parries > 0 {
        bonus += performance.parries as f32 * 0.05;
    }
    
    bonus.min(1.0)
}
}

Best Practices

1. **Balance Stamina Economy**: Ensure attacks have meaningful stamina costs to create decision points
2. **Poise Windows**: Use stagger states to create openings for both players and AI
3. **Readable Attacks**: Give clear visual tells before powerful attacks
4. **Combo Depth**: Reward skill with combo multipliers but keep basic attacks viable

- **Damage Sponges**: Avoid enemies that just have more health; vary resistances and mechanics
- **Inventory Overflow**: Always handle full inventory gracefully
- **Recipe Bloat**: Curate recipes to avoid overwhelming players
- **Mod Stacking**: Prevent multiplicative mod abuse

Related Documentation

• AI Companions - Combat companion behaviors
• Adaptive Bosses - Advanced boss combat AI
• Physics Integration - Combat physics
• Configuration Reference - Combat tuning parameters

Dialogue Systems

AstraWeave’s dialogue system combines traditional branching dialogue with LLM-powered dynamic conversations, enabling NPCs to engage in contextual, personality-driven interactions while maintaining narrative coherence.

Architecture Overview

graph TB
    subgraph Input["Player Input"]
        PI[Player Choice] --> DM
        TI[Text Input] --> NLP[NLP Parser]
        NLP --> DM
    end
    
    subgraph DialogueManager["Dialogue Manager"]
        DM[Dialogue Controller] --> SC[Script Check]
        SC -->|Scripted| SN[Script Node]
        SC -->|Dynamic| LLM[LLM Handler]
        
        SN --> VAL[Validator]
        LLM --> VAL
        VAL --> OUT[Output]
    end
    
    subgraph Context["Context System"]
        MEM[Memory] --> DM
        REL[Relationships] --> DM
        QS[Quest State] --> DM
        WS[World State] --> DM
    end
    
    OUT --> UI[Dialogue UI]
    OUT --> AUD[Voice/Audio]
    OUT --> EVT[Event Triggers]

Core Components

Dialogue Node System

Define structured dialogue with branching paths:

#![allow(unused)]
fn main() {
use astraweave_ecs::prelude::*;
use std::collections::HashMap;

#[derive(Debug, Clone)]
pub struct DialogueTree {
    pub id: DialogueId,
    pub nodes: HashMap<NodeId, DialogueNode>,
    pub entry_node: NodeId,
    pub metadata: DialogueMetadata,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct DialogueId(pub u64);

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NodeId(pub u32);

#[derive(Debug, Clone)]
pub struct DialogueNode {
    pub id: NodeId,
    pub speaker: SpeakerId,
    pub content: DialogueContent,
    pub responses: Vec<DialogueResponse>,
    pub conditions: Vec<DialogueCondition>,
    pub effects: Vec<DialogueEffect>,
}

#[derive(Debug, Clone)]
pub enum DialogueContent {
    Text(String),
    Localized { key: String, fallback: String },
    Dynamic { prompt_template: String },
    Voice { text: String, audio_id: String },
}

#[derive(Debug, Clone)]
pub struct DialogueResponse {
    pub text: String,
    pub next_node: Option<NodeId>,
    pub conditions: Vec<DialogueCondition>,
    pub effects: Vec<DialogueEffect>,
    pub tone: ResponseTone,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ResponseTone {
    Neutral,
    Friendly,
    Hostile,
    Curious,
    Sarcastic,
    Romantic,
}

#[derive(Debug, Clone)]
pub enum DialogueCondition {
    QuestState { quest_id: u64, state: String },
    RelationshipMin { npc_id: u64, value: i32 },
    HasItem { item_id: u64, quantity: u32 },
    PlayerStat { stat: String, min: i32 },
    Flag { name: String, value: bool },
    TimeOfDay { start: u32, end: u32 },
    Custom { script: String },
}

#[derive(Debug, Clone)]
pub enum DialogueEffect {
    SetFlag { name: String, value: bool },
    ModifyRelationship { npc_id: u64, delta: i32 },
    GiveItem { item_id: u64, quantity: u32 },
    TakeItem { item_id: u64, quantity: u32 },
    StartQuest { quest_id: u64 },
    AdvanceQuest { quest_id: u64, stage: String },
    TriggerEvent { event_name: String },
    PlayAnimation { animation: String },
}
}

Dialogue Controller

Manage dialogue state and flow:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct DialogueController {
    pub active_dialogue: Option<ActiveDialogue>,
    pub history: Vec<DialogueHistoryEntry>,
    pub context: DialogueContext,
}

#[derive(Debug)]
pub struct ActiveDialogue {
    pub tree: DialogueTree,
    pub current_node: NodeId,
    pub participants: Vec<Entity>,
    pub started_at: f64,
}

#[derive(Debug, Clone)]
pub struct DialogueHistoryEntry {
    pub node_id: NodeId,
    pub speaker: SpeakerId,
    pub text: String,
    pub timestamp: f64,
    pub response_chosen: Option<usize>,
}

#[derive(Debug, Default)]
pub struct DialogueContext {
    pub player_name: String,
    pub location: String,
    pub time_of_day: String,
    pub recent_events: Vec<String>,
    pub custom_vars: HashMap<String, String>,
}

impl DialogueController {
    pub fn start_dialogue(&mut self, tree: DialogueTree, participants: Vec<Entity>, time: f64) {
        self.active_dialogue = Some(ActiveDialogue {
            current_node: tree.entry_node,
            tree,
            participants,
            started_at: time,
        });
    }
    
    pub fn get_current_node(&self) -> Option<&DialogueNode> {
        self.active_dialogue.as_ref().and_then(|active| {
            active.tree.nodes.get(&active.current_node)
        })
    }
    
    pub fn select_response(&mut self, index: usize, time: f64) -> Option<Vec<DialogueEffect>> {
        let active = self.active_dialogue.as_mut()?;
        let node = active.tree.nodes.get(&active.current_node)?;
        let response = node.responses.get(index)?;
        
        self.history.push(DialogueHistoryEntry {
            node_id: active.current_node,
            speaker: node.speaker,
            text: match &node.content {
                DialogueContent::Text(t) => t.clone(),
                DialogueContent::Localized { fallback, .. } => fallback.clone(),
                DialogueContent::Dynamic { .. } => "[Dynamic]".into(),
                DialogueContent::Voice { text, .. } => text.clone(),
            },
            timestamp: time,
            response_chosen: Some(index),
        });
        
        if let Some(next) = response.next_node {
            active.current_node = next;
            Some(response.effects.clone())
        } else {
            let effects = response.effects.clone();
            self.active_dialogue = None;
            Some(effects)
        }
    }
    
    pub fn end_dialogue(&mut self) {
        self.active_dialogue = None;
    }
}
}

Dialogue System

Process dialogue logic each frame:

#![allow(unused)]
fn main() {
pub fn dialogue_system(
    mut dialogue_query: Query<&mut DialogueController>,
    mut effect_events: EventWriter<DialogueEffectEvent>,
    conditions: Res<ConditionEvaluator>,
    time: Res<Time>,
) {
    for mut controller in dialogue_query.iter_mut() {
        let Some(active) = &controller.active_dialogue else {
            continue;
        };
        
        let Some(node) = active.tree.nodes.get(&active.current_node) else {
            controller.end_dialogue();
            continue;
        };
        
        if !conditions.evaluate_all(&node.conditions) {
            if let Some(fallback) = find_fallback_node(&active.tree, &conditions) {
                if let Some(active) = controller.active_dialogue.as_mut() {
                    active.current_node = fallback;
                }
            } else {
                controller.end_dialogue();
            }
            continue;
        }
        
        for effect in &node.effects {
            effect_events.send(DialogueEffectEvent {
                effect: effect.clone(),
                timestamp: time.elapsed_seconds_f64(),
            });
        }
    }
}

pub fn dialogue_effect_system(
    mut effect_events: EventReader<DialogueEffectEvent>,
    mut quest_events: EventWriter<QuestEvent>,
    mut inventory_events: EventWriter<InventoryEvent>,
    mut relationship_events: EventWriter<RelationshipEvent>,
    mut flags: ResMut<GameFlags>,
) {
    for event in effect_events.iter() {
        match &event.effect {
            DialogueEffect::SetFlag { name, value } => {
                flags.set(name.clone(), *value);
            }
            DialogueEffect::ModifyRelationship { npc_id, delta } => {
                relationship_events.send(RelationshipEvent::Modify {
                    npc_id: *npc_id,
                    delta: *delta,
                });
            }
            DialogueEffect::GiveItem { item_id, quantity } => {
                inventory_events.send(InventoryEvent::Add {
                    item_id: *item_id,
                    quantity: *quantity,
                });
            }
            DialogueEffect::StartQuest { quest_id } => {
                quest_events.send(QuestEvent::Start { quest_id: *quest_id });
            }
            DialogueEffect::AdvanceQuest { quest_id, stage } => {
                quest_events.send(QuestEvent::Advance {
                    quest_id: *quest_id,
                    stage: stage.clone(),
                });
            }
            _ => {}
        }
    }
}
}

LLM-Powered Dialogue

Dynamic Conversation Handler

Enable free-form AI conversations:

#![allow(unused)]
fn main() {
use astraweave_llm::prelude::*;

#[derive(Component)]
pub struct DynamicDialogue {
    pub npc_persona: NpcPersona,
    pub conversation_history: Vec<ConversationTurn>,
    pub memory_context: Vec<String>,
    pub allowed_topics: Vec<String>,
    pub forbidden_topics: Vec<String>,
    pub max_history: usize,
}

#[derive(Debug, Clone)]
pub struct NpcPersona {
    pub name: String,
    pub personality: String,
    pub background: String,
    pub speaking_style: String,
    pub knowledge: Vec<String>,
    pub goals: Vec<String>,
    pub relationships: HashMap<String, String>,
}

#[derive(Debug, Clone)]
pub struct ConversationTurn {
    pub role: ConversationRole,
    pub content: String,
    pub timestamp: f64,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum ConversationRole {
    Player,
    Npc,
    System,
}

impl DynamicDialogue {
    pub fn new(persona: NpcPersona) -> Self {
        Self {
            npc_persona: persona,
            conversation_history: Vec::new(),
            memory_context: Vec::new(),
            allowed_topics: Vec::new(),
            forbidden_topics: Vec::new(),
            max_history: 20,
        }
    }
    
    pub fn add_turn(&mut self, role: ConversationRole, content: String, time: f64) {
        self.conversation_history.push(ConversationTurn {
            role,
            content,
            timestamp: time,
        });
        
        if self.conversation_history.len() > self.max_history {
            self.conversation_history.remove(0);
        }
    }
    
    pub fn build_prompt(&self, player_input: &str, context: &DialogueContext) -> String {
        let mut prompt = format!(
            r#"You are {}, an NPC in a fantasy game.

Personality: {}
Background: {}
Speaking style: {}

Current situation:
- Location: {}
- Time: {}
- Recent events: {}

Knowledge you have:
{}

Your goals:
{}

"#,
            self.npc_persona.name,
            self.npc_persona.personality,
            self.npc_persona.background,
            self.npc_persona.speaking_style,
            context.location,
            context.time_of_day,
            context.recent_events.join(", "),
            self.npc_persona.knowledge.join("\n- "),
            self.npc_persona.goals.join("\n- "),
        );
        
        if !self.memory_context.is_empty() {
            prompt.push_str("Relevant memories:\n");
            for memory in &self.memory_context {
                prompt.push_str(&format!("- {}\n", memory));
            }
            prompt.push('\n');
        }
        
        prompt.push_str("Conversation so far:\n");
        for turn in &self.conversation_history {
            let speaker = match turn.role {
                ConversationRole::Player => &context.player_name,
                ConversationRole::Npc => &self.npc_persona.name,
                ConversationRole::System => "[System]",
            };
            prompt.push_str(&format!("{}: {}\n", speaker, turn.content));
        }
        
        prompt.push_str(&format!("\n{}: {}\n", context.player_name, player_input));
        prompt.push_str(&format!("\nRespond as {}. Stay in character. Keep response under 100 words.", 
            self.npc_persona.name));
        
        prompt
    }
}
}

LLM Dialogue System

Process dynamic dialogue requests:

#![allow(unused)]
fn main() {
pub struct LlmDialogueSystem {
    llm: LlmClient,
    validator: DialogueValidator,
}

impl LlmDialogueSystem {
    pub async fn generate_response(
        &self,
        dialogue: &mut DynamicDialogue,
        player_input: &str,
        context: &DialogueContext,
    ) -> Result<String, DialogueError> {
        dialogue.add_turn(
            ConversationRole::Player, 
            player_input.to_string(), 
            0.0
        );
        
        let prompt = dialogue.build_prompt(player_input, context);
        
        let response = self.llm.complete(&prompt).await
            .map_err(|e| DialogueError::LlmError(e.to_string()))?;
        
        let validated = self.validator.validate_response(
            &response,
            &dialogue.forbidden_topics,
            &dialogue.npc_persona,
        )?;
        
        dialogue.add_turn(ConversationRole::Npc, validated.clone(), 0.0);
        
        Ok(validated)
    }
}

pub struct DialogueValidator {
    blocked_patterns: Vec<regex::Regex>,
}

impl DialogueValidator {
    pub fn validate_response(
        &self,
        response: &str,
        forbidden_topics: &[String],
        persona: &NpcPersona,
    ) -> Result<String, DialogueError> {
        if response.len() > 500 {
            return Err(DialogueError::ResponseTooLong);
        }
        
        for pattern in &self.blocked_patterns {
            if pattern.is_match(response) {
                return Err(DialogueError::BlockedContent);
            }
        }
        
        for topic in forbidden_topics {
            if response.to_lowercase().contains(&topic.to_lowercase()) {
                return Err(DialogueError::ForbiddenTopic(topic.clone()));
            }
        }
        
        Ok(response.trim().to_string())
    }
}

#[derive(Debug)]
pub enum DialogueError {
    LlmError(String),
    ResponseTooLong,
    BlockedContent,
    ForbiddenTopic(String),
    ValidationFailed,
}
}

Tool-Based Dialogue Actions

Allow NPCs to take actions during conversation:

#![allow(unused)]
fn main() {
use astraweave_ai::tools::*;

pub fn create_dialogue_tools() -> Vec<AiTool> {
    vec![
        AiTool {
            name: "give_item".into(),
            description: "Give an item to the player as a gift or quest reward".into(),
            parameters: json!({
                "type": "object",
                "properties": {
                    "item_name": { "type": "string" },
                    "quantity": { "type": "integer", "minimum": 1 },
                    "reason": { "type": "string" }
                },
                "required": ["item_name", "quantity"]
            }),
            handler: Box::new(|params| {
                let item = params["item_name"].as_str().unwrap();
                let qty = params["quantity"].as_i64().unwrap() as u32;
                ToolResult::Success(json!({
                    "action": "give_item",
                    "item": item,
                    "quantity": qty
                }))
            }),
        },
        AiTool {
            name: "share_rumor".into(),
            description: "Share a rumor or piece of information with the player".into(),
            parameters: json!({
                "type": "object",
                "properties": {
                    "rumor_id": { "type": "string" },
                    "importance": { "type": "string", "enum": ["minor", "major", "critical"] }
                },
                "required": ["rumor_id"]
            }),
            handler: Box::new(|params| {
                let rumor = params["rumor_id"].as_str().unwrap();
                ToolResult::Success(json!({
                    "action": "share_rumor",
                    "rumor": rumor,
                    "unlocked": true
                }))
            }),
        },
        AiTool {
            name: "offer_quest".into(),
            description: "Offer a quest to the player".into(),
            parameters: json!({
                "type": "object",
                "properties": {
                    "quest_id": { "type": "string" },
                    "urgency": { "type": "string", "enum": ["low", "medium", "high"] }
                },
                "required": ["quest_id"]
            }),
            handler: Box::new(|params| {
                let quest = params["quest_id"].as_str().unwrap();
                ToolResult::Success(json!({
                    "action": "offer_quest",
                    "quest": quest
                }))
            }),
        },
        AiTool {
            name: "express_emotion".into(),
            description: "Show an emotional reaction through animation".into(),
            parameters: json!({
                "type": "object",
                "properties": {
                    "emotion": { 
                        "type": "string", 
                        "enum": ["happy", "sad", "angry", "surprised", "fearful", "disgusted"]
                    },
                    "intensity": { "type": "number", "minimum": 0, "maximum": 1 }
                },
                "required": ["emotion"]
            }),
            handler: Box::new(|params| {
                let emotion = params["emotion"].as_str().unwrap();
                let intensity = params.get("intensity")
                    .and_then(|v| v.as_f64())
                    .unwrap_or(0.5);
                ToolResult::Success(json!({
                    "action": "express_emotion",
                    "emotion": emotion,
                    "intensity": intensity
                }))
            }),
        },
    ]
}
}

Relationship System

Relationship Tracking

Track player-NPC relationships:

#![allow(unused)]
fn main() {
#[derive(Component)]
pub struct RelationshipTracker {
    pub relationships: HashMap<Entity, Relationship>,
}

#[derive(Debug, Clone)]
pub struct Relationship {
    pub affinity: i32,
    pub trust: i32,
    pub fear: i32,
    pub respect: i32,
    pub romantic_interest: i32,
    pub interaction_count: u32,
    pub last_interaction: f64,
    pub memories: Vec<RelationshipMemory>,
}

#[derive(Debug, Clone)]
pub struct RelationshipMemory {
    pub event: String,
    pub impact: i32,
    pub timestamp: f64,
}

impl Relationship {
    pub fn new() -> Self {
        Self {
            affinity: 0,
            trust: 0,
            fear: 0,
            respect: 0,
            romantic_interest: 0,
            interaction_count: 0,
            last_interaction: 0.0,
            memories: Vec::new(),
        }
    }
    
    pub fn get_disposition(&self) -> Disposition {
        let total = self.affinity + self.trust + self.respect - self.fear;
        match total {
            t if t >= 50 => Disposition::Friendly,
            t if t >= 20 => Disposition::Warm,
            t if t >= -20 => Disposition::Neutral,
            t if t >= -50 => Disposition::Cool,
            _ => Disposition::Hostile,
        }
    }
    
    pub fn modify(&mut self, event: &str, changes: RelationshipChanges, time: f64) {
        self.affinity = (self.affinity + changes.affinity).clamp(-100, 100);
        self.trust = (self.trust + changes.trust).clamp(-100, 100);
        self.fear = (self.fear + changes.fear).clamp(0, 100);
        self.respect = (self.respect + changes.respect).clamp(-100, 100);
        self.romantic_interest = (self.romantic_interest + changes.romantic).clamp(0, 100);
        
        self.interaction_count += 1;
        self.last_interaction = time;
        
        let impact = changes.affinity + changes.trust + changes.respect;
        if impact.abs() >= 5 {
            self.memories.push(RelationshipMemory {
                event: event.to_string(),
                impact,
                timestamp: time,
            });
            
            if self.memories.len() > 20 {
                self.memories.sort_by(|a, b| b.impact.abs().cmp(&a.impact.abs()));
                self.memories.truncate(10);
            }
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Disposition {
    Hostile,
    Cool,
    Neutral,
    Warm,
    Friendly,
}

#[derive(Debug, Clone, Default)]
pub struct RelationshipChanges {
    pub affinity: i32,
    pub trust: i32,
    pub fear: i32,
    pub respect: i32,
    pub romantic: i32,
}
}

Relationship-Aware Dialogue

Modify dialogue based on relationship:

#![allow(unused)]
fn main() {
pub fn relationship_dialogue_modifier(
    dialogue: &mut DynamicDialogue,
    relationship: &Relationship,
) {
    let disposition = relationship.get_disposition();
    
    let style_modifier = match disposition {
        Disposition::Hostile => "Be cold and dismissive. Keep responses short. Show distrust.",
        Disposition::Cool => "Be polite but distant. Don't volunteer extra information.",
        Disposition::Neutral => "Be professional and helpful when asked.",
        Disposition::Warm => "Be friendly and open. Share more freely.",
        Disposition::Friendly => "Be warm and trusting. Treat them as a close friend.",
    };
    
    dialogue.npc_persona.speaking_style.push_str(&format!("\n{}", style_modifier));
    
    for memory in &relationship.memories {
        dialogue.memory_context.push(format!(
            "{} (impact: {:+})",
            memory.event,
            memory.impact
        ));
    }
}
}

Voice Integration

Text-to-Speech Support

Generate voice output for dialogue:

#![allow(unused)]
fn main() {
use astraweave_audio::prelude::*;

#[derive(Component)]
pub struct VoiceDialogue {
    pub voice_id: String,
    pub pitch: f32,
    pub speed: f32,
    pub volume: f32,
}

pub struct VoiceSynthesizer {
    tts_endpoint: String,
}

impl VoiceSynthesizer {
    pub async fn synthesize(
        &self,
        text: &str,
        voice: &VoiceDialogue,
    ) -> Result<AudioBuffer, VoiceError> {
        let request = VoiceSynthRequest {
            text: text.to_string(),
            voice_id: voice.voice_id.clone(),
            pitch: voice.pitch,
            speed: voice.speed,
        };
        
        let response = reqwest::Client::new()
            .post(&self.tts_endpoint)
            .json(&request)
            .send()
            .await?
            .bytes()
            .await?;
        
        Ok(AudioBuffer::from_bytes(&response))
    }
}

pub fn dialogue_voice_system(
    dialogue_query: Query<(&DialogueController, &VoiceDialogue)>,
    synthesizer: Res<VoiceSynthesizer>,
    mut audio_events: EventWriter<PlayAudioEvent>,
    runtime: Res<TokioRuntime>,
) {
    for (controller, voice) in dialogue_query.iter() {
        if let Some(node) = controller.get_current_node() {
            if let DialogueContent::Voice { text, audio_id } = &node.content {
                if let Some(cached) = try_get_cached_audio(audio_id) {
                    audio_events.send(PlayAudioEvent {
                        buffer: cached,
                        volume: voice.volume,
                        spatial: false,
                    });
                } else {
                    let text = text.clone();
                    let voice = voice.clone();
                    runtime.spawn(async move {
                        if let Ok(buffer) = synthesizer.synthesize(&text, &voice).await {
                            cache_audio(audio_id, buffer);
                        }
                    });
                }
            }
        }
    }
}
}

Dialogue UI

Dialogue Display Component

#![allow(unused)]
fn main() {
use astraweave_ui::prelude::*;

#[derive(Component)]
pub struct DialogueUI {
    pub visible: bool,
    pub speaker_name: String,
    pub current_text: String,
    pub responses: Vec<String>,
    pub selected_response: usize,
    pub text_progress: f32,
    pub chars_per_second: f32,
}

impl DialogueUI {
    pub fn show(&mut self, speaker: &str, text: &str, responses: Vec<String>) {
        self.visible = true;
        self.speaker_name = speaker.to_string();
        self.current_text = text.to_string();
        self.responses = responses;
        self.selected_response = 0;
        self.text_progress = 0.0;
    }
    
    pub fn get_visible_text(&self) -> &str {
        let char_count = (self.current_text.len() as f32 * self.text_progress) as usize;
        &self.current_text[..char_count.min(self.current_text.len())]
    }
    
    pub fn is_text_complete(&self) -> bool {
        self.text_progress >= 1.0
    }
    
    pub fn skip_to_end(&mut self) {
        self.text_progress = 1.0;
    }
}

pub fn dialogue_ui_system(
    mut ui_query: Query<&mut DialogueUI>,
    dialogue_query: Query<&DialogueController>,
    input: Res<Input>,
    time: Res<Time>,
    npc_query: Query<&NpcInfo>,
) {
    for (mut ui, controller) in ui_query.iter_mut().zip(dialogue_query.iter()) {
        if let Some(node) = controller.get_current_node() {
            let speaker_name = npc_query
                .get(node.speaker.0)
                .map(|n| n.name.clone())
                .unwrap_or_else(|_| "Unknown".to_string());
            
            let text = match &node.content {
                DialogueContent::Text(t) => t.clone(),
                DialogueContent::Localized { fallback, .. } => fallback.clone(),
                _ => String::new(),
            };
            
            let responses: Vec<String> = node.responses
                .iter()
                .map(|r| r.text.clone())
                .collect();
            
            if !ui.visible || ui.current_text != text {
                ui.show(&speaker_name, &text, responses);
            }
            
            if !ui.is_text_complete() {
                ui.text_progress += time.delta_seconds() * ui.chars_per_second 
                    / ui.current_text.len() as f32;
                ui.text_progress = ui.text_progress.min(1.0);
            }
            
            if input.just_pressed(KeyCode::Space) || input.just_pressed(MouseButton::Left) {
                if !ui.is_text_complete() {
                    ui.skip_to_end();
                }
            }
            
            if ui.is_text_complete() {
                if input.just_pressed(KeyCode::Up) {
                    ui.selected_response = ui.selected_response.saturating_sub(1);
                }
                if input.just_pressed(KeyCode::Down) {
                    ui.selected_response = (ui.selected_response + 1).min(ui.responses.len() - 1);
                }
            }
        } else {
            ui.visible = false;
        }
    }
}
}

Best Practices

1. **Blend Scripted and Dynamic**: Use scripted dialogue for critical story beats, dynamic for flavor
2. **Maintain Consistency**: Ensure LLM responses align with established NPC personality
3. **Respect Player Time**: Keep responses concise; players can ask for details
4. **Branch Meaningfully**: Only offer choices that have real consequences

- **Context Window Overflow**: Trim conversation history to prevent LLM context issues
- **Hallucination**: Validate LLM outputs against game state to prevent impossible claims
- **Tone Whiplash**: Ensure relationship state affects dialogue tone gradually
- **Dead Ends**: Always provide a way to exit or continue dialogue

Related Documentation

• AI Companions - Companion dialogue integration
• AI System Overview - LLM configuration
• Quest Systems - Dialogue-quest integration
• Audio Systems - Voice synthesis setup

Procedural Content Generation

AstraWeave’s PCG system combines traditional algorithmic generation with AI-driven content creation, enabling infinite variety while maintaining coherent, designer-guided output.

Architecture Overview

graph TB
    subgraph Input["Generation Input"]
        SEED[Seed/Parameters] --> GEN
        RULES[Design Rules] --> GEN
        CONTEXT[World Context] --> GEN
    end
    
    subgraph Generator["PCG Pipeline"]
        GEN[Generator Core] --> ALGO[Algorithmic Pass]
        ALGO --> AI[AI Enhancement]
        AI --> VAL[Validation]
        VAL --> POST[Post-Processing]
    end
    
    subgraph Output["Generated Content"]
        POST --> TERRAIN[Terrain]
        POST --> DUNGEONS[Dungeons]
        POST --> ITEMS[Items]
        POST --> QUESTS[Quests]
        POST --> NPCS[NPCs]
    end
    
    VAL -->|Reject| GEN

Core PCG Framework

Generator Trait

Define the common interface for all generators:

#![allow(unused)]
fn main() {
use astraweave_ecs::prelude::*;
use std::hash::{Hash, Hasher};

pub trait Generator<T> {
    fn generate(&self, params: &GenerationParams) -> GenerationResult<T>;
    fn validate(&self, output: &T, params: &GenerationParams) -> ValidationResult;
    fn seed_from_hash<H: Hash>(&self, hashable: H) -> u64;
}

#[derive(Debug, Clone)]
pub struct GenerationParams {
    pub seed: u64,
    pub difficulty: f32,
    pub density: f32,
    pub theme: String,
    pub constraints: Vec<GenerationConstraint>,
    pub context: GenerationContext,
}

#[derive(Debug, Clone)]
pub struct GenerationContext {
    pub world_position: Vec3,
    pub biome: String,
    pub player_level: u32,
    pub story_stage: String,
    pub nearby_content: Vec<String>,
}

#[derive(Debug, Clone)]
pub enum GenerationConstraint {
    MinSize(f32),
    MaxSize(f32),
    MustContain(String),
    MustNotContain(String),
    ConnectTo(Vec3),
    StyleMatch(String),
    Custom { name: String, value: String },
}

pub type GenerationResult<T> = Result<T, GenerationError>;

#[derive(Debug)]
pub enum GenerationError {
    InvalidParams(String),
    ConstraintViolation(String),
    MaxIterationsReached,
    ValidationFailed(String),
}

#[derive(Debug)]
pub enum ValidationResult {
    Valid,
    Invalid(String),
    NeedsAdjustment(Vec<String>),
}
}

Seeded Random Generator

Deterministic random number generation:

#![allow(unused)]
fn main() {
use rand::{Rng, SeedableRng};
use rand_chacha::ChaCha8Rng;

pub struct SeededRng {
    rng: ChaCha8Rng,
    initial_seed: u64,
}

impl SeededRng {
    pub fn new(seed: u64) -> Self {
        Self {
            rng: ChaCha8Rng::seed_from_u64(seed),
            initial_seed: seed,
        }
    }
    
    pub fn from_position(x: i32, y: i32, z: i32, world_seed: u64) -> Self {
        let position_hash = ((x as u64) << 42) ^ ((y as u64) << 21) ^ (z as u64);
        Self::new(world_seed ^ position_hash)
    }
    
    pub fn next_float(&mut self) -> f32 {
        self.rng.gen()
    }
    
    pub fn next_range(&mut self, min: i32, max: i32) -> i32 {
        self.rng.gen_range(min..=max)
    }
    
    pub fn next_float_range(&mut self, min: f32, max: f32) -> f32 {
        self.rng.gen_range(min..=max)
    }
    
    pub fn choose<T: Clone>(&mut self, options: &[T]) -> Option<T> {
        if options.is_empty() {
            None
        } else {
            let index = self.rng.gen_range(0..options.len());
            Some(options[index].clone())
        }
    }
    
    pub fn weighted_choose<T: Clone>(&mut self, options: &[(T, f32)]) -> Option<T> {
        let total_weight: f32 = options.iter().map(|(_, w)| w).sum();
        let mut roll = self.next_float() * total_weight;
        
        for (item, weight) in options {
            roll -= weight;
            if roll <= 0.0 {
                return Some(item.clone());
            }
        }
        
        options.last().map(|(item, _)| item.clone())
    }
    
    pub fn fork(&mut self) -> Self {
        Self::new(self.rng.gen())
    }
}
}

Terrain Generation

Heightmap Generator

Generate terrain heightmaps with noise:

#![allow(unused)]
fn main() {
use noise::{NoiseFn, Perlin, Fbm, MultiFractal};

pub struct TerrainGenerator {
    base_noise: Fbm<Perlin>,
    detail_noise: Perlin,
    erosion_passes: u32,
}

impl TerrainGenerator {
    pub fn new(seed: u64) -> Self {
        let mut fbm = Fbm::new(seed as u32);
        fbm.octaves = 6;
        fbm.frequency = 0.005;
        fbm.lacunarity = 2.0;
        fbm.persistence = 0.5;
        
        Self {
            base_noise: fbm,
            detail_noise: Perlin::new(seed as u32 + 1),
            erosion_passes: 50,
        }
    }
    
    pub fn generate_chunk(&self, chunk_x: i32, chunk_z: i32, size: usize) -> Heightmap {
        let mut heights = vec![vec![0.0f32; size]; size];
        
        for z in 0..size {
            for x in 0..size {
                let world_x = (chunk_x * size as i32 + x as i32) as f64;
                let world_z = (chunk_z * size as i32 + z as i32) as f64;
                
                let base = self.base_noise.get([world_x, world_z]) as f32;
                
                let detail = self.detail_noise.get([world_x * 0.1, world_z * 0.1]) as f32 * 0.1;
                
                heights[z][x] = (base + detail + 1.0) * 0.5 * 256.0;
            }
        }
        
        self.apply_erosion(&mut heights);
        
        Heightmap {
            data: heights,
            chunk_x,
            chunk_z,
            size,
        }
    }
    
    fn apply_erosion(&self, heights: &mut Vec<Vec<f32>>) {
        let size = heights.len();
        let mut water = vec![vec![0.0f32; size]; size];
        let mut sediment = vec![vec![0.0f32; size]; size];
        
        for _ in 0..self.erosion_passes {
            for z in 1..size - 1 {
                for x in 1..size - 1 {
                    let current = heights[z][x];
                    
                    let neighbors = [
                        (heights[z - 1][x], 0, -1),
                        (heights[z + 1][x], 0, 1),
                        (heights[z][x - 1], -1, 0),
                        (heights[z][x + 1], 1, 0),
                    ];
                    
                    if let Some((lowest, dx, dz)) = neighbors
                        .iter()
                        .filter(|(h, _, _)| *h < current)
                        .min_by(|a, b| a.0.partial_cmp(&b.0).unwrap())
                    {
                        let diff = current - lowest;
                        let transfer = diff * 0.1;
                        
                        heights[z][x] -= transfer * 0.5;
                        heights[(z as i32 + dz) as usize][(x as i32 + dx) as usize] += transfer * 0.3;
                    }
                }
            }
        }
    }
}

#[derive(Debug)]
pub struct Heightmap {
    pub data: Vec<Vec<f32>>,
    pub chunk_x: i32,
    pub chunk_z: i32,
    pub size: usize,
}

impl Heightmap {
    pub fn get_height(&self, x: usize, z: usize) -> f32 {
        self.data.get(z).and_then(|row| row.get(x)).copied().unwrap_or(0.0)
    }
    
    pub fn get_normal(&self, x: usize, z: usize) -> Vec3 {
        let h_l = self.get_height(x.saturating_sub(1), z);
        let h_r = self.get_height((x + 1).min(self.size - 1), z);
        let h_d = self.get_height(x, z.saturating_sub(1));
        let h_u = self.get_height(x, (z + 1).min(self.size - 1));
        
        Vec3::new(h_l - h_r, 2.0, h_d - h_u).normalize()
    }
}
}

Biome Assignment

Assign biomes based on terrain properties:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Biome {
    Ocean,
    Beach,
    Plains,
    Forest,
    Desert,
    Tundra,
    Mountains,
    Swamp,
    Jungle,
    Volcanic,
}

pub struct BiomeGenerator {
    temperature_noise: Perlin,
    moisture_noise: Perlin,
}

impl BiomeGenerator {
    pub fn new(seed: u64) -> Self {
        Self {
            temperature_noise: Perlin::new(seed as u32 + 100),
            moisture_noise: Perlin::new(seed as u32 + 200),
        }
    }
    
    pub fn get_biome(&self, x: f64, z: f64, height: f32) -> Biome {
        if height < 10.0 {
            return Biome::Ocean;
        }
        if height < 15.0 {
            return Biome::Beach;
        }
        if height > 200.0 {
            return Biome::Mountains;
        }
        
        let temp = (self.temperature_noise.get([x * 0.001, z * 0.001]) + 1.0) * 0.5;
        let moisture = (self.moisture_noise.get([x * 0.001, z * 0.001]) + 1.0) * 0.5;
        
        let temp = temp as f32 - (height - 50.0) * 0.002;
        
        match (temp, moisture as f32) {
            (t, _) if t < 0.2 => Biome::Tundra,
            (t, m) if t > 0.8 && m < 0.3 => Biome::Desert,
            (t, m) if t > 0.7 && m > 0.7 => Biome::Jungle,
            (_, m) if m > 0.8 => Biome::Swamp,
            (_, m) if m > 0.5 => Biome::Forest,
            _ => Biome::Plains,
        }
    }
    
    pub fn get_biome_properties(&self, biome: Biome) -> BiomeProperties {
        match biome {
            Biome::Ocean => BiomeProperties {
                tree_density: 0.0,
                grass_density: 0.0,
                rock_density: 0.1,
                enemy_level_mod: 0.8,
                ambient_sound: "ocean".into(),
            },
            Biome::Forest => BiomeProperties {
                tree_density: 0.7,
                grass_density: 0.8,
                rock_density: 0.2,
                enemy_level_mod: 1.0,
                ambient_sound: "forest".into(),
            },
            Biome::Desert => BiomeProperties {
                tree_density: 0.02,
                grass_density: 0.05,
                rock_density: 0.4,
                enemy_level_mod: 1.2,
                ambient_sound: "desert".into(),
            },
            Biome::Mountains => BiomeProperties {
                tree_density: 0.1,
                grass_density: 0.2,
                rock_density: 0.8,
                enemy_level_mod: 1.5,
                ambient_sound: "wind".into(),
            },
            _ => BiomeProperties::default(),
        }
    }
}

#[derive(Debug, Clone)]
pub struct BiomeProperties {
    pub tree_density: f32,
    pub grass_density: f32,
    pub rock_density: f32,
    pub enemy_level_mod: f32,
    pub ambient_sound: String,
}
}

Dungeon Generation

Room-Based Dungeon Generator

Generate dungeons using room placement:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct DungeonLayout {
    pub rooms: Vec<Room>,
    pub corridors: Vec<Corridor>,
    pub entry_room: usize,
    pub boss_room: usize,
    pub width: i32,
    pub height: i32,
}

#[derive(Debug, Clone)]
pub struct Room {
    pub id: usize,
    pub bounds: Rect,
    pub room_type: RoomType,
    pub connections: Vec<usize>,
    pub content: RoomContent,
}

#[derive(Debug, Clone, Copy, PartialEq)]
pub enum RoomType {
    Entry,
    Normal,
    Treasure,
    Boss,
    Secret,
    Shop,
    Shrine,
}

#[derive(Debug, Clone)]
pub struct RoomContent {
    pub enemies: Vec<EnemySpawn>,
    pub items: Vec<ItemSpawn>,
    pub props: Vec<PropSpawn>,
    pub triggers: Vec<TriggerSpawn>,
}

#[derive(Debug, Clone)]
pub struct Corridor {
    pub from_room: usize,
    pub to_room: usize,
    pub path: Vec<(i32, i32)>,
    pub width: i32,
}

pub struct DungeonGenerator {
    min_rooms: usize,
    max_rooms: usize,
    room_size_range: (i32, i32),
    room_templates: Vec<RoomTemplate>,
}

impl DungeonGenerator {
    pub fn generate(&self, params: &GenerationParams) -> GenerationResult<DungeonLayout> {
        let mut rng = SeededRng::new(params.seed);
        let room_count = rng.next_range(self.min_rooms as i32, self.max_rooms as i32) as usize;
        
        let mut rooms = Vec::new();
        let mut attempts = 0;
        let max_attempts = room_count * 100;
        
        while rooms.len() < room_count && attempts < max_attempts {
            let width = rng.next_range(self.room_size_range.0, self.room_size_range.1);
            let height = rng.next_range(self.room_size_range.0, self.room_size_range.1);
            let x = rng.next_range(0, 100 - width);
            let y = rng.next_range(0, 100 - height);
            
            let bounds = Rect { x, y, width, height };
            
            if !rooms.iter().any(|r: &Room| r.bounds.intersects_padded(&bounds, 2)) {
                let room_type = if rooms.is_empty() {
                    RoomType::Entry
                } else {
                    self.choose_room_type(&mut rng, rooms.len(), room_count)
                };
                
                rooms.push(Room {
                    id: rooms.len(),
                    bounds,
                    room_type,
                    connections: Vec::new(),
                    content: RoomContent::default(),
                });
            }
            
            attempts += 1;
        }
        
        if rooms.len() < self.min_rooms {
            return Err(GenerationError::MaxIterationsReached);
        }
        
        let corridors = self.connect_rooms(&mut rooms, &mut rng);
        
        let boss_room = rooms.iter()
            .enumerate()
            .filter(|(_, r)| r.room_type != RoomType::Entry)
            .max_by_key(|(_, r)| self.distance_from_entry(&rooms, r.id))
            .map(|(i, _)| i)
            .unwrap_or(rooms.len() - 1);
        
        rooms[boss_room].room_type = RoomType::Boss;
        
        for room in &mut rooms {
            room.content = self.generate_room_content(room, params, &mut rng);
        }
        
        Ok(DungeonLayout {
            rooms,
            corridors,
            entry_room: 0,
            boss_room,
            width: 100,
            height: 100,
        })
    }
    
    fn connect_rooms(&self, rooms: &mut [Room], rng: &mut SeededRng) -> Vec<Corridor> {
        let mut corridors = Vec::new();
        let mut connected = vec![false; rooms.len()];
        connected[0] = true;
        
        while connected.iter().any(|&c| !c) {
            let mut best_pair = None;
            let mut best_dist = f32::MAX;
            
            for (i, room_a) in rooms.iter().enumerate() {
                if !connected[i] {
                    continue;
                }
                
                for (j, room_b) in rooms.iter().enumerate() {
                    if connected[j] {
                        continue;
                    }
                    
                    let dist = room_a.bounds.center_distance(&room_b.bounds);
                    if dist < best_dist {
                        best_dist = dist;
                        best_pair = Some((i, j));
                    }
                }
            }
            
            if let Some((from, to)) = best_pair {
                let path = self.create_corridor_path(
                    rooms[from].bounds.center(),
                    rooms[to].bounds.center(),
                    rng,
                );
                
                rooms[from].connections.push(to);
                rooms[to].connections.push(from);
                connected[to] = true;
                
                corridors.push(Corridor {
                    from_room: from,
                    to_room: to,
                    path,
                    width: 2,
                });
            } else {
                break;
            }
        }
        
        corridors
    }
    
    fn create_corridor_path(
        &self,
        start: (i32, i32),
        end: (i32, i32),
        rng: &mut SeededRng,
    ) -> Vec<(i32, i32)> {
        let mut path = Vec::new();
        let (mut x, mut y) = start;
        
        if rng.next_float() > 0.5 {
            while x != end.0 {
                path.push((x, y));
                x += (end.0 - x).signum();
            }
            while y != end.1 {
                path.push((x, y));
                y += (end.1 - y).signum();
            }
        } else {
            while y != end.1 {
                path.push((x, y));
                y += (end.1 - y).signum();
            }
            while x != end.0 {
                path.push((x, y));
                x += (end.0 - x).signum();
            }
        }
        
        path.push(end);
        path
    }
    
    fn choose_room_type(&self, rng: &mut SeededRng, current: usize, total: usize) -> RoomType {
        let options = [
            (RoomType::Normal, 10.0),
            (RoomType::Treasure, 2.0),
            (RoomType::Secret, 1.0),
            (RoomType::Shop, 1.5),
            (RoomType::Shrine, 1.0),
        ];
        
        rng.weighted_choose(&options).unwrap_or(RoomType::Normal)
    }
    
    fn generate_room_content(
        &self,
        room: &Room,
        params: &GenerationParams,
        rng: &mut SeededRng,
    ) -> RoomContent {
        let mut content = RoomContent::default();
        
        match room.room_type {
            RoomType::Entry => {}
            RoomType::Normal => {
                let enemy_count = rng.next_range(1, 4);
                for _ in 0..enemy_count {
                    content.enemies.push(EnemySpawn {
                        position: room.bounds.random_point(rng),
                        enemy_type: "skeleton".into(),
                        level: params.context.player_level,
                    });
                }
            }
            RoomType::Treasure => {
                content.items.push(ItemSpawn {
                    position: room.bounds.center(),
                    loot_table: "treasure_chest".into(),
                });
            }
            RoomType::Boss => {
                content.enemies.push(EnemySpawn {
                    position: room.bounds.center(),
                    enemy_type: "boss".into(),
                    level: params.context.player_level + 5,
                });
            }
            _ => {}
        }
        
        content
    }
}
}

Item Generation

Procedural Item Generator

Generate items with random properties:

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct GeneratedItem {
    pub base_type: ItemBaseType,
    pub name: String,
    pub rarity: ItemRarity,
    pub level: u32,
    pub stats: ItemStats,
    pub affixes: Vec<ItemAffix>,
    pub special_ability: Option<SpecialAbility>,
}

#[derive(Debug, Clone)]
pub struct ItemStats {
    pub damage: Option<(f32, f32)>,
    pub armor: Option<f32>,
    pub durability: f32,
    pub weight: f32,
}

#[derive(Debug, Clone)]
pub struct ItemAffix {
    pub affix_type: AffixType,
    pub tier: u32,
    pub value: f32,
}

#[derive(Debug, Clone, Copy)]
pub enum AffixType {
    Strength,
    Agility,
    Intelligence,
    Vitality,
    FireDamage,
    IceDamage,
    LightningDamage,
    LifeSteal,
    CriticalChance,
    CriticalDamage,
    AttackSpeed,
    MovementSpeed,
}

pub struct ItemGenerator {
    name_generator: NameGenerator,
    affix_pool: Vec<AffixTemplate>,
}

impl ItemGenerator {
    pub fn generate(&self, params: &ItemGenParams, rng: &mut SeededRng) -> GeneratedItem {
        let rarity = self.roll_rarity(params.base_rarity_chance, rng);
        let affix_count = self.affix_count_for_rarity(rarity);
        
        let base = &params.base_type;
        let mut stats = self.roll_base_stats(base, params.level, rng);
        
        let mut affixes = Vec::new();
        for _ in 0..affix_count {
            if let Some(affix) = self.roll_affix(params.level, &affixes, rng) {
                affixes.push(affix);
            }
        }
        
        for affix in &affixes {
            self.apply_affix_to_stats(&mut stats, affix);
        }
        
        let special = if rarity >= ItemRarity::Epic && rng.next_float() > 0.5 {
            Some(self.generate_special_ability(params.level, rng))
        } else {
            None
        };
        
        let name = self.generate_name(base, &affixes, rarity, rng);
        
        GeneratedItem {
            base_type: base.clone(),
            name,
            rarity,
            level: params.level,
            stats,
            affixes,
            special_ability: special,
        }
    }
    
    fn roll_rarity(&self, base_chance: f32, rng: &mut SeededRng) -> ItemRarity {
        let roll = rng.next_float() * base_chance;
        match roll {
            r if r > 0.99 => ItemRarity::Legendary,
            r if r > 0.95 => ItemRarity::Epic,
            r if r > 0.85 => ItemRarity::Rare,
            r if r > 0.65 => ItemRarity::Uncommon,
            _ => ItemRarity::Common,
        }
    }
    
    fn affix_count_for_rarity(&self, rarity: ItemRarity) -> usize {
        match rarity {
            ItemRarity::Common => 0,
            ItemRarity::Uncommon => 1,
            ItemRarity::Rare => 2,
            ItemRarity::Epic => 3,
            ItemRarity::Legendary => 4,
        }
    }
    
    fn roll_affix(
        &self,
        level: u32,
        existing: &[ItemAffix],
        rng: &mut SeededRng,
    ) -> Option<ItemAffix> {
        let available: Vec<_> = self.affix_pool
            .iter()
            .filter(|a| a.min_level <= level)
            .filter(|a| !existing.iter().any(|e| e.affix_type == a.affix_type))
            .collect();
        
        if available.is_empty() {
            return None;
        }
        
        let template = rng.choose(&available)?;
        let tier = rng.next_range(1, template.max_tier as i32) as u32;
        let value = template.base_value * (1.0 + tier as f32 * 0.25);
        
        Some(ItemAffix {
            affix_type: template.affix_type,
            tier,
            value,
        })
    }
    
    fn generate_name(
        &self,
        base: &ItemBaseType,
        affixes: &[ItemAffix],
        rarity: ItemRarity,
        rng: &mut SeededRng,
    ) -> String {
        if rarity >= ItemRarity::Legendary {
            return self.name_generator.generate_legendary_name(base, rng);
        }
        
        let prefix = affixes.first().map(|a| self.affix_to_prefix(a));
        let suffix = affixes.get(1).map(|a| self.affix_to_suffix(a));
        
        match (prefix, suffix) {
            (Some(p), Some(s)) => format!("{} {} {}", p, base.display_name(), s),
            (Some(p), None) => format!("{} {}", p, base.display_name()),
            (None, Some(s)) => format!("{} {}", base.display_name(), s),
            (None, None) => base.display_name().to_string(),
        }
    }
}
}

AI-Enhanced Generation

LLM-Powered Content Creation

Use AI for narrative content:

#![allow(unused)]
fn main() {
use astraweave_llm::prelude::*;

pub struct AiContentGenerator {
    llm: LlmClient,
    templates: ContentTemplates,
}

impl AiContentGenerator {
    pub async fn generate_quest(
        &self,
        context: &QuestGenContext,
    ) -> Result<GeneratedQuest, GenerationError> {
        let prompt = format!(
            r#"Generate a side quest for a fantasy RPG.

Setting: {}
Player level: {}
Available NPCs: {}
Recent events: {}
Theme: {}

Generate a quest with:
1. Title (catchy, thematic)
2. Description (2-3 sentences)
3. Objectives (3-5 steps)
4. Rewards (appropriate for level)
5. Optional twist or complication

Return as JSON."#,
            context.location,
            context.player_level,
            context.available_npcs.join(", "),
            context.recent_events.join(", "),
            context.theme
        );
        
        let response = self.llm.complete(&prompt).await
            .map_err(|e| GenerationError::InvalidParams(e.to_string()))?;
        
        self.parse_quest_response(&response)
    }
    
    pub async fn generate_npc_backstory(
        &self,
        npc: &NpcGenContext,
    ) -> Result<NpcBackstory, GenerationError> {
        let prompt = format!(
            r#"Create a backstory for an NPC in a fantasy game.

Name: {}
Role: {}
Location: {}
Personality traits: {}

Generate:
1. Background (2-3 sentences)
2. Current motivation
3. Secret or hidden aspect
4. Connection to the world
5. Speech mannerism

Keep responses concise and game-appropriate."#,
            npc.name,
            npc.role,
            npc.location,
            npc.personality_traits.join(", ")
        );
        
        let response = self.llm.complete(&prompt).await
            .map_err(|e| GenerationError::InvalidParams(e.to_string()))?;
        
        self.parse_npc_response(&response)
    }
    
    pub async fn generate_location_description(
        &self,
        location: &LocationGenContext,
    ) -> Result<LocationDescription, GenerationError> {
        let prompt = format!(
            r#"Describe a location for a fantasy game.

Type: {}
Biome: {}
Key features: {}
Mood: {}

Provide:
1. Name (evocative)
2. Short description (1 sentence for UI)
3. Full description (2-3 sentences for exploration)
4. Notable elements (3-5 items)
5. Ambient sounds suggestion"#,
            location.location_type,
            location.biome,
            location.features.join(", "),
            location.mood
        );
        
        let response = self.llm.complete(&prompt).await
            .map_err(|e| GenerationError::InvalidParams(e.to_string()))?;
        
        self.parse_location_response(&response)
    }
}

#[derive(Debug)]
pub struct GeneratedQuest {
    pub title: String,
    pub description: String,
    pub objectives: Vec<QuestObjective>,
    pub rewards: Vec<QuestReward>,
    pub twist: Option<String>,
}

#[derive(Debug)]
pub struct NpcBackstory {
    pub background: String,
    pub motivation: String,
    pub secret: String,
    pub world_connection: String,
    pub speech_pattern: String,
}
}

Validation and Constraints

Content Validator

Ensure generated content meets requirements:

#![allow(unused)]
fn main() {
pub struct ContentValidator {
    rules: Vec<ValidationRule>,
}

pub enum ValidationRule {
    MinRooms(usize),
    MaxDeadEnds(usize),
    RequireRoomType(RoomType),
    MaxDifficulty(f32),
    Connectivity,
    NoOverlap,
    Custom(Box<dyn Fn(&DungeonLayout) -> ValidationResult>),
}

impl ContentValidator {
    pub fn validate_dungeon(&self, dungeon: &DungeonLayout) -> ValidationResult {
        for rule in &self.rules {
            match rule {
                ValidationRule::MinRooms(min) => {
                    if dungeon.rooms.len() < *min {
                        return ValidationResult::Invalid(
                            format!("Too few rooms: {} < {}", dungeon.rooms.len(), min)
                        );
                    }
                }
                ValidationRule::MaxDeadEnds(max) => {
                    let dead_ends = dungeon.rooms
                        .iter()
                        .filter(|r| r.connections.len() <= 1)
                        .count();
                    if dead_ends > *max {
                        return ValidationResult::Invalid(
                            format!("Too many dead ends: {} > {}", dead_ends, max)
                        );
                    }
                }
                ValidationRule::RequireRoomType(room_type) => {
                    if !dungeon.rooms.iter().any(|r| r.room_type == *room_type) {
                        return ValidationResult::Invalid(
                            format!("Missing required room type: {:?}", room_type)
                        );
                    }
                }
                ValidationRule::Connectivity => {
                    if !self.check_connectivity(dungeon) {
                        return ValidationResult::Invalid("Dungeon is not fully connected".into());
                    }
                }
                _ => {}
            }
        }
        
        ValidationResult::Valid
    }
    
    fn check_connectivity(&self, dungeon: &DungeonLayout) -> bool {
        if dungeon.rooms.is_empty() {
            return true;
        }
        
        let mut visited = vec![false; dungeon.rooms.len()];
        let mut stack = vec![0usize];
        
        while let Some(current) = stack.pop() {
            if visited[current] {
                continue;
            }
            visited[current] = true;
            
            for &connected in &dungeon.rooms[current].connections {
                if !visited[connected] {
                    stack.push(connected);
                }
            }
        }
        
        visited.iter().all(|&v| v)
    }
}
}

Best Practices

1. **Seed Everything**: Use deterministic RNG for reproducible generation
2. **Validate Early**: Reject invalid content before expensive operations
3. **Layer Generation**: Start coarse, refine with detail passes
4. **Cache Results**: Store expensive generation results for reuse

- **Infinite Loops**: Always limit generation attempts
- **Memory Bloat**: Stream large content; don't hold everything in memory
- **Sameness**: Vary parameters enough to feel unique
- **Performance**: Profile generation; move to background threads if slow

Related Documentation

• Terrain System - Terrain rendering integration
• Quest Systems - Generated quest execution
• AI System Overview - AI content enhancement
• Configuration Reference - PCG parameters

Save & Load Systems

Crates: astraweave-persistence-ecs, astraweave-core
Status: Production Ready

AstraWeave provides deterministic save/load with full ECS state serialization, player profiles, and versioned migrations.

Quick Start

#![allow(unused)]
fn main() {
use astraweave_persistence_ecs::{SaveSystem, LoadSystem, SaveConfig};
use astraweave_ecs::World;

let config = SaveConfig {
    path: "saves/",
    compression: true,
    encryption: false,
    ..Default::default()
};

let save_system = SaveSystem::new(config);

// Save world state
save_system.save(&world, "quicksave")?;

// Load world state
let loaded_world = save_system.load("quicksave")?;
}

Save System Architecture

Save File Structure
├── Header (version, timestamp, checksum)
├── World State
│   ├── Entities (sparse set serialization)
│   ├── Components (per-archetype)
│   └── Resources (global state)
├── Player Data
│   ├── Inventory
│   ├── Progress
│   └── Settings
└── Metadata
    ├── Screenshot (optional)
    └── Play time

ECS Serialization

Component Registration

Components must be registered for serialization:

#![allow(unused)]
fn main() {
use astraweave_ecs::{Component, Serialize, Deserialize};

#[derive(Component, Serialize, Deserialize)]
struct Health {
    current: f32,
    max: f32,
}

#[derive(Component, Serialize, Deserialize)]
struct Position {
    x: f32,
    y: f32,
    z: f32,
}

// Register with world
app.register_serializable::<Health>();
app.register_serializable::<Position>();
}

Selective Serialization

Mark components to skip during save:

#![allow(unused)]
fn main() {
#[derive(Component)]
#[component(skip_save)]
struct RenderCache {
    // Regenerated at load time
}

#[derive(Component, Serialize, Deserialize)]
#[component(save_priority = "high")]
struct PlayerData {
    // Saved first, loaded first
}
}

Save Slots

Slot Management

#![allow(unused)]
fn main() {
use astraweave_persistence_ecs::{SaveSlot, SlotManager};

let mut slots = SlotManager::new("saves/", 10); // 10 slots

// Get available slots
let available = slots.list()?;
for slot in &available {
    println!("Slot {}: {} ({})", slot.index, slot.name, slot.timestamp);
}

// Save to slot
slots.save_to_slot(3, &world, "My Save")?;

// Load from slot
let world = slots.load_from_slot(3)?;

// Delete slot
slots.delete_slot(3)?;
}

Auto-Save

#![allow(unused)]
fn main() {
use astraweave_persistence_ecs::AutoSave;

let mut autosave = AutoSave::new(Duration::from_secs(300)); // 5 minutes

// In game loop
if autosave.should_save() {
    slots.save_to_slot(0, &world, "Autosave")?;
    autosave.mark_saved();
}
}

Player Profiles

Profile Management

#![allow(unused)]
fn main() {
use astraweave_persistence_ecs::{PlayerProfile, ProfileManager};

let mut profiles = ProfileManager::new("profiles/")?;

// Create profile
let profile = PlayerProfile::new("Player1");
profiles.create(profile)?;

// Load profile
let profile = profiles.load("Player1")?;

// Update settings
profile.settings.volume = 0.8;
profile.settings.difficulty = Difficulty::Hard;
profiles.save(&profile)?;
}

Profile Contents

#![allow(unused)]
fn main() {
pub struct PlayerProfile {
    pub name: String,
    pub created: DateTime,
    pub play_time: Duration,
    pub settings: PlayerSettings,
    pub achievements: Vec<Achievement>,
    pub statistics: PlayerStats,
}

pub struct PlayerSettings {
    pub volume: f32,
    pub music_volume: f32,
    pub sfx_volume: f32,
    pub voice_volume: f32,
    pub difficulty: Difficulty,
    pub controls: ControlBindings,
    pub graphics: GraphicsSettings,
}
}

Versioning & Migration

Version Handling

#![allow(unused)]
fn main() {
use astraweave_persistence_ecs::{SaveVersion, Migration};

// Current save version
const SAVE_VERSION: SaveVersion = SaveVersion::new(1, 2, 0);

// Load with migration
let world = save_system.load_with_migrations(
    "old_save",
    &[
        Migration::new(
            SaveVersion::new(1, 0, 0),
            SaveVersion::new(1, 1, 0),
            migrate_1_0_to_1_1,
        ),
        Migration::new(
            SaveVersion::new(1, 1, 0),
            SaveVersion::new(1, 2, 0),
            migrate_1_1_to_1_2,
        ),
    ],
)?;

fn migrate_1_0_to_1_1(data: &mut SaveData) -> Result<()> {
    // Add new health.shield field
    for entity in data.entities_with::<Health>() {
        let health: &mut Health = data.get_mut(entity)?;
        health.shield = 0.0; // New field
    }
    Ok(())
}
}

Corruption Recovery

Backup System

#![allow(unused)]
fn main() {
use astraweave_persistence_ecs::BackupConfig;

let config = SaveConfig {
    backup: BackupConfig {
        enabled: true,
        max_backups: 3,
        backup_on_save: true,
    },
    ..Default::default()
};

// Backups created automatically
// saves/quicksave.sav
// saves/quicksave.sav.bak1
// saves/quicksave.sav.bak2
// saves/quicksave.sav.bak3
}

Integrity Verification

#![allow(unused)]
fn main() {
use astraweave_persistence_ecs::verify_save;

match verify_save("saves/quicksave.sav") {
    Ok(info) => {
        println!("Valid save: v{}", info.version);
    }
    Err(SaveError::Corrupted) => {
        // Try backup
        if let Ok(backup) = find_valid_backup("quicksave") {
            restore_from_backup(backup)?;
        }
    }
    Err(SaveError::VersionMismatch(v)) => {
        println!("Save from future version: {}", v);
    }
}
}

Deterministic Replay

AstraWeave’s deterministic ECS enables save/load that reproduces exact game states:

#![allow(unused)]
fn main() {
use astraweave_core::replay::{ReplayRecorder, ReplayPlayer};

// Record session
let mut recorder = ReplayRecorder::new();
recorder.start(&world);

// During gameplay
recorder.record_frame(&world, &inputs);

// Save replay
recorder.save("replay.bin")?;

// Play back (bit-identical to original)
let mut player = ReplayPlayer::load("replay.bin")?;
while let Some(frame) = player.next_frame() {
    world.apply_inputs(frame.inputs);
    world.step();
    
    assert_eq!(world.checksum(), frame.checksum);
}
}

Performance

Optimization Tips

1. Async saves - Don’t block gameplay
2. Incremental saves - Only save changed data
3. Compression - 60-80% size reduction
4. Memory-mapped loading - Faster large worlds

#![allow(unused)]
fn main() {
// Async save
let handle = save_system.save_async(&world, "quicksave");

// Continue gameplay...

// Wait for completion
handle.await?;
}

See Also

• ECS Architecture
• Deterministic Simulation
• Player Profiles

Scripting with Rhai

Crates: astraweave-scripting, astraweave-author
Status: Production Ready (Sandboxed)

AstraWeave provides secure Rhai scripting for modding, behavior authoring, and runtime customization with full sandboxing.

Quick Start

// scripts/my_behavior.rhai

// Called when entity spawns
fn on_spawn(entity) {
    log("Entity spawned: " + entity.id);
    entity.set_health(100);
    entity.play_animation("idle");
}

// Called every frame
fn on_update(entity, dt) {
    let player = find_nearest("Player");
    
    if distance(entity.position, player.position) < 10.0 {
        entity.look_at(player);
        entity.move_towards(player, dt * 5.0);
    }
}

// Called when taking damage
fn on_damage(entity, amount, source) {
    if entity.health - amount <= 0 {
        entity.play_animation("death");
        spawn_particles("blood", entity.position, 20);
    }
}

Script Engine Setup

#![allow(unused)]
fn main() {
use astraweave_scripting::{ScriptEngine, ScriptConfig};

let config = ScriptConfig {
    max_operations: 100_000,    // Operation limit per call
    timeout_ms: 10,             // Max execution time
    memory_limit_kb: 1024,      // Memory limit
    allow_network: false,       // Network access
    allow_filesystem: false,    // File access
};

let mut engine = ScriptEngine::new(config);

// Register scripts
engine.load_script("behaviors/enemy.rhai")?;
engine.load_script("behaviors/companion.rhai")?;

// Execute
engine.call("on_spawn", (entity,))?;
}

Available APIs

Entity API

// Position & Movement
entity.position              // Get Vec3
entity.set_position(x, y, z) // Set position
entity.move_towards(target, speed)
entity.look_at(target)
entity.rotate(yaw, pitch, roll)

// Health & Combat
entity.health               // Current health
entity.max_health           // Maximum health
entity.set_health(amount)
entity.damage(amount)
entity.heal(amount)
entity.is_dead()

// Animation
entity.play_animation(name)
entity.stop_animation()
entity.is_animating()

// Components
entity.has_component("Physics")
entity.get_tag("faction")
entity.set_tag("faction", "enemy")

World API

// Entity queries
let player = find_nearest("Player");
let enemies = find_all("Enemy");
let nearby = find_in_radius(position, radius);

// Spawning
let entity = spawn("enemy_type", position);
destroy(entity);

// Raycasting
let hit = raycast(origin, direction, max_distance);
if hit.success {
    log("Hit: " + hit.entity.name + " at " + hit.point);
}

// Time
let time = game_time();
let dt = delta_time();

Math API

// Vectors
let v = vec3(1.0, 2.0, 3.0);
let dist = distance(a, b);
let dir = normalize(v);
let dot = dot_product(a, b);
let cross = cross_product(a, b);

// Interpolation
let result = lerp(a, b, t);
let smooth = smoothstep(a, b, t);

// Random
let r = random();           // 0.0 - 1.0
let ri = random_range(1, 10); // 1 - 10
let choice = random_choice(array);

Audio API

// Sound playback
play_sound("sfx/explosion.ogg");
play_sound_at("sfx/growl.ogg", position);
play_music("music/combat.ogg", fade_in_seconds);
stop_music(fade_out_seconds);
set_volume("sfx", 0.8);

Particle API

spawn_particles("fire", position, count);
spawn_particles_at_entity("smoke", entity, count);
stop_particles(particle_system);

Behavior Components

Attaching Scripts to Entities

#![allow(unused)]
fn main() {
use astraweave_scripting::ScriptComponent;

commands.spawn((
    Transform::default(),
    Health::new(100),
    ScriptComponent::new("behaviors/enemy.rhai"),
));
}

Callbacks

Security Sandboxing

Operation Limits

// This will be terminated after 100,000 operations
fn infinite_loop(entity) {
    while true {
        // Will hit operation limit
    }
}

Memory Limits

fn memory_hog(entity) {
    let huge_array = [];
    for i in 0..1000000 {
        huge_array.push(i);  // Will hit memory limit
    }
}

Blocked Operations

Scripts cannot:

• Access filesystem
• Open network connections
• Call system commands
• Modify engine internals
• Access other scripts’ data

Hot Reloading

Scripts can be modified at runtime:

#![allow(unused)]
fn main() {
// Enable hot reload
engine.enable_hot_reload(true);

// In game loop
engine.check_for_changes()?; // Reloads modified scripts
}

Development workflow:

1. Run game
2. Edit .rhai files
3. Changes apply immediately
4. No restart needed

Custom Functions

Exposing Rust to Scripts

#![allow(unused)]
fn main() {
use astraweave_scripting::ScriptEngine;

engine.register_fn("custom_ability", |entity: Entity, power: f64| {
    // Rust implementation
    let damage = power * 2.0;
    apply_area_damage(entity.position(), damage, 5.0);
});
}

Using in Scripts

fn on_special_attack(entity) {
    custom_ability(entity, 50.0);
    play_sound("sfx/special.ogg");
    spawn_particles("explosion", entity.position, 100);
}

State Machines

Defining States

// AI state machine
let state = "idle";

fn on_update(entity, dt) {
    switch state {
        "idle" => {
            if see_player() {
                state = "chase";
            }
        }
        "chase" => {
            let player = find_nearest("Player");
            entity.move_towards(player, dt * 8.0);
            
            if distance(entity.position, player.position) < 2.0 {
                state = "attack";
            }
        }
        "attack" => {
            entity.attack();
            state = "cooldown";
            set_timer("attack_cooldown", 1.0);
        }
        "cooldown" => {
            if timer_expired("attack_cooldown") {
                state = "chase";
            }
        }
    }
}

Debugging

Logging

log("Debug message");
log_warn("Warning message");
log_error("Error message");

Console Commands

#![allow(unused)]
fn main() {
// Register console command
engine.register_command("spawn_enemy", |args| {
    let count = args.get(0).unwrap_or(1);
    for _ in 0..count {
        spawn("enemy", random_position());
    }
});
}

Script Inspector

The editor provides:

• Breakpoints
• Variable inspection
• Call stack
• Performance profiling

Performance

Optimization Tips

1. Cache lookups - Don’t find entities every frame
2. Limit scope - Smaller scripts are faster
3. Use events - Don’t poll in on_update
4. Batch operations - Group similar calls

// Bad: Finding player every frame
fn on_update(entity, dt) {
    let player = find_nearest("Player"); // Expensive!
}

// Good: Cache reference
let cached_player = null;

fn on_spawn(entity) {
    cached_player = find_nearest("Player");
}

fn on_update(entity, dt) {
    if cached_player != null {
        entity.look_at(cached_player);
    }
}

See Also

• Behavior Trees
• AI System
• Modding Guide
• Rhai Language Reference

Working Examples

AstraWeave includes over 20 examples demonstrating different aspects of the engine. This page focuses on the working examples that you can build and run to learn the engine.

Note: AstraWeave is under active development. Some examples have compilation issues due to API evolution. This page focuses on examples that are confirmed to work.

Core AI Examples

These examples demonstrate the AI-native architecture:

Hello Companion ✅

Location: examples/hello_companion
Status: ✅ Working (expected panic)

The simplest example of AI perception, planning, and validation.

cargo run -p hello_companion --release

What it demonstrates:

• AI perception system capturing world state
• LLM-based planning generating intents
• Tool validation system (demonstrates failure case)
• Fixed-tick simulation loop

Expected behavior: Shows AI plan generation, then panics with “LosBlocked” error. This demonstrates that the AI cannot perform invalid actions.

→ Detailed walkthrough

Adaptive Boss ✅

Location: examples/adaptive_boss
Status: ✅ Working

Multi-phase boss with Director AI that adapts tactics based on player behavior.

cargo run -p adaptive_boss --release

What it demonstrates:

• BossDirector for dynamic encounter planning
• Budget-constrained AI decisions
• Telegraph system for attack warnings
• Phase-based combat behavior

→ Detailed walkthrough

Companion Profile ✅

Location: examples/companion_profile
Status: ✅ Working

Demonstrates persistent AI profiles that learn and adapt.

cargo run -p companion_profile --release

What it demonstrates:

• AI profile serialization/deserialization
• Learning from player interactions
• Personality trait adjustment
• Long-term memory systems

Core Engine Examples

These examples showcase fundamental engine systems:

Fluids Demo ✅

Location: examples/fluids_demo
Status: ✅ Working

Interactive fluid simulation with PCISPH physics and multiple scenarios.

cargo run -p fluids_demo --release

What it demonstrates:

• Real-time particle-based fluid simulation
• Multiple scenarios (laboratory, ocean, waterfall, splash)
• Interactive particle spawning (click to add water)
• LOD optimization for performance scaling
• egui debug panel with live parameters

→ Detailed walkthrough

Unified Showcase ✅

Location: examples/unified_showcase
Status: ✅ Working

Comprehensive rendering demo with shadows, terrain, GLTF models, and skybox.

cargo run -p unified_showcase --release

What it demonstrates:

• Shadow mapping with 2048×2048 depth textures
• GLTF model loading with materials
• Procedural terrain with multi-texture blending
• HDR skybox rendering
• 4× MSAA antialiasing

→ Detailed walkthrough

Physics Demo 3D ✅

Location: examples/physics_demo3d
Status: ✅ Working

Demonstrates the Rapier3D physics integration with character controllers, destructibles, and environmental forces.

cargo run -p physics_demo3d --release

What it demonstrates:

• 3D physics simulation with Rapier3D
• Character controller with slope handling
• Destructible objects that shatter
• Water buoyancy and wind forces
• Collision layer filtering

→ Detailed walkthrough

Navmesh Demo ✅

Location: examples/navmesh_demo
Status: ✅ Working

Shows navigation mesh baking and A* pathfinding.

cargo run -p navmesh_demo --release

What it demonstrates:

• NavMesh baking from triangle geometry
• Slope-based walkability filtering
• A* pathfinding with path visualization
• Agent radius margin calculation

→ Detailed walkthrough

Audio Spatial Demo ✅

Location: examples/audio_spatial_demo
Status: ✅ Working

Spatial audio system with 3D positioning and music crossfading.

cargo run -p audio_spatial_demo --release

What it demonstrates:

• 3D positional audio (left/center/right beeps)
• Music playback with crossfading
• Listener tracking tied to camera
• Volume bus control (master/music/SFX)

→ Detailed walkthrough

Networking Examples

These examples show multiplayer and IPC capabilities:

IPC Loopback ✅

Location: examples/ipc_loopback
Status: ✅ Should work

Demonstrates inter-process communication for AI models.

cargo run -p ipc_loopback --release

What it demonstrates:

• Local/cloud AI model switching
• Process isolation for AI
• IPC message passing
• AI model hot-swapping

Coop Server/Client ✅

Location: examples/coop_server, examples/coop_client
Status: ✅ Working

Basic multiplayer client-server architecture.

# Terminal 1
cargo run -p coop_server --release

# Terminal 2  
cargo run -p coop_client --release

What it demonstrates:

• Server-authoritative validation
• Intent-based networking
• AI agent synchronization
• Anti-cheat through determinism

Tool and Planning Examples

These examples focus on AI planning and tool usage:

LLM Tool Call ✅

Location: examples/llm_toolcall
Status: ✅ Working

Direct demonstration of LLM tool calling.

cargo run -p llm_toolcall --release

What it demonstrates:

• LLM integration
• Tool definition and usage
• Structured AI responses
• Planning validation

Phase Director ✅

Location: examples/phase_director
Status: ✅ Working

Complex AI director managing multiple phases.

cargo run -p phase_director --release

What it demonstrates:

• Multi-phase AI behavior
• Director pattern implementation
• State machine management
• Complex AI coordination

Development Examples

These examples help with engine development:

Debug Overlay ❌

Location: examples/debug_overlay
Status: ❌ Has compilation issues (egui API)

Debug UI overlay for development.

Known issues: egui API mismatches with current version.

Persona Loader ✅

Location: examples/persona_loader
Status: ✅ Working

Loading and managing AI personas from files.

cargo run -p persona_loader --release

What it demonstrates:

• AI persona definition files
• Dynamic persona loading
• Personality trait configuration
• Behavioral parameter tuning

Known Compilation Issues

Some examples have known issues due to API evolution:

Graphics Examples ❌

• visual_3d: winit API mismatches
• ui_controls_demo: egui API compatibility issues
• debug_overlay: egui API changes

Authoring Examples ❌

• rhai_authoring: Depends on broken astraweave-author crate
• Issues with rhai sync/send traits

Complex Demos ❌

• npc_town_demo: Multiple API mismatches
• weaving_playground: Dependency issues
• cutscene_render_demo: Graphics API issues

Testing Examples

To verify your installation is working:

Minimal Test Sequence

# 1. Build core components
cargo build -p astraweave-core -p astraweave-ai -p hello_companion

# 2. Run the basic example
cargo run -p hello_companion --release

# 3. Run unit tests
cargo test -p astraweave-input

Debugging Build Issues

If examples fail to compile:

1. Check Rust version: rustc --version should match rust-toolchain.toml
2. Update dependencies: cargo update
3. Clean build: cargo clean && cargo build
4. Check system dependencies: Ensure graphics and audio libraries are installed

Reporting Issues

If you find compilation issues with examples marked as working:

1. Check your platform and Rust version
2. Ensure all system dependencies are installed
3. Try a clean build
4. Report the issue with full error output

Building Your Own Examples

When creating new examples:

Minimal Example Structure

// examples/my_example/src/main.rs
use astraweave_core::*;
use astraweave_ai::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the engine
    let mut world = World::new();
    
    // Add your systems
    world.add_system(my_custom_system);
    
    // Run the simulation
    world.run()?;
    
    Ok(())
}

Cargo.toml Template

[package]
name = "my_example"
version.workspace = true
edition.workspace = true

[dependencies]
astraweave-core = { path = "../../astraweave-core" }
astraweave-ai = { path = "../../astraweave-ai" }
anyhow.workspace = true

Next Steps

• Start Simple: Begin with Hello Companion
• Learn Architecture: Read AI-Native Design
• Build Something: Follow Building Your First Game
• Contribute: Help fix broken examples in Contributing Guide

The working examples are your best introduction to AstraWeave’s capabilities. Start with hello_companion and work your way up to more complex scenarios.

Hello Companion Walkthrough

The hello_companion example is the perfect introduction to AstraWeave’s AI-native architecture. This walkthrough explains every step of what happens when you run this example and why it’s designed this way.

Running the Example

cargo run -p hello_companion --release

Expected Output

[INFO] Initializing AstraWeave Engine...
[INFO] Creating world with ECS...
[INFO] Spawning AI companion entity
[INFO] Starting simulation loop at 60Hz
[INFO] Tick 1: Capturing perception snapshot
[INFO] AI perception: 1 entities visible, 0 audio events
[INFO] Sending perception to AI planning layer
[INFO] AI generated plan: MoveTo { target: Vec3(10.0, 0.0, 5.0), urgency: 0.7 }
[INFO] Validating movement tool usage...
[ERROR] Tool validation failed: LosBlocked - No clear line of sight to target
thread 'main' panicked at examples/hello_companion/src/main.rs:42:5:
called `Result::unwrap()` on an `Err` value: ToolValidationError(LosBlocked)

This panic is intentional! It demonstrates AstraWeave’s core principle: AI agents cannot perform actions that violate the game world’s constraints.

Code Walkthrough

Let’s examine the source code to understand each step:

1. Engine Initialization

// examples/hello_companion/src/main.rs
use astraweave_core::*;
use astraweave_ai::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize logging
    env_logger::init();
    
    // Create the ECS world
    let mut world = World::new();
    
    // Configure the engine systems
    world.add_plugin(CorePlugin)
         .add_plugin(AIPlugin)
         .add_plugin(PhysicsPlugin);

What’s happening:

• Sets up the Entity-Component-System (ECS) world
• Registers core systems for AI, physics, and simulation
• Configures 60Hz fixed-tick simulation

2. Spawning the AI Companion

#![allow(unused)]
fn main() {
    // Spawn an AI companion entity
    let companion = world.spawn()
        .insert(Position(Vec3::new(0.0, 0.0, 0.0)))
        .insert(AIAgent {
            perception_range: 10.0,
            planning_interval: Duration::from_millis(500),
            ai_model: AIModel::Local("companion-7b".to_string()),
        })
        .insert(MovementCapability {
            max_speed: 5.0,
            acceleration: 2.0,
        })
        .id();
    
    info!("Spawned AI companion with ID: {:?}", companion);
}

What’s happening:

• Creates a new entity in the ECS world
• Adds position component (where the companion is)
• Adds AI agent component (makes it intelligent)
• Adds movement capability (what it can do)

3. The Simulation Loop

#![allow(unused)]
fn main() {
    // Run simulation for a few ticks
    for tick in 0..5 {
        info!("Starting tick {}", tick);
        
        // This is where the AI magic happens
        world.step(Duration::from_nanos(16_666_667)); // 1/60 second
        
        // Small delay so we can see the output
        std::thread::sleep(Duration::from_millis(100));
    }
}

What’s happening:

• Runs exactly 5 simulation ticks
• Each tick advances the world by exactly 1/60th of a second
• The deterministic timing ensures consistent behavior

4. The AI Pipeline (Inside world.step())

During each world.step() call, several systems run in sequence:

A. Perception System

#![allow(unused)]
fn main() {
fn ai_perception_system(
    mut query: Query<(&Position, &AIAgent, &mut PerceptionState)>,
    world_query: Query<&Position>,
) {
    for (pos, agent, mut perception) in query.iter_mut() {
        // Gather what the AI can see
        let mut visible_entities = Vec::new();
        
        for other_pos in world_query.iter() {
            let distance = pos.0.distance(other_pos.0);
            if distance <= agent.perception_range {
                visible_entities.push(EntityData {
                    position: other_pos.0,
                    distance,
                    entity_type: "unknown".to_string(),
                });
            }
        }
        
        // Create perception snapshot
        perception.last_snapshot = Some(PerceptionSnapshot {
            timestamp: world.current_tick(),
            agent_id: entity,
            visible_entities,
            audio_events: vec![], // None in this simple example
            world_state: WorldState::default(),
        });
    }
}
}

B. AI Planning System

#![allow(unused)]
fn main() {
fn ai_planning_system(
    mut query: Query<(&AIAgent, &PerceptionState, &mut PlanningState)>,
    ai_service: Res<AIService>,
) {
    for (agent, perception, mut planning) in query.iter_mut() {
        if let Some(snapshot) = &perception.last_snapshot {
            // Send to AI model for planning
            let plan_request = PlanningRequest {
                perception: snapshot.clone(),
                agent_profile: agent.clone(),
                available_tools: vec!["MovementTool", "InteractionTool"],
            };
            
            // This is where the LLM generates a plan
            let plan = ai_service.generate_plan(plan_request)?;
            
            info!("AI generated plan: {:?}", plan.intent);
            planning.current_plan = Some(plan);
        }
    }
}
}

C. Tool Validation System

#![allow(unused)]
fn main() {
fn tool_validation_system(
    mut query: Query<(&PlanningState, &mut ActionState)>,
    tool_registry: Res<ToolRegistry>,
    world: &World,
) {
    for (planning, mut action) in query.iter_mut() {
        if let Some(plan) = &planning.current_plan {
            for tool_usage in &plan.tools {
                // This is where the validation happens
                let validation_result = tool_registry
                    .get_tool(&tool_usage.tool_name)
                    .unwrap()
                    .validate(world, tool_usage);
                
                match validation_result {
                    ValidationResult::Valid => {
                        info!("Tool validation passed: {}", tool_usage.tool_name);
                        action.pending_actions.push(tool_usage.clone());
                    }
                    ValidationResult::Blocked(reason) => {
                        error!("Tool validation failed: {:?}", reason);
                        // This causes the panic in hello_companion
                        return Err(ToolValidationError::from(reason));
                    }
                }
            }
        }
    }
}
}

Why Does It Panic?

The panic occurs because the AI tries to move to a position but there’s no clear line of sight. Here’s what happens:

1. AI Perception

• The companion perceives its current position (0, 0, 0)
• It detects no obstacles in its perception range

2. AI Planning

• The AI decides it wants to move to position (10, 0, 5)
• This seems reasonable based on its limited perception

3. Tool Validation

• The MovementTool.validate() method checks line of sight
• There’s an invisible obstacle blocking the path
• Validation fails with LosBlocked error

4. Engine Authority

• The engine refuses to execute the invalid action
• This maintains world integrity and prevents AI cheating

Key Learning Points

1. AI Cannot Cheat

The AI doesn’t have perfect information about the world. It can only act based on what it perceives, and all actions must be validated by the engine.

2. Deterministic Behavior

Run the example multiple times - you’ll get the same result every time. This determinism is crucial for:

• Reliable testing
• Networking (same simulation on all clients)
• Debugging AI behavior

3. Tool-Based Architecture

The AI doesn’t directly move entities or change the world. It can only request actions through validated tools:

• MovementTool (for movement)
• InteractionTool (for object interaction)
• CombatTool (for attacks)
• CommunicationTool (for dialogue)

4. Perception vs Reality

The AI’s perception is limited and may not match reality. This creates interesting emergent behavior as AI agents must:

• Explore to gather information
• Make decisions with incomplete data
• Adapt when actions fail

Modifying the Example

Make It Not Panic

To see successful AI behavior, modify the world setup:

#![allow(unused)]
fn main() {
// Remove the obstacle that blocks line of sight
world.remove_obstacle(Vec3::new(5.0, 0.0, 2.5));

// Or give the AI perfect perception
ai_agent.perception_range = f32::INFINITY;
}

Add More Interesting Behavior

#![allow(unused)]
fn main() {
// Add a target for the AI to find
world.spawn()
    .insert(Position(Vec3::new(15.0, 0.0, 0.0)))
    .insert(InteractableItem {
        item_type: "treasure_chest".to_string(),
        value: 100,
    });

// The AI will now try to navigate to and interact with the chest
}

Enable Logging for More Detail

RUST_LOG=debug cargo run -p hello_companion --release

This shows detailed information about:

• ECS system execution order
• AI model input/output
• Tool validation steps
• World state changes

Architectural Insights

Fixed-Tick Simulation

The 60Hz fixed timestep ensures:

• Physics determinism
• Consistent AI decision making
• Reliable networking
• Predictable performance

ECS Benefits

The Entity-Component-System architecture provides:

• Cache-friendly performance
• Clear separation of concerns
• Easy parallel system execution
• Modular, testable code

AI Validation Pipeline

The perception → planning → validation → execution pipeline ensures:

• No AI cheating
• Consistent game rules
• Emergent behavior from constraints
• Easy debugging and testing

Next Steps

After understanding hello_companion:

1. Explore More Examples: Try Adaptive Boss for complex AI
2. Learn Architecture: Read AI-Native Design
3. Build Your Own: Follow Building Your First Game
4. Dive Deeper: Study Core AI Systems

Common Questions

Q: Why does it panic instead of just logging the error?

A: The panic demonstrates that validation failures are serious. In a real game, you’d handle this gracefully, but the example uses panic to make the validation concept crystal clear.

Q: Can I make the AI smarter to avoid this error?

A: Yes! You can:

• Improve the AI’s perception system
• Give it better pathfinding tools
• Add obstacle detection to its planning
• Implement learning from failed actions

Q: Is this really how a game AI should work?

A: For AI-native games, yes! This approach:

• Prevents AI cheating
• Creates emergent behavior
• Works in multiplayer
• Enables complex AI interactions

The “failed action = learning opportunity” approach leads to much more interesting AI behavior than scripted sequences.

The hello_companion example may be simple, but it demonstrates the fundamental principles that enable AstraWeave’s AI-native gameplay. Every complex AI behavior in the engine builds on these same validation patterns.

Adaptive Boss Walkthrough

The adaptive_boss example demonstrates AstraWeave’s Director System - an AI-driven game master that orchestrates boss encounters with dynamic phase transitions, telegraphed attacks, and budget-constrained tactical decisions.

Running the Example

cargo run -p adaptive_boss --release

For the full Veilweaver boss experience (requires veilweaver_slice feature):

cargo run -p adaptive_boss --release --features veilweaver_slice

What It Demonstrates

• BossDirector: AI that plans boss encounter actions
• Phase-based combat: Boss behavior changes based on situation
• Director budget: Limited resources for spawns, traps, and terrain edits
• Telegraph system: Visual/audio warnings before powerful attacks
• OathboundWardenDirector: Full Veilweaver boss with Fate-weaving mechanics

Expected Output

Warden phase: Stalking
Telegraphs: ["Thread gathering at position (5, 3)"]
Director plan: {
  "spawn": [{"enemy": "shade", "pos": [4, 1]}],
  "traps": [{"type": "thread_snare", "pos": [6, 2]}],
  "terrain": []
}
Remaining budget: traps=1, terrain_edits=2, spawns=1

Code Walkthrough

1. Arena Setup

#![allow(unused)]
fn main() {
let mut w = World::new();

// Create the combat arena: player, companion, and boss
let player = w.spawn("Player", IVec2 { x: 2, y: 2 }, Team { id: 0 }, 100, 0);
let comp = w.spawn("Comp", IVec2 { x: 3, y: 2 }, Team { id: 1 }, 80, 30);
let boss = w.spawn("Boss", IVec2 { x: 14, y: 2 }, Team { id: 2 }, 400, 0);
}

The world contains three entities:

• Player (HP: 100): The human-controlled character
• Companion (HP: 80, Ammo: 30): AI ally
• Boss (HP: 400): The adversary with high HP

2. World Snapshot

#![allow(unused)]
fn main() {
let snap = WorldSnapshot {
    t: w.t,
    player: PlayerState { hp: 100, pos: w.pos_of(player).unwrap(), ... },
    me: CompanionState { ammo: 30, morale: 0.8, pos: w.pos_of(comp).unwrap(), ... },
    enemies: vec![EnemyState { id: boss, hp: 400, cover: "high", ... }],
    pois: vec![],
    obstacles: vec![],
    objective: Some("defeat_boss".into()),
};
}

The Director receives a perception snapshot containing:

• Current game time
• Player state (health, position, stance)
• Companion state (ammo, morale, cooldowns)
• Enemy states (the boss from its perspective)

3. Director Budget

#![allow(unused)]
fn main() {
let mut budget = DirectorBudget {
    traps: 2,      // Can place 2 traps
    terrain_edits: 2, // Can modify terrain twice
    spawns: 2,     // Can summon 2 minions
};
}

The budget prevents the Director from overwhelming the player. Each action consumes budget:

• Spawns: Summoning minions costs 1 spawn point
• Traps: Placing hazards costs 1 trap point
• Terrain edits: Blocking paths or creating cover costs 1 edit point

4. Director Planning (Basic)

#![allow(unused)]
fn main() {
#[cfg(not(feature = "veilweaver_slice"))]
{
    let director = BossDirector;
    let plan = director.plan(&snap, &budget);
    apply_director_plan(&mut w, &mut budget, &plan, &mut log);
}
}

The basic BossDirector analyzes the world state and generates a plan within budget.

5. Veilweaver Director (Advanced)

#![allow(unused)]
fn main() {
#[cfg(feature = "veilweaver_slice")]
{
    let mut director = OathboundWardenDirector::new();
    let directive = director.step(&snap, &budget);
    
    println!("Warden phase: {:?}", directive.phase);
    if !directive.telegraphs.is_empty() {
        println!("Telegraphs: {:?}", directive.telegraphs);
    }
    
    apply_director_plan(&mut w, &mut budget, &directive.plan, &mut log);
}
}

The Oathbound Warden has distinct phases:

• Stalking: Observing, placing traps, gathering threads
• Weaving: Manipulating fate threads, buffing/debuffing
• Severing: Aggressive attacks, breaking player connections
• Unraveling: Desperate phase when low HP

Director System Architecture

┌────────────────────────────────────────────────────────┐
│                    BossDirector                        │
├────────────────────────────────────────────────────────┤
│  Input: WorldSnapshot + DirectorBudget                 │
│                                                        │
│  ┌──────────┐   ┌──────────┐   ┌──────────────────┐   │
│  │ Analyze  │ → │ Plan     │ → │ Apply within     │   │
│  │ Threat   │   │ Response │   │ Budget           │   │
│  └──────────┘   └──────────┘   └──────────────────┘   │
│                                                        │
│  Output: DirectorPlan { spawns, traps, terrain }       │
└────────────────────────────────────────────────────────┘

Telegraph System

Telegraphs provide fair warning to players before powerful attacks:

#![allow(unused)]
fn main() {
if !directive.telegraphs.is_empty() {
    for telegraph in &directive.telegraphs {
        // Display visual/audio warning
        // e.g., "Thread gathering at position (5, 3)"
    }
}
}

Telegraph types:

• Thread gathering: Fate-weaving attack incoming
• Ground tremor: Area attack warning
• Shadow forming: Minion spawn location
• Pattern shift: Phase transition imminent

Key Concepts

Budget-Constrained AI

Unlike traditional boss AI that can spam abilities, the Director operates under resource constraints. This creates:

• Strategic decisions: Trade-offs between aggression and defense
• Fair encounters: Players can anticipate resource depletion
• Dynamic difficulty: Budget recharges over time

Phase-Based Behavior

The boss doesn’t just cycle through attacks. Phases emerge from:

• HP thresholds: Different behavior at 75%, 50%, 25% HP
• Player behavior: Adapts to aggressive vs defensive playstyles
• Companion effectiveness: Responds to ally threat level

Related Examples

• Hello Companion - Basic AI perception and planning
• Fluids Demo - Physics simulation
• Physics Demo - Rapier3D integration

Troubleshooting

Missing veilweaver_slice feature

The advanced Warden Director requires the Veilweaver game data:

cargo run -p adaptive_boss --release --features veilweaver_slice

Empty plan output

If the Director returns an empty plan, the budget may already be exhausted or the boss doesn’t see any targets.

Source Location

• Example: examples/adaptive_boss/src/main.rs
• Director: astraweave-director/src/lib.rs
• Warden: astraweave-director/src/oathbound_warden.rs (feature-gated)

Physics Demo Walkthrough

The physics_demo3d example showcases AstraWeave’s Rapier3D-based physics system with character controllers, destructible objects, water buoyancy, wind forces, and real-time rendering.

Running the Example

cargo run -p physics_demo3d --release

What It Demonstrates

• Character controller: Physics-driven movement with climb detection
• Destructible objects: Boxes that break under force
• Water simulation: Buoyancy and drag in water volumes
• Wind forces: Environmental wind affecting dynamic objects
• Collision layers: Filtering which objects collide
• Real-time rendering: wgpu-based visualization

Controls

Camera

Character

Physics

Expected Behavior

When you run the demo:

1. Initial scene: Ground plane, wall, character (green), water volume, destructible box
2. Press J/L: Character slides left/right with physics
3. Press F: Box drops and bounces
4. Press T: Wind pushes boxes in the wind direction
5. Press G: Water volume toggles, affecting buoyancy
6. Press M: Destructible box shatters into fragments

Code Walkthrough

1. Physics World Setup

#![allow(unused)]
fn main() {
let mut phys = PhysicsWorld::new(vec3(0.0, -9.81, 0.0));
let _ground = phys.create_ground_plane(vec3(100.0, 0.0, 100.0), 1.0);
}

• Creates a physics world with Earth gravity (9.81 m/s²)
• Adds a ground plane at Y=0

2. Static Geometry

#![allow(unused)]
fn main() {
let _wall = phys.add_static_trimesh(
    &[
        vec3(5.0, 0.0, 0.0),
        vec3(5.0, 3.0, 0.0),
        // ... vertices
    ],
    &[[0, 1, 2], [3, 2, 1]],  // Triangle indices
    Layers::CHARACTER | Layers::DEFAULT,
);
}

Static meshes (walls, floors) don’t move but participate in collisions. The Layers flags control which objects can collide.

3. Character Controller

#![allow(unused)]
fn main() {
let char_id = phys.add_character(
    vec3(-2.0, 1.0, 0.0),  // Start position
    vec3(0.4, 0.9, 0.4),   // Capsule half-extents
);
}

The character controller:

• Handles walking on slopes (up to 50° by default)
• Provides ground detection and step climbing
• Prevents tunneling through walls

4. Character Movement

#![allow(unused)]
fn main() {
// In the game loop:
let desired = vec3(self.move_dir.x, 0.0, self.move_dir.z);
self.phys.control_character(self.char_id, desired, dt, self.climb_try);
}

The controller converts desired velocity into physics-respecting movement.

5. Destructible Objects

#![allow(unused)]
fn main() {
let id = phys.add_destructible_box(
    vec3(-1.0, 1.0, 2.0),   // Position
    vec3(0.4, 0.4, 0.4),    // Half-size
    3.0,                     // Mass (kg)
    50.0,                    // Break force threshold
    12.0,                    // Fragment mass
);
}

When break force is exceeded:

#![allow(unused)]
fn main() {
self.phys.break_destructible(id);  // Shatters into fragments
}

6. Water Volume

#![allow(unused)]
fn main() {
phys.add_water_aabb(
    vec3(-2.0, 0.0, -2.0),  // Min corner
    vec3(2.0, 1.2, 2.0),    // Max corner
    1000.0,                  // Water density (kg/m³)
    0.8,                     // Drag coefficient
);
}

Objects inside the volume experience:

• Buoyancy: Upward force proportional to submerged volume
• Drag: Velocity-dependent resistance

7. Wind Forces

#![allow(unused)]
fn main() {
self.phys.set_wind(
    vec3(1.0, 0.0, 0.2).normalize(),  // Direction
    8.0,                               // Strength
);
}

Wind applies continuous force to dynamic bodies.

8. Rendering Loop

#![allow(unused)]
fn main() {
fn about_to_wait(&mut self, _event_loop: &ActiveEventLoop) {
    // Update physics
    self.phys.step();
    
    // Sync render instances from physics transforms
    self.instances.clear();
    for (handle, _body) in self.phys.bodies.iter() {
        if let Some(m) = self.phys.body_transform(id) {
            self.instances.push(Instance { transform: m, ... });
        }
    }
    
    // Render
    renderer.update_instances(&self.instances);
    renderer.render()?;
}
}

Physics Architecture

┌─────────────────────────────────────────────────────────┐
│                    PhysicsWorld                         │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │ Rigid Bodies│  │ Colliders   │  │ Constraints     │ │
│  │ (dynamic)   │  │ (shapes)    │  │ (joints)        │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │ Character   │  │ Water       │  │ Wind/Forces     │ │
│  │ Controller  │  │ Volumes     │  │                 │ │
│  └─────────────┘  └─────────────┘  └─────────────────┘ │
│                                                         │
│  Backend: Rapier3D 0.22                                 │
└─────────────────────────────────────────────────────────┘

Collision Layers

AstraWeave uses bitflag layers to control collisions:

#![allow(unused)]
fn main() {
pub struct Layers: u32 {
    const DEFAULT   = 0b0001;  // General objects
    const CHARACTER = 0b0010;  // Player/NPC capsules
    const PROJECTILE= 0b0100;  // Bullets, arrows
    const TRIGGER   = 0b1000;  // Non-solid triggers
}
}

Objects only collide if their layer masks overlap.

Performance Notes

The physics demo runs at 60 FPS with:

• ~50 dynamic bodies
• Character controller
• Water volume intersection tests
• Wind force application

For larger simulations, consider:

• Reducing simulation substeps
• Using simpler collision shapes
• Spatial partitioning for many bodies

Related Examples

• Fluids Demo - Particle-based fluid simulation
• Navmesh Demo - Pathfinding on terrain
• Unified Showcase - Rendering pipeline

Troubleshooting

Character falls through floor

Ensure the ground plane is created before spawning the character.

Objects don’t collide

Check that collision layers overlap between the objects.