prometeu-studio/docs/specs/pbs/1. Language Charter.md

PBS Language Charter

Status: Draft v1
Applies to: Prometeu Base Script (PBS) language design

1. Mission

PBS exists to make 2D game development on Prometeu intuitive for beginners and reliable for experienced developers, without sacrificing deterministic runtime behavior.

2. Product Vision

PBS is a game-first language for a logical, evolving hardware platform. It must feel fluid for frame-driven gameplay code while remaining strict enough to produce stable, verifiable bytecode for a closed VM target.

3. Target Users

• Beginner creators building their first playable 2D games.
• Intermediate developers shipping complete games with predictable behavior.
• Advanced developers who need explicit control of architecture and performance costs.

4. Core Principles

1. Game-first ergonomics: common gameplay patterns must be concise.
2. Determinism first: same program + same inputs/events => same behavior.
3. Explicit boundaries: host interaction, costs, and side effects must be visible.
4. Safe defaults: simple code paths should be hard to misuse.
5. Progressive power: advanced control is opt-in, not mandatory.
6. Compatibility discipline: language evolution must not silently break cartridges.

5. Scope of PBS v1

• Stable core syntax and grammar contract.
• Static and dynamic semantics for deterministic game code.
• Toolchain-managed host binding model aligned with syscall/capability model.
• Module visibility and import model suitable for multi-file game projects.
• Diagnostics and conformance requirements for interoperable implementations.

6. Out of Scope for PBS v1

• New VM opcodes as a language requirement.
• Non-deterministic async execution models.
• Mandatory custom allocator model replacing runtime GC.
• Advanced memory syntax (alloc/borrow/mutate/...) before explicit profile activation.
• User-authored declaration of canonical host primitive bindings outside reserved SDK/toolchain declare host surfaces.

7. Non-Negotiable Constraints

• Runtime and bytecode authority override language preferences.
• Closed VM compatibility is mandatory.
• FRAME_SYNC-based execution semantics are preserved.
• Host API usage remains capability-gated and versioned.
• Canonical host primitive bindings remain reserved to SDK/toolchain-controlled declare host surfaces.

8. Evolution Commitments

• Additive-first evolution for minor releases.
• Incompatible changes only in major lines with migration guidance.
• Canonical host primitive versioning by (module, name, version).
• User-facing host-backed APIs evolve through SDK/stdlib surfaces, not direct user-authored host-binding declarations outside reserved declare host modules.
• Deterministic loader rejection when target contracts are unsupported.

9. Quality Bar

PBS is considered healthy only if:

• newcomers can produce a working 2D game loop quickly,
• generated behavior is deterministic and replayable,
• diagnostics are stable and actionable,
• performance risks are visible in tooling,
• older supported cartridges keep running across updates.

10. Required Spec Set Before Implementation

Before implementation starts, PBS must define at least:

1. Core Syntax Specification.
2. Static Semantics Specification.
3. Dynamic Semantics Specification.
4. Memory and Lifetime Specification.
5. Host ABI Binding Specification.
6. Module/Package Specification.
7. Diagnostics Specification.
8. IR and Lowering Specification.
9. Conformance Test Specification.
10. Compatibility and Evolution Policy.

11. Decision Rule

When trade-offs appear, decisions must prioritize, in order:

1. Determinism and compatibility.
2. Clarity for beginners.
3. Fluency for real game workflows.
4. Performance transparency for advanced users.