Project structure and configuration

Understand source files, generated output, prismatix.json, and the canonical project contract.

Files you will work with

The starter and the additional files introduced later in this handbook form a layout like this:

my-game/
  prismatix.json              Author configuration
  package.json               Pinned tool versions
  package-lock.json          Reproducible dependency resolution
  Story/main.pxstory          Entry story
  Characters/guide.pxcharacter
  Assets/window.png
  Assets/guide.png
  Content/UI/Title.pxui
  Content/Fonts/              Starter font and license
  Content/Localization/zh-TW.json
  Content/Extensions/        Added in the extension tutorial
  Content/game.pxgame         Added or selected for game variables
  .prismatix/                Generated intermediate output
  dist/                      Normal build distribution output

This is a working-layout illustration, not a promise that create generates every advanced file. Preserve the starter's licenses and provenance. Do not treat compiled files under .prismatix/ as your source: the next build may replace them.

Beginner configuration versus the canonical contract

prismatix.json can specify only the values an author needs to override. The CLI loads it and lets the SDK prepare canonical project data. This minimal conceptual example is not a replacement for a generated project's assets, characters, and UI entries:

{
  "id": "first-light",
  "name": "First Light",
  "defaultLocale": "zh-TW",
  "resolution": {"width": 1280, "height": 720}
}

A complete project.pxproject follows the PrismatiXProject revision-2 schema, including versions, Story and UI entry points, a Story index, a game catalog, and extensions. Beginners do not need to handwrite that entire canonical document before creating a game.

When given a directory, the CLI looks for prismatix.json, then project.pxproject, then the conventional Story/main.pxstory fallback. Keeping two manifests can make it easy to edit the wrong one. Choose a clear authoring manifest, or pass a specific manifest path when necessary.

Common fields

Field	Purpose
`id`, `name`	Stable project identity and display name
`resolution`	Logical viewport dimensions, not necessarily physical device pixels
`defaultLocale`, `supportedLocales`	Default language and available languages
`assets`, `characters`	Resource identities, source paths, character documents
`gameCatalog`	Game variables, gallery, and unlockable definitions
`storyIndex`	Chapters, scenes, and language-specific Story sources
`extensions`	Explicit list of `.pxextension` manifests
`uiEntryPoints`, `uiComponents`	Routes mapped to screens and reusable UI components
`graphicsTier`, `effects`	Graphics capability tier and custom effect descriptors
`version`, `contentVersion`, `saveVersion`, `saveMigrations`	Release and save-compatibility information

Merge new configuration into the existing object. The variables tutorial adds gameCatalog; the extension tutorial adds extensions. Append to existing arrays rather than deleting previously registered characters or plugins.

Paths and identities are different

Content paths use / and are relative to the project root, such as Assets/window.png. Do not use absolute Windows or Unix paths, ../outside.png, or a URL. Extension entry and modules use a distinct rule: they are relative to the extension manifest's directory.

An asset UUID identifies a resource. guide is an author-friendly character alias. [id main.welcome] pins the identity of a Story operation. These are not interchangeable and should not be randomly regenerated on every build. Allocate new identities for genuinely new items; preserve the identities of logical items that have already shipped.

Version control and collaboration

Commit Story sources, author configuration, assets and licenses, extension sources and reproducible build configuration, and the project's package.json and lockfile. Do not commit node_modules/, temporary Preview revisions, or real player saves as tutorial fixtures.

The globally installed CLI is not the project's version authority. Another machine should restore the pinned dependencies from the lockfile. Upgrade in a separate branch and retest old saves and the packaged Player. Keep build output away from source directories and unrelated existing folders.

Next: Your first complete story.

Sources: Project schema, Starter manifest, CLI loading implementation.