What Lives Here

Hand-authored documentation pages under docs/
Generated API and source documentation for the public include tree under engine/include/pixelbullet plus the implementation tree under engine/src
Durable module-local notes that are useful to keep alongside the code they describe

Documentation Map

Guides

Repo development and distribution model
Engine architecture and ownership model
First-person weapon presentation model
Graphics roadmap and asset contract
Logging workflow

Module Notes

The graphics and shader pipeline notes live in the Graphics Module page generated from engine/src/graphics/module_notes.md.

API Surface

The repo distribution model lives in Repo development and distribution model; engine source hierarchy, integration ownership, backend ownership, and staged migration direction live in Engine architecture and ownership model.
Public engine headers live under engine/include/pixelbullet and are exported through curated engine Bazel targets.
Repo-internal first-party engine integration contracts live under engine/integration and are not part of the source-level public API surface.
Asset-owned authoring detail inspection and external glTF import execution live under engine/integration/assets, scene runtime contracts live under engine/integration/scene/runtime, authoring persistence and validation contracts live under engine/integration/scene/authoring, shared scene asset helpers such as mesh bounds live under engine/integration/scene/assets, and renderer-facing subrender and shadow contracts live under engine/integration/scene/rendering.
The cleaned host/runtime graphics API is now part of the public engine include surface under engine/include/pixelbullet/graphics, including renderer, backend-neutral render-target/stage declarations, backend-neutral frame submission, and backend-neutral GPU diagnostics/session helpers; public window declarations are backend-neutral as well.
Public engine headers are backend-neutral and must not include Volk or expose Vulkan handles/constants; Vulkan result helpers, API-version packing, physical-device selection diagnostics, device/surface/instance plumbing, graphics runtime state, frame flow, render-stage runtime, render-target runtime internals, and backend implementation sources now live in focused packages under engine/backend/graphics/vulkan.
engine/integration/graphics/runtime owns repo-internal host binding, engine/integration/graphics/textures owns the neutral repo-internal texture-loading facade used by editor and UI surfaces, pixelbullet/graphics/mesh_types.h owns render-facing mesh payload value types, engine/integration/graphics/meshes owns the neutral repo-internal mesh payload loading facade used by render backends, and engine/integration/graphics/materials owns the neutral repo-internal render-material payload facade used by Vulkan scene rendering. Vulkan Image2D loading, mesh buffer upload, and render-material payload loading stay hidden behind focused backend factory/resource code.
engine/backend/graphics/vulkan is a package family: core, devices, commands, descriptors, buffers, images, pipelines, passes, presentation, runtime, scene, diagnostics/gpu_listing, ui/rmlui, and ui/imgui own low-level Vulkan backend/resource/test-support headers and implementation sources, including Image/Image2D, GLFW-to-Vulkan surface creation, the texture backend factory, graphics runtime state, frame flow, render-stage runtime, render-target runtime internals, Vulkan-specific render-device runtime access, scene render-resource resolution, Vulkan scene subrender runtimes, hidden-window GPU-listing backend factory, Vulkan RmlUi surface drawing runtime, and Vulkan ImGui descriptor/renderpass/texture submission runtime. Include paths remain rooted at pixelbullet/backend/graphics/vulkan/..., C++ types live under pixelbullet::backend::graphics::vulkan, and the root backend package retains only forward declarations plus source inventory aggregation. engine/src/graphics remains the neutral Graphics/RenderDevice facade plus public render-target/stage declarations, narrow validation helpers, and neutral texture backend seam, engine/src/window owns GLFW window/input lifecycle, neutral input/event callback routing, and window callback state without Vulkan surface helpers, engine/src/scene remains the integration adapter/registration/extraction layer for scene rendering and owns neutral scene subrender runtime interfaces that create Vulkan drawing through focused backend factory seams, and engine/private has been drained and should not be reintroduced.
Application startup adapts application specification and launch options into neutral filesystem, window, graphics, and logging config before constructing lower-level systems; public window/graphics and Vulkan backend code consume WindowConfig, GraphicsConfig, GraphicsDeviceSelection, and GraphicsApplicationInfo rather than application-shaped config. GPU launch-default persistence is public under engine/include/pixelbullet/application/launch_gpu_defaults.h as application-owned persistence only; the current-session snapshot lives in engine/include/pixelbullet/graphics/gpu_session.h as GraphicsDeviceSelectionSession, and engine/src/graphics must not depend on application launch-default state. engine/src/application owns CLI flow, user-facing GPU-listing output, and saved-default semantics, while engine/src/graphics owns the neutral GPU diagnostics/backend session seam and creates Vulkan GPU enumeration through the focused backend factory under engine/backend/graphics/vulkan/diagnostics/gpu_listing. RmlUi surface integration lives under engine/integration/ui/rmlui; engine/src/ui/rmlui owns RmlUi lifecycle through a neutral runtime interface and creates Vulkan drawing through engine/backend/graphics/vulkan/ui/rmlui. Sampled ImGui texture integration lives under engine/integration/application/imgui; public application ImGui headers live under engine/include/pixelbullet/application/imgui with includes rooted at pixelbullet/application/imgui, generic application Layer lifecycle remains UI-toolkit-neutral through hooks such as OnUiFrame, engine/src/application/imgui owns the public/application ImGui adapter, context, settings, and appearance through neutral runtime and platform backend seams, engine/src/application/imgui/glfw owns the ImGui GLFW platform backend handoff, and Vulkan descriptor/renderpass/texture submission is created through engine/backend/graphics/vulkan/ui/imgui.
Event dispatch/result types are core foundation under pixelbullet/core/event.h; key/mouse events are input-owned under pixelbullet/input, window lifecycle events are window-owned under pixelbullet/window/window_events.h, and application owns only application lifecycle events plus layer routing.
Native GLFW window handles are not public API; ImGui and the Vulkan backend use a focused engine/src/window internal access seam when they need the current GLFW window.
//engine:pixelbullet_workspace_api is the retained header-only umbrella target for pixelbullet/pixelbullet.h; umbrella composition and public-header enumeration live under engine/include/pixelbullet, while Doxygen owns documentation inventory aggregation.
The engine implementation surface is split across subsystem libraries such as pixelbullet_core, pixelbullet_filesystem, pixelbullet_assets, pixelbullet_scene, pixelbullet_window, pixelbullet_audio, pixelbullet_graphics, pixelbullet_logging, pixelbullet_application, and pixelbullet_imgui.
pixelbullet_logging is the neutral logging foundation, pixelbullet_application is the application framework surface, and pixelbullet_imgui is the optional Vulkan/GLFW ImGui integration layer.
The source-level public header surface lives under engine/include/pixelbullet. The only supported public include form is pixelbullet/<subsystem>/<snake_case>.h. First-party repo code uses pixelbullet/integration/... for engine integration contracts and pixelbullet/backend/graphics/vulkan/... for Vulkan backend contracts; runtime orchestration headers remain internal under engine/src.
platform/authoring, platform/scene_play, and platform/ui are first-party internal platform layers shared by the editor, products, and examples, not external distribution surfaces.
platform/authoring owns the reusable non-UI authoring core; editor/ is the authoring client and UI shell built on top of it.
platform/scene_play owns the canonical runtime client, application layer adapter, shared presentation frame, and presentation spine used by the editor, products, and examples.
platform/ui owns capability-based runtime-UI services rather than separate live-vs-authoring facades.
products/ is the home for first-party playable builds that consume that platform, currently including level_slice, behavior_lab, combat_lab, and world_sandbox.
world_sandbox is the dedicated graphics-first exploration product; level_slice, behavior_lab, and combat_lab remain gameplay, logic, and actor/combat pressure surfaces respectively.
The editor, products, and curated examples stay application-focused; their source trees are not treated as primary API documentation surfaces, and first-party code should use direct includes plus focused subsystem deps rather than pixelbullet_workspace_api or root engine runtime aggregates.
tests/engine covers first-party engine API and behavior, while tests/internal/engine is the intentional home for engine-private coverage.

Build And Verification Entry Points

The repository is Bazel-first. The main entrypoints are:

bazel test //:fast_ci_tests
bazel build --config=debug //engine:pixelbullet_workspace_api
bazel run //tools/dev:refresh_compile_commands
bazel build //doxygen:html

The generated HTML output is written under bazel-bin/doxygen/html/.

Optional slower validation suites:

bazel test //:desktop_smoke_tests
bazel test //:extended_regression_tests
bazel test //:artifact_smoke_tests
bazel test //:repo_policy_tests
bazel test //:repo_audit_tests

Local CI Parity

PixelBullet supports local job parity, not full GitLab runner emulation.

Windows/MSVC:

.\ci\bootstrap_wsl.ps1
.\ci\local.ps1 fast_ci
.\ci\local.ps1 desktop_smoke
.\ci\local.ps1 extended_regression
.\ci\local.ps1 -Wsl fast_ci

Bash or WSL:

bash ci/bootstrap_wsl.sh
bash ci/local.sh fast_ci
bash ci/local.sh desktop_smoke
bash ci/local.sh extended_regression

Use the bootstrap script when Ubuntu/WSL does not already have Bazelisk on PATH. Add -InstallSystemPackages or --install-system-packages if you want the wrapper to install the broader Ubuntu toolchain with apt-get.

Packaging Notes

PixelBullet currently treats the editor runtime bundle as the only intentional packaged output:

//packaging:bundle_editor_release for the editor runtime bundle

The per-app runtime bundle targets remain available for first-party local workflows:

//packaging:bundle_level_slice_release for the level_slice runtime bundle
//packaging:bundle_behavior_lab_release for the behavior_lab runtime bundle
//packaging:bundle_combat_lab_release for the combat_lab runtime bundle
//packaging:bundle_world_sandbox_release for the world_sandbox runtime bundle

Those runtime bundle targets, including their _debug variants, should still be treated as host-specific developer artifacts rather than portable distributions.

The legacy aggregate Bazel targets //engine:pixelbullet_foundation and //engine:pixelbullet_engine are no longer part of the supported surface.

Theme Integration

This site uses a pinned upstream doxygen-awesome-css dependency through Bazel, plus a small repo-local header and logo layer under doxygen/theme/ to preserve the PixelBullet presentation. The plain Doxygen helper reuses the same staged theme assets instead of keeping a vendored theme copy in the workspace.

Table of Contents