Anvil 3D Game Engine

A modern 3D game engine written in Rust, featuring a modular architecture with ECS, physics, rendering, and debug tooling.

Features

Core Systems

• Math & Transform System - SIMD-optimized math with glam, transform hierarchy
• Time Management - Delta time tracking, fixed timestep support
• ECS (Entity Component System) - Powered by hecs for efficient entity management
• 3D Rendering - wgpu-based renderer with Metal/D3D12/Vulkan support
  • Depth buffering for correct 3D rendering
  • Colored vertex rendering
  • Perspective camera system
• Physics - Rapier3D integration for realistic physics simulation
• Asset Loading - GLTF model and texture loading support
• Debug Overlay - Real-time performance and scene statistics with egui
  • FPS and frame time tracking
  • Entity, draw call, and vertex counts
  • Custom statistics support
  • F3 key toggle
• Simulation Engine - Hour-based simulation with realtime constraints
  • Day/night cycle awareness (24-hour days)
  • Pause, resume, and speed control (0.5x, 1x, 2x, etc.)
  • Realtime budget system with timeout handling
  • Automatic recovery when simulation falls behind
  • Pluggable system architecture for custom behaviors

Architecture

The engine is organized into focused crates:

anvil/
├── crates/
│   ├── anvil_core/      # Math, time, transforms
│   ├── anvil_ecs/       # Entity component system
│   ├── anvil_render/    # Graphics rendering
│   ├── anvil_physics/   # Physics simulation
│   ├── anvil_assets/    # Asset loading
│   ├── anvil_debug/     # Debug overlay & stats
│   └── anvil_sim/       # Simulation engine
└── examples/
    └── anvil_examples/  # Example applications

Getting Started

Prerequisites

• Rust 1.70 or higher
• A GPU with Vulkan, Metal, or DirectX 12 support

Running Examples

# Minimal rendering example - rotating colored cube
cargo run --example minimal_render

# Debug overlay example - cube with performance stats
cargo run --example debug_overlay

# Simulation example - agents with day/night behaviors (console)
cargo run --example simulation

# Integrated 3D simulation - visual agents with debug overlay
cargo run --example sim_3d

# Complete city simulation - AI agents in a living world
cargo run --example city_sim

Running Tests

cargo test --workspace

Examples

minimal_render

A basic example showing a rotating colored cube with proper depth buffering.

debug_overlay

Demonstrates the debug overlay system with real-time performance metrics:

• FPS counter with color-coded status (green/yellow/red)
• Frame time in milliseconds
• Entity count, draw calls, vertices rendered
• Custom statistics (rotation, camera position)
• Toggle with F3 key

simulation

Demonstrates the simulation engine with agent behaviors (console-based):

• 3 agents (Alice, Bob, Charlie) with daily routines
• Activities change based on time of day (sleeping, working, eating, entertainment)
• Hour-based simulation progressing through 2 full days
• Budget tracking and statistics reporting
• Shows day/night cycle awareness

sim_3d

Integrated 3D simulation combining rendering, simulation, and debug overlay:

• 3 agents visualized as colored cubes
• Activity-based colors (sleeping=blue, working=red, eating=green, commuting=yellow, entertainment=magenta)
• Day/night background color transitions (sky blue during day, dark blue at night)
• Real-time simulation stats in debug panel
• Keyboard controls:
  • Space: Pause/resume simulation
  • +/-: Increase/decrease simulation speed (2x/0.5x)
  • F3: Toggle debug overlay
  • Escape: Exit
• Shows simulation time, time of day, speed, pause state, and budget statistics

city_sim

Complete living city with AI-driven agents:

• City Layout:
  • 9 homes (residential district, brown buildings)
  • 4 offices (business district, gray buildings)
  • 3 restaurants (city center, orange buildings)
  • 2 entertainment venues (purple buildings)
• 10 AI Agents with individual needs and personalities
  • Make autonomous decisions based on hunger, energy, entertainment needs
  • Follow daily routines (work, eat, entertain, sleep)
  • Respect building opening hours
• Visual Feedback:
  • Agent colors show current activity (blue=home, red=work, green=eating, magenta=entertainment)
  • Day/night background transitions
  • 3D city layout with different building heights
• Comprehensive Debug Stats:
  • Agent activity breakdown
  • Average hunger/energy/satisfaction levels
  • Simulation performance metrics
• Camera Controls:
  • WASD: Pan camera (forward/back/left/right)
  • Q/E: Rotate camera around target
  • Z/X: Zoom in/out
  • Space: Pause/resume
  • +/-: Adjust simulation speed
  • F3: Toggle debug overlay

Development Status

Current version: 0.1.0

• ✅ Core math and transform system (8 tests passing)
• ✅ ECS integration with hecs (1 test passing)
• ✅ wgpu rendering with depth buffer (1 test passing)
• ✅ Rapier3D physics integration (1 test passing)
• ✅ Debug overlay with egui (0.29)
• ✅ Simulation engine with realtime constraints (23 tests passing)
• ✅ AI decision-making system with utility-based behavior (28 tests passing)
• ✅ Complete city simulation with living world

Recent Fixes

• Fixed aspect_ratio() division by zero on window resize
• Fixed Transform.look_at() panic on degenerate inputs (zero direction vector)
• Fixed egui-wgpu lifetime issues with update_buffers() and forget_lifetime()

License

MIT OR Apache-2.0