Prospectus Celestial

Language Specification & System Architecture — v1.0
Markup Language Visual Engine UWP / Win2D v1.0 Stable

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:

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:

1.2 Terminology

TermDefinition
PCMLProspectus Celestial Markup Language — the source format
PCEProspectus Celestial Engine — the runtime processor
TagA named block beginning with @keyword
SigilA prefix character with syntactic meaning (@, $, #, ->, --)
DomainOne of eight categorized namespaces of tags
LayerA numbered z-order composition plane (0–7)
AVKAudio-Visual-Kinesthetic — the three output channels of PCE
SceneA complete renderable unit composed of tagged blocks
ScopeThe 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:

.pcs Source
→
Lexer
→
Parser
→
AST Builder
→
Renderer
→
Win2D 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.

Note The pipeline is stateless between frames. All animation and state change must be expressed through @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

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

RequirementMinimumRecommended
OSWindows 10 1903Windows 11 22H2+
Runtime.NET 6.0 UWP.NET 8.0 UWP
Graphics APIWin2D 1.26 / Direct2D 1.1Win2D 1.27+
GPUDirect3D 11 Feature Level 9.3Direct3D 12 Feature Level 11.0
Memory512 MB RAM4 GB RAM
NuGetMicrosoft.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.

Domain 1
Script
Textual and logical content: phrases, fragments, expressions
Domain 2
Visual
Images, graphics, bitmaps, shapes, and all rendered visuals
Domain 3
Audio
Sound effects, music tracks, audio nodes and graphs
Domain 4
Geometry
Vectors, paths, transforms, collision shapes
Domain 5
Relational
Entity relationships, binding, events, and data flow
Domain 6
Data
Structured data: records, tables, lists, and persistence
Domain 7
Application
App lifecycle, navigation, views, and platform services
Domain 8
Meta
Scene metadata, settings, imports, and engine configuration

6.1 Domain Membership Rules

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).

LayerConventional UseZ-Order
0Background, skybox, environmentBottom (first drawn)
1Terrain, floor, background objects↑
2World objects, props, platforms↑
3Characters, entities, NPCs↑
4Projectiles, effects, particles↑
5UI panels, HUD elements↑
6Overlays, notifications, tooltips↑
7Debug, cursor, highest-priority overlayTop (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

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:

ChannelMeaningPrimary TagsWin2D / Platform API
A — AudioSound, music, voice@sound, @music, @audionodeWindows.Media.Audio
V — VisualRendered imagery, text, geometry@image, @graphic, @bitmap, @phraseCanvasDrawingSession
K — KinestheticInput, haptics, interaction response@event, @bind, @gesturePointerInput, 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.

ModifierSyntaxVisibility
publicpublic @image id="hero" { }Accessible from any other scene or module
privateprivate $counter = 0Accessible only within the same @zqml block
protectedprotected @fragment id="helper" { }Accessible within the block and any derived/child scenes
Note When no modifier is specified, the default visibility is 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:

// 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

LevelNameRequirements
L0CoreMust support: Script, Visual, Meta domains; Layers 0–7; @zqml root; UTF-8; PCFileService
L1StandardL0 + Audio, Geometry, Data domains; AVK viewport; all access modifiers
L2FullL1 + Relational, Application domains; Infinity Principle; Win2D GPU path; IDE support

12. Error Model

The PCE pipeline raises typed errors at each stage:

Error ClassStageDescription
PCLexErrorLexerUnrecognized character, malformed sigil, unterminated string
PCParseErrorParserInvalid tag structure, missing required attribute, wrong domain
PCScopeErrorAST BuilderUnresolved reference, access modifier violation, undefined variable
PCRenderErrorRendererMissing asset, out-of-range layer, Win2D draw failure
PCRuntimeErrorRuntimeExpression 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" ;