Prospectus Celestial API Reference
The Prospectus Celestial API is the C# programmer's interface to the PCE runtime. All classes reside in the ProspectusCelestial namespace unless otherwise noted. The API is async-first — loading, compilation, and asset operations return Task or Task<T>.
using ProspectusCelestial; and using ProspectusCelestial.Runtime; to your UWP page or class to access the full API surface. NuGet package: ProspectusCelestial.Engine.
PCFileService
The primary file-loading service. Resolves .pcs scene files from the application package, local storage, or a custom IZQFileResolver. All load operations are asynchronous.
Constructor
Creates a new file service. If resolver is null, uses the default PackageFileResolver which loads from the app's Assets folder.
Methods
Loads and compiles a .pcs scene file. Returns a fully parsed PCScene ready for rendering.
| Parameter | Type | Description |
|---|---|---|
path | string | Relative path to the .pcs file, e.g. "Scenes/MainMenu.pcs" |
options | PCLoadOptions | Optional load configuration (preload assets, strict mode, etc.) |
Throws: PCParseError on malformed PCML. FileNotFoundException if path does not resolve.
Reads raw PCML text from a file without parsing. Useful for tooling, syntax highlighting, or source inspection.
Begins background loading of the listed scene files into the internal cache. Subsequent calls to LoadSceneAsync for these paths return immediately from cache.
Removes a scene from the cache and disposes all associated GPU and audio resources.
Returns true if the given path is currently in the scene cache.
Properties
| Property | Type | Description |
|---|---|---|
Resolver | IZQFileResolver | The active file resolver implementation |
CachedSceneCount | int | Number of scenes currently in memory |
StrictMode | bool | If true, warnings are promoted to errors |
Usage Example
var service = new PCFileService();
PCScene scene = await service.LoadSceneAsync("Scenes/Starfall.pcs");
// Attach scene to Win2D canvas
canvasControl.Draw += scene.OnDraw;
canvasControl.Update += scene.OnUpdate;
DataReader
PCDataReader provides typed access to the data values inside a loaded PCScene — variables, element attributes, and data domain records.
Methods
Gets the current value of a scene variable by name (without the $ prefix).
float x = reader.Get<float>("playerX");
int hp = reader.Get<int>("health");
Sets a scene variable from C#. Changes are reflected in the next engine update tick.
reader.Set("playerX", 320.0f);
reader.Set("health", 75);
Gets the current value of a named attribute on any scene element by its id.
float alpha = reader.GetAttr<float>("player", "alpha");
Sets an element attribute at runtime, bypassing the expression system. Useful for direct C# control of scene elements.
Returns the names of all variables in the given scope. Useful for debugging and inspector tools.
Returns the structured record from an @record data domain tag by its id. Fields are accessible as a dictionary.
PCRecord rec = reader.GetRecord("playerProfile");
string name = rec["name"].AsString();
PCScene
Key Members
| Member | Type | Description |
|---|---|---|
Name | string | Scene name from @zqml name=... |
Version | Version | PCML version declared in the file |
DataReader | PCDataReader | Runtime read/write access to scene variables |
AVK | PCAVKViewport | The active AVK viewport for this scene |
LayerStack | PCLayerStack | The eight-layer composition stack |
IsLoaded | bool | True if assets are fully preloaded |
OnDraw | TypedEventHandler | Wire to CanvasAnimatedControl.Draw |
OnUpdate | TypedEventHandler | Wire to CanvasAnimatedControl.Update |
Methods
Finds and returns a scene node by its declared id. Returns null if not found.
Returns all nodes belonging to the specified domain.
Fires a named @event from C# code, allowing external triggers to drive scene expressions.
Pre-loads all textures, audio files, and font assets referenced by the scene into GPU/audio memory. Call before first render for smooth startup.
Releases all GPU, audio, and managed resources. Always call when a scene is no longer needed.
PCEngine
Static Properties
| Property | Type | Description |
|---|---|---|
PCEngine.Instance | PCEngine | Global singleton engine instance |
PCEngine.Version | string | Engine version string, e.g. "1.0.0" |
PCEngine.TargetFPS | int | Target frames per second (default 60) |
PCEngine.DeltaTime | float | Seconds elapsed since last update tick |
PCEngine.TotalTime | float | Total seconds since engine start |
PCEngine.ActiveScene | PCScene | The currently rendering scene |
Methods
Binds the engine to a UWP CanvasAnimatedControl. Must be called once before loading any scene. Wire this in your Page.Loaded event handler.
// In Page.xaml.cs
private void Page_Loaded(object sender, RoutedEventArgs e)
{
PCEngine.Instance.Initialize(myCanvas);
}
Loads and immediately activates a scene as the ActiveScene. Replaces the previously active scene.
Loads a new scene and transitions to it with a visual effect.
| PCTransition | Effect |
|---|---|
PCTransition.Fade | Cross-fade between scenes |
PCTransition.SlideLeft | New scene slides in from right |
PCTransition.SlideRight | New scene slides in from left |
PCTransition.Dissolve | Pixel dissolve transition |
PCTransition.None | Immediate cut |
PCNode
| Property | Type | Description |
|---|---|---|
Id | string | The tag's declared id attribute |
Domain | PCDomain | Which of the 8 domains this node belongs to |
Layer | int | Render layer 0–7 |
Access | PCAccess | Public, Private, or Protected |
Children | IReadOnlyList<PCNode> | Child nodes in the AST |
Parent | PCNode | Parent node (null for top-level) |
IsVisible | bool | Current visibility state |
Attributes | PCAttributeMap | All parsed attributes as a typed dictionary |
PCVisualNode
| Property | Type | Description |
|---|---|---|
Position | Vector2 | Current screen position |
Size | Vector2 | Current render size |
Rotation | float | Current rotation in degrees |
Scale | Vector2 | Current scale factors |
Alpha | float | Current opacity 0.0–1.0 |
Tint | Color | Multiplicative color tint |
Bitmap | CanvasBitmap | Underlying Win2D bitmap (if applicable) |
Transform | Matrix3x2 | Computed world transform matrix |
Issues Win2D draw calls for this node into the provided CanvasDrawingSession. Called automatically by the renderer; expose for custom render passes.
Returns the axis-aligned bounding box of this visual element in screen space.
PCAudioNode
| Method / Property | Type | Description |
|---|---|---|
Play() | void | Starts or resumes playback |
Stop() | void | Stops playback and resets position |
Pause() | void | Pauses playback at current position |
FadeTo(float vol, float dur) | void | Fades volume to target over dur seconds |
Volume | float | Current volume 0.0–1.0 |
Pitch | float | Current pitch multiplier |
IsPlaying | bool | True if currently playing |
Position | TimeSpan | Current playback position |
Duration | TimeSpan | Total audio length |
PCRenderer
| Property | Type | Description |
|---|---|---|
BackgroundColor | Color | Scene clear color (default black) |
RenderScale | float | Uniform scale applied to all layers (for DPI scaling) |
DebugOverlay | bool | If true, renders layer outlines and node bounds |
DrawCallCount | int | Number of Win2D draw calls issued last frame |
FrameTime | float | Last frame render time in milliseconds |
Renders a single layer to the provided drawing session. Use for custom compositing effects.
Changes the blend mode used when compositing the given layer onto the frame.
| ZQBlendMode | Effect |
|---|---|
Normal | Standard alpha blending (default) |
Additive | Light/glow effects |
Multiply | Shadow/darkening effects |
Screen | Brightening/highlight effects |
PCAVKViewport
| Property | Type | Description |
|---|---|---|
Width | float | Viewport width in pixels |
Height | float | Viewport height in pixels |
DPI | float | Display DPI |
TargetFPS | int | Target frame rate |
AudioEnabled | bool | Master audio channel toggle |
VisualEnabled | bool | Master visual channel toggle |
KinestheticEnabled | bool | Master input channel toggle |
MasterVolume | float | Global volume multiplier 0.0–1.0 |
PCLayerStack
Gets a ZQLayer object for the given layer index (0–7). Supports the Infinity Principle: index 8 returns Layer 0.
| ZQLayer Property | Type | Description |
|---|---|---|
IsVisible | bool | Toggle an entire layer on/off |
Alpha | float | Master opacity for the layer |
BlendMode | ZQBlendMode | Compositing blend mode |
NodeCount | int | Number of nodes on this layer |
Nodes | IReadOnlyList<PCNode> | All nodes on this layer, in draw order |
PCExpressionRuntime
Evaluates an arbitrary PCML expression string against the current scene's variable environment. Useful for dynamic queries and hot-reloading.
ZQValue result = runtime.Evaluate("$playerX + $speed * 2");
float val = result.AsFloat();
Registers a C# delegate as a callable function within PCML expressions. Callable as name(args) inside any @expression block.
Exception Types
| Exception | Namespace | When thrown |
|---|---|---|
PCLexError | ProspectusCelestial.Parsing | Tokenization failure in the Lexer stage |
PCParseError | ProspectusCelestial.Parsing | Invalid tag structure, wrong domain, missing required attribute |
PCScopeError | ProspectusCelestial.AST | Unresolved reference, access modifier violation |
PCRenderError | ProspectusCelestial.Runtime | Missing asset, out-of-range layer, Win2D failure |
PCRuntimeError | ProspectusCelestial.Runtime | Expression evaluation failure, null reference |
All ZQ exceptions inherit from ProspectusCelestial.PCException, which provides:
| Property | Description |
|---|---|
Line | Source line number in the .pcs file (where applicable) |
Column | Source column number |
Stage | Which pipeline stage raised the error |
ElementId | The id of the tag that caused the error (where applicable) |
ZQCode | Machine-readable error code string, e.g. "ZQ-P-001" |
Diagnostics API
| Property | Type | Description |
|---|---|---|
FPS | float | Current frames per second |
FrameTimeMs | float | Last frame duration in milliseconds |
DrawCallCount | int | Win2D draw calls issued last frame |
NodeCount | int | Total nodes in the active scene AST |
ExpressionEvalCount | int | Expression blocks evaluated last tick |
AudioLatencyMs | float | Audio pipeline latency in milliseconds |
GPUMemoryMB | float | Estimated GPU texture memory in use (MB) |
PCMath
Static math utility class with helpers commonly needed in PCML expression logic and C# game code.
| Method | Signature | Description |
|---|---|---|
Clamp | float Clamp(float v, float lo, float hi) | Clamps value between lo and hi |
Lerp | float Lerp(float a, float b, float t) | Linear interpolation |
SmoothStep | float SmoothStep(float edge0, float edge1, float x) | Smooth Hermite interpolation |
Wrap | float Wrap(float v, float min, float max) | Wraps value within [min, max] |
Distance | float Distance(Vector2 a, Vector2 b) | 2D Euclidean distance |
Angle | float Angle(Vector2 from, Vector2 to) | Angle in degrees from from to to |
Normalize | Vector2 Normalize(Vector2 v) | Unit vector |
RandomRange | float RandomRange(float lo, float hi) | Random float in [lo, hi] |
PCColor
Color utility for parsing PCML color literals and converting between color spaces.
| Method | Description |
|---|---|
PCColor.Parse(string hex) | Parses #RRGGBB or #RRGGBBAA to Color |
PCColor.FromHSV(float h, float s, float v) | Creates color from Hue/Saturation/Value |
PCColor.Lerp(Color a, Color b, float t) | Interpolates between two colors |
PCColor.ToHex(Color c) | Converts Color to #RRGGBBAA string |
PCAssetCache
Manages preloaded texture and audio assets to avoid redundant disk and GPU loads across multiple scenes.
| Method | Description |
|---|---|
GetBitmap(string path) | Returns cached CanvasBitmap or loads if not cached |
GetAudioFile(string path) | Returns cached audio file node |
Evict(string path) | Removes an asset from cache and frees GPU memory |
EvictAll() | Clears all cached assets |
TotalSizeMB | Total size of cached assets in megabytes |