Getting started

繁體中文

1. Prepare the authoring environment

Install Node.js with npm. Upstream CI uses Node.js 24.14.0; this candidate also records a Windows journey using 24.2.0. This is not a compatibility claim for every Node.js version. Confirm that your terminal can find both tools:

node --version
npm --version

The author workflow requires a matching CLI package containing the native runtime for your platform. You do not need C++, CMake, vcpkg, or an engine checkout. A missing runtime is an installation or platform-support problem, not a reason for a story author to compile the engine.

Package status: The commands below describe the published-package interface. Evidence for this source snapshot comes from candidate packages in an isolated registry, not confirmed public npm publication. If a maintainer supplies a private registry, configure access to that registry first. This handbook does not invent a package download URL.

2. Start with three commands

Run these in the directory where you want to keep your game:

npm install -g @prismatix/cli
prismatix create my-game
prismatix dev my-game

create prepares a short Chinese story, original character and background artwork, branches, a title screen, the default dialogue HUD, and Save/Load routes. It also installs exact project-local CLI/SDK versions and writes package-lock.json. You do not need a separate npm init or a second authoring SDK installation.

Preview opens at the title screen. Select Start to enter the story. A visible window is not evidence that every audio, text-rendering, or save scenario works; later chapters explain what to test.

3. Customize creation

Creation options are non-interactive:

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

--name is the display name; --id is the stable project identifier. --locale sets a locale tag; it does not translate the template into that language. Width and height must be integers from 1 through 16384. Quote paths containing spaces.

The destination must not exist or must be empty. Do not point create at an existing game. Initial preparation requires registry access. The CLI prepares a sibling staging directory and publishes the destination only after preparation succeeds.

4. Change your first line

Open my-game/Story/main.pxstory and find the dialogue associated with [id main.welcome]. Keep that identity and change the prose:

[id main.welcome]
@guide
Welcome to the first story I wrote!

Save and watch both the terminal and Preview. A successful edit prepares a new revision and waits for the replacement Preview to acknowledge applying and playing it before closing the previous Preview. The current policy restarts the scene; it does not promise to preserve your dialogue position. A syntax error produces diagnostics while retaining the last playable revision. The watcher also recovers from initial syntax errors when you fix and save the file.

Press Ctrl+C to end the development session. .prismatix/dev/ may retain the last successful revision for diagnosis; it is generated data, not story source to commit.

5. Validate and build

prismatix validate my-game
prismatix build my-game

validate checks the project and Story. Normal build produces a desktop distribution containing the Player, game content, and redistributable dependencies under my-game/dist/<project-id>/ by default. Players do not need Node.js or the SDK. See Packaging before distributing it.

To work from inside the project instead:

cd my-game
npm exec -- prismatix dev .

You can also use pnpm exec prismatix dev . in an already prepared project. However, create currently prepares dependencies by invoking npm. Starting the CLI through pnpm does not remove the npm prerequisite. Avoid competing lockfiles, and keep the exact local tool versions reproducible. The global prismatix command respects the project's pinned local CLI.

Check the result

You should be able to enter the story from the title screen, see your edited line, try both choices, and receive a successful validation result. Preview Save/Load slots last only for the current session and are cleared by a rebuild or Preview shutdown. Test saving, closing, and reopening the game with a packaged Player instead.

Next: Project structure and configuration.

Sources: Getting started, Creation implementation, CLI.