Crate Reference

AstraWeave is organized as a workspace of interconnected crates, each providing focused functionality. This reference documents the crate hierarchy, dependencies, and public APIs.

Workspace Overview

graph TB
    subgraph Core["Core Layer"]
        ECS[astraweave-ecs]
        MATH[astraweave-math]
        SDK[astraweave-sdk]
    end
    
    subgraph AI["AI Layer"]
        AI_CORE[astraweave-ai]
        LLM[astraweave-llm]
        MEMORY[astraweave-memory]
        PERSONA[astraweave-persona]
        BEHAVIOR[astraweave-behavior]
    end
    
    subgraph Rendering["Rendering Layer"]
        RENDER[astraweave-render]
        MATERIALS[astraweave-materials]
        ASSET[astraweave-asset]
        UI[astraweave-ui]
    end
    
    subgraph Simulation["Simulation Layer"]
        PHYSICS[astraweave-physics]
        NAV[astraweave-nav]
        AUDIO[astraweave-audio]
    end
    
    subgraph Gameplay["Gameplay Layer"]
        GAMEPLAY[astraweave-gameplay]
        DIALOGUE[astraweave-dialogue]
        QUESTS[astraweave-quests]
        PCG[astraweave-pcg]
    end
    
    SDK --> ECS
    SDK --> AI_CORE
    SDK --> RENDER
    SDK --> PHYSICS
    
    AI_CORE --> ECS
    AI_CORE --> LLM
    AI_CORE --> MEMORY
    
    RENDER --> ECS
    RENDER --> ASSET
    RENDER --> MATERIALS
    
    GAMEPLAY --> ECS
    GAMEPLAY --> AI_CORE
    GAMEPLAY --> PHYSICS

Core Crates

astraweave-ecs

The foundation Entity Component System providing deterministic, high-performance entity management.

[dependencies]
astraweave-ecs = "0.1"

Key Types:

Example:

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

#[derive(Component)]
struct Position(Vec3);

#[derive(Component)]
struct Velocity(Vec3);

fn movement_system(mut query: Query<(&mut Position, &Velocity)>) {
    for (mut pos, vel) in query.iter_mut() {
        pos.0 += vel.0;
    }
}
}

Features:

• parallel - Enable parallel system execution (default)
• tracing - Add performance tracing instrumentation
• serde - Serialization support for components

astraweave-math

Mathematics library optimized for game development with SIMD acceleration.

[dependencies]
astraweave-math = "0.1"

Key Types:

Example:

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

let pos = Vec3::new(1.0, 2.0, 3.0);
let rotation = Quat::from_axis_angle(Vec3::Y, 45.0_f32.to_radians());
let transform = Transform::from_translation(pos).with_rotation(rotation);

let world_pos = transform.transform_point(Vec3::ZERO);
}

astraweave-sdk

High-level SDK that re-exports commonly used types and provides convenience APIs.

[dependencies]
astraweave-sdk = "0.1"

Re-exports:

#![allow(unused)]
fn main() {
pub use astraweave_ecs::prelude::*;
pub use astraweave_ai::prelude::*;
pub use astraweave_render::prelude::*;
pub use astraweave_physics::prelude::*;
pub use astraweave_audio::prelude::*;
pub use astraweave_input::prelude::*;
}

App Builder:

use astraweave_sdk::prelude::*;

fn main() {
    App::new()
        .add_plugin(DefaultPlugins)
        .add_startup_system(setup)
        .add_system(game_logic)
        .run();
}

AI Crates

astraweave-ai

Core AI framework with perception, planning, and behavior systems.

[dependencies]
astraweave-ai = "0.1"

Key Types:

Example:

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

let mut agent = AiAgent::new()
    .with_perception_radius(50.0)
    .with_tick_budget_ms(8);

agent.add_goal(AiGoal::Patrol { 
    waypoints: vec![point_a, point_b, point_c] 
});
}

Features:

• llm - Enable LLM integration (requires astraweave-llm)
• goap - Goal-Oriented Action Planning
• utility - Utility AI scoring system

astraweave-llm

LLM integration for AI agents with tool calling and validation.

[dependencies]
astraweave-llm = "0.1"

Key Types:

Example:

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

let config = LlmConfig {
    endpoint: "http://localhost:11434".into(),
    model: "hermes2-pro-mistral".into(),
    temperature: 0.7,
    max_tokens: 256,
};

let client = LlmClient::new(config);
let response = client.complete("What should I do next?").await?;
}

Supported Backends:

• Ollama (local)
• OpenAI-compatible APIs
• Custom endpoints

astraweave-memory

Memory systems for AI agents including short-term, long-term, and episodic memory.

[dependencies]
astraweave-memory = "0.1"

Key Types:

astraweave-behavior

Behavior tree implementation with visual editor support.

[dependencies]
astraweave-behavior = "0.1"

Node Types:

Example:

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

let tree = BehaviorTree::new(
    Selector::new(vec![
        Sequence::new(vec![
            Condition::new("has_target"),
            Action::new("attack_target"),
        ]).into(),
        Action::new("patrol").into(),
    ])
);
}

Rendering Crates

astraweave-render

GPU rendering with Vulkan/DX12/Metal backends via wgpu.

[dependencies]
astraweave-render = "0.1"

Key Types:

Features:

• pbr - Physically-based rendering (default)
• shadows - Shadow mapping with CSM
• post-process - Bloom, SSAO, tone mapping
• skeletal - Skeletal animation

astraweave-materials

PBR material system with shader graph support.

[dependencies]
astraweave-materials = "0.1"

Material Properties:

astraweave-asset

Asset loading, caching, and hot-reloading.

[dependencies]
astraweave-asset = "0.1"

Key Types:

Supported Formats:

• Meshes: glTF 2.0, OBJ, FBX
• Textures: PNG, JPEG, KTX2, DDS
• Audio: WAV, OGG, MP3
• Fonts: TTF, OTF

astraweave-ui

Immediate-mode UI with retained state for game interfaces.

[dependencies]
astraweave-ui = "0.1"

Key Types:

Built-in Widgets:

• Button, Label, TextInput
• Slider, Checkbox, RadioGroup
• Panel, ScrollView, Modal
• ProgressBar, Tooltip

Simulation Crates

astraweave-physics

3D physics with Rapier backend.

[dependencies]
astraweave-physics = "0.1"

Key Types:

Collider Shapes:

• Ball, Cuboid, Capsule, Cylinder
• ConvexHull, TriMesh, HeightField
• Compound (multiple shapes)

astraweave-nav

Navigation mesh and pathfinding.

[dependencies]
astraweave-nav = "0.1"

Key Types:

Features:

• A* pathfinding with string pulling
• Dynamic obstacle avoidance
• Off-mesh links for jumps/ladders
• Hierarchical pathfinding for large worlds

astraweave-audio

Spatial audio with multiple backends.

[dependencies]
astraweave-audio = "0.1"

Key Types:

Features:

• 3D spatial audio with HRTF
• Reverb zones
• Audio occlusion
• Streaming for music

Gameplay Crates

astraweave-gameplay

High-level gameplay systems and components.

[dependencies]
astraweave-gameplay = "0.1"

Systems:

• Combat and damage
• Inventory management
• Status effects
• Interactable objects
• Save/load integration

astraweave-dialogue

Dialogue tree and conversation systems.

[dependencies]
astraweave-dialogue = "0.1"

Key Types:

astraweave-quests

Quest tracking and objective systems.

[dependencies]
astraweave-quests = "0.1"

Key Types:

astraweave-pcg

Procedural content generation framework.

[dependencies]
astraweave-pcg = "0.1"

Generators:

• Terrain heightmaps with erosion
• Dungeon layouts
• Item properties
• NPC backstories (AI-enhanced)
• Quest generation (AI-enhanced)

Tool Crates

aw_editor

Visual editor for scenes, behavior trees, and materials.

cargo run -p aw_editor

Features:

• Scene hierarchy view
• Component inspector
• Behavior tree editor
• Material graph editor
• Asset browser

aw_asset_cli

Command-line asset processing.

cargo run -p aw_asset_cli -- --help

Commands:

• import - Convert assets to engine format
• pack - Create asset bundles
• validate - Check asset integrity
• optimize - Compress and optimize assets

aw_debug

Runtime debugging tools.

[dependencies]
aw_debug = "0.1"

Features:

• Entity inspector overlay
• Performance graphs
• Physics debug visualization
• AI state visualization
• Console commands

Feature Flags Summary

Dependency Graph

graph LR
    subgraph External["External Dependencies"]
        wgpu[wgpu]
        rapier[rapier3d]
        tokio[tokio]
        serde[serde]
    end
    
    ECS[astraweave-ecs] --> serde
    RENDER[astraweave-render] --> wgpu
    RENDER --> ECS
    PHYSICS[astraweave-physics] --> rapier
    PHYSICS --> ECS
    LLM[astraweave-llm] --> tokio
    AI[astraweave-ai] --> ECS
    AI --> LLM

Related Documentation

• Getting Started - Initial setup
• Configuration Reference - Runtime configuration
• Building from Source - Build instructions
• Contributing - Development guidelines