The pfx tool

pfx, a game and render engine: scaffold, edit, bench and bake games and scenes, stage Steam builds, and render apps’ shots, logos, icons and scenes offline on its path tracer.

pfx --help prints:

pfx, a game and render engine: scaffold, edit, bench and bake games and scenes, stage Steam builds, and render apps' shots, logos, icons and scenes offline on its path tracer.

usage:
  pfx render --app <app> --shot <shot> (--clip | --still) --fixtures <dir> (--rev <tag|rev> | --app-dir <dir> | --adapter <bin>) [flags]
  pfx render --asset <kind> --product <product> [--recipes <dir>] [flags]
  pfx render --icons <set> --product <product> [--recipes <dir>] [flags]
  pfx render --scene <shot> --product <product> (--clip | --still) [--recipes <dir>] [flags]
  pfx encode --manifest <path>
  pfx archive --retry|--reindex
  pfx archive import --app <app> --shot <shot> (--clip | --still) --rev <tag|commit> <files...>
  pfx list --shots|--presets|--scenes [flags]
  pfx bake --scene <dir> [flags]
  pfx steam stage --manifest <game>/steam.toml --out <caller tmp dir>
  pfx cache [--prune]
  pfx cache --json
  pfx cache prune --json [--dry-run]
  pfx font subset --font <ttf> --out <ttf> [--chars <file>]... [--base gb2312-1|none] [--no-closure]
  pfx edit <scene.toml>
  pfx edit <project folder>
  pfx new <game> [--path <dir>] [--with-module]
  pfx bench <scene.toml> --seconds N [--camera <object>] [--replay <recording.json>] [--size WxH] [--stats <path>] [--seed S]
  pfx scene migrate <scene.toml> [--dry-run]
  pfx scene fix <scene.toml> [--dry-run]
  pfx --version
  pfx --help
clip masters are x264 at 60 fps; pconv makes video deliveries
still --derive and --web add PNG deliveries; --hdr adds diagnostic scene-linear EXR files; --no-archive skips the archive step
--samples N overrides a shot's samples; --class interactive|clip|truth|search sets the pgpu class (app renders default to clip for stills and clips, asset renders and bake to truth, list --shots to interactive)
asset recipes come from --recipes <dir>, then PFX_RECIPES, then <git toplevel>/render/assets: presets/<product>.toml, icons/<product>/<set>.toml, shots/<product>.toml, every product a shot lists read from that one folder
a logo, wordmark or lockup reads its master from --assets <dir>, then PITO_ASSETS, then <git toplevel>/render/marks: logos/<product>.svg, wordmarks/<product>.svg, lockups/<product>.svg
an app renders only itself: run from its own git tree, whose render/engine.toml [app] names it; --rev checks out that tree's own revision
steam stage writes Steam's build scripts and stages depots; it does not upload
bench plays a scene headless for N seconds at 60 fps, from its own camera, an object's (--camera) or a recorded input stream (--replay), writes the engine's frame stats to --stats (default tmp/pfx/bench/<scene>-<time>.jsonl) and prints one JSON summary line (docs/frame-stats.md, Bench); it paces like pgpu's manners ask, so run it under pgpu
scene migrate rewrites a scene's format 0 files as format 1, keeping comments; scene fix writes the ids its entries lack; both refuse to write when the check fails
new scaffolds a game into an existing, empty repo folder (default ./<game>): one binary that plays the game and opens it in the editor with `<game> edit` (docs/projects.md)

Commands

Command	Shape
render	pfx render [OPTIONS] <--app <APP>|--asset <ASSET>|--icons <ICONS>|--scene <SCENE>>
encode	pfx encode --manifest <MANIFEST>
archive	pfx archive <--retry|--reindex|import>
list	pfx list [OPTIONS] <--shots|--presets|--scenes>
bake	pfx bake [OPTIONS] --scene <SCENE>
steam	pfx steam <COMMAND>
cache	pfx cache [OPTIONS] [COMMAND]
font	pfx font <COMMAND>
edit	pfx edit <PATH>
new	pfx new [OPTIONS] <GAME>
bench	pfx bench [OPTIONS] --seconds <SECONDS> <SCENE>
scene	pfx scene <COMMAND>

Flags

Each mode takes the flags below and refuses any other. A switch takes no value; any other flag takes one, as --flag value or --flag=value. new, edit, bench, scene, font subset and archive take what their usage lines above show.

pfx render –app

An app’s shot, rendered by its own adapter.

Flag	Kind
--adapter	takes a value
--app	takes a value
--app-dir	takes a value
--at	takes a value
--class	takes a value
--clip	switch
--day	takes a value
--derive	takes a value
--fixtures	takes a value
--force-fixtures	switch
--hdr	switch
--fps	takes a value
--heading	takes a value
--hour	takes a value
--keep-frames	switch
--latitude	takes a value
--no-encode	switch
--no-archive	switch
--out	takes a value
--rev	takes a value
--samples	takes a value
--seconds	takes a value
--seed	takes a value
--set	takes a value
--shot	takes a value
--size	takes a value
--still	switch
--web	takes a value

pfx render –asset

A logo, wordmark, lockup, tile or card on the path tracer.

Flag	Kind
--angle	takes a value
--asset	takes a value
--assets	takes a value
--at	takes a value
--background	takes a value
--class	takes a value
--columns	takes a value
--count	takes a value
--day	takes a value
--derive	takes a value
--draft	switch
--fps	takes a value
--heading	takes a value
--hour	takes a value
--jitter	takes a value
--keep-frames	switch
--key	takes a value
--latitude	takes a value
--layout	takes a value
--lens	takes a value
--margin	takes a value
--move	takes a value
--no-encode	switch
--no-archive	switch
--ortho	switch
--out	takes a value
--preset-file	takes a value
--product	takes a value
--recipes	takes a value
--roll	takes a value
--samples	takes a value
--scale	takes a value
--seconds	takes a value
--seed	takes a value
--set	takes a value
--shadow	takes a value
--shot-file	takes a value
--size	takes a value
--spacing	takes a value
--supersample	takes a value
--target	takes a value
--tilt	takes a value
--turn	takes a value
--use	takes a value
--web	takes a value
--zoom	takes a value

pfx render –icons

An icon set on the path tracer.

Flag	Kind
--angle	takes a value
--assets	takes a value
--at	takes a value
--background	takes a value
--class	takes a value
--columns	takes a value
--count	takes a value
--day	takes a value
--derive	takes a value
--draft	switch
--fps	takes a value
--heading	takes a value
--hour	takes a value
--icons	takes a value
--jitter	takes a value
--keep-frames	switch
--key	takes a value
--latitude	takes a value
--layout	takes a value
--lens	takes a value
--margin	takes a value
--move	takes a value
--no-encode	switch
--no-archive	switch
--only	takes a value
--ortho	switch
--out	takes a value
--preset-file	takes a value
--product	takes a value
--recipes	takes a value
--roll	takes a value
--samples	takes a value
--scale	takes a value
--seconds	takes a value
--seed	takes a value
--set	takes a value
--shadow	takes a value
--shot-file	takes a value
--size	takes a value
--spacing	takes a value
--supersample	takes a value
--target	takes a value
--tilt	takes a value
--turn	takes a value
--use	takes a value
--web	takes a value
--zoom	takes a value

pfx render –scene

A shot from a recipe folder’s shots file on the path tracer.

Flag	Kind
--angle	takes a value
--assets	takes a value
--at	takes a value
--background	takes a value
--class	takes a value
--clip	switch
--columns	takes a value
--count	takes a value
--day	takes a value
--derive	takes a value
--draft	switch
--fps	takes a value
--heading	takes a value
--hour	takes a value
--jitter	takes a value
--keep-frames	switch
--key	takes a value
--latitude	takes a value
--layout	takes a value
--lens	takes a value
--margin	takes a value
--move	takes a value
--no-encode	switch
--no-archive	switch
--ortho	switch
--out	takes a value
--preset-file	takes a value
--product	takes a value
--recipes	takes a value
--roll	takes a value
--samples	takes a value
--scale	takes a value
--scene	takes a value
--seconds	takes a value
--seed	takes a value
--set	takes a value
--shadow	takes a value
--shot-file	takes a value
--size	takes a value
--spacing	takes a value
--still	switch
--supersample	takes a value
--target	takes a value
--tilt	takes a value
--turn	takes a value
--use	takes a value
--web	takes a value
--zoom	takes a value

pfx list –shots

An app’s shots.

Flag	Kind
--adapter	takes a value
--app	takes a value
--app-dir	takes a value
--class	takes a value
--rev	takes a value
--shots	switch

pfx list –presets

The recipe folder’s presets.

Flag	Kind
--presets	switch
--recipes	takes a value

pfx list –scenes

The recipe folder’s scene shots.

Flag	Kind
--product	takes a value
--recipes	takes a value
--scenes	switch

pfx encode

Re-encode a master from its manifest.

Flag	Kind
--manifest	takes a value

pfx cache

The machine cache.

Flag	Kind
--prune	switch
--json	switch
--dry-run	switch

pfx bake

Path-traced probes, lightmaps, plates and detail maps.

Flag	Kind
--scene	takes a value
--assets	takes a value
--out	takes a value
--anchors	takes a value
--samples	takes a value
--name	takes a value
--force	switch
--detail	switch

pfx steam stage

Stage Steam’s build scripts and depots.

Flag	Kind
--manifest	takes a value
--out	takes a value

Errors

Input the tool can’t parse gets clap’s answer on stderr with exit 2: the error, the command’s usage line and For more information, try '--help'. A refusal after a successful parse is one line, pfx: …, with exit 1. pfx bench’s flags and summary are in Benchmark a scene and Frame stats.