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
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

Public engine headers live under engine/include/pixelbullet and are exported through curated engine Bazel targets.
Repo-private first-party engine bridges live under engine/private and are not part of the source-level public API surface.
Within scene-private code, engine/private/scene/common owns the shared scene model and helper layer, while scene/authoring, scene/runtime, and scene/rendering stay domain-specific.
engine/private/scene/rendering is reserved for renderer-facing subrender, shadow, and render-resource support rather than shared camera, extraction, analysis, or transform/prefab resolution surfaces.
The cleaned host/runtime graphics bridge is now part of the public engine include surface under engine/include/pixelbullet/graphics, including renderer, render-target, render-stage, render-frame-context, GPU diagnostics, and GPU-session helpers.
engine/private/graphics/runtime is now reserved for repo-private host binding plus explicit non-default runtime-support image/resource wrappers, while graphics/rendering stays the lower-level backend/resource/test-support surface.
GPU launch-default persistence is also public under engine/include/pixelbullet/application/launch_gpu_defaults.h; engine/private/application/rmlui remains private.
//engine:pixelbullet_workspace_api is the retained header-only umbrella target for pixelbullet/pixelbullet.h.
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_application, and pixelbullet_imgui.
pixelbullet_application is the application framework surface, while 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/private/... for engine-private bridge headers, and lower-level backend and plumbing 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, concrete scene-play layer, and shared 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, and world_sandbox.
world_sandbox is the dedicated graphics-first exploration product; level_slice and behavior_lab remain gameplay and logic 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 explicit subsystem deps rather than pixelbullet_workspace_api.
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_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