138 lines
5.8 KiB
Markdown
138 lines
5.8 KiB
Markdown
# PBS Specs
|
|
|
|
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 three separately indexed files:
|
|
|
|
- `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.
|
|
|
|
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`, 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/general/specs`.
|
|
|
|
## 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.
|