CLI reference

繁體中文

This table follows the pinned snapshot's CLI option table, not every possible future version. The global command respects a project's pinned local CLI. Consult help from the version actually used by your project.

Everyday commands

prismatix create my-game
prismatix dev my-game
prismatix validate my-game
prismatix build my-game

Inside the project, use npm exec -- prismatix dev ., or pnpm exec prismatix dev . in an already prepared pnpm environment. Initial create dependency preparation still invokes npm.

Shared rules

Use prismatix --help or prismatix <command> --help. Commands accept at most one positional argument. Default path resolution depends on the command, so explicitly passing my-game or . is clearer for everyday work. Quote paths containing spaces.

Value options accept --name value and --name=value. Boolean flags such as --once do not take a following true. Unknown or duplicate options, invalid numbers, and incompatible combinations are rejected. Do not copy --verbose, --platform, or other flags from unrelated CLIs.

--json enables machine-readable output. Diagnostics are NDJSON on stderr, with status output on stdout. Do not merge both streams and parse them as one JSON document. Automation must check exit codes as well as output.

create

prismatix create "my game" --name "First Light" --id first-light --locale zh-TW --width 1280 --height 720

The destination must not exist or must be empty. This is not an upgrade command for an existing game.

dev

Normally use prismatix dev my-game. Advanced value options are --runtime, --preview-host, and --debounce; flags are --once and --smoke.

--once supports one-shot apply/play acknowledgment and shutdown, not continuous editing. --smoke is for smoke validation. Runtime/PreviewHost overrides are package-diagnostic or maintainer tools; normal authors should not have to locate an unrelated native executable before opening a project.

validate

prismatix validate my-game --json

There are no additional command-specific options. Validation loads project sources and dependencies, checks them, and compiles them. It does not establish successful execution of every JavaScript callback, audio path, visual result, or save interaction.

build / pack / run

Shared value options are --output, --runtime, --packager, --player, and --compression, plus the --encrypt flag. Compression must be none, fast, balanced, or maximum.

build additionally accepts --artifact-only and --distribution, which cannot be combined. Normal build already takes the distribution path; a Player does not require an extra distribution flag.

prismatix build my-game --output "release/First Light"
prismatix build my-game --artifact-only --output my-game/.prismatix/artifact
prismatix pack my-game --compression balanced
prismatix run my-game

These illustrate alternatives, not a mandatory sequence. See Packaging for output protection and platform boundaries.

ids: maintain Story identities

Value options are --document-id, --prefix, and --backup; flags are --write and --check.

prismatix ids --help
prismatix ids my-game/Story/main.pxstory --check

Check and review changes before writing. --write changes source files. Do not regenerate every explicit ID in released content merely to make a check pass. Keep a backup and inspect the version-control diff. See Story identity.

migrate: author-document migration

Start with prismatix migrate --help to confirm the source type you intend to migrate. Value options are --report, --backup, --entry-story, --entry-ui, --supported-locales, --save-version, --id, --name, --version, --content-version, --default-locale, --story-index, and --game-catalog. The write flag is --write.

Do not experiment on the only copy of a project. Back up, inspect reports and diffs, write deliberately, then validate and playtest. This command is not synonymous with saveMigrations and does not automatically rewrite all legacy extension logic to a newer API.

inspect-save: diagnose a save

prismatix inspect-save --help

Value options are --package, --secret, --runtime, and --player. Use a matching package/runtime and provide the information required by help. Keep secrets out of public issues, screenshots, and shared shell histories. Successful inspection is not a guarantee that arbitrary versions can restore the save.

Automation practice

Distinguish author-data validation, candidate-package installation, real native startup, and visual/audio experience. Record engine version, Node version, OS, exact commands, exit codes, and diagnostic source locations. Never let automated checks overwrite unrelated projects or player data.

Sources: CLI option table, parser, and commands, Author workflow.