PixelBullet is a controlled first-party source workspace. Engine libraries, frameworks, BulletSketch, the generic scene runner, examples, authored content, tests, and packaging rules evolve together under one Bazel graph.

The surface taxonomy is authoritative for the distinction between tools, examples, labs, fixtures, and products. This page defines workspace and distribution posture.

Supported Model

The primary development model is a source workspace, or a closely related branch or fork that builds the same engine, framework, editor, runtime, and content graph. Public engine headers are deliberate source-level seams for first-party consumers; they are not a frozen external SDK or ABI promise.

The repository may eventually support an installed editor/runtime distribution. That would be a separately versioned deliverable with an explicit consumer, runtime match, validation contract, and support policy. It must not emerge accidentally from the presence of public headers.

Shipped products are a third distribution lane. A product package is owned by that product and is not evidence that the engine itself needs a public SDK.

Current Distribution Contract

The editor runtime bundle is the only intentional packaged output. It contains BulletSketch and the generic pixelbullet-scene-runner as sibling binaries, editor assets, and the narrow shared runtime-core allowlist. It does not contain the complete shared content depot.

The authored labs are workspace content with no dedicated application or package. The executable galleries are buildable with shared runfiles but have no gallery-specific bundles. See Packaging and Distribution for the concrete bundle layout and validation surface.

API And Artifact Interpretation

engine/include/pixelbullet is the source-level public engine header seam.
//engine:pixelbullet_workspace_api is a header compile surface, not a packaged SDK.
engine/integration is a repository-internal contract surface.
A Bazel target is not automatically a supported artifact.
A packaged artifact is not automatically a product.
An application is an executable form, not a semantic category.

Every proposed long-lived API or artifact must identify its consumer, owner, support level, validation lane, and removal condition. If those facts are not known, keep the surface inside the controlled workspace model.

Compatibility Posture

Source-level APIs are curated but not frozen. Ownership-correct moves, renames, and demotions are allowed when their first-party consumers and policy checks are updated together. Serialized authored formats and shipped package layouts carry their own compatibility requirements and must not be inferred from C++ header placement.