Files
prometeu-studio/docs/specs/compiler-languages/pbs/README.md
T
bquarkz bf31184d4d feat(pbs): add sprite animation and shared Studio authoring
Implement DEC-0084 with factory-only Sprite/Animator structs, complete result
lowering, validated animation sidecars, generated PBS factories and JavaFX/MCP
authoring through shared services.

Qualify native dev/release with ordinary and optimized producers, zero-allocation
playback, private-cycle reclamation, canonical Composer pixels, installed JARs
and JavaFX lifecycle. Preserve the runtime checkout and existing host ABI.
2026-11-05 15:16:07 +00:00

209 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PBS Specs
Owner: `compiler/pbs`. Canonical source: `docs/specs/compiler-languages/pbs`.
This directory contains the normative PBS specification set.
## Installed Quickstart (Informative)
This guide and the numbered specifications are packaged with the PBS frontend.
They describe the installed distribution, not a promise of a numbered language
release. A spec's `Draft v1` status is not the compiler version or SDK version.
The project manifest selects the SDK major with `stdlib`; current packaged
Game SDK resources use major `1`. Unknown language/compiler versions remain
unknown in Studio's context.
For an external coding agent:
1. Request `studio_project_context` for the absolute root of the open project.
2. Read `pbs:quickstart`, `pbs:spec:3` (syntax), `pbs:spec:4` (static semantics)
and the relevant SDK reference IDs returned in that context. Continue pages
until `nextOffset` is null. References are IDs, not filesystem paths.
3. Inspect the project and its dependencies before changing source. Only edit
the project's editable scope, excluding read-only SDK/external libraries.
4. Use the installed LSP and compiler to check changes. When the corresponding
MCP tools are available, acquire project control after the developer's DEV
grant, then use the advertised language/build tools. Documentation reads do
not require that grant. Missing tools/capabilities must not be assumed.
5. Build and test small changes. Runtime execution also requires a compatible
configured runtime; reading references does not install one.
### Small Game Project
The installed example has separately indexed files. Its basic game entry consists of:
- `pbs:example:game:1:prometeu.json`: a Game manifest with `language: pbs`,
`stdlib: 1` (serialized as a string), and no external dependencies;
- `pbs:example:game:1:src/main.pbs`: `[Init]` and `[Frame]` functions drawing a
moving rectangle through `Gfx` and constructing colors through `Color`;
- `pbs:example:game:1:src/mod.barrel`: the module's public declarations.
Additional runnable examples include `src/collections.pbs` for List/Cursor,
`src/linked.pbs` for Linked, `src/sets.pbs` for Set and `src/hashing.pbs` for
scalar hashing and typed instance queries. Read the corresponding SDK/spec
references; Set's order is unspecified and custom equality is explicit.
Copy these reference texts to the corresponding paths only when creating that
example in your editable project. The example is compiled in the test suite;
it is not a complete game or a claim that every requested gameplay abstraction
already exists. If a project has no external dependencies, no registry is needed.
For dependencies, follow the installed compiler's manifest/registry requirements.
PBS source lives under `src` for the installed provider. Functions use `fn`,
typed parameters and `->` return types. `let` declares a local binding;
`declare global` declares persistent global state. Imports name exports and a
module address, for example `import { Gfx } from @sdk:gfx;`. A `mod.barrel`
describes a module's public surface. Read the syntax/static-semantics chapters
for exact rules rather than inferring compatibility with another language.
### SDK Navigation and Limits
`pbs:sdk:game:1:sdk/gfx/main.pbs` exposes the actual installed Gfx source,
including documentation comments and signatures. Its `mod.barrel` reference
defines exports. Equivalent references exist for `sdk/asset`, `sdk/composer`,
`sdk/input`, `sdk/log`, `sdk/math`, `sdk/mathf`, `sdk/random`, `sdk/hash`,
`sdk/collections`, and `core/color`. Read those interfaces before calling
them. Game SDK 1 does not currently ship `audio` or `core/math` modules.
Ordinary game source uses public services such as `Gfx`; it must not manufacture
host bindings or mutate SDK declarations. Asset/composer workflows require their
real asset/scene data and runtime capabilities. Reference availability does not
guarantee those project resources exist. SDK or tooling limitations should be
reported for separate work, not patched in read-only dependencies.
The reference index is generated from these owner-maintained documents and the
frontend's SDK/example resources. The index schema revision is not a language
version. Source hashes bind texts to the installed bundle; no repository checkout
or network is needed to read them. The numbered specifications remain normative;
this onboarding section and example are explanatory, not a second specification.
## Purpose
Specs define the official PBS language/frontend contract.
They exist to make behavior, constraints, and interfaces stable across implementations and reviews.
Cross-language acceptance rules are not defined here.
Those are maintained in `docs/specs/compiler`.
## Expected Format
The exact structure may vary by document, but a spec should usually contain:
1. Title
2. Status
3. Scope or Applies To
4. Purpose
5. Authority and Precedence
6. Normative Inputs
7. Core Rules
8. Non-Goals
9. Exit Criteria
Some specs may also include:
- already-settled inputs,
- initial section targets,
- `TODO` sections for tracked unresolved items,
- cross-references to adjacent specs.
## Writing Rules
- Write in normative language.
- Integrate only decisions that have already been closed.
- Keep debate history and exploratory alternatives out of the spec body.
- Preserve clear boundaries between adjacent specs.
- Use `TODO` only for explicitly tracked unresolved items, not as a substitute for agenda work.
## Upstream Rule
Specs should normally be fed by:
1. agendas that frame the open topic,
2. decisions that close the architectural question,
3. then spec integration.
If a spec edit would require guessing an unresolved design choice, the correct action is to stop and surface the missing decision first.
## Current Chapter Focus
The active PBS chapter focus is:
- `11. AST Specification.md`
- `12. Diagnostics Specification.md`
- `13. Lowering IRBackend Specification.md`
## Frontend-Owned Semantic Presentation Rule
PBS, as a frontend, owns its semantic vocabulary and semantic editor presentation contract.
That means:
- PBS semantic keys are PBS-owned contract data,
- PBS semantic highlight resources belong to PBS rather than to Studio or LSP,
- PBS publishes that contract through `FrontendSpec`,
- and Studio/LSP consume that contract without becoming owners of PBS semantic presentation assets.
The `@sdk:random` module exports `Random` and `random`. Use an explicit long seed;
copying a generator shares its state. Read `pbs:spec:20`
and `pbs:example:game:1:src/random.pbs` for the exact contract and a small example.
## Authority and reading order
Read syntax and static semantics (3–4), module/SDK resolution (5), host/intrinsic
boundaries (6–8), execution/memory (9–10), and compiler projections (11–13).
Thematic chapters 14–25 own their complete feature contracts. Base chapters
retain syntax, AST, diagnostics and lowering responsibilities and refer to those
owners for detailed rules. The accepted explicit-initialization rule in chapter 17
applies to every completing ordinary/generic constructor, including Random fields.
[General compiler specifications](../../compiler/README.md) own shared handoff
and acceptance; the [runtime mirror policy](../../../vm-arch/README.md) identifies
the provider's separate ABI/execution authority. Keep those boundaries explicit.
## Chapter index
- [1. Language Charter](1.%20Language%20Charter.md)
- [2. Governance and Versioning](2.%20Governance%20and%20Versioning.md)
- [3. Core Syntax Specification](3.%20Core%20Syntax%20Specification.md)
- [4. Static Semantics Specification](4.%20Static%20Semantics%20Specification.md)
- [5. Manifest, Stdlib, and SDK Resolution Specification](5.%20Manifest%2C%20Stdlib%2C%20and%20SDK%20Resolution%20Specification.md)
- [6. VM-owned vs Host-backed](6.%20VM-owned%20vs%20Host-backed.md)
- [6.1. Intrinsics and Builtin Types Specification](6.1.%20Intrinsics%20and%20Builtin%20Types%20Specification.md)
- [6.2. Host ABI Binding and Loader Resolution Specification](6.2.%20Host%20ABI%20Binding%20and%20Loader%20Resolution%20Specification.md)
- [7. Cartridge Manifest and Runtime Capabilities Specification](7.%20Cartridge%20Manifest%20and%20Runtime%20Capabilities%20Specification.md)
- [8. Stdlib Environment Packaging and Loading Specification](8.%20Stdlib%20Environment%20Packaging%20and%20Loading%20Specification.md)
- [9. Dynamic Semantics Specification](9.%20Dynamic%20Semantics%20Specification.md)
- [10. Memory and Lifetime Specification](10.%20Memory%20and%20Lifetime%20Specification.md)
- [11. AST Specification](11.%20AST%20Specification.md)
- [12. Diagnostics Specification](12.%20Diagnostics%20Specification.md)
- [13. Lowering IRBackend Specification](13.%20Lowering%20IRBackend%20Specification.md)
- [14. Typed Arrays and Optional Execution Specification](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Specification.md)
- [15. First-Class Functions and Captures Specification](15.%20First-Class%20Functions%20and%20Captures%20Specification.md)
- [16. Generic Contracts Specification](16.%20Generic%20Contracts%20Specification.md)
- [17. Generic Structs and Free Functions Specification](17.%20Generic%20Structs%20and%20Free%20Functions%20Specification.md)
- [18. Input and Existing Type Runtime Alignment Specification](18.%20Input%20and%20Existing%20Type%20Runtime%20Alignment%20Specification.md)
- [19. Service Constants and Runtime Math Specification](19.%20Service%20Constants%20and%20Runtime%20Math%20Specification.md)
- [20. Runtime Random Integration Specification](20.%20Runtime%20Random%20Integration%20Specification.md)
- [21. SDK List and Cursor Specification](21.%20SDK%20List%20and%20Cursor%20Specification.md)
- [22. SDK Linked and Cursor Specification](22.%20SDK%20Linked%20and%20Cursor%20Specification.md)
- [23. SDK Set and Identity Specification](23.%20SDK%20Set%20and%20Identity%20Specification.md)
- [24. SDK Map and Keyval Specification](24.%20SDK%20Map%20and%20Keyval%20Specification.md)
- [25. SDK Stack and Queue Specification](25.%20SDK%20Stack%20and%20Queue%20Specification.md)
## Installed reference compatibility
Each numbered chapter is indexed as `pbs:spec:<number>`; this README is
`pbs:quickstart`. Published filename-based IDs for chapters 14–25 remain aliases
of the same canonical packaged text and hash. New callers should use the numbered
IDs returned by project context. The alias catalog is generated by the frontend
build from this single source directory. It does not read a second spec tree.
The internal resource path is `pbs-knowledge/specs/<numbered filename>.md`;
reference clients resolve IDs through the catalog instead of constructing paths.
- [Memcard Bootstrap and SDK](<26. Memcard Bootstrap and SDK Specification.md>): opt-in persistence producer and runtime-consumer boundaries.
- [Sprite and animation contract](27.%20Core%20Sprite%20and%20Animation%20Specification.md) — core API, explicit ticks, shared bank authoring and generated factories.