realism 0.1.5

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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# Realism

**The High-Performance, Scoped Scene Graph for Modern Rust Engines.**

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

`realism` is a data-oriented scene management library designed for engines requiring high-density entity counts and seamless world-scale streaming. It provides the high-performance "glue" between simulation and rendering hardware.

---

## ⚡ Performance Matrix (Latest Benchmarks)

*Benchmarks performed on **Intel Core i5-11400F**, **Intel Arc A380**, **16GB DDR4 RAM**.*

| Operations (100k Entities) | Throughput / Mean Time | Optimization Path |
| :--- | :--- | :--- |
| **Transform Propagation** | **1.36 ms** | SIMD Vectorized (4x Batch) |
| **Spatial Selection (Visible)** | **760 µs** | Dynamic Octree (65k Cull) |
| **Entity Spawn/Despawn** | **O(1)** | Generational Dense List |
| **Component Access** | **O(1)** | Cache-Optimized Sparse Set |

---

## 💎 Core Value Propositions


*   **⚡ SIMD-Accelerated Math**: Leveraging Nightly Rust's `portable_simd`, Realism batches transform composition to process 100,000+ entities with unparalleled speed.
*   **🌍 World-Scale Streaming**: Integrated async chunk management for seamless world loading/unloading, built-in memory monitoring, and thread-safe asset integration.
*   **🌳 Dynamic Spatial Index**: A loose/dynamic Octree handles frustum culling and spatial queries, ensuring only visible data reaches your GPU.
*   **🏗️ Engine Agnostic Architecture**:
    *   **Generic Physics Bridge**: Decoupled traits for Rapier, Jolt, or custom physics synchronization.
    *   **Render Extraction**: Extracts a pure command stream (`RenderCommand`) ready for Vulkan, WGPU, or Dx12.
*   **📦 Industrial-Grade Serialization**: Native JSON and binary support for world snapshots and modular prefabs.

---

## ⚙️ Installation


Add to your `Cargo.toml`. To enable SIMD optimizations, use a **Nightly Rust** toolchain.

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

---

## 🚀 API Usage Examples


### 1. Basic Scene Setup

```rust
use realism::Scene;
use realism::transform::Transform;
use glam::Vec3;

let mut scene = Scene::new();

// Spawn a hierarchy: Parent (0, 10, 0) -> Child (5, 0, 0)
let parent = scene.spawn_with_transform(Transform::from_xyz(0.0, 10.0, 0.0));
let child = scene.spawn_with_transform(Transform::from_xyz(5.0, 0.0, 0.0));
scene.attach(child, parent);

// SIMD Propagation computes World Matrices for the entire hierarchy in batches of 4
scene.propagate_transforms();

let world_pos = scene.transform(child).unwrap().cached_world_transform.w_axis.truncate();
assert_eq!(world_pos, Vec3::new(5.0, 10.0, 0.0));
```

### 2. Physics & Render Extraction

```rust
// 1. Sync transforms with your physical world (Rapier, Jolt, etc.)
scene.sync_physics(&mut physics_engine);

// 2. Extract visible command stream for the current frame
let view_proj = camera.view_projection();
let draw_calls = scene.extract(Some(view_proj));

renderer.draw(draw_calls);
```

### 3. World-Scale Streaming

```rust
use realism::streaming::{ChunkManager, ChunkLoader};

let mut manager = ChunkManager::new(500.0, 1000.0); // Load radius, Unload radius
manager.update(camera.position());

for id in manager.chunks_to_load() {
    loader.load_chunk_async(id, format!("assets/chunks/{}.json", id));
}

// Poll background thread results and integrate into Scene
let loaded = loader.poll();
realism::streaming::integrate_chunks(&mut scene, &mut manager, loaded);
```

---

## 🛡️ Architecture

For a deep dive into the internal sparse set storage, Octree heuristics, and SIMD batching logic, refer to the [Internal Guide](docs/ARCHITECTURE.md).

## 📄 License

Licensed under Apache License, Version 2.0.