# Dimentra3D Language Specification

**Status:** v0.1 independent grammar and parser; not a compiler/runtime.
**Canonical implementation:** `dimentra3d.js`.
**Implementation roadmap:** [`ASSISTANT-ROADMAP.md`](ASSISTANT-ROADMAP.md).

Dimentra3D is a new language. Rustba is legacy source material used to learn
from—not a syntax base, compatibility target, or permanent constraint. The
language family contributes concepts, not inherited spellings:

- Hardware awareness and explicit effects become checked resource contracts.
- Mobile interaction is stateful and gesture-native.
- Petri flow becomes typed workflow composition.
- 20-dimensional synthesis informs material/geometry composition.
- Type and verification discipline applies to every declaration.
- Geometry, materials, lights, shaders and scene identity are native language
  constructs, not opaque strings passed to an unrelated viewer.

The founder confirmed that tRust's role in this language is types and
verification. Its historical art-composition file is retained as provenance,
not treated as a competing syntax.

## Conformance and project goals

| Requirement | v0.1 status | What proves it |
|---|---|---|
| An independent name, grammar and parser | Implemented | Dimentra3D-prefixed source, parser and tests |
| Typed state, records and located failures | Basic literals/record fields are parsed and checked | `dimentra3d.test.cjs` |
| Hardware-aware effects and guards | Resource sets/requirements are parsed; no effects execute | `mobile.dimentra` |
| Mobile screens, gestures and state bindings | Syntax and references are checked, not rendered | `mobile.dimentra` |
| Native mesh, materials, lights and 3D scenes | Parser checks declarations; experimental CPU preview lowers only icospheres, opaque colors, supported material fields, declared lights and orbit/orthographic camera | `dimentra3d-render.js`, `scene.dimentra` |
| Mathematical shader/material description | Derivations are represented as source expressions, not run | `systems.dimentra` |
| Petri-net workflows and 20D synthesis | Small declarations are parsed; no scheduler/synthesis runtime | `systems.dimentra` |
| State-aware identity and complete asset coverage | One asset/context coverage rule is checked | `scene.dimentra` |
| Better graphics performance | A design goal, not yet measured | Requires compiled backends and repeatable benchmarks |
| Mobile/desktop/tool targets | Design requirement; no target compiler yet | Later compiler/backend work |
| GBC-first owned-game compiler | Future; no ROM output exists | Requires tested code generation and hardware evidence |

This table separates parser conformance and the narrow CPU preview from
execution, general compilation, GPU/native rendering, and measured
performance. No unimplemented capability is implied by a parsed AST.

## Source model and lexical rules

1. A file begins with `language Dimentra3D 1;`. This language identifier is
   mandatory and exactly once.
2. `//` starts a line comment outside a quoted string.
3. Names use ASCII letters or `_`, followed by letters, digits or `_`.
4. Strings use double quotes and JSON-compatible escapes.
5. Numeric literals are unsigned decimal integers or decimals.
6. Colors are `#RGB`, `#RGBA`, `#RRGGBB` or `#RRGGBBAA`.
7. Statements end in `;`; blocks use balanced braces and can nest to 64 levels.
8. The prototype bounds input to 1,000,000 JavaScript UTF-16 code units.
9. A diagnostic reports file, one-based line and column, stable code, and
   message. Invalid input throws and cannot yield a partial AST.

## v0.1 grammar

This EBNF covers the executable parser subset. `ID`, `STRING`, `NUMBER`,
`COLOR`, and `EXPR` are lexical/source forms; `EXPR` is retained as text and is
not evaluated by this version.

```ebnf
program       = "language Dimentra3D 1;" NL { declaration } ;
declaration   = hardware | profile | state | record | screen | effect
              | material | light | mesh | scene | identity | flow
              | synthesis | shader ;
block         = "{" NL { statement } "}" ;

hardware      = "hardware" ID block ;
profile       = "profile" ID block ;
observation   = "observe" ID ":" ID "=" EXPR ";" ;
state         = "state" ID ":" type "=" literal ";" ;
type          = ID [ "[" ID "]" ] ;
literal       = STRING | NUMBER | "true" | "false" | COLOR ;
record        = "record" ID "{" { ID ":" type ";" } "}" ;

screen        = "screen" ID "{" { layout | widget | row | gesture } "}" ;
layout        = "layout" ID ";" ;
row           = "row" block ;
widget        = ("title" | "text" | "note" | "input") STRING ";"
              | "button" STRING "=>" ("show" ID | "invoke" ID
                | ID ("+=" | "=") EXPR) ";"
              | "toggle" STRING "bind" ID ";"
              | "slider" STRING "range" NUMBER ".." NUMBER "bind" ID ";"
              | "list" STRING "options" "[" STRING { "," STRING } "]" "bind" ID ";"
              | "spacer" ";" ;
gesture       = "on" ("tap" | "longpress") "=>" "show" ID ";"
              | "on" "swipe" direction "=>" "show" ID ";"
              | "on" "pinch" ("in" | "out") "=>" "update" ID ";" ;
direction     = "left" | "right" | "up" | "down" ;

effect        = "effect" ID "uses" "[" ID { "," ID } "]" block ;
requirement   = "require" EXPR ";" ;
effect-rule   = requirement | "strategy" ID ";" | "sync" ("propose" | "commit") ";" ;

material      = "material" ID block ;
material-rule = ("base_color" | "emission") COLOR ";"
              | ("roughness" | "metallic" | "clearcoat") NUMBER ";" ;
light         = "light" ID "{" "color" COLOR ";" "intensity" NUMBER ";" "}" ;
mesh          = "mesh" ID "=" ID "(" EXPR ")" ";" ;
scene         = "scene" ID block ;
scene-rule    = "camera" ("orbit" | "perspective" | "orthographic") ";"
              | "place" ID "at" "(" EXPR ")" "using" ID ";"
              | "illuminate" ID ";" ;

identity      = "identity" ID block ;
identity-rule = "states" "[" ID { "," ID } "]" ";"
              | "predicate" ID ":" EXPR ";"
              | "asset" ID "{" { "when" ID "=>" ID ";" } "}" ;

flow          = "flow" ID block ;
flow-rule     = "places" "[" ID { "," ID } "]" ";"
              | "transition" ID "from" ID "to" ID ";" ;
synthesis     = "synthesis" ID "dimensions 20" block ;
synthesis-rule= "fold" ID "and" ID "into" ID ";"
              | "project" ID "through dimension" NUMBER "as" ID ";" ;
shader        = "shader" ID block ;
shader-rule   = "derive" ID "=" EXPR ";" ;
```

The implementation rejects duplicate state/declarations and fields,
undeclared UI references, scene mesh/material/light references, invalid
material ranges, uncovered identity states, and invalid flow places. It
currently does **not** type-check arbitrary expressions, compile shader
expressions, evaluate guards, lay out screens, schedule flow, or render meshes.

## Performance and graphics architecture

Performance is a target that must be established by design and measurement,
not by the language name. Dimentra3D is intended to make optimized execution
possible through:

- typed geometry/material/scene data that can be analyzed before runtime;
- explicit resource/effect declarations instead of hidden host access;
- direct backend lowering, avoiding a general-purpose interpreter in shipped
  hot paths;
- GPU-oriented batching, stable buffers and data-oriented scene layouts where
  benchmarks show they win;
- target-specific code generation for desktop/mobile and, separately, consoles;
- equivalent reference workloads and repeatable CPU/GPU/memory measurements.

The first compiler should compare optimized generated output against a
correctness reference: scene images within a declared tolerance, identical
state/flow results, and resource usage/latency measured on named hardware.
No speedup claim is valid until representative workloads pass correctness and
performance thresholds against a named baseline.

## Safety and execution boundary

The canonical implementation tokenizes, parses, builds a typed-shape AST, and
checks bounded references. It does not evaluate expressions, invoke processes,
access paths named in source, load assets, access a network, or perform host
effects. The browser playground prints AST/diagnostics using `textContent`.

Future effects must pass through capability-scoped runtime APIs and an
independently reviewed host gate. Dimentra3D source must never gain unrestricted
JavaScript, shell, PowerShell, filesystem, network, or native-host access.
