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.
209 lines
11 KiB
Markdown
209 lines
11 KiB
Markdown
# 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.
|