PCML Markup Language Reference

Complete tag, syntax, and domain reference for Prospectus Celestial Markup Language v1.0
All 8 Domains Full Tag Reference Syntax Grammar

1. Sigils

Sigils are special prefix characters that give syntactic meaning to identifiers and operators in PCML. There are five sigils:

@
Tag Sigil
Introduces a domain tag or root keyword. Example: @image, @sound, @zqml
$
Variable Sigil
Declares or references a variable. Example: $speed = 5.0, $playerX
#
ID Reference Sigil
References an element by its declared id. Example: #player, #background
->
Pointer / Reference Operator
Expresses a cross-domain reference or binding. Example: -> #player.x
--
Inline Comment / Separator
Single-line comment or visual separator in annotation blocks. Example: -- end of section

2. Tag Anatomy

Every PCML block follows this structure:

[modifier] @tagname [attr1="value"] [attr2=42] ... {
    // child tags or statements
}
PartRequired?Description
[modifier]Optionalpublic, private, or protected. Default: private.
@tagnameRequiredThe domain tag keyword, prefixed with @.
attr=valueVariesKey-value attribute pairs. String values are double-quoted. Numbers are unquoted.
{ ... }RequiredBlock body. May be empty ({ }) for self-contained tags.
Note The id attribute is optional on all tags but strongly recommended for any element that will be referenced by other tags via #id or cross-domain binding.

3. Value Types

TypeSyntaxExamples
String"..." (double quotes only)"hello", "sprite.png"
IntegerBare decimal integer0, 255, -10
FloatDecimal with .1.0, 3.14, -0.5
Booleantrue / falsetrue, false
Color#RRGGBB or #RRGGBBAA#FF0000, #00FF0080
Vector2(x, y)(320, 240), (0.0, 1.0)
Rect(x, y, w, h)(0, 0, 100, 50)
Identifier ref#id#player, #bgMusic
Variable ref$name$speed, $health

4. Comments & Annotations

PCML supports four comment forms:

// Single-line comment — extends to end of line

/* Multi-line comment
   spans multiple lines
   until the closing */

/** Documentation comment — used by the ZQ IDE for hover docs
 *  @param id  The unique identifier of this element
 *  @layer 0–7 Render layer assignment
 */

-- Separator / inline annotation (used in annotation blocks)

5. Variables

Variables are declared with the $ sigil and are typed implicitly at assignment. They may appear at scene scope (outside all domain blocks) or within @expression and @fragment blocks.

// Scene-scope variable declarations
$playerX    = 100.0
$playerY    = 200.0
$health     = 100
$playerName = "Aria"
$alive      = true

// Access modifiers apply to variables too
private   $score    = 0
public    $level    = 1
protected $maxSpeed = 8.5

5.1 @information Tag

The @information tag is a structured variable container used to group related variables:

@information id="playerStats" {
    $health    = 100
    $mana      = 50
    $stamina   = 80
    $level     = 1
    $xp        = 0
}

6. Expressions

The @expression tag hosts imperative logic evaluated on every engine update tick. It is part of the Script domain.

@expression id="movePlayer" tick=true {
    $playerX = $playerX + $speed
    if ($playerX > 1920) {
        $playerX = 0
    }
}

6.1 Expression Attributes

AttributeTypeDefaultDescription
idstring—Unique identifier for this expression block
tickboolfalseIf true, evaluated every engine update frame
triggerstring—ID of an @event that activates this expression
onceboolfalseIf true, evaluated only on the first trigger
delayfloat0.0Seconds to wait before evaluation

7. Operators

CategoryOperatorsNotes
Arithmetic+ - * / % **** is exponentiation
Comparison== != < > <= >=Returns boolean
Logical&& || !Short-circuit evaluation
Assignment= += -= *= /=Compound assignment in expressions
Reference-> #id $varCross-domain and variable dereferencing
String+ (concat)Only valid between string operands
Ternarycondition ? a : bInline conditional expression

8. Access Modifiers

// Public: accessible from any scene or module
public @image id="sharedSprite" src="shared.png" { }

// Private: only accessible within this @zqml block (default)
private $internalTimer = 0.0

// Protected: accessible in this block and any derived scenes
protected @fragment id="baseUpdate" { }

9. Script Domain (Domain 1)

The Script domain handles all textual content, logical fragments, and runtime expressions.

@fragmentScript

A named, reusable logic block. Analogous to a function or subroutine. Can be called by reference from @expression blocks.

AttributeTypeDescription
idstringUnique name for this fragment
paramsstringComma-separated parameter names
returnsstringReturn type hint (int, float, bool, string)
@fragment id="clamp" params="val, lo, hi" returns="float" {
    return ($val < $lo) ? $lo : ($val > $hi) ? $hi : $val
}
@phraseScript

Renders a text string to the visual output. Belongs to both Script (content) and Visual (rendering) domains; layer assignment controls draw order.

AttributeTypeDescription
idstringElement identifier
textstringText content or $var reference
fontstringFont family name
sizefloatFont size in pixels
colorcolorText color (#RRGGBB)
posvector2Screen position (x, y)
layerintRender layer 0–7
alignstring"left", "center", "right"
@phrase id="scoreDisplay" text="Score: $score"
         font="Segoe UI" size=24 color="#FFFFFF"
         pos=(20, 20) layer=5 { }
@expressionScript

A block of imperative logic evaluated each tick or on trigger. Contains variable assignments, conditionals, loops, and fragment calls. See Section 6 for full attribute reference.

@expression id="gravity" tick=true {
    $velocityY += 0.5
    $playerY   += $velocityY
    if ($playerY >= 900) {
        $playerY   = 900
        $velocityY = 0
    }
}

10. Visual Domain (Domain 2)

The Visual domain encompasses all rendered imagery, sprites, bitmaps, and graphic primitives.

@imageVisual

Renders a raster image file to the scene. The most common visual tag.

AttributeTypeDescription
idstringElement identifier
srcstringRelative path to image file (PNG, JPG, BMP)
posvector2Top-left position on screen
sizevector2Render dimensions (overrides natural size)
layerintRender layer 0–7
alphafloatOpacity 0.0–1.0 (default 1.0)
visibleboolWhether to render (default true)
originvector2Rotation/scale origin (default top-left)
rotationfloatRotation in degrees
scalevector2Scale factor per axis
cliprectSource rectangle for sprite-sheet clipping
tintcolorMultiplicative color tint
@image id="player" src="hero.png"
       pos=(100, 400) layer=3
       alpha=1.0 rotation=0 scale=(1.0, 1.0) { }
@graphicVisual

Renders vector graphic primitives: rectangles, ellipses, lines, and polygons.

AttributeTypeDescription
shapestring"rect", "ellipse", "line", "polygon"
posvector2Position of the shape
sizevector2Bounding dimensions
fillcolorFill color
strokecolorBorder color
strokeWidthfloatBorder thickness in pixels
layerintRender layer 0–7
radiusfloatCorner radius (rect only)
@graphic id="healthBar" shape="rect"
         pos=(20, 60) size=(200, 16)
         fill="#22AA44" stroke="#FFFFFF"
         strokeWidth=1.5 radius=4 layer=5 { }
@bitmapVisual

A direct Win2D CanvasBitmap wrapper for high-performance, low-level pixel access. Use for procedurally generated textures or raw pixel manipulation.

AttributeTypeDescription
widthintBitmap width in pixels
heightintBitmap height in pixels
formatstring"rgba8", "rgb8", "a8"
layerintRender layer 0–7
posvector2Screen position

11. Audio Domain (Domain 3)

@soundAudio

A one-shot or looping sound effect.

AttributeTypeDescription
srcstringPath to audio file (WAV, MP3, OGG)
volumefloat0.0–1.0
pitchfloatPitch shift (1.0 = normal)
loopboolLoop playback
autoplayboolPlay on scene load
spatialboolEnable 2D positional audio
posvector2Audio source position (if spatial)
@sound id="jumpSFX" src="jump.wav"
       volume=0.8 pitch=1.0 loop=false { }
@musicAudio

Background music track with fade and loop support.

AttributeTypeDescription
srcstringPath to audio file
volumefloat0.0–1.0
loopboolLoop (default true)
fadeinfloatFade-in duration in seconds
fadeoutfloatFade-out duration in seconds
autoplayboolPlay on scene load
@music id="bgTrack" src="theme.mp3"
       volume=0.6 loop=true fadein=2.0 autoplay=true { }
@audionodeAudio

A node in the Windows Media Audio graph. Use for DSP effects, mixing, or custom audio routing.

AttributeTypeDescription
typestring"effect", "submix", "output"
effectstring"reverb", "echo", "equalizer", "limiter"
inputstringID of source node

12. Geometry Domain (Domain 4)

@vectorGeometry

A 2D vector value, usable as a position, direction, or velocity.

@vector id="gravity" x=0.0 y=9.8 { }
@pathGeometry

A sequence of 2D points defining a bezier or linear path. Used for movement rails, collision shapes, or visual curves.

AttributeTypeDescription
pointsstringSpace-separated (x,y) pairs
closedboolConnect last point to first
typestring"linear", "bezier", "catmull"
@path id="enemyRail" closed=false type="linear"
      points="(0,300) (400,300) (400,500) (800,500)" { }
@transformGeometry

Applies a reusable transformation (translate, rotate, scale) to one or more elements.

AttributeTypeDescription
targetstringID of element to transform
translatevector2Pixel offset
rotatefloatDegrees clockwise
scalevector2Scale per axis
originvector2Transform pivot point

13. Relational Domain (Domain 5)

@bindRelational

Creates a one-way or two-way data binding between two element properties.

// Bind healthBar width to $health variable, scaled to 200px max
@bind source="$health" target="#healthBar.size.x"
      transform="$health * 2.0" { }
@eventRelational

Defines an input or system event handler.

AttributeTypeDescription
onstringEvent name: "keydown", "keyup", "tap", "collision", "timer", "load"
keystringKey name for keyboard events (e.g. "Space", "ArrowLeft")
callstringID of @expression or @fragment to invoke
targetstringID of element for collision events
@event on="keydown" key="Space" call="jump" { }
@event on="collision" target="#enemy" call="takeDamage" { }
@gestureRelational

Recognizes touch or pointer gestures.

AttributeTypeDescription
typestring"swipe", "pinch", "tap", "drag"
directionstring"left", "right", "up", "down" (swipe only)
callstringFragment or expression to invoke

14. Data Domain (Domain 6)

@recordData

A structured data record — analogous to a struct or row.

@record id="enemy01" {
    $type   = "grunt"
    $health = 30
    $speed  = 2.5
    $reward = 10
}
@tableData

A collection of @record blocks sharing a common schema. Supports indexed access.

@table id="enemies" schema="type health speed reward" {
    @record { $type="grunt"  $health=30  $speed=2.5 $reward=10 }
    @record { $type="elite"  $health=100 $speed=4.0 $reward=50 }
    @record { $type="boss"   $health=500 $speed=1.5 $reward=200 }
}
@persistData

Marks a variable or record for persistent storage (ApplicationData.LocalSettings).

@persist target="$highScore" key="game.highScore" { }

15. Application Domain (Domain 7)

@viewApplication

Defines a named application screen/page that can be navigated to.

@view id="mainMenu" title="Main Menu" default=true { }
@navigateApplication

Navigates to a target @view, optionally passing parameters.

@navigate to="#gameScene" transition="fade" duration=0.5 { }
@serviceApplication

Declares a background service or platform integration (storage, notifications, network).

@service id="saveService" type="storage" { }

16. Meta Domain (Domain 8)

@metaMeta

Scene-level configuration block. Must appear before all other domain blocks.

@meta {
    @viewport width=1920 height=1080 fps=60
              avk="audio visual kinesthetic"
              colorspace="sRGB" { }
    @import src="shared/ui.pcs" { }
    @setting vsync=true msaa=4 debug=false { }
}
@importMeta

Imports another .pcs file into the current scene. All public symbols become available.

AttributeTypeDescription
srcstringRelative path to .pcs file
asstringOptional namespace prefix for imported symbols

17. Reserved Words

The following identifiers are reserved and may not be used as user-defined identifiers:

zqml  meta  import  setting  viewport  information
fragment  phrase  expression  image  graphic  bitmap
sound  music  audionode  vector  path  transform
bind  event  gesture  record  table  persist
view  navigate  service  layer  avk
public  private  protected  true  false  null
if  else  while  for  return  call  and  or  not

18. Common Attributes

These attributes are valid on most tags across all domains:

AttributeTypeDefaultDescription
idstring—Unique identifier within the scene
layerint 0–72Render layer (Visual domain tags only)
visiblebooltrueWhether the element is active
enabledbooltrueWhether the element processes events
tagstring—Arbitrary user label for grouping
namestring—Human-readable display name