Start Here

Start Here

This page explains NWBLot in the simplest order. Other pages go deeper after these ideas are clear.

What NWBLot Is

NWBLot is a C++ engine that loads cooked assets, creates an ECS scene, and renders it through a Vulkan graphics backend.

The build supports Windows x64, Windows ARM64, and Linux x64. Run builds from the repository root through python -m launcher (python3 on Linux):

python -m launcher testbed --build-only --config opt
python -m launcher testbed --config opt

The first command configures and builds Testbed and its assets; the second also starts it. See Build and Verification for the host toolchain, all-target and focused builds, and test execution. See Platform and GPU Support for Vulkan capability requirements and fallback behavior.

The engine is built around one important rule:

runtime code consumes cooked data, not raw authoring files

That means source files are prepared before the game or Testbed starts. The runtime then works with binary assets that already have known types, validated layouts, compiled shader bytecode, and stable virtual paths.

The Simplest Flow

The complete engine can be read as five steps:

1. Artists or programmers author source assets.
2. The asset pipeline converts those assets into cooked volume data.
3. The loader starts the runtime and mounts the cooked volume.
4. Project code creates an ECS world.
5. Renderer systems turn that world into GPU commands.

In one line:

source -> cook -> load -> simulate -> render

In chart form:

flowchart LR
    Source["Source assets"]
    Cook["Cook"]
    Load["Load typed assets"]
    Simulate["Simulate ECS world"]
    Render["Render through Vulkan"]

    Source --> Cook --> Load --> Simulate --> Render

Loading

What Each Step Means

Source

Source assets are human-authored files. Examples include:

• .nwb metadata files
• .tex raw UASTC texture sidecars
• .slang shader files
• .slangi shared shader include files
• .bind material/shader interface files
• .surface material surface hook fragments
• .bxdf deferred lighting model fragments
• mesh, model, skin, skeleton, and CSG authoring data

These files live under shared engine asset roots such as impl/assets and project roots such as CoolStuff/Testbed/assets.

Cook

The asset pipeline validates source assets and writes runtime data. dependency_computer, asset_builder, and asset_gatherer compile shader language, check material metadata, pack typed binary payloads, and publish cooked volume segments.

The important idea is that failures should happen here when possible. If a material layout is wrong, a shader interface does not match, or an asset dependency is invalid, the pipeline should catch it before runtime.

Load

The loader starts the engine process. It initializes crash handling, logging, graphics, input, telemetry, resource mounting, asset codec registration, and shader archive lookup.

The runtime then loads assets through AssetManager. The asset manager does not guess file formats. It asks the asset registry for the codec that matches the cooked asset type.

Simulate

Project code creates an ECS world. The world owns entities, components, systems, message buffers, and update scheduling.

The Testbed project creates a scene with camera state, renderable objects, lights, skinned content, ground geometry, UI controls, and renderer systems.

Render

The renderer reads ECS state and cooked assets. It prepares frame targets, material pipelines, mesh resources, skinning work, CSG state, transparent passes with camera refraction, shadows, refractive caustics, reflections, and composite work.

The graphics backend then executes command lists through Vulkan.

What To Read Next

Read Glossary if the terms are unfamiliar.

Read Engine Concepts for a simple map of the main engine parts.

Read Asset Flow and Frame Life Cycle when you want the first detailed walkthroughs.

Read CPU Task Scheduler and GPU Task Graph for the frame-owned execution services.

Read Platform and GPU Support before qualifying a new GPU or changing an architecture-sensitive renderer path.