Prospectus Celestial
1. Introduction
Prospectus Celestial (PCML) is a declarative, domain-structured markup language and real-time visual engine designed for building rich interactive applications on Windows. It is composed of two tightly coupled systems:
- PCML — the Prospectus Celestial Markup Language, a tagged-block syntax for defining all elements of an application (visuals, audio, logic, data, geometry, relations, meta, and application control).
- PCE — the Prospectus Celestial Engine, a UWP runtime backed by Win2D that compiles, parses, and renders PCML source into GPU-accelerated 2D output.
Prospectus Celestial draws on principles of Zen philosophy — simplicity, intentionality, and balance — fused with the precision and power of modern graphics programming. Its name reflects the goal of achieving complex, dynamic results through clear, minimal declarations.
1.1 Scope of This Document
This specification defines:
- The normative grammar and syntax of PCML v1.0
- The semantics of all eight domains and their tags
- The eight-layer composition system
- The AVK (Audio-Visual-Kinesthetic) viewport model
- The OOP-style access modifier and scoping system
- The Infinity Principle governing layer wrapping
- Platform requirements and conformance levels
1.2 Terminology
| Term | Definition |
|---|---|
| PCML | Prospectus Celestial Markup Language — the source format |
| PCE | Prospectus Celestial Engine — the runtime processor |
| Tag | A named block beginning with @keyword |
| Sigil | A prefix character with syntactic meaning (@, $, #, ->, --) |
| Domain | One of eight categorized namespaces of tags |
| Layer | A numbered z-order composition plane (0–7) |
| AVK | Audio-Visual-Kinesthetic — the three output channels of PCE |
| Scene | A complete renderable unit composed of tagged blocks |
| Scope | The visibility boundary of a variable or fragment |
2. Design Goals
Prospectus Celestial is designed around five core principles:
2.1 Clarity Over Cleverness
Every PCML tag has a single, unambiguous purpose. The syntax is optimized for readability; a developer should be able to understand a PCML scene without prior training beyond familiarity with the domain concepts.
2.2 Domain Isolation
Visual, audio, geometric, relational, data, script, application, and meta concerns are strictly separated into domains. Cross-domain references are explicit and traceable.
2.3 Declarative First, Imperative Second
PCML is primarily declarative — you describe what exists, not how to build it. Procedural logic lives inside @expression and @fragment blocks, which are isolated from structural declarations.
2.4 Layered Composition
All rendering is managed through a transparent eight-layer system, giving precise z-order control without imperative draw-order management.
2.5 Full-Platform Integration
PCE integrates with Win2D at the GPU level. PCML scenes are not interpreted at runtime — they are compiled to an intermediate AST and then to Win2D draw calls, achieving near-native performance.
3. Processing Pipeline
A PCML source file passes through five stages before output:
Stage 1 — Lexer
The Lexer tokenizes raw .pcs text into a stream of typed tokens: SIGIL, KEYWORD, IDENTIFIER, LITERAL, OPERATOR, BLOCK_OPEN, BLOCK_CLOSE, and COMMENT. Whitespace is non-significant except within string literals.
Stage 2 — Parser
The Parser consumes the token stream and validates tag structure, attribute grammar, and domain membership. It emits structured Node objects and raises PCParseError for malformed input.
Stage 3 — AST Builder
The AST Builder assembles Nodes into a hierarchical Abstract Syntax Tree, resolves variable references ($vars), and annotates each node with its domain, layer, scope, and access level.
Stage 4 — Renderer
The Renderer walks the AST layer by layer (0 → 7), translating each node into a Win2D draw call, audio command, or kinesthetic event. The CanvasAnimatedControl update loop drives per-frame re-rendering.
Stage 5 — Win2D Output
Win2D executes GPU-accelerated 2D drawing operations. The three AVK channels are dispatched: Visual → CanvasDrawingSession, Audio → Windows.Media.Audio graph, Kinesthetic → Input event subscribers.
@expression blocks evaluated on each Update tick. This guarantees deterministic rendering.
4. File Format
Prospectus Celestial source files use the extension .pcs (Prospectus Celestial Scene). Files are encoded in UTF-8 with or without BOM. Line endings may be LF or CRLF.
4.1 File Structure
A well-formed .pcs file has the following top-level structure:
// Prospectus Celestial Scene File — version declaration is mandatory
@zqml version="1.0" name="MyScene" {
// Meta domain — scene-wide settings
@meta { ... }
// Variable declarations
$myVar = 42
// Domain blocks
@visual { ... }
@audio { ... }
@script { ... }
// ... other domains
}
4.2 Naming Rules
- Scene names, identifiers, and tag names are case-sensitive.
- Identifiers must begin with a letter or underscore, followed by letters, digits, or underscores.
- Reserved sigils (
@,$,#) must not appear inside identifiers. - File names must match the
nameattribute of the root@zqmlblock.
4.3 Loading via PCFileService
At runtime, .pcs files are loaded through PCFileService:
PCFileService service = new PCFileService();
PCScene scene = await service.LoadSceneAsync("MyScene.pcs");
canvasControl.Draw += scene.OnDraw;
5. Platform Requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| OS | Windows 10 1903 | Windows 11 22H2+ |
| Runtime | .NET 6.0 UWP | .NET 8.0 UWP |
| Graphics API | Win2D 1.26 / Direct2D 1.1 | Win2D 1.27+ |
| GPU | Direct3D 11 Feature Level 9.3 | Direct3D 12 Feature Level 11.0 |
| Memory | 512 MB RAM | 4 GB RAM |
| NuGet | Microsoft.Graphics.Win2D 1.0+ | Microsoft.Graphics.Win2D latest |
6. The Eight Domains
All PCML tags belong to exactly one of eight domains. Domains define the semantic category of a tag and constrain which child tags are valid within a block. Cross-domain interaction is permitted only through explicit references.
6.1 Domain Membership Rules
- Every tag belongs to exactly one domain. A tag's domain is determined by its keyword prefix.
- A block of one domain may reference another domain by ID using the
->sigil (pointer/reference operator). - Domain blocks may be nested only within same-domain parent blocks or within the root
@zqmlblock. - The
@metablock must appear before all other domain blocks in a scene.
7. The Eight-Layer System
All renderable content in Prospectus Celestial is assigned to one of eight composition layers, numbered 0 through 7. Layers are composited in ascending order: Layer 0 is drawn first (background), Layer 7 is drawn last (foreground/overlay).
| Layer | Conventional Use | Z-Order |
|---|---|---|
0 | Background, skybox, environment | Bottom (first drawn) |
1 | Terrain, floor, background objects | ↑ |
2 | World objects, props, platforms | ↑ |
3 | Characters, entities, NPCs | ↑ |
4 | Projectiles, effects, particles | ↑ |
5 | UI panels, HUD elements | ↑ |
6 | Overlays, notifications, tooltips | ↑ |
7 | Debug, cursor, highest-priority overlay | Top (last drawn) / wraps to 0 |
7.1 Assigning Layers
@image id="background" layer=0 src="sky.png" { }
@image id="player" layer=3 src="hero.png" { }
7.2 Layer Ordering Guarantees
- Within the same layer, elements are drawn in declaration order (first declared = drawn first = visually behind).
- Layer assignment is a per-tag attribute; all un-assigned tags default to Layer 2.
- Layers are composited using alpha blending with premultiplied alpha by default.
8. AVK Viewport System
The Audio-Visual-Kinesthetic (AVK) Viewport is the three-channel output model of the Prospectus Celestial Engine. Every piece of output in PCE is classified as one of three types:
| Channel | Meaning | Primary Tags | Win2D / Platform API |
|---|---|---|---|
| A — Audio | Sound, music, voice | @sound, @music, @audionode | Windows.Media.Audio |
| V — Visual | Rendered imagery, text, geometry | @image, @graphic, @bitmap, @phrase | CanvasDrawingSession |
| K — Kinesthetic | Input, haptics, interaction response | @event, @bind, @gesture | PointerInput, GamepadInput |
8.1 Viewport Declaration
@meta {
@viewport width=1920 height=1080 dpi=96
avk="audio visual kinesthetic"
fps=60
colorspace="sRGB" { }
}
8.2 Channel Independence
AVK channels are processed independently and asynchronously. The Visual channel is driven by CanvasAnimatedControl.Draw; Audio by the media graph; Kinesthetic by pointer/gamepad event subscriptions. All three are synchronized at the scene frame boundary.
9. Scope & Access Modifiers
Prospectus Celestial adopts OOP-style access modifiers to control the visibility of tags, variables, and fragments across scene files and modules.
| Modifier | Syntax | Visibility |
|---|---|---|
public | public @image id="hero" { } | Accessible from any other scene or module |
private | private $counter = 0 | Accessible only within the same @zqml block |
protected | protected @fragment id="helper" { } | Accessible within the block and any derived/child scenes |
private. This enforces encapsulation by default and encourages explicit exposure of shared elements.
10. The Infinity Principle
The Infinity Principle is a foundational concept in Prospectus Celestial's layer architecture: Layer 7, the highest layer, wraps back to Layer 0.
Conceptually, the eight layers are not a stack with a ceiling — they are a continuous loop. This means:
- Content on Layer 7 is considered both the "top" (drawn last, highest priority) and the "bottom" (can be treated as the ground state for the next composition cycle).
- Procedural scroll or parallax systems that promote content from layer to layer naturally cycle back to the beginning without explicit reset logic.
- The Renderer implements this via a modulo-8 layer index:
effectiveLayer = requestedLayer % 8.
// These two declarations are equivalent under the Infinity Principle
@image id="bg" layer=0 src="background.png" { }
@image id="bg" layer=8 src="background.png" { } // layer 8 % 8 = 0
11. Conformance Levels
| Level | Name | Requirements |
|---|---|---|
| L0 | Core | Must support: Script, Visual, Meta domains; Layers 0–7; @zqml root; UTF-8; PCFileService |
| L1 | Standard | L0 + Audio, Geometry, Data domains; AVK viewport; all access modifiers |
| L2 | Full | L1 + Relational, Application domains; Infinity Principle; Win2D GPU path; IDE support |
12. Error Model
The PCE pipeline raises typed errors at each stage:
| Error Class | Stage | Description |
|---|---|---|
PCLexError | Lexer | Unrecognized character, malformed sigil, unterminated string |
PCParseError | Parser | Invalid tag structure, missing required attribute, wrong domain |
PCScopeError | AST Builder | Unresolved reference, access modifier violation, undefined variable |
PCRenderError | Renderer | Missing asset, out-of-range layer, Win2D draw failure |
PCRuntimeError | Runtime | Expression evaluation failure, null reference, stack overflow |
13. Versioning
PCML uses Semantic Versioning (MAJOR.MINOR). The version is declared in the root @zqml block. The engine MUST reject files with a MAJOR version greater than its own. MINOR version mismatches produce a warning but continue loading.
14. Grammar Summary (EBNF)
scene = "@zqml" attrs "{" block* "}" ;
block = [modifier] "@" keyword attrs "{" (block | stmt)* "}" ;
modifier = "public" | "private" | "protected" ;
keyword = letter (letter | digit | "_")* ;
stmt = varDecl | reference | comment | expression ;
varDecl = "$" identifier "=" value ;
reference = "->" identifier ;
comment = "//" text NL | "/*" text "*/" | "/**" text "*/" ;
attrs = (identifier "=" value)* ;
value = string | number | boolean | identifier ;
string = '"' char* '"' ;
number = digit+ ["." digit+] ;
boolean = "true" | "false" ;
identifier = letter (letter | digit | "_")* ;
letter = "a".."z" | "A".."Z" | "_" ;
digit = "0".."9" ;