package PBS references and expose paginated MCP reads

This commit is contained in:
2026-09-29 08:48:33 +01:00
parent 58f11a8123
commit feb57c5298
23 changed files with 738 additions and 21 deletions
@@ -2,6 +2,73 @@
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.