Engine internals

The white-box properties that make Euca a world engine sit on top of a real game engine: an archetype ECS, a real-time PBR renderer, and a custom physics solver. This page is the honest map of what’s actually implemented — what runs by default, what’s opt-in, and what’s built but not yet wired into the default frame.

​

The ECS core

The world is an archetype ECS (euca-ecs), built for throughput:

• Columnar (SoA) storage — components of the same archetype live in contiguous columns, so systems iterate cache-friendly arrays.
• Generational entities — an entity is an index + a generation; freed slots are recycled with a bumped generation so stale handles are detected, never silently reused.
• Opt-in sparse sets — rarely-attached components can be stored sparsely to avoid archetype churn.
• Rayon-parallel queries — par_for_each shards iteration across cores in 2048-row chunks (falling back to sequential below ~16K rows or for sparse components).
• Change detection — per-row change ticks drive Changed<T> filters.
• Bulk ops — spawn_batch for fast mass spawning; a Commands buffer defers structural mutation so it can’t race in-flight queries.
• Parallel scheduler — systems are topologically ordered and run concurrently when their component access doesn’t conflict; a debug-only access guard catches violations with zero release-build cost.
• Double-buffered events — events live two ticks so producers and consumers at different points in the frame both see them.

This is the substrate behind the world-as-a-table view and the performance numbers.

​

Rendering

Euca ships a real-time physically-based forward renderer (euca-render) over a generic RHI (euca-rhi), with two backends: wgpu 27 (cross-platform, default) and a hand-written native Metal backend (macOS). Live by default — what the frame method actually executes:

• PBR — Cook-Torrance specular (GGX distribution, Smith geometry, Schlick Fresnel).
• Shadows — 3-cascade cascaded shadow maps (2048² depth array) with 16-tap rotated-Poisson PCF filtering.
• Anti-aliasing — MSAA 4× + FXAA.
• HDR + post — Rgba16Float HDR target, bloom, ACES tonemapping, color grading, vignette.
• SSAO, separate transparent and water passes, an editor outline pass, and a velocity/motion-vector pass.

Opt-in (built, tested, off by default): TAA, motion blur, depth-of-field, screen-space reflections, volumetric fog, image-based lighting (split-sum) + spherical-harmonic probes, HZB occlusion culling, GPU particles, and MetalFX upscaling (Metal backend only). Headless rendering to PNG is real, by two paths: the visual_check example renders the full PBR pipeline to an offscreen target and saves a PNG, and the dataset CaptureRenderer renders flat-shaded geometry plus ground-truth segmentation and depth channels (the answer-key’s visual side).

​

Physics

euca-physics is a custom, dependency-free 3D physics engine (no Rapier/PhysX):

• Solver — fixed-timestep semi-implicit Euler with a two-stage constraint solve: position correction then an iterated sequential-impulse (PGS) velocity solve with cross-frame warm-starting, full world-space inertia tensors, and union-find contact islands solved in parallel.
• Broad phase — a uniform spatial-hash grid (large bodies handled all-pairs).
• Narrow phase — AABB/OBB boxes (SAT + clipped manifolds), spheres, capsules, convex hulls (SAT + clip), static triangle meshes (BVH + per-triangle clip), and compound colliders.
• Articulation — reduced-coordinate articulation (RNEA + Cholesky) for serial fixed-base chains of 1-DoF revolute/prismatic joints, plus a free-floating 6-DoF body, with motors, limits, link colliders, and contacts; alongside maximal-coordinate joints (distance/ball/ revolute with motors and limits).
• Controllers — a kinematic capsule character controller (ground probe, coyote time) and a raycast-suspension vehicle controller (engine curve, auto gears).
• Queries — raycast, overlap, and sweep.
• Determinism — the solver is run-to-run bit-identical within the same binary, gated by a committed golden-hash test.