Realism

A high-performance, production-ready scene management crate for Rust game engines.

realism provides a robust, data-oriented foundation for managing large game worlds. It is designed to sit between your game logic and your renderer, handling the complexity of entity transforms, visibility culling, and scene organization with minimal overhead.

✨ Key Features

• 🚀 High Performance: Built on a generational index system and sparse set storage. Handles 100k+ entities with sub-millisecond overhead for transform propagation.
• 🌳 Spatial Partitioning: Integrated Dynamic Octree for incredibly fast spatial queries and frustum culling.
• 🔄 Hierarchy System: complete parent-child transform propagation with dirty flag optimization.
• 📦 Asset & Prefab Support:
  • JSON-based scene serialization/deserialization.
  • Additive scene loading (Prefabs) with root offsets.
  • Seamless integration with Archetype Asset via xxhash compatibility.
• 🎨 Renderer Agnostic: Does not enforce a specific rendering backend. Extracts a linear buffer of RenderCommands that you can consume in WGPU, Vulkan, or any other API.

📦 Installation

Add this to your Cargo.toml:

[dependencies]

realism = "0.1.0"

glam = "0.29"

🚀 Quick Start

use realism::scene::Scene;
use realism::transform::Transform;
use glam::{Vec3, Mat4};

fn main() {
    // 1. Initialize Scene
    let mut scene = Scene::new();

    // 2. Spawn Entities
    let entity = scene.spawn_with_transform(
        Transform::from_xyz(10.0, 0.0, 5.0)
    );

    // 3. Update Transforms (Game Loop)
    scene.update_transforms();

    // 4. Extract for Rendering
    // Providing a view-projection matrix automatically applies frustum culling!
    let view_proj = Mat4::perspective_rh(1.0, 1.0, 0.1, 100.0) * 
                    Mat4::look_at_rh(Vec3::ZERO, Vec3::Z, Vec3::Y);
    
    let render_commands = scene.extract(Some(view_proj));

    // 5. Draw!
    for cmd in render_commands {
        // Send `cmd.mesh_id` and `cmd.transform` to your renderer...
    }
}

📖 Architecture

Realism is built on three core pillars:

1. Entity-Component System (ECS-lite): Uses opaque EntityId handles and component pools for cache efficiency.
2. Spatial Index: A loose/dynamic Octree that automatically tracks entities with WorldBounds.
3. Render Extraction: A explicit synchronization phase that produces a safe, read-only snapshot for the renderer.

See ARCHITECTURE.md for a deep dive.

🤝 Integration

Using with Archetype Asset

realism is fully compatible with the archetype_asset crate. Both use xxh3 for asset path hashing.

1. Register asset path in Realism: scene.add_renderable(...)
2. Extract frame: let cmds = scene.extract(...)
3. In Renderer: asset_cache.get(cmd.mesh_id)

📄 License

Licensed under Apache License, Version 2.0.