Build, package, and release

繁體中文

1. Most authors just need build

After validation and playtesting:

prismatix validate my-game
prismatix build my-game

Normal build creates a Player distribution, not just intermediate IR. The default destination is my-game/dist/<project-id>/, containing the Player, packaged content, and redistributable dependencies. Players do not need Node.js, npm, the SDK, or engine sources.

To choose a destination:

prismatix build my-game --output "release/First Light"

--output changes the destination, not the build mode. Keep it away from Story, Assets, Content, the project root, and unrelated existing work.

2. Artifact, pack, and run

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

These demonstrate alternatives; they are not a mandatory sequence for every release. Giving someone a Runtime IR file does not give them a complete game.

3. Output-directory protection

The CLI uses staging and an ownership inventory to protect sources and existing files. If the Player adds saves/logs to a distribution directory, or you manually modify it, a later replacement may be refused.

Choose a fresh output directory and preserve player data separately. Do not delete unrelated data or bypass ownership checks merely to make the build succeed. Distribute the complete output tree, dependencies, and licenses rather than copying only an executable.

4. Platforms and capabilities

Intended desktop targets are Windows x64, Linux x64, and macOS x64/arm64, but release support claims require platform-specific native evidence. The CLI option table does not expose a universal --platform cross-compilation switch. Use a matching target platform and runtime bundle, and verify each target separately.

WASM is a Studio Preview path, not a complete web-game distribution promise. Native video and custom GPU-effect capabilities differ. Custom shaders compile offline during packaging; not every build host produces every native shader format.

--compression accepts none, fast, balanced, and maximum. --encrypt is an additional packaging option, not a promise that content can never be extracted. It does not replace resource licensing, save compatibility, or integrity tests.

5. Release testing

Launch the output in a clean directory or machine without your source checkout, node_modules, or author-specific environment variables. Check title navigation, a new game, both branches, both languages, Chinese glyphs, images, audio, and custom UI.

Save, fully exit the Player, reopen it, and load. Cover empty and existing slots, rollback, animation cancellation, and extension-state restoration. Validate upgrades with isolated saves from the previous release, not destructive experiments on real player data.

Check that the output excludes unnecessary sources, secrets, private saves, and debug material, while retaining licenses and third-party notices. Record the game version, engine snapshot, platform, test results, and artifact checksums.

6. Offline work and upgrades

Initial creation requires a registry. Once dependencies and the matching runtime bundle are prepared, the documented dev/build author path supports offline work. Creating one project does not mean every future dependency, missing platform bundle, or external asset source has been cached.

Keep the local CLI/SDK and lockfile pinned. Upgrade deliberately in a branch, validate Story and extensions, and test the packaged Player and old saves. Updating a global CLI should not silently change an existing project's compiler version.

7. Native builds are for engine contributors

This is not the ordinary author workflow. In an engine checkout, prepare C++20, CMake, Ninja, and platform dependencies as described by the upstream README, then run:

npm ci
npm run check

Windows example from a Visual Studio Developer PowerShell:

$env:VCPKG_ROOT = "C:\path\to\vcpkg"
cmake --preset x64-debug
cmake --build --preset x64-debug
cmake --install out/build/x64-debug --prefix out/install/x64-debug --component PrismatiXRuntime
$env:PRISMATIX_PHASE1_RUNTIME = "out/install/x64-debug"
npm run test:phase1

On macOS, use the upstream macos-debug preset. For other hosts, consult the same snapshot's presets instead of copying another developer's absolute SDK paths. The default mock gate tests orchestration, not real graphics or audio. Record real-runtime gates, clean-machine launches, and human playtests separately.

Candidate-package maintainers can also run:

node scripts/phase1-clean-install.mjs --mock --keep
node scripts/phase1-clean-install.mjs --runtime /path/to/installed-runtime --keep

The second command requires the correct installed runtime component; its path is a placeholder. These are contributor acceptance checks, not setup steps every story author must perform.

Sources: Author quickstart, CLI build/pack implementation, Engine README, Release audit.