Assets, characters, expressions, and audio

繁體中文

1. Reuse existing resources first

The starter registers Assets/window.png, Assets/guide.png, and Characters/guide.pxcharacter. Your first story can use them immediately:

[bg asset=10000000-0000-4000-8000-000000000001]
[show guide expression=smile position=left scale=0.8]

An asset UUID and a source path are two ways to reference a resource, not necessarily two different images. Registered identities give you an explicit mapping when moving source files, but changes still need old-save and packaging tests.

2. Add a background

Place an image you are allowed to use at Assets/garden.png. Append one descriptor to the existing assets array in prismatix.json:

{
  "id": "10000000-0000-4000-8000-000000000002",
  "name": "Garden",
  "kind": "background",
  "source": "Assets/garden.png"
}

This is one asset descriptor, not the entire project. The example ID is suitable only if it is unused in your tutorial project. Allocate and retain unique UUIDs for real resources. Then reference the image from Story:

[bg Assets/garden.png]

The path is relative to the project root, not the Story directory. Keep filename casing consistent. A valid resource reference, an existing file, and successful decoding are different checks. Inspect the native preview after validation.

3. Add an expression without duplicating a character

Suppose the same guide has another image at Assets/guide-thinking.png. Append an asset descriptor:

{
  "id": "20000000-0000-4000-8000-000000000002",
  "name": "Guide thinking",
  "kind": "character",
  "source": "Assets/guide-thinking.png"
}

Append this expression to expressions in Characters/guide.pxcharacter:

{
  "id": "61000000-0000-4000-8000-000000000002",
  "name": "Thinking",
  "aliases": ["thinking"],
  "assetId": "20000000-0000-4000-8000-000000000002",
  "thumbnailAssetId": null
}

Keep the existing character ID, aliases, default expression, and smile expression. Use the new alias in Story:

[show guide expression=thinking position=center]
@guide
Let me think about that.

For a genuinely different character, add another .pxcharacter with a new character ID, expression IDs, and image resource IDs. Register its source and alias in the project's characters array. Changing @alias alone does not create a character.

4. Music, sound effects, and voice

Provide real, decodable media files, such as WAV files, and register their assets. For example:

{
  "id": "70000000-0000-4000-8000-000000000001",
  "name": "Evening music",
  "kind": "audio",
  "source": "Assets/evening.wav"
}

After supplying the corresponding files:

[bgm Assets/evening.wav]
[se Assets/bell.wav]
[voice Assets/greeting.wav]
@guide
Welcome back.

Every referenced file must exist. A descriptor is not a substitute for the media itself. These Story commands lower only resource references; they do not expose complete volume, bus, or fade controls. Use extension APIs such as ctx.audio.playBGM, setBGMVolume, and play for those features. See Runtime APIs.

Test actual playback, volume, dialogue timing, and behavior after skipping, rollback, and loading. Matching file extensions do not establish matching codecs; validate containers and codecs through the native media pipeline on the target platform.

5. Fonts and licenses

The starter includes Noto Sans TC and its license. fontChain in Content/Localization/zh-TW.json points to the packaged font source. For another language, test glyph coverage, line wrapping, punctuation, button width, and line height. Changing --locale does not automatically install every language's fonts.

Maintain provenance and license information for images, audio, fonts, and video. The starter's font license and provenance document are not disposable decoration. Check redistribution permissions and keep the release pipeline limited to resources the game actually needs.

6. Troubleshoot in order

Run prismatix validate my-game for declarations and references, inspect images and audio in Preview, and finally test the packaged Player. For a missing character image, check its source path, asset ID, the expression's assetId, and the actual file instead of repeatedly changing identifiers.

Sources: Starter manifest, Starter character, Author cookbook.