This page defines physical ownership. Dependency and visibility rules are in Dependency and API Surfaces; executable and content classifications are in the surface taxonomy.

Engine

Public engine API

engine/include/pixelbullet owns backend-neutral engine concepts, value types, and facades intentionally available to first-party consumers. Public includes use pixelbullet/<domain>/<snake_case>.h. Public headers do not expose Vulkan, Volk, GLFW native handles, or backend implementation types.

This is a source-level API, not a frozen SDK. The root //engine:pixelbullet_workspace_api target compiles the umbrella header; normal first-party code uses focused headers and subsystem targets.

Neutral implementation

engine/src owns private implementations of public facades, backend-neutral runtime state, and focused adapters. Implementations consume exact subsystem contracts rather than routing through root runtime aggregates.

Neutral foundation ownership is split by purpose:

core: event dispatch and small general-purpose primitives;
time and math: policy-light time and numeric helpers;
filesystem: logical-path resolution and native file access;
serialization: Node, result types, YAML and binary IO support;
image: packed CPU RGBA8 bitmap storage and image codecs;
logging: process/session logging;
audio, input, physics, and window: their neutral runtime domains;
graphics: backend-neutral rendering concepts and resource facades;
assets and scene: authored asset formats and neutral scene data/runtime integration respectively.

Repository-internal integration

engine/integration owns narrow contracts shared by engine implementation, frameworks, BulletSketch, products, examples, and tests without promoting those contracts into public engine API. It is not a general private-header bucket.

Concrete backend

engine/backend owns backend-specific implementation. The current production backend is the package family under engine/backend/graphics/vulkan. Backend code may use Vulkan directly; production framework, editor, product, and example code may not include it.

Framework

framework is the first-party layer above engine, not an operating-system abstraction:

framework/authoring owns reusable document, asset, validation, and non-UI authoring workflows.
framework/scene_play owns gameplay schema, runtime orchestration, controllers, simulation, presentation, inspection, and the application adapter for authored scene play.
framework/ui owns reusable runtime UI values, documents, rendering inputs, and RmlUi-facing services.

Root framework facade targets are the preferred concrete-application boundary when a consumer does not need a named leaf package. Rich editor and test code may use exact leaf targets when the ownership relationship is intentional.

Editor And Executable Consumers

editor owns BulletSketch application composition and editor-specific UI, workspace, document, preview, material, diagnostics, and launch services. It builds on framework/authoring, uses ScenePlayClient for in-process play, and does not make authored assets depend on editor implementation.

tools/scene_runner owns generic external authored-scene execution. Examples own only their teaching-specific application composition. A product owns its game rules, session lifecycle, interactive adapters, assets, package, and composition root.

Naming

Core utilities and neutral policy-light modules use STL-adjacent lower-case functions where established. Engine domain APIs, frameworks, editor, and products use PascalCase functions. New camelCase C++ APIs are not introduced; serialized keys, shader ABI names, macros, third-party APIs, and user-visible text retain their required spelling.

Focused semantic modules are preferred over a catch-all foundation/ or resources/ directory.