Prospectus Celestial — Examples Guide

Complete working examples from Hello World to a full game scene
PCML v1.0 Win2D 14 Examples

1. Hello, World

The minimal Prospectus Celestial scene. A white text label on a dark background, rendered on Layer 5 (UI).

hello-world.pcsPCML
// hello-world.pcs — The simplest Prospectus Celestial scene
@pcml version="1.0" name="hello-world" {

    @meta {
        @viewport width=1280 height=720 fps=60
                  avk="visual"
                  colorspace="sRGB" { }
    }

    @phrase id="greeting"
            text="Hello, Prospectus Celestial!"
            font="Segoe UI" size=48
            color="#F0C060"
            pos=(320, 300)
            layer=5
            align="center" { }

}

2. Variables & Expressions

Declaring scene variables and updating them each tick using @expression.

counter.pcsPCML
@pcml version="1.0" name="counter" {

    @meta { @viewport width=800 height=600 fps=60 avk="visual" { } }

    // Declare scene variables
    $count     = 0
    $timer     = 0.0
    $interval  = 1.0   // increment every 1 second

    @phrase id="display"
            text="Count: $count"
            font="Segoe UI" size=36
            color="#F8E0A0"
            pos=(400, 280)
            align="center"
            layer=5 { }

    @expression id="tick" tick=true {
        $timer += PCEngine.DeltaTime
        if ($timer >= $interval) {
            $count += 1
            $timer  = 0.0
        }
    }

}

3. Using the Layer System

Demonstrating all eight layers: background sky (0), terrain (1), world objects (2), character (3), particles (4), HUD (5), notification (6), debug cursor (7).

layers-demo.pcsPCML
@pcml version="1.0" name="layers-demo" {

    @meta { @viewport width=1920 height=1080 fps=60 avk="visual" { } }

    // Layer 0 — Background environment
    @image id="sky"        layer=0 src="sky.png"       pos=(0,0)      { }

    // Layer 1 — Terrain
    @image id="ground"     layer=1 src="terrain.png"  pos=(0,800)   { }

    // Layer 2 — World props
    @image id="tree"       layer=2 src="tree.png"     pos=(200,600) { }

    // Layer 3 — Player character
    @image id="player"     layer=3 src="hero.png"     pos=(400,700) { }

    // Layer 4 — Particles / effects
    @image id="sparkle"    layer=4 src="spark.png"    pos=(420,680) { }

    // Layer 5 — HUD
    @graphic id="hpbar"   layer=5 shape="rect"
             pos=(20,20) size=(200,16)
             fill="#22AA44" stroke="#FFFFFF"
             strokeWidth=1 radius=4 { }

    // Layer 6 — Notification overlay
    @phrase id="notice"    layer=6 text="New Area!"
            font="Segoe UI" size=28 color="#F0C060"
            pos=(960, 80) align="center" { }

    // Layer 7 — Debug cursor (wraps to 0 under Infinity Principle)
    @graphic id="cursor"  layer=7 shape="ellipse"
             pos=(960,540) size=(12,12)
             fill="#FF8090" stroke="#FFFFFF"
             strokeWidth=2 { }

}

4. Sprite & Frame Animation

Animating a sprite sheet using clip attribute cycling inside an @expression.

sprite-anim.pcsPCML
@pcml version="1.0" name="sprite-anim" {

    @meta { @viewport width=800 height=600 fps=60 avk="visual" { } }

    $frame       = 0
    $frameTimer = 0.0
    $frameDur   = 0.1   // 10 fps animation
    $frameCount = 8
    $frameW     = 64
    $frameH     = 64

    @image id="runner"
           src="hero-sheet.png"
           pos=(368, 268)
           clip=(0, 0, 64, 64)
           layer=3 { }

    @expression id="animate" tick=true {
        $frameTimer += PCEngine.DeltaTime
        if ($frameTimer >= $frameDur) {
            $frame      = ($frame + 1) % $frameCount
            $frameTimer = 0.0
            // Update clip region to next frame
            #runner.clip = ($frame * $frameW, 0, $frameW, $frameH)
        }
    }

}

5. Sound Effects & Music

audio-demo.pcsPCML
@pcml version="1.0" name="audio-demo" {

    @meta { @viewport width=800 height=600 fps=60
              avk="audio visual kinesthetic" { } }

    // Background music — autoplays with 2-second fade in
    @music id="bgm" src="theme.mp3"
           volume=0.65 loop=true
           fadein=2.0 autoplay=true { }

    // Jump sound — triggered by event
    @sound id="jumpSFX" src="jump.wav"
           volume=0.9 pitch=1.0 loop=false { }

    // Coin pickup — higher pitch variant
    @sound id="coinSFX" src="coin.wav"
           volume=0.7 pitch=1.2 loop=false { }

    // Reverb node for ambience
    @audionode id="hall"
               type="effect" effect="reverb"
               input="bgm" { }

    // Jump input binding
    @event id="onJump" trigger="key:Space" {
        @expression { #jumpSFX.Play() }
    }

}

A production-ready main menu with logo, animated background, button graphics, and music.

main-menu.pcsComplete Scene
@pcml version="1.0" name="main-menu" {

    @meta {
        @viewport width=1920 height=1080 fps=60
                  avk="audio visual kinesthetic"
                  colorspace="sRGB" { }
    }

    // === Variables ===
    $titlePulse = 0.0
    $starY     = 0.0
    $selected  = 0    // 0=Play, 1=Options, 2=Quit

    // === Layer 0: Animated starfield ===
    @image id="stars" src="starfield.png"
           pos=(0,0) size=(1920,1080)
           layer=0 { }

    // === Layer 1: Nebula background ===
    @image id="nebula" src="nebula.png"
           pos=(0,0) size=(1920,1080)
           alpha=0.5 layer=1 { }

    // === Layer 5: UI — Title logo ===
    @image id="logo" src="logo.png"
           pos=(660, 80) layer=5
           alpha=1.0 { }

    // === Layer 5: Menu buttons ===
    @graphic id="btnPlay"    shape="rect"
             pos=(760,460) size=(400,60)
             fill="#1a2a4a" stroke="#60C0FF"
             strokeWidth=2 radius=8 layer=5 { }
    @phrase text="▶  Play"
            font="Segoe UI" size=28 color="#F0C060"
            pos=(960,480) align="center" layer=5 { }

    @graphic id="btnOptions" shape="rect"
             pos=(760,540) size=(400,60)
             fill="#1a2a4a" stroke="#2e2856"
             strokeWidth=2 radius=8 layer=5 { }
    @phrase text="⚙  Options"
            font="Segoe UI" size=28 color="#C0D4F0"
            pos=(960,560) align="center" layer=5 { }

    // === Audio ===
    @music id="menuBGM" src="menu-theme.mp3"
           volume=0.6 loop=true fadein=3.0 autoplay=true { }

    // === Expression: pulse title alpha ===
    @expression id="pulse" tick=true {
        $titlePulse += PCEngine.DeltaTime * 1.8
        #logo.alpha = 0.8 + (PCMath.Sin($titlePulse) * 0.2)
    }

    // === Kinesthetic: button hover detection ===
    @bind id="hoverPlay" target="btnPlay" event="hover" {
        @expression { #btnPlay.stroke = "#F0C060"  $selected = 0 }
    }
    @bind id="clickPlay" target="btnPlay" event="click" {
        @expression { PCEngine.TransitionTo("Scenes/game.pcs", PCTransition.Fade) }
    }

}

7. Complete Game — Starfall

The reference game from Chapter 17 of the original spec. A side-scrolling shooter with player movement, bullet firing, enemy waves, score tracking, and game-over logic.

starfall.pcsComplete Game
@pcml version="1.0" name="starfall" {

    @meta {
        @viewport width=1280 height=720 fps=60
                  avk="audio visual kinesthetic"
                  colorspace="sRGB" { }
    }

    // === Game State ===
    $playerX    = 640.0
    $playerY    = 600.0
    $speed      = 320.0   // px/sec
    $health     = 3
    $score      = 0
    $level      = 1
    $gameOver   = false
    $fireTimer  = 0.0
    $fireCooldown = 0.25
    $scrollSpeed = 60.0
    $bgY        = 0.0

    // === Layer 0: Scrolling starfield ===
    @image id="bg" src="space-bg.png"
           pos=(0,0) size=(1280,1440) layer=0 { }

    // === Layer 3: Player ship ===
    @image id="ship" src="ship.png"
           pos=(608, 600) layer=3
           origin=(32,32) { }

    // === Layer 5: HUD ===
    @graphic id="hpbar"  shape="rect" pos=(20,20)
             size=(200,16) fill="#22AA44"
             stroke="#FFFFFF" strokeWidth=1
             radius=4 layer=5 { }
    @phrase id="scoreText" text="Score: $score"
            font="Segoe UI" size=24
            color="#F0C060" pos=(1100,20)
            align="right" layer=5 { }

    // === Audio ===
    @music id="bgm"     src="starfall-ost.mp3"  volume=0.6 loop=true autoplay=true { }
    @sound id="laser"   src="laser.wav"         volume=0.7 pitch=1.0 { }
    @sound id="explode" src="explosion.wav"     volume=0.9 { }
    @sound id="hit"     src="hit.wav"           volume=0.8 { }

    // === Fragments ===
    @fragment id="clamp" params="val,lo,hi" returns="float" {
        return ($val < $lo) ? $lo : ($val > $hi) ? $hi : $val
    }

    // === Main Game Loop ===
    @expression id="gameLoop" tick=true {
        if ($gameOver) { return }

        // Scroll background
        $bgY = ($bgY + $scrollSpeed * PCEngine.DeltaTime) % 720
        #bg.pos = (0, $bgY - 720)

        // Player movement (keyboard)
        if (PCInput.IsDown("Left")) {
            $playerX -= $speed * PCEngine.DeltaTime
        }
        if (PCInput.IsDown("Right")) {
            $playerX += $speed * PCEngine.DeltaTime
        }
        $playerX = clamp($playerX, 32, 1248)
        #ship.pos = ($playerX, $playerY)

        // Firing
        $fireTimer += PCEngine.DeltaTime
        if (PCInput.IsDown("Space") && $fireTimer >= $fireCooldown) {
            $fireTimer = 0.0
            PCScene.Spawn("bullet", $playerX, $playerY - 40)
            #laser.Play()
        }

        // HP bar width reflects health
        #hpbar.size = ($health * 66, 16)

        // Game over check
        if ($health <= 0) {
            $gameOver = true
            #bgm.FadeTo(0.0, 2.0)
            PCEngine.TransitionTo("Scenes/gameover.pcs", PCTransition.Fade)
        }
    }

    // === Input: Gamepad support ===
    @gesture id="padFire" device="gamepad" button="A" {
        @expression {
            if ($fireTimer >= $fireCooldown) {
                PCScene.Spawn("bullet", $playerX, $playerY - 40)
                #laser.Play()
                $fireTimer = 0.0
            }
        }
    }

}

8. C# Host Integration

How to load and drive a Prospectus Celestial scene from a UWP C# host application.

MainPage.xaml.csC# / UWP
using ProspectusCelestial;
using ProspectusCelestial.Runtime;
using Microsoft.Graphics.Canvas.UI.Xaml;

public sealed partial class MainPage : Page
{
    private PCScene _scene;

    private async void Page_Loaded(object sender, RoutedEventArgs e)
    {
        // 1. Bind engine to canvas
        PCEngine.Instance.Initialize(myCanvas);

        // 2. Load scene from .pcs file
        var service = new PCFileService();
        _scene = await service.LoadSceneAsync("Scenes/starfall.pcs");

        // 3. Preload GPU assets
        await _scene.PreloadAssetsAsync();

        // 4. Wire to canvas events
        myCanvas.Draw   += _scene.OnDraw;
        myCanvas.Update += _scene.OnUpdate;

        // 5. Read/write variables from C#
        _scene.DataReader.Set("playerX", 640.0f);
        int score = _scene.DataReader.Get<int>("score");

        // 6. Fire a scene event from C#
        _scene.TriggerEvent("onJump");
    }

    protected override void OnNavigatedFrom(NavigationEventArgs e)
    {
        _scene?.Dispose();
        base.OnNavigatedFrom(e);
    }
}
Next Steps See the API Reference for the full PCFileService, PCScene, PCEngine, and PCDataReader surface. See the Language Specification for grammar, domain rules, and the Infinity Principle.