Glossary

Glossary

This page defines common NWBLot terms in plain language. Most pages use these words without redefining them.

Asset

An asset is named content that the engine can load. Examples include shaders, materials, textures, meshes, skins, skeletons, models, and CSG shapes.

NWBLot assets are typed. A compute shader is loaded as ComputeShader, a pixel shader as PixelShader, a material as Material, and so on. Concrete shader types share the IShader interface and entry-point/bytecode storage.

Authored Asset

An authored asset is the source version of an asset. It is meant for humans and tools to edit.

Examples:

• CoolStuff/Testbed/assets/materials/mat_white_opaque.nwb
• CoolStuff/Testbed/assets/shaders/surface.bind
• CoolStuff/Testbed/assets/shaders/surface.surface
• CoolStuff/Testbed/assets/shaders/lambert.bxdf
• shared engine shader files under impl/assets/graphics

Authored assets are inputs to the asset pipeline.

Cooked Asset

A cooked asset is the runtime version of an asset. It is already parsed, validated, packed, and ready for typed loading.

Runtime code should load cooked assets from mounted volumes instead of parsing authored source files.

Asset Pipeline

The asset pipeline converts authored assets into cooked assets. In this repository that role is three executables plus a Python orchestrator:

• dependency_computer writes selected inputs and, with --include-skin-dependencies, adds textures referenced by selected UI skins
• asset_builder compiles selected .nwb files into standalone .nwba artifacts
• asset_gatherer packages those artifacts into the published graphics volume
• pipeline/launch.py, discovered as the pipeline launcher command, runs the three stages in order

The pipeline validates metadata, compiles shader language, packs binary payloads, and writes cooked volume data.

Volume

A volume is a cooked resource container. The loader mounts the graphics volume from the runtime res directory and serves asset bytes from it.

Think of a volume as the runtime asset store.

Virtual Path

A virtual path is the path used by engine systems to refer to an asset inside the asset system. It is not the same thing as arbitrary filesystem access at runtime.

Virtual paths let cooked assets refer to each other without depending on physical source locations.

Asset Codec

An asset codec knows how to load one asset type from binary payload bytes.

For example, material assets and shader assets have different runtime payload formats, so they use different codecs.

Concrete shader types have separate registered codecs, such as ComputeShaderAssetCodec and PixelShaderAssetCodec, sharing the same shader payload/serialization implementation. The concrete type validates the payload's physical stage at admission.

Asset Registry

The asset registry maps asset type names to codecs. When the asset manager receives bytes for a typed asset, the registry selects the correct loader.

Asset Manager

The asset manager is the runtime service that loads assets for project and engine systems. It reads bytes from a binary source and deserializes them through the registered typed codecs.

Loader

The loader is the common runtime executable shell. It starts crash capture, logging, frame/window state, graphics, input, telemetry, cooked volume mounting through IFilesystem, asset registration, shader archive lookup, project callbacks, and the frame loop.

Project

A project is an engine client. The current project is Testbed.

Project code supplies callbacks, creates an ECS world, registers systems, and decides what scene content exists at startup.

Project Runtime Context

ProjectRuntimeContext is the bridge from project code to engine services. It gives project code access to graphics, input, clipboard and native text-input services, asset loading, the mounted asset filesystem, the frame-owned CPU and GPU task schedulers, the loader-owned project task scope, telemetry and perf hooks, shader path resolution, and quit requests.

CPU Task Scheduler

CpuTaskScheduler is the shared CPU execution service owned by Frame. Systems own CpuTaskScope lifetimes and borrow the scheduler. Cost, priority, and main-thread targeting are independent options. Ready queues accept concurrent producers from any thread. Completion includes descendants and capture retirement. See CPU Task Scheduler.

GPU Task Scheduler

GpuTaskScheduler records and submits compiled GPU task-graph packets. It is a peer of the CPU scheduler: CPU completion does not imply GPU completion. GraphicsRuntime attaches it to the live device and detaches it before device destruction. See GPU Task Graph.

ECS

ECS means entity-component-system.

• An entity is an ID for something in the world.
• A component is data attached to an entity.
• A system runs logic over matching entities and components.

Core ECS is content-agnostic. Scene, model, skinning, render, and UI components live in implementation modules.

World

The ECS world owns entities, components, systems, message buffers, and update scheduling.

The project owns the world and ticks it from its onUpdate callback. The frame loop invokes the project callback.

Renderer System

RendererSystem is the main ECS/render pass bridge. It reads scene and render components, loads renderer-facing asset resources, prepares frame targets and pipelines, and records rendering work.

Graphics Backend

The graphics backend is the implementation of the engine graphics API. The current backend is Vulkan.

Backend code owns device selection, swapchain handling, buffers, textures, pipelines, command lists, acceleration structures, shader modules, synchronization, and GPU diagnostics.

Shader Archive

The shader archive maps cooked shader names, variants, and stages to cooked shader asset paths.

Its stage names may denote archive roles: mesh_compute maps to ComputeShader assets, while mesh_object_vertex maps to a VertexShader. Physical stages come from concrete shader types, not an authored asset.stage field.

Runtime renderer code resolves shaders through this archive instead of compiling shader source.

Material Interface

A material interface describes typed shader/material parameters. In the current material path, binding uses generated typed .bind helpers at binding 6.

Material and shader interface names must match, and stable authored instance identifiers are part of the contract.

Material Surface

A material surface is an authored .surface hook that defines a material's base color, normal, render coverage, BXDF parameters, specular F0, perceptual roughness, optical absorption tint, and shader-side refraction values. The cook wraps it with engine authoring code and the material .bind interface to generate the G-buffer pixel shader, and may also reuse it for transparent AVBOIT passes, surface dispatch for shadow optics, refractive caustics, and reflection shading.

BXDF

A BXDF is an authored .bxdf lighting model. Each material names one, the cook assigns a deterministic shading-model id per unique BXDF source, and deferred lighting or transparent accumulation dispatches to it from the material id.

Meshlet

A meshlet is a small chunk of mesh geometry prepared for GPU rendering. The renderer can use hardware mesh shaders when available or a compute/vertex emulation path when native mesh shader support is not active.

CSG

CSG means constructive solid geometry. NWBLot includes renderer support for CSG receivers and cutters, interval passes, cap rendering, and runtime transparency interaction.

AVBOIT

AVBOIT is the renderer's transparency path for order-independent transparency. It is kept consistent with the opaque material helper logic and has dedicated smoke coverage.

Reflection Trace Mode

The reflection trace mode selects how the renderer produces reflection radiance: Disabled writes identity outputs, ScreenSpace traces a hierarchical min/max depth pyramid, Hardware admits pixels into a bounded ray queue, and the default Hybrid continues unresolved or uncertain screen samples through hardware.

Optical Volume

An optical volume is authored transparent geometry with a finite surface IOR above 1.0 (nwbRefractionIorEligible in impl/assets/graphics/refraction/ior.slangi). Renderer paths transport bounded secondary transmission through it: camera refraction resolves the primary per-pixel volume, and reflections trace entry, exit, and absorption when a reflected path enters one. Coincident volume handling is shared across render paths.

Shadow Transmittance

Shadow transmittance is the RGB light that survives a shadow ray hit. Transparent occluders compute it through their material surface hook; opaque occluders block the ray.

Bindless Descriptor Heap

A single Device-owned global descriptor heap addressed by an opaque GpuDescriptorHandle. It is the only active renderer resource transport and supplies traversal geometry, raster mesh/frame data, renderer targets, scene/light inputs, and UI bindings. VK_EXT_descriptor_buffer is required; descriptor indexing remains required only for shader heap indexing. See Bindless Descriptor Heap.

Descriptor Buffer

A required VK_EXT_descriptor_buffer transport. DescriptorBufferManager owns mapped resource and sampler segments; the global heap writes driver-sized descriptors into aligned blocks and command lists select those blocks by offset. Every pipeline layout is descriptor-buffer compatible, while pipeline-local layouts carry push constants only. There is no classic descriptor-set fallback. See Bindless Descriptor Heap.

Command-List Resource-State Handoff

CommandListResourceStateHandoff carries tracked texture/buffer state, sharing, and (for exclusive resources) queue ownership between native command-list recordings. The GPU task graph uses these state seeds internally and can import them at recording boundaries; it owns ordinary packet-barrier planning and execution dependencies. A handoff alone does not synchronize queues or keep resources alive.

Queue Submission Token

A QueueSubmissionToken represents an accepted physical-queue submission and its completion timeline value. A same-queue dependency is satisfied by queue order; a distinct physical queue waits for that timeline value. Rejected submissions do not produce usable tokens.

GPU Task Graph

GpuTaskGraph declares semantic GPU tasks, resource uses, and external completions. Its compiler reads one coherent declaration revision, infers hazards, assigns physical queues, forms packets, and plans barriers and ownership handoffs, including buffer byte ranges. Recording freezes that declaration for the plan and publishes exact immutable command-list recordings. GpuTaskScheduler consumes those publications transactionally; accepted callbacks commit application-visible state, while exception cleanup terminalizes unaccepted work before rethrow. See GPU Task Graph.

GPU Task Graph Packet

A compiler-generated native-recording and submission unit containing one or more compatible graph tasks. Packets carry resolved physical-queue identity, dependencies, prologue/epilogue barriers, recording-frontier depth, and optional timing/recovery metadata.

Resource Queue Sharing

Resources imported into a graph declare concurrent or exclusive sharing. Concurrent resources remain shared between compatible families. For exclusive resources that cross queue families, the compiler emits the paired ownership transfer and the submitter establishes the accepted timeline dependency; a same-family physical-queue move needs the dependency but no family transfer.

Testbed

Testbed is the current executable project in the repository. It is the practical place to see the engine boot, create a world, load cooked assets, render a scene, and expose runtime controls.