Home

NWBLot Engine Wiki

NWBLot is a C++ engine with a cooked-asset runtime, an ECS scene model, and a renderer using a graphics provider selected at compile time. Vulkan is the default and only implemented provider; Metal remains an unsupported future extension. See Architecture for the neutral contracts and selection boundary.

author assets -> cook typed payloads -> mount a volume -> update an ECS world -> execute CPU and GPU tasks

This wiki documents the contract on main: current build commands, file locations, APIs, and feature paths.

First Run

Use these pages first:

1. Build and Verification for tool requirements, launcher build commands, and test execution.
2. Platform and GPU Support for Windows ARM64, Vulkan requirements, texture formats, and renderer fallbacks.
3. Start Here for the source-to-runtime mental model.
4. Testbed for the interactive engine project and smoke scenes.
5. Code Reading Guide for the current implementation entry points.

Supported build targets are Windows x64, Windows ARM64, and Linux x64. Users configure and build through python -m launcher; it invokes CMake, Ninja Multi-Config, and Clang/LLVM internally. Visual Studio can open the repository as a CMake project; CMake target definitions are the source-file and project source of truth.

On Windows ARM64, native mesh shaders are disabled by default. Eligible engine mesh programs use persistent indexed raster; other draws use cooker-derived compute emulation. Native mesh shaders are an explicit pre-instance opt-in for a qualified adapter. Texture upload, ray effects, queue routing, and other Vulkan paths are selected from the active device capabilities rather than the CPU architecture.

Architecture And Runtime

• Architecture: repository domains and ownership boundaries.
• Engine Concepts: build-time, runtime, and GPU work.
• Runtime Boot: loader startup, resource mounting, and shutdown.
• Project API: project callbacks and ProjectRuntimeContext.
• Runtime and ECS: world ownership, systems, scene content, skinning, and UI.
• CPU Task Scheduler: shared CPU execution, scopes, heterogeneous placement, and profiling.
• Frame Life Cycle: one frame from project update through presentation.

Assets

• Asset Flow: end-to-end authored-to-runtime data flow.
• Asset Pipeline: staged pipeline tools, payload construction, and runtime loading.
• Filesystem: project-selectable IFilesystem mounts and the default volume backend.
• Asset Types: shader, material, texture, sampler, mesh, skin, skeleton, model, and CSG contracts.
• Cooked Volumes: staged publication, mounting, caches, and virtual paths.
• Texture Conversion: UASTC authoring and capability-driven ASTC/BC/uncompressed upload.
• FBX to NWB Conversion: mesh import and package generation.
• Shader and Material System: Slang, .bind, .surface, .bxdf, and typed material storage.
• Mesh Model and Skinning: meshlets, models, skeletons, and GPU skinning.

Rendering

• Renderer: subsystem overview and data flow.
• Renderer Frame Flow: preparation, declaration, recording, submission, and presentation.
• Renderer Feature Paths: mesh, ray, shadow, caustic, and surfel-GI selection.
• GPU Task Graph: GPU scheduler, dependency analysis, physical queues, packets, barriers, byte ranges, and recovery.
• Bindless Descriptor Heap: the required descriptor-buffer transport and shader ABI.
• HDR10 Presentation: HDR10 opt-in and SDR fallback.
• CSG and Transparency: interval rendering, AVBOIT, and camera refraction.
• Reflections: hybrid screen-space and hardware reflection routing, filtering, and statistics.

Operations

• Diagnostics and Invariants: rules enforced across engine domains.
• Diagnostics and Telemetry: logs, crash packages, timing, and frame-graph capture.
• Third-Party Packages: vendored-package policy and update metadata.

Runtime Rule

The runtime consumes cooked, typed data. Shader compilation, material schema validation, source texture conversion, and asset dependency validation belong in authoring or cook tools, not in the frame loop.