Assets looks up the files and characters that were built into the game: where an image is, how big it is, which audio folder a sound is in, and so on. It doesn't load images or play audio itself. Use the result's url on an element, or use AudioManager for sound.
Assets are found by their key, the file name without its extension, or by their name, the file name in the build. For Forest Path.png, the key is forest_path. Every method that takes a key also takes a file picked in a File variable (an AssetRef).
| Member | Description |
|---|---|
AssetRef |
What a File variable holds |
GetImage() |
An image's url and size |
GetAudio() |
An audio file's url and folder |
GetVideo() |
A video's url |
GetModel() |
A 3D model's url |
GetChapter() |
A chapter file's url |
GetCharacter() |
A character from the Character Manager |
GetVariant() |
One variant of a character |
Get() |
Any asset's entry, by key or name |
GetAll() |
Every asset of one kind |
LoadFile() |
Loads a data file, such as a chapter |
Register() |
Adds an asset while the game runs |
GetImage
Assets.GetImage(name: string): ImageAssetInfo | null
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
string |
The image's key or file name |
Returns an object with:
| Field | Type | Description |
|---|---|---|
url |
string |
Where to load it from, for example to set an image element's src |
key |
string |
The file name without its extension |
name |
string |
The file name in the build |
kind |
string |
"image" |
width, height |
number |
Its size in pixels. Missing if the build couldn't read it |
It returns null, and writes a warning to the browser console, if there's no such image.
Example
showPortrait(key: string) {
const image = Assets.GetImage(key);
if (!image) return;
this.dom.portrait.src = image.url; // the portrait node is an image node
this.dom.portrait.style.aspectRatio = `${image.width} / ${image.height}`;
},
GetAudio
Assets.GetAudio(name: string): AudioAssetInfo | null
Returns the same fields as GetImage (without the size), plus type: the audio folder the file is in, such as "music", "ambient", "voice" or "sfx". Returns null if there's no such file.
Example
onStart() {
const track = Assets.GetAudio("theme");
if (track?.type !== "music") logWarning("theme isn't in the music folder");
},
GetVideo
Assets.GetVideo(name: string): AssetInfo | null
Returns the video's url, key, name and kind, or null if there's no such video.
Example
playIntro() {
const video = this.dom.intro_video;
video.src = Assets.GetVideo("intro")?.url ?? "";
video.play();
},
GetModel
Assets.GetModel(name: string): AssetInfo | null
Returns a 3D model's url, key, name and kind, or null if there's no such model.
GetChapter
Assets.GetChapter(key: ChapterName): AssetInfo | null
Returns a chapter file's url, key, name and kind, or null, with a warning in the console, if there's no such chapter. It doesn't load the chapter. Use LoadFile for its contents, or Revealer.StartRevealChapterByID to reveal it.
Example
onEnter() {
this.dom.bonus_button.hidden = !Assets.GetChapter("bonus"); // only offer the bonus chapter if this build has it
},
GetCharacter
Assets.GetCharacter(key: string): any
Returns a character from the Character Manager, or null if there isn't one with that key. Its fields include:
| Field | Description |
|---|---|
key |
The character's key |
name |
The name shown to players |
description |
Its description |
image |
The url of its main image, if it has one |
tags |
Its tags |
variants |
Its variants, by name. Each has an image and variables |
variables |
Its variables. Chapters can change them, and they're saved with the game |
Example
showSpeaker(event: RevealerEvent) {
const character = Assets.GetCharacter(event.args[0]);
if (!character) return;
this.dom.speaker_name.textContent = character.name;
this.dom.speaker_image.src = character.image ?? "";
},
GetVariant
Assets.GetVariant(key: string, variantName: string): any
Returns one variant of a character, with its image and variables, or null if the character or variant doesn't exist.
Example
setExpression(key: string, expression: string) {
const variant = Assets.GetVariant(key, expression) ?? Assets.GetCharacter(key);
this.dom.speaker_image.src = variant?.image ?? ""; // falls back to the character's own image
},
Get
Assets.Get(key: string, kind?: string): AssetEntry | null
Finds any asset by its key or file name.
| Parameter | Type | Default | Description |
|---|---|---|---|
key |
string |
The asset's key or file name | |
kind |
string |
Any kind | Only look at one kind, such as "image", "audio", "video", "model" or "chapter" |
Returns the asset's entry from the build, or null if there isn't one. The entry has key, name and kind, and its location is in path, not url. Use the Get... methods above when you want a url.
Example
onStart() {
if (!Assets.Get("bonus_level", "chapter")) {
this.dom.bonus_button.hide(); // this build doesn't include the bonus chapter
}
},
GetAll
Assets.GetAll(kind: string): AssetEntry[]
Returns the entries for every asset of one kind, or an empty array.
Example
onEnter() {
const tracks = Assets.GetAll("audio").filter((entry) => entry.type === "music");
this.dom.track_count.textContent = `${tracks.length} tracks`;
},
LoadFile
Assets.LoadFile(key: string, kind?: string): Promise<any>
Loads a data file from the build, such as a chapter, and reads it as JSON.
| Parameter | Type | Default | Description |
|---|---|---|---|
key |
string |
The file's key or name | |
kind |
string |
Any kind | The asset kind, such as "chapter" |
Returns a promise of the file's contents.
How it works
- Each file is only fetched once. Later calls, including ones made while it's still loading, share the same result.
- The promise is rejected if there's no such file or it fails to load. A failed load is tried again next time.
Example
async onStart() {
const chapter = await Assets.LoadFile("chapter_01", "chapter");
log(`chapter_01 has ${chapter.nodes.length} nodes`);
await Revealer.StartRevealChapter(chapter);
},
Register
Assets.Register(name: string, kind: string, data: any): void
Adds an asset while the game runs, for files that aren't in the project, such as ones downloaded from a server.
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
string |
The name to find it by | |
kind |
string |
Its kind, such as "image" |
|
data |
any |
Its entry. Give it key, name, kind and path, like the entries Get returns |
How it works
Get(name, kind)and theGet...methods for that kind find it.Getwithout a kind, andGetAll, don't.- Registering the same name and kind again replaces it.
- For sounds, use
AudioManager.RegisterAudio, which does this for you.
Example
onMapDownloaded(url: string) {
Assets.Register("bonus_map", "image", { key: "bonus_map", name: "bonus_map.png", kind: "image", path: url });
this.dom.map.src = Assets.GetImage("bonus_map")?.url ?? "";
},
AssetRef
interface AssetRef<K> {
kind: K;
key: string;
name: string;
url: string;
path: string;
width?: number;
height?: number;
type?: string;
}
What a File variable holds in game, whether it's a scene variable, a project variable or a character variable. Pass it straight to the engine function for its kind, instead of working out the file's name yourself.
| Field | Description |
|---|---|
kind |
"image", "audio", "video", "chapter", "scene", "character", "model" or "spriteLoop" |
key |
The name engine functions take, such as "pause_menu". For a character, its key from the Character Manager |
name |
The file name in the build, such as "pause_menu.mmsc" |
url |
Where to load the file from, for an image's src and so on. Empty for scenes and characters |
path |
The file's path in the build |
width, height |
An image's size in pixels, if the build could read it |
type |
An audio file's folder, such as "music" |
How it works
- These take an AssetRef as well as a name:
- every
SceneManagermethod that takes a scene; AudioManager.PlayMusic,PlayAmbient,PlaySFX,PlayVoiceandUnload;Revealer.StartRevealChapterByID;- every
Assetsmethod that takes a key; Store.SetCharacterTarget.
- every
- A file variable with no file picked is
"". - Turned into text, it's its
url, or itskeywhen there's no url, so{$portrait}in a chapter shows the image's url. Compare AssetRefs by theirkey, not with===. - It's saved with the game and found again on load, so it still works after the project is rebuilt.
- In TypeScript, use
urlwhere a string is expected. Assigning the AssetRef itself to an image'ssrcworks when the game runs, but is a type error. - Those functions also accept a file's path as a string, such as
"assets/scenes/pause_menu.mmsc".
Example
// menu (Scene), portrait (Image) and hitSound (Audio) are File scene variables
async onPausePressed() {
await SceneManager.AttachScene(this.vars.menu, this.dom.overlay);
},
onStart() {
if (this.vars.portrait) this.dom.portrait.src = this.vars.portrait.url;
},
onHit() {
AudioManager.PlaySFX(this.vars.hitSound);
},