Prospectus Celestial API Reference

Complete C# / UWP programmer's interface for the Prospectus Celestial Engine v1.0
C# / .NET UWP / Win2D Async-First

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

Namespace Add 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.

PCFileService
ProspectusCelestial.IO.PCFileService
Loads, caches, and manages Prospectus Celestial scene files (.pcs). Singleton per application instance.

Constructor

public PCFileService(IZQFileResolver resolver = null)

Creates a new file service. If resolver is null, uses the default PackageFileResolver which loads from the app's Assets folder.

Methods

public async Task<PCScene> LoadSceneAsync(string path, PCLoadOptions options = null)async

Loads and compiles a .pcs scene file. Returns a fully parsed PCScene ready for rendering.

ParameterTypeDescription
pathstringRelative path to the .pcs file, e.g. "Scenes/MainMenu.pcs"
optionsPCLoadOptionsOptional load configuration (preload assets, strict mode, etc.)

Throws: PCParseError on malformed PCML. FileNotFoundException if path does not resolve.

public async Task<string> ReadRawAsync(string path)async

Reads raw PCML text from a file without parsing. Useful for tooling, syntax highlighting, or source inspection.

public void Preload(string[] paths)

Begins background loading of the listed scene files into the internal cache. Subsequent calls to LoadSceneAsync for these paths return immediately from cache.

public void Unload(string path)

Removes a scene from the cache and disposes all associated GPU and audio resources.

public bool IsCached(string path)prop

Returns true if the given path is currently in the scene cache.

Properties

PropertyTypeDescription
ResolverIZQFileResolverThe active file resolver implementation
CachedSceneCountintNumber of scenes currently in memory
StrictModeboolIf 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.

PCDataReader
ProspectusCelestial.Runtime.PCDataReader
Read and write access to scene variables, element attributes, and data domain records at runtime.

Methods

public T Get<T>(string variableName)returns T

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");
public void Set<T>(string variableName, T value)

Sets a scene variable from C#. Changes are reflected in the next engine update tick.

reader.Set("playerX", 320.0f);
reader.Set("health", 75);
public T GetAttr<T>(string elementId, string attributeName)returns T

Gets the current value of a named attribute on any scene element by its id.

float alpha = reader.GetAttr<float>("player", "alpha");
public void SetAttr<T>(string elementId, string attr, T value)

Sets an element attribute at runtime, bypassing the expression system. Useful for direct C# control of scene elements.

public IEnumerable<string> ListVariables(PCScope scope = PCScope.All)returns IEnumerable

Returns the names of all variables in the given scope. Useful for debugging and inspector tools.

public PCRecord GetRecord(string dataId)returns PCRecord

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

PCScene
ProspectusCelestial.Runtime.PCScene
Represents a fully compiled, renderable Prospectus Celestial scene. Returned by PCFileService.LoadSceneAsync. Attach to a CanvasAnimatedControl to render.

Key Members

MemberTypeDescription
NamestringScene name from @zqml name=...
VersionVersionPCML version declared in the file
DataReaderPCDataReaderRuntime read/write access to scene variables
AVKPCAVKViewportThe active AVK viewport for this scene
LayerStackPCLayerStackThe eight-layer composition stack
IsLoadedboolTrue if assets are fully preloaded
OnDrawTypedEventHandlerWire to CanvasAnimatedControl.Draw
OnUpdateTypedEventHandlerWire to CanvasAnimatedControl.Update

Methods

public PCNode FindById(string id)returns PCNode

Finds and returns a scene node by its declared id. Returns null if not found.

public IEnumerable<PCNode> FindByDomain(PCDomain domain)returns IEnumerable

Returns all nodes belonging to the specified domain.

public void TriggerEvent(string eventId)

Fires a named @event from C# code, allowing external triggers to drive scene expressions.

public async Task PreloadAssetsAsync()async

Pre-loads all textures, audio files, and font assets referenced by the scene into GPU/audio memory. Call before first render for smooth startup.

public void Dispose()

Releases all GPU, audio, and managed resources. Always call when a scene is no longer needed.

PCEngine

PCEngine
ProspectusCelestial.Runtime.PCEngine
Top-level engine controller. Manages scene transitions, global settings, and the Win2D CanvasAnimatedControl lifecycle.

Static Properties

PropertyTypeDescription
PCEngine.InstancePCEngineGlobal singleton engine instance
PCEngine.VersionstringEngine version string, e.g. "1.0.0"
PCEngine.TargetFPSintTarget frames per second (default 60)
PCEngine.DeltaTimefloatSeconds elapsed since last update tick
PCEngine.TotalTimefloatTotal seconds since engine start
PCEngine.ActiveScenePCSceneThe currently rendering scene

Methods

public void Initialize(CanvasAnimatedControl canvas)

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);
}
public async Task LoadSceneAsync(string path)async

Loads and immediately activates a scene as the ActiveScene. Replaces the previously active scene.

public async Task TransitionToAsync(string path, PCTransition transition)async

Loads a new scene and transitions to it with a visual effect.

PCTransitionEffect
PCTransition.FadeCross-fade between scenes
PCTransition.SlideLeftNew scene slides in from right
PCTransition.SlideRightNew scene slides in from left
PCTransition.DissolvePixel dissolve transition
PCTransition.NoneImmediate cut

PCNode

PCNode
ProspectusCelestial.AST.PCNode
Base class for all compiled PCML elements. Provides common identity, domain, layer, and scope information.
PropertyTypeDescription
IdstringThe tag's declared id attribute
DomainPCDomainWhich of the 8 domains this node belongs to
LayerintRender layer 0–7
AccessPCAccessPublic, Private, or Protected
ChildrenIReadOnlyList<PCNode>Child nodes in the AST
ParentPCNodeParent node (null for top-level)
IsVisibleboolCurrent visibility state
AttributesPCAttributeMapAll parsed attributes as a typed dictionary

PCVisualNode

PCVisualNode
ProspectusCelestial.AST.PCVisualNode : PCNode
Extended node for all Visual domain elements (@image, @graphic, @bitmap, @phrase). Exposes transform, color, and Win2D drawing primitives.
PropertyTypeDescription
PositionVector2Current screen position
SizeVector2Current render size
RotationfloatCurrent rotation in degrees
ScaleVector2Current scale factors
AlphafloatCurrent opacity 0.0–1.0
TintColorMultiplicative color tint
BitmapCanvasBitmapUnderlying Win2D bitmap (if applicable)
TransformMatrix3x2Computed world transform matrix
public void Draw(CanvasDrawingSession ds)

Issues Win2D draw calls for this node into the provided CanvasDrawingSession. Called automatically by the renderer; expose for custom render passes.

public Rect GetBounds()returns Rect

Returns the axis-aligned bounding box of this visual element in screen space.

PCAudioNode

PCAudioNode
ProspectusCelestial.AST.PCAudioNode : PCNode
Node for Audio domain elements (@sound, @music, @audionode). Wraps Windows.Media.Audio graph nodes.
Method / PropertyTypeDescription
Play()voidStarts or resumes playback
Stop()voidStops playback and resets position
Pause()voidPauses playback at current position
FadeTo(float vol, float dur)voidFades volume to target over dur seconds
VolumefloatCurrent volume 0.0–1.0
PitchfloatCurrent pitch multiplier
IsPlayingboolTrue if currently playing
PositionTimeSpanCurrent playback position
DurationTimeSpanTotal audio length

PCRenderer

PCRenderer
ProspectusCelestial.Runtime.PCRenderer
The Win2D-backed rendering engine. Composites all layers (0→7) into the final frame each draw call.
PropertyTypeDescription
BackgroundColorColorScene clear color (default black)
RenderScalefloatUniform scale applied to all layers (for DPI scaling)
DebugOverlayboolIf true, renders layer outlines and node bounds
DrawCallCountintNumber of Win2D draw calls issued last frame
FrameTimefloatLast frame render time in milliseconds
public void RenderLayer(CanvasDrawingSession ds, int layer)

Renders a single layer to the provided drawing session. Use for custom compositing effects.

public void SetLayerBlendMode(int layer, ZQBlendMode mode)

Changes the blend mode used when compositing the given layer onto the frame.

ZQBlendModeEffect
NormalStandard alpha blending (default)
AdditiveLight/glow effects
MultiplyShadow/darkening effects
ScreenBrightening/highlight effects

PCAVKViewport

PCAVKViewport
ProspectusCelestial.Runtime.PCAVKViewport
Controls the three AVK output channels for the active scene — Audio, Visual, and Kinesthetic.
PropertyTypeDescription
WidthfloatViewport width in pixels
HeightfloatViewport height in pixels
DPIfloatDisplay DPI
TargetFPSintTarget frame rate
AudioEnabledboolMaster audio channel toggle
VisualEnabledboolMaster visual channel toggle
KinestheticEnabledboolMaster input channel toggle
MasterVolumefloatGlobal volume multiplier 0.0–1.0

PCLayerStack

PCLayerStack
ProspectusCelestial.Runtime.PCLayerStack
Manages the 8-layer composition system. Provides per-layer visibility, blend mode, and node enumeration.
public ZQLayer this[int index]indexer

Gets a ZQLayer object for the given layer index (0–7). Supports the Infinity Principle: index 8 returns Layer 0.

ZQLayer PropertyTypeDescription
IsVisibleboolToggle an entire layer on/off
AlphafloatMaster opacity for the layer
BlendModeZQBlendModeCompositing blend mode
NodeCountintNumber of nodes on this layer
NodesIReadOnlyList<PCNode>All nodes on this layer, in draw order

PCExpressionRuntime

PCExpressionRuntime
ProspectusCelestial.Runtime.PCExpressionRuntime
Evaluates @expression and @fragment script blocks. Exposes the expression environment for debugging and external injection.
public ZQValue Evaluate(string zqmlExpression)returns ZQValue

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();
public void InjectFunction(string name, Func<ZQValue[], ZQValue> fn)

Registers a C# delegate as a callable function within PCML expressions. Callable as name(args) inside any @expression block.

Exception Types

ExceptionNamespaceWhen thrown
PCLexErrorProspectusCelestial.ParsingTokenization failure in the Lexer stage
PCParseErrorProspectusCelestial.ParsingInvalid tag structure, wrong domain, missing required attribute
PCScopeErrorProspectusCelestial.ASTUnresolved reference, access modifier violation
PCRenderErrorProspectusCelestial.RuntimeMissing asset, out-of-range layer, Win2D failure
PCRuntimeErrorProspectusCelestial.RuntimeExpression evaluation failure, null reference

All ZQ exceptions inherit from ProspectusCelestial.PCException, which provides:

PropertyDescription
LineSource line number in the .pcs file (where applicable)
ColumnSource column number
StageWhich pipeline stage raised the error
ElementIdThe id of the tag that caused the error (where applicable)
ZQCodeMachine-readable error code string, e.g. "ZQ-P-001"

Diagnostics API

ZQDiagnostics
ProspectusCelestial.Diagnostics.ZQDiagnostics
Runtime performance and debugging metrics for the PCE pipeline.
PropertyTypeDescription
FPSfloatCurrent frames per second
FrameTimeMsfloatLast frame duration in milliseconds
DrawCallCountintWin2D draw calls issued last frame
NodeCountintTotal nodes in the active scene AST
ExpressionEvalCountintExpression blocks evaluated last tick
AudioLatencyMsfloatAudio pipeline latency in milliseconds
GPUMemoryMBfloatEstimated GPU texture memory in use (MB)

PCMath

Static math utility class with helpers commonly needed in PCML expression logic and C# game code.

MethodSignatureDescription
Clampfloat Clamp(float v, float lo, float hi)Clamps value between lo and hi
Lerpfloat Lerp(float a, float b, float t)Linear interpolation
SmoothStepfloat SmoothStep(float edge0, float edge1, float x)Smooth Hermite interpolation
Wrapfloat Wrap(float v, float min, float max)Wraps value within [min, max]
Distancefloat Distance(Vector2 a, Vector2 b)2D Euclidean distance
Anglefloat Angle(Vector2 from, Vector2 to)Angle in degrees from from to to
NormalizeVector2 Normalize(Vector2 v)Unit vector
RandomRangefloat RandomRange(float lo, float hi)Random float in [lo, hi]

PCColor

Color utility for parsing PCML color literals and converting between color spaces.

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

MethodDescription
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
TotalSizeMBTotal size of cached assets in megabytes