Dependency And API Surfaces

Dependency Direction

The production dependency direction is:

1. engine/include/pixelbullet defines backend-neutral source-level API.
2. engine/src implements neutral behavior and private adapters.
3. engine/integration defines repository-internal seams where ownership crosses engine domains.
4. engine/backend implements concrete backends behind neutral seams.
5. framework builds authoring, scene-play, and UI capabilities on the engine.
6. editor, tools, examples, and products compose engine and framework capabilities.

Backends do not depend on framework or executable consumers. Framework code does not depend on editor, tool, example, or product code. Products and applications do not include concrete backend headers.

Engine Surface Lanes

Lane	Ownership and consumers
engine/include/pixelbullet	Backend-neutral source-level public API for first-party workspace consumers
engine/src	Private neutral implementation and internal adapters
engine/integration	Named repository-internal cross-domain contracts
engine/backend	Concrete backend mechanics and backend test support
focused _test_support targets	Test-only access without widening production visibility

Root engine aggregates are composition targets, not dependency shortcuts. First-party production and test targets depend on the focused header, implementation, integration, or test-support target they actually use.

Integration Inventory

The policy-locked top-level engine/integration categories are:

• application
• assets
• filesystem
• graphics
• scene
• ui

Add a category only for a stable cross-domain contract with multiple first-party consumers and update the repository policy inventory with it. Generally useful backend-neutral behavior belongs in public engine API; single-owner implementation detail stays with its implementation or backend.

Important current seams include:

• engine/integration/application/imgui for sampled ImGui textures;
• engine/integration/assets for asset details and glTF import operations;
• engine/integration/graphics/{runtime,textures,meshes,materials,environments} for host binding and renderer-facing payloads;
• engine/integration/scene/{runtime,authoring,assets,rendering} for scene runtime, persistence, asset dependency, and render extraction boundaries;
• engine/integration/ui/rmlui for neutral RmlUi surface integration.

Framework-Owned Scene-Play Schema

There are no known first-party scene-play schema headers under engine/include/pixelbullet/scene.

Known public scene-play-like headers: none.

Generic scene entities, transforms, prefab resolution, serialization, and render extraction remain engine-owned. First-party gameplay schema and registration are framework-owned:

• components and registration: framework/scene_play/components:component_schema;
• missions, objectives, and interactions: framework/scene_play/{missions,objectives,interactions};
• actor-control schema: framework/scene_play/actor_control:actor_control_schema;
• attachment profiles: framework/scene_play/attachments:attachment_profile_schema;
• behavior schema: framework/scene_play/behavior:behavior_schema;
• animation graphs: framework/scene_play/animation_graph:animation_graph_schema;
• combat profiles: framework/scene_play/combat:hitscan_timing and framework/scene_play/combat:weapon_combat_profile_schema;
• weapon presentation: framework/scene_play/weapon_presentation:action_schema, framework/scene_play/weapon_presentation:cue_payload_schema, and framework/scene_play/weapon_presentation:profile_schema.

Scene registers engine-neutral components by default. CreateScenePlayScene, CreateScenePlayPrefabAsset, and RegisterScenePlayComponents supply the framework registration set. Deserialization and nested prefab resolution preserve the caller's registration set.

Domain Foundations

• Event dispatch is owned by pixelbullet/core/event.h; physical input events are under pixelbullet/input; window events are under pixelbullet/window/window_events.h; application events are limited to application lifecycle. Window events use EventCategory::Window.
• Application launch state is adapted into pixelbullet/window/window_config.h, pixelbullet/graphics/graphics_config.h, and neutral logging/filesystem configuration. GPU launch-default storage is an application persistence API only; current selection is exposed through pixelbullet/graphics/gpu_session.h and GraphicsDeviceSelectionSession.
• Logging is the neutral pixelbullet/logging/log.h surface through //engine:pixelbullet_logging.
• CPU RGBA8 images are owned by pixelbullet/image/bitmap.h through //engine:pixelbullet_image; private EXR decode support is pixelbullet/image/exr_decode_internal.h.
• Graphics resource caching is owned by pixelbullet/graphics/graphics_resource_cache.h and GraphicsResourceCache.
• Serialization foundations are pixelbullet/serialization/serialization_result.h, pixelbullet/serialization/node_file_io.h, and //engine:pixelbullet_serialization.
• Filesystem runtime lookup is public and neutral; Bazel runfiles construction remains private behind //engine/src/filesystem:runfiles_runtime_resolver, with test access through //engine/src/filesystem:runfiles_test_support.

Test Boundary

tests/engine covers supported engine behavior and API. tests/internal/engine covers private engine and backend behavior. Framework and editor tests use owner-provided focused test-support targets. A test is not justification to make an internal integration facade public or to widen production visibility.