Co-authored-by: Nilton Constantino <nilton.constantino@visma.com>
Reviewed-on: #8
This commit is contained in:
2026-03-24 13:40:22 +00:00
co-authored by Nilton Constantino
parent 05838d10b0
commit f9120e740b
128 changed files with 19414 additions and 4567 deletions
@@ -0,0 +1,10 @@
# PRs for Junie — Compiler Dependency Resolution & Linking Pipeline
> Goal: Move dependency resolution + linking orchestration into **prometeu_compiler** so that the compiler produces a **single fully-linked bytecode blob**, and the VM/runtime only **loads + executes**.
## Non-goals (for this PR set)
* No lockfile format (yet)
* No registry (yet)
* No advanced SAT solver: first iteration is deterministic and pragmatic
* No incremental compilation (yet)
@@ -0,0 +1,341 @@
# Prometeu Base Script (PBS)
> **A didactic scripting language for game development with explicit cost, explicit memory, and predictable runtime.**
---
## 0. What PBS Is (and What It Is Not)
PBS (Prometeu Base Script) is a **small, explicit scripting language designed for game engines and real‑time runtimes**.
Its core goals are:
* **Didactic clarity** — the language teaches how memory, data, and APIs really work.
* **Game‑friendly execution** — predictable runtime, no hidden allocation, no tracing GC.
* **Explicit cost model** — you always know *when* you allocate, *where* data lives, and *who* can mutate it.
PBS is **not**:
* a general‑purpose application language
* a productivity scripting language like Python or Lua
* a language that hides runtime cost
PBS is intentionally opinionated. It is built for developers who want **control, predictability, and understanding**, especially in **game and engine contexts**.
---
## 1. The Core Philosophy
PBS is built around one rule:
> **If you do not allocate, you are safe. If you allocate, you are responsible.**
From this rule, everything else follows.
### 1.1 Two Worlds
PBS has **two explicit memory worlds**:
| World | Purpose | Properties |
| ----- | -------------- | ---------------------------------------------- |
| SAFE | Stack / values | No aliasing, no leaks, no shared mutation |
| HIP | Storage / heap | Explicit aliasing, shared mutation, refcounted |
You never cross between these worlds implicitly.
---
## 2. First Contact: SAFE‑Only PBS
A PBS program that never allocates lives entirely in the SAFE world.
SAFE code:
* uses value semantics
* copies data on assignment (conceptually)
* cannot leak memory
* cannot accidentally share mutable state
This makes SAFE PBS ideal for:
* gameplay logic
* math and simulation
* AI logic
* scripting without fear
Example:
```pbs
let a = Vector(1, 2);
let b = a; // conceptual copy
b.scale(2);
// a is unchanged
```
No pointers. No references. No surprises.
---
## 3. Values, Not Objects
PBS does not have objects with identity by default.
### 3.1 Value Types
All basic types are **values**:
* numbers
* bool
* string (immutable)
* tuples
* user‑defined `struct`
A value:
* has no identity
* has no lifetime beyond its scope
* is safe to copy
This matches how most gameplay data *should* behave.
---
## 4. Structs (Data First)
Structs are **pure data models**.
```pbs
declare struct Vector(x: float, y: float)
{
pub fn len(self: this): float { ... }
pub fn scale(self: mut this, s: float): void { ... }
}
```
Rules:
* fields are private
* mutation is explicit (`mut this`)
* no inheritance
* no identity
Structs are designed to be:
* cache‑friendly
* predictable
* easy to reason about
---
## 5. Mutability Is a Property of Bindings
In PBS, **types are never mutable**. Bindings are.
```pbs
let v = Vector.ZERO;
v.scale(); // ERROR
let w = mut Vector.ZERO;
w.scale(); // OK
```
This single rule eliminates entire classes of bugs.
---
## 6. When You Need Power: Allocation (HIP World)
Allocation is **explicit**.
```pbs
let enemies = alloc list<Enemy>();
```
Once you allocate:
* data lives in Storage (heap)
* access happens through **gates** (handles)
* aliasing is real and visible
This is intentional and explicit.
---
## 7. Gates (Handles, Not Pointers)
A gate is a small value that refers to heap storage.
Properties:
* cheap to copy
* may alias shared data
* managed by reference counting
### 7.1 Strong vs Weak Gates
* **Strong gate** — keeps data alive
* **Weak gate** — observes without ownership
```pbs
let a = alloc Node;
let w: weak<Node> = a as weak;
let maybeA = w as strong;
```
This model mirrors real engine constraints without hiding them.
---
## 8. Controlled Access to Storage
Heap data is never accessed directly.
You must choose *how*:
* `peek` — copy to SAFE
* `borrow` — temporary read‑only access
* `mutate` — temporary mutable access
```pbs
mutate enemies as e
{
e.push(newEnemy);
}
```
This keeps mutation visible and scoped.
---
## 9. Errors Are Values
PBS has no exceptions.
### 9.1 `optional<T>`
Used when absence is normal.
```pbs
let x = maybeValue else 0;
```
### 9.2 `result<T, E>`
Used when failure matters.
```pbs
let v = loadTexture(path)?;
```
Error propagation is explicit and typed.
---
## 10. Control Flow Without Surprises
PBS favors explicit flow:
* `if` — control only
* `when` — expression
* `for` — bounded loops only
```pbs
for i in [0b..count] {
update(i);
}
```
No unbounded iteration by accident.
---
## 11. Services: Explicit API Boundaries
A `service` is how behavior crosses module boundaries.
```pbs
pub service Audio
{
fn play(sound: Sound): void;
}
```
Services are:
* explicit
* statically checked
* singleton‑like
They map naturally to engine subsystems.
---
## 12. Contracts: Static Guarantees
Contracts define **what exists**, not how.
```pbs
pub declare contract Gfx host
{
fn drawText(x: int, y: int, msg: string): void;
}
```
Contracts:
* have no runtime cost
* are validated at compile time
* define engine ↔ script boundaries
---
## 13. Modules (Simple and Predictable)
* one directory = one module
* only `pub` symbols cross modules
* no side effects on import
This keeps build and runtime deterministic.
---
## 14. Why PBS Works for Games
PBS is designed around real engine needs:
* frame‑based execution
* explicit allocation
* deterministic cleanup
* predictable performance
It teaches developers **why engines are written the way they are**, instead of hiding reality.
---
## 15. Who PBS Is For
PBS is for:
* game developers who want control
* engine developers
* students learning systems concepts
* educators teaching memory and runtime models
PBS is *not* for:
* rapid prototyping without constraints
* general app scripting
* hiding complexity
---
## 16. Design Promise
PBS makes one promise:
> **Nothing happens behind your back.**
If you understand PBS, you understand your runtime.
That is the product.