realism 0.1.0

A high-performance, production-ready scene management crate for Rust game engines
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# Realism

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

[![Crates.io](https://img.shields.io/crates/v/realism.svg)](https://crates.io/crates/realism)
[![Documentation](https://docs.rs/realism/badge.svg)](https://docs.rs/realism)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

`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 `RenderCommand`s that you can consume in WGPU, Vulkan, or any other API.

## 📦 Installation


Add this to your `Cargo.toml`:

```toml
[dependencies]
realism = "0.1.0"
glam = "0.29"
```

## 🚀 Quick Start


```rust
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](docs/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.