Realism

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

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.

💎 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.

[dependencies]

realism = "0.1.0"

glam = "0.29"

🚀 API Usage Examples

1. Basic Scene Setup

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

// 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

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.

📄 License

Licensed under Apache License, Version 2.0.