Documentation

1[workspace.dependencies]
2pulsar_scenedb = { git = "https://github.com/Far-Beyond-Pulsar/SceneDB" }
3pulsar_scenedb_derive = { git = "https://github.com/Far-Beyond-Pulsar/SceneDB" }
4
5[dependencies]
6pulsar_scenedb = { workspace = true, features = ["gpu"] }
7pulsar_scenedb_derive = { workspace = true }
8
9# "gpu" is opt-in (off by default) -- enables wgpu and every #[gpu]-mirrored
10# path (SceneGpuStore, the World mirror, GPU asset storage). The storage,
11# spatial, streaming, and replication layers need nothing beyond the
12# default feature set.
13#
14# "telemetry" (also opt-in; pulls in "gpu") enables TelemetryServer -- the
15# TCP monitoring socket that streams world/gpu snapshots to dashboards such
16# as the companion scenedb_dashboard crate.

1use pulsar_scenedb::{World, Entity};
2
3struct Pos(f32, f32, f32);
4struct Vel(f32, f32, f32);
5struct Health(u32);
6
7let mut world = World::new();
8
9let e = world.spawn();
10world.insert(e, Pos(0.0, 0.0, 0.0));
11world.insert(e, Vel(1.0, 0.0, 0.0));
12
13for (entity, (pos, vel)) in world.query::<(&Pos, &Vel)>() {
14    // entity: Entity, pos: &Pos, vel: &Vel
15}
16
17// Don't need the entity handle? query_items skips fetching it.
18for (pos, vel) in world.query_items::<(&Pos, &Vel)>() {
19    // pos: &Pos, vel: &Vel
20}
21
22// Bundle: one destination archetype, every column written directly.
23world.reserve_bundle::<(Pos, Vel, Health)>(10_000);
24let e = world.spawn_bundle((Pos(0.0, 0.0, 0.0), Vel(1.0, 0.0, 0.0), Health(100)));
25
26// get_mut returns a Mut guard. On a mirrored World its #[gpu] fields
27// write through to the GPU when the guard drops.
28{
29    let mut health = world.get_mut::<Health>(e).unwrap();
30    health.0 = 50;
31}

1use pulsar_scenedb::{SpatialCell, Aabb, Handle};
2
3// A spatial cell is a page of entities with six dedicated f32 columns
4// for AABB min/max per axis. No per-entity iteration in queries.
5let mut cell = SpatialCell::new(256).unwrap();
6
7let handle: Handle = cell.alloc(Aabb {
8    min: [0.0, 0.0, 0.0],
9    max: [1.0, 1.0, 1.0],
10}).unwrap();
11
12// Query scans directly over the column arrays, no allocation.
13let mut results = vec![0u32; cell.rows_in_use() as usize];
14let hit_count = cell.query_aabb(
15    &Aabb { min: [-1.0; 3], max: [2.0; 3] },
16    &mut results,
17);
18// results[0] == 0 (the handle's row passed the query)

1use pulsar_scenedb::gpu::grid::{StreamingGrid, GridConfig, CellCoord, Domain, StreamingBudget};
2
3let mut grid = StreamingGrid::new(
4    GridConfig {
5        cell_width: 100.0,
6        margin_radius: 150.0,
7        pad_fraction: 0.10,
8        hysteresis: 20.0,
9    },
10    StreamingBudget {
11        vram_hlod_budget: 256_000_000,
12        vram_geometry_budget: 1_000_000_000,
13        max_materialized_cells: 1024,
14        proxy_mesh_bytes: 4096,
15        mean_cell_geometry_bytes: 1_048_576,
16    },
17    &[], // inner region classes
18).unwrap();
19
20grid.materialize(CellCoord { x: 0, z: 0 });
21
22// Two players: overlapping load areas work correctly. A cell promotes
23// if ANY player is close enough and demotes only when ALL have left.
24grid.classify(&[
25    Aabb { min: [-10.0, -10.0, -10.0], max: [10.0, 10.0, 10.0] },
26    Aabb { min: [490.0, -10.0, -10.0], max: [510.0, 10.0, 10.0] },
27]);
28
29let transitions = grid.take_transitions();
30
31// Pin a cell to keep it loaded regardless of player positions.
32grid.pin(CellCoord { x: 5, z: 3 }, Domain::Inner);
33grid.unpin(CellCoord { x: 5, z: 3 });

1use pulsar_scenedb::{World, gpu::{GpuMirrorHandle, SceneGpuStore}};
2use pulsar_scenedb_derive::SceneStore;
3use std::sync::Arc;
4
5/// #[gpu(layout = packed)] interleaves every #[gpu] field into one SSBO
6/// row instead of one buffer per field.
7#[derive(SceneStore, Clone, Copy)]
8#[gpu(layout = packed)]
9struct Instance {
10    #[gpu(mirror = Once)]    // written on first insert, never again
11    model: [f32; 16],
12    #[gpu(mirror = Once)]
13    normal_mat: [f32; 16],
14    #[gpu]                   // DirtyTracked (the default): re-synced on change
15    mesh_id: u32,
16}
17
18// Setup, once. No register_gpu_columns call needed -- the first insert of
19// a #[gpu]-bearing type registers its columns for you.
20let store = Arc::new(SceneGpuStore::new(&ctx, cfg));
21let mut world = World::new_with_gpu_mirror(GpuMirrorHandle::new(Arc::clone(&store), queue.clone()));
22
23let entity = world.spawn();
24world.insert(entity, Instance { model, normal_mat, mesh_id: 7 });
25// Every #[gpu] field above already wrote or dirty-marked itself inside
26// insert() -- no manual dispatch call.
27
28// Once per frame, after your simulation step:
29world.flush_gpu_mirror(&queue);

1// Ahead of a known-size batch (streaming a sublevel, spawning a wave):
2world.reserve_gpu_mirror_capacity(&queue, 10_000)
3    .expect("mirror attached")
4    .expect("reserve succeeds");
5
6// At a natural boundary after a peak-then-drop (not every frame --
7// this is a real GPU-to-GPU copy, same cost as growth):
8world.shrink_gpu_mirror_to_fit(&queue, highest_live_entity_index, 1.5);

1use pulsar_scenedb_derive::SceneStore;
2
3/// A material component with mixed storage locations:
4///   - color, roughness, metallic → CPU + GPU (dirty-tracked mirror)
5///   - name → CPU only (no GPU mirror, no VRAM cost)
6#[derive(SceneStore)]
7#[repr(C)]
8pub struct Material {
9    #[gpu]                        // CPU + GPU, DirtyTracked
10    pub albedo: [f32; 4],
11
12    #[gpu(mirror = DirtyTracked)] // CPU + GPU, explicit
13    pub roughness: f32,
14
15    #[gpu]                        // CPU + GPU, DirtyTracked
16    pub metallic: f32,
17
18    // No #[gpu]: CPU only. No VRAM, no dirty tracking.
19    pub name: [u8; 64],
20}

1use pulsar_scenedb_derive::Replicate;
2use pulsar_scenedb::ReplicationEncoding::{self, *};
3use pulsar_scenedb::ReplicationCondition::{self, *};
4
5/// A player state component with per-field replication control.
6#[derive(Replicate, Default)]
7struct PlayerState {
8    /// Full transform: replicated every frame as raw Pod bytes.
9    #[replicate(encoding = Pod, condition = Always)]
10    position: [f32; 3],
11
12    /// Health: only sent to non-owning simulated proxies.
13    #[replicate(encoding = DeltaCompressed, condition = SimulatedOnly)]
14    health: f32,
15
16    /// Ammo: only relevant to the owning client.
17    #[replicate(encoding = Pod, condition = AutonomousOnly)]
18    ammo: u32,
19
20    /// Sent once at spawn, never again.
21    #[replicate(encoding = Serialized, condition = InitialOnly)]
22    inventory: Vec<Item>,
23
24    /// One-shot event, delivered via the RPC channel.
25    #[replicate(encoding = Event, condition = Multicast)]
26    on_damage_taken: DamageEvent,
27}
28
29let mut registry = ReplicationRegistry::new();
30PlayerState::register_replication(&mut registry);

1use std::any::Any;
2use pulsar_scenedb::{SceneDb, Subsystem, World};
3use pulsar_scenedb::gpu::{SimulateA, SimulateB, RetiredPhase};
4
5struct PhysicsSubsystem { gravity: [f32; 3] }
6
7impl Subsystem for PhysicsSubsystem {
8    fn name(&self) -> &'static str { "physics" }
9
10    fn simulate_a(&mut self, _world: &mut World, _witness: &SimulateA) {
11        // gameplay mutation is permitted here
12    }
13
14    fn simulate_b(&mut self, _world: &mut World, _witness: &SimulateB) {
15        // physics writeback
16    }
17
18    fn boundary(&mut self, _phase: &RetiredPhase) {
19        // after retire, before compact
20    }
21
22    fn as_any(&self) -> &dyn Any { self }
23    fn as_any_mut(&mut self) -> &mut dyn Any { self }
24}
25
26let mut db = SceneDb::new();
27db.register_subsystem(PhysicsSubsystem { gravity: [0.0, -9.8, 0.0] });
28
29db.step(); // SimulateA -> SimulateB across every subsystem; flushes the World mirror if attached
30
31let physics = db.subsystem_mut::<PhysicsSubsystem>().unwrap();
32physics.gravity = [0.0, -1.6, 0.0];
33
34// By-name path for scripts/events: invoke a #[subsystem_method] through
35// the reflection registry.
36db.dispatch("physics", "apply_impulse", vec![Box::new(42u64), Box::new([1.0f32, 0.0, 0.0])])
37    .expect("dispatch succeeds");

1use pulsar_scenedb::{RelationIndex, Entity};
2
3struct PortalLink { linked_to: Entity }
4
5// Rebuild once per boundary: scan every PortalLink in the world and
6// classify each into a confirmed pair, unmatched, or a conflict.
7let mut index = RelationIndex::new();
8index.build::<PortalLink>(&world, |link| link.linked_to);
9
10let view = index.view();
11// view.pairs:     &[(Entity, Entity)] -- reciprocal links, emitted once each
12// view.unmatched: &[Entity]           -- target has no link back (or no component)
13// view.conflicts: &[ConflictEntry]    -- target reciprocates with someone else;
14//   each entry carries source, target, and ConflictReason::NotReciprocated(
15//   what_the_target_links_to_instead)

1// FrameDriver owns one frame's progression. Each transition consumes the
2// previous witness, so reordering or skipping a phase won't compile.
3
4let sim_a = driver.begin();                       // SimulateA -- gameplay mutation
5let sim_b = sim_a.end();                          // SimulateB -- physics writeback
6let harvest = sim_b.end();                        // HarvestPhase -- read-only snapshots
7let boundary = harvest.end();                     // BoundaryPhase
8let (retired, _drained) = boundary.retire(store, cells);  // RetiredPhase
9let stats = retired.compact(store, cells).sync(store, cells); // SyncStats
10
11// store/cells are the caller's SceneGpuStore and CellSlot slices.
12// SceneDb's step()/step_gpu() drive exactly this chain for you.

1use pulsar_scenedb::{World, ChangeTracker, CpuSimulateWitness};
2
3let mut world = World::new();
4let mut tracker = ChangeTracker::new();
5let witness = CpuSimulateWitness::new();
6
7let delta = witness.run_tracked(&mut world, &mut tracker, |world, tracker| {
8    // Systems write to the world and track changes here.
9    let entity = world.spawn_tracked(tracker);
10    world.insert_tracked(entity, 100.0f32, tracker);
11});
12
13// delta contains spawned entities, despawned entities, and component
14// changes, each already encoded via the field's Replicable impl.

1use pulsar_scenedb::{Snapshot, RelevanceSet};
2
3// Full world state.
4let full = Snapshot::capture_full(&world, &registry, current_frame);
5
6// Only entities relevant to a specific client.
7let relevant = Snapshot::capture_relevant(&world, &registry, &relevance, current_frame);
8
9// Restore into a World, e.g. a client resyncing after a connection gap.
10let mut client_world = pulsar_scenedb::World::new();
11full.restore_to_world(&mut client_world, &registry).unwrap();