PCML Markup Language Reference
1. Sigils
Sigils are special prefix characters that give syntactic meaning to identifiers and operators in PCML. There are five sigils:
@image, @sound, @zqml$speed = 5.0, $playerXid. Example: #player, #background-> #player.x-- end of section2. Tag Anatomy
Every PCML block follows this structure:
[modifier] @tagname [attr1="value"] [attr2=42] ... {
// child tags or statements
}
| Part | Required? | Description |
|---|---|---|
[modifier] | Optional | public, private, or protected. Default: private. |
@tagname | Required | The domain tag keyword, prefixed with @. |
attr=value | Varies | Key-value attribute pairs. String values are double-quoted. Numbers are unquoted. |
{ ... } | Required | Block body. May be empty ({ }) for self-contained tags. |
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
| Type | Syntax | Examples |
|---|---|---|
| String | "..." (double quotes only) | "hello", "sprite.png" |
| Integer | Bare decimal integer | 0, 255, -10 |
| Float | Decimal with . | 1.0, 3.14, -0.5 |
| Boolean | true / false | true, 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
| Attribute | Type | Default | Description |
|---|---|---|---|
id | string | — | Unique identifier for this expression block |
tick | bool | false | If true, evaluated every engine update frame |
trigger | string | — | ID of an @event that activates this expression |
once | bool | false | If true, evaluated only on the first trigger |
delay | float | 0.0 | Seconds to wait before evaluation |
7. Operators
| Category | Operators | Notes |
|---|---|---|
| Arithmetic | + - * / % ** | ** is exponentiation |
| Comparison | == != < > <= >= | Returns boolean |
| Logical | && || ! | Short-circuit evaluation |
| Assignment | = += -= *= /= | Compound assignment in expressions |
| Reference | -> #id $var | Cross-domain and variable dereferencing |
| String | + (concat) | Only valid between string operands |
| Ternary | condition ? a : b | Inline 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.
A named, reusable logic block. Analogous to a function or subroutine. Can be called by reference from @expression blocks.
| Attribute | Type | Description |
|---|---|---|
id | string | Unique name for this fragment |
params | string | Comma-separated parameter names |
returns | string | Return type hint (int, float, bool, string) |
@fragment id="clamp" params="val, lo, hi" returns="float" {
return ($val < $lo) ? $lo : ($val > $hi) ? $hi : $val
}
Renders a text string to the visual output. Belongs to both Script (content) and Visual (rendering) domains; layer assignment controls draw order.
| Attribute | Type | Description |
|---|---|---|
id | string | Element identifier |
text | string | Text content or $var reference |
font | string | Font family name |
size | float | Font size in pixels |
color | color | Text color (#RRGGBB) |
pos | vector2 | Screen position (x, y) |
layer | int | Render layer 0–7 |
align | string | "left", "center", "right" |
@phrase id="scoreDisplay" text="Score: $score"
font="Segoe UI" size=24 color="#FFFFFF"
pos=(20, 20) layer=5 { }
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.
Renders a raster image file to the scene. The most common visual tag.
| Attribute | Type | Description |
|---|---|---|
id | string | Element identifier |
src | string | Relative path to image file (PNG, JPG, BMP) |
pos | vector2 | Top-left position on screen |
size | vector2 | Render dimensions (overrides natural size) |
layer | int | Render layer 0–7 |
alpha | float | Opacity 0.0–1.0 (default 1.0) |
visible | bool | Whether to render (default true) |
origin | vector2 | Rotation/scale origin (default top-left) |
rotation | float | Rotation in degrees |
scale | vector2 | Scale factor per axis |
clip | rect | Source rectangle for sprite-sheet clipping |
tint | color | Multiplicative color tint |
@image id="player" src="hero.png"
pos=(100, 400) layer=3
alpha=1.0 rotation=0 scale=(1.0, 1.0) { }
Renders vector graphic primitives: rectangles, ellipses, lines, and polygons.
| Attribute | Type | Description |
|---|---|---|
shape | string | "rect", "ellipse", "line", "polygon" |
pos | vector2 | Position of the shape |
size | vector2 | Bounding dimensions |
fill | color | Fill color |
stroke | color | Border color |
strokeWidth | float | Border thickness in pixels |
layer | int | Render layer 0–7 |
radius | float | Corner 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 { }
A direct Win2D CanvasBitmap wrapper for high-performance, low-level pixel access. Use for procedurally generated textures or raw pixel manipulation.
| Attribute | Type | Description |
|---|---|---|
width | int | Bitmap width in pixels |
height | int | Bitmap height in pixels |
format | string | "rgba8", "rgb8", "a8" |
layer | int | Render layer 0–7 |
pos | vector2 | Screen position |
11. Audio Domain (Domain 3)
A one-shot or looping sound effect.
| Attribute | Type | Description |
|---|---|---|
src | string | Path to audio file (WAV, MP3, OGG) |
volume | float | 0.0–1.0 |
pitch | float | Pitch shift (1.0 = normal) |
loop | bool | Loop playback |
autoplay | bool | Play on scene load |
spatial | bool | Enable 2D positional audio |
pos | vector2 | Audio source position (if spatial) |
@sound id="jumpSFX" src="jump.wav"
volume=0.8 pitch=1.0 loop=false { }
Background music track with fade and loop support.
| Attribute | Type | Description |
|---|---|---|
src | string | Path to audio file |
volume | float | 0.0–1.0 |
loop | bool | Loop (default true) |
fadein | float | Fade-in duration in seconds |
fadeout | float | Fade-out duration in seconds |
autoplay | bool | Play on scene load |
@music id="bgTrack" src="theme.mp3"
volume=0.6 loop=true fadein=2.0 autoplay=true { }
A node in the Windows Media Audio graph. Use for DSP effects, mixing, or custom audio routing.
| Attribute | Type | Description |
|---|---|---|
type | string | "effect", "submix", "output" |
effect | string | "reverb", "echo", "equalizer", "limiter" |
input | string | ID of source node |
12. Geometry Domain (Domain 4)
A 2D vector value, usable as a position, direction, or velocity.
@vector id="gravity" x=0.0 y=9.8 { }
A sequence of 2D points defining a bezier or linear path. Used for movement rails, collision shapes, or visual curves.
| Attribute | Type | Description |
|---|---|---|
points | string | Space-separated (x,y) pairs |
closed | bool | Connect last point to first |
type | string | "linear", "bezier", "catmull" |
@path id="enemyRail" closed=false type="linear"
points="(0,300) (400,300) (400,500) (800,500)" { }
Applies a reusable transformation (translate, rotate, scale) to one or more elements.
| Attribute | Type | Description |
|---|---|---|
target | string | ID of element to transform |
translate | vector2 | Pixel offset |
rotate | float | Degrees clockwise |
scale | vector2 | Scale per axis |
origin | vector2 | Transform pivot point |
13. Relational Domain (Domain 5)
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" { }
Defines an input or system event handler.
| Attribute | Type | Description |
|---|---|---|
on | string | Event name: "keydown", "keyup", "tap", "collision", "timer", "load" |
key | string | Key name for keyboard events (e.g. "Space", "ArrowLeft") |
call | string | ID of @expression or @fragment to invoke |
target | string | ID of element for collision events |
@event on="keydown" key="Space" call="jump" { }
@event on="collision" target="#enemy" call="takeDamage" { }
Recognizes touch or pointer gestures.
| Attribute | Type | Description |
|---|---|---|
type | string | "swipe", "pinch", "tap", "drag" |
direction | string | "left", "right", "up", "down" (swipe only) |
call | string | Fragment or expression to invoke |
14. Data Domain (Domain 6)
A structured data record — analogous to a struct or row.
@record id="enemy01" {
$type = "grunt"
$health = 30
$speed = 2.5
$reward = 10
}
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 }
}
Marks a variable or record for persistent storage (ApplicationData.LocalSettings).
@persist target="$highScore" key="game.highScore" { }
15. Application Domain (Domain 7)
Defines a named application screen/page that can be navigated to.
@view id="mainMenu" title="Main Menu" default=true { }
Navigates to a target @view, optionally passing parameters.
@navigate to="#gameScene" transition="fade" duration=0.5 { }
Declares a background service or platform integration (storage, notifications, network).
@service id="saveService" type="storage" { }
16. Meta Domain (Domain 8)
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 { }
}
Imports another .pcs file into the current scene. All public symbols become available.
| Attribute | Type | Description |
|---|---|---|
src | string | Relative path to .pcs file |
as | string | Optional 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:
| Attribute | Type | Default | Description |
|---|---|---|---|
id | string | — | Unique identifier within the scene |
layer | int 0–7 | 2 | Render layer (Visual domain tags only) |
visible | bool | true | Whether the element is active |
enabled | bool | true | Whether the element processes events |
tag | string | — | Arbitrary user label for grouping |
name | string | — | Human-readable display name |