@atrament/core NPM

Atrament

atrament-core is a framework for choice-based games, built around inkjs.

If you need a ready-to-use library for web applications, check out atrament-web.

If you are looking for an example of a web application based on Atrament, check out atrament-web-ui.

Features

Implements game flow: loading Ink story, getting text content, making choices
Manages global application settings
Parses tags, and handles some of them (mostly compatible with Inky)
Auto-observe variables defined with 'observe' global tag
Manages sound and music via knot tags
Manages autosaves, checkpoints, and named saves for every game
Music state is saved and restored along with game state
All changes affect the internal state

Installation

npm install @atrament/core

Tags handled by Atrament

Global tags

Tag	Description
`# observe: varName`	Register variable observer for `varName` Ink variable. The variable value is available in the `vars` section of Atrament state.
`# persist: varName`	Save this variable value to persistent storage, and restore it before the game starts.
`# autosave: false`	Disables autosaves.
`# single_scene`	Store only the last scene in the Atrament state.
`# continue_maximally: false`	Pause story after each line. In this mode the `scene` object contains the `canContinue` field, which is set to true if the story can be continued.

Knot tags

Tag	Description
`# CLEAR`	Clear the scenes list before saving the current scene to Atrament state.
`# AUDIO: sound.mp3`	Play sound (once).
`# AUDIOLOOP: music.mp3`	Play background music (looped). There can be only one background music track.
`# AUDIOLOOP: false`	Stop playing all background music.
`# PLAY_SOUND: sound.mp3`	Play sound (once).
`# STOP_SOUND: sound.mp3`	Stop playing specific sound.
`# STOP_SOUND`	Stop playing all sounds.
`# PLAY_MUSIC: music.mp3`	Play background music (looped). There can be multiple background music tracks, played simultaneously.
`# STOP_MUSIC: music.mp3`	Stop playing specific background music.
`# STOP_MUSIC`	Stop playing all background music.
`# CHECKPOINT`	Save the game to the default checkpoint.
`# CHECKPOINT: checkpointName`	Save the game to checkpoint `checkpointName`.
`# SAVEGAME: saveslot`	Save the game to `saveslot`.
`# RESTART`	Start game from beginning.
`# RESTART_FROM_CHECKPOINT`	Restart the game from the latest checkpoint.
`# RESTART_FROM_CHECKPOINT: checkpointName`	Restart game from named checkpoint.
`# IMAGE: picture.jpg`	Adds specified image to the `images` attribute of the scene and paragraph. It can be used to preload image files for the scene.

Note: For sound effects, please use either AUDIO/AUDIOLOOP or PLAY_SOUND/PLAY_MUSIC/STOP_SOUND/STOP_MUSIC tags. Combining them may lead to unexpected side effects.

Choice tags

Tag	Description
`# UNCLICKABLE`	Alternative names: `#DISABLED`, `#INACTIVE`.Sets `disabled: true` attribute to the choice.

API Reference

atrament.version

Atrament version string. Read-only.

Base methods

atrament.defineInterfaces()

Defines interface modules for:

loader: ink file loader
persistent: persistent storage
sound: sound control (optional)
state: state management

Interfaces should be defined before calling any other methods.

atrament.defineInterfaces({
    loader: interfaceLoader,
    persistent: persistentInterface,
    sound: soundInterface,
    state: stateInterface
});

atrament.init(Story, configuration)

Initialize the game engine. Takes two parameters:

Story is an inkjs constructor, imported directly from inkjs
configuration is a configuration object:
- applicationID should be a unique string. It is used to distinguish persistent storage of your application.
- settings is a default settings object. These settings are immediately applied.

import {Story} from 'inkjs';
const config = {
    applicationID: 'your-application-id',
    settings: {
        mute: true,
        volume: 10,
        fullscreen: true
    }
}
atrament.init(Story, config);

atrament.on(event, listener)

Subscribe to specific Atrament events. The listener function is called with a single argument containing event parameters.

You can subscribe to all Atrament events:

atrament.on('*', (event, args) => { ... });

atrament.off(event, listener)

Unsubscribe specified listener from the Atrament event.

atrament.state

Returns Atrament state interface. Can be used to operate state directly:

atrament.state.setSubkey('game', 'checkpoint', true);

atrament.store

Return raw store object. It can be used in hooks, for example:

const gamestate = useStore(atrament.store);

atrament.interfaces

Returns raw interface objects. It can be used to operate with them directly.

const { state, persistent } = atrament.interfaces;

Game methods

async atrament.game.init(path, file, gameID)

Initialize game object. It is required to perform operations with saves. Parameters:

path: path to Ink file
file: Ink file name
gameID: optional. If provided, Atrament will use the given ID for save management. Otherwise, it will be generated based on path and filename.

Event: 'game/init', { pathToInkFile: path, inkFile: file }

async atrament.game.initInkStory()

Load Ink file and initialize Ink Story object. Then it updates game metadata and initializes variable observers.

Event: 'game/initInkStory'

atrament.game.getSaveSlotKey({ name, type })

Returns save slot identifier for given save name and type. Possible save types: atrament.game.SAVE_GAME, atrament.game.SAVE_CHECKPOINT, atrament.game.SAVE_AUTOSAVE. For autosaves, the name parameter should be omitted. The returned value can be used as a saveslot parameter.

async atrament.game.start(saveslot)

If the game is started for the first time, or the initialized game is not the same as the current one - call initInkStory first. Clears game state, and gets initial data for variable observers. If saveslot is defined, load state from specified save.

Event: 'game/start', { saveSlot: saveslot }

async atrament.game.resume()

Resume saved game:

if autosave exists, resume from autosave
if checkpoints exist, resume from the newest checkpoint
otherwise, start a new game

Event: 'game/resume', { saveSlot: saveslot }

async atrament.game.canResume()

Returns save slot identifier if game can be resumed.

Event: 'game/canResume', { saveSlot: saveslot }

async atrament.game.restart(saveslot)

Restart the game from the specified save slot (if saveslot is not defined, start a new game).

Event: 'game/restart', { saveSlot: saveslot }

async atrament.game.restartAndContinue(saveslot)

Run atrament.game.restart, then run atrament.game.continueStory() to regenerate game content.

async atrament.game.load(saveslot)

Load game state from specified save slot.

Event: 'game/load', saveslot

async atrament.game.saveGame(name)

Save game state to save slot.

Event: 'game/save', { type: 'game', name }

async atrament.game.saveCheckpoint(name)

Save the game state to the checkpoint.

Event: 'game/save', { type: 'checkpoint', name }

async atrament.game.saveAutosave()

Save the game state to autosave slot.

Event: 'game/save', { type: 'autosave' }

async atrament.game.listSaves()

Returns array of all existing saves for active game.

Event: 'game/listSaves', savesListArray

async atrament.game.removeSave(saveslot)

Removes specified game save slot.

Event: 'game/removeSave', saveslot

async atrament.game.existSave(saveslot)

Returns true if specified save slot exists.

atrament.game.continueStory()

gets Ink scene content
run scene processors
process tags
updates Atrament state with a scene content

Event: 'game/continueStory'

Event for tag handling: 'game/handleTag', { [tagName]: tagValue }

atrament.game.makeChoice(id)

Make a choice in Ink. Wrapper for atrament.ink.makeChoice.

atrament.game.defineSceneProcessor(processorFunction)

function processCheckpoint(scene) {
    if (scene.tags.CHECKPOINT) {
        scene.is_checkpoint = true;
    }
}
atrament.game.defineSceneProcessor(processCheckpoint);

atrament.game.getAssetPath(file)

Returns the full path to asset file (image, sound, music).

atrament.game.clear()

Method to call at the game end. It stops music, and clears scenes and vars in the Atrament state.

Event: 'game/clear'

atrament.game.reset()

Method to call at the game end. It calls atrament.game.clear(), then clears metadata and game in Atrament state.

Event: 'game/reset'

atrament.game.getSession()

Returns current game session.

atrament.game.setSession(sessionID)

Sets current game session. If set to empty value, reset session ID to default.

Event: 'game/setSession', sessionID

async atrament.game.getSessions()

Returns list of existing sessions in a { sessionName: numberOfSaves, ... } format.

Event: 'game/getSessions', sessionList

async atrament.game.deleteSession(sessionID)

Delete all saves for a given session.

Event: 'game/deleteSession', sessionID

Ink methods

atrament.ink.initStory()

Initializes Ink story with loaded content.

Event: 'ink/initStory'

atrament.ink.story()

Returns current Story instance.

atrament.ink.loadState(state)

Load Ink state from JSON.

atrament.ink.getState()

Returns current Ink state as JSON object.

atrament.ink.makeChoice(id)

Wrapper for Story.ChooseChoiceIndex.

Event: 'ink/makeChoice', { id: choiceId }

atrament.ink.getVisitCount(ref)

Wrapper for Story.VisitCountAtPathString.

Event: 'ink/getVisitCount', { ref: ref, visitCount: value }

atrament.ink.evaluateFunction(functionName, argsArray)

Evaluates Ink function, then returns the result of the evaluation. Wrapper for Story.EvaluateFunction.

Event: 'ink/evaluateFunction', { function: functionName, args: argsArray, result: functionReturnValue }

atrament.ink.getGlobalTags()

Returns parsed Ink global tags.

Event: 'ink/getGlobalTags', { globalTags: globalTagsObject }

atrament.ink.getVariable(variableName)

Returns value of specified Ink variable.

Event: 'ink/getVariable', { name: variableName }

atrament.ink.getVariables()

Returns all variables and their values as a key-value object.

Event: 'ink/getVariables', inkVariablesObject

atrament.ink.setVariable(variableName, value)

Sets value of specified Ink variable.

Event: 'ink/setVariable', { name: variableName, value: value }

atrament.ink.observeVariable(variableName, observerFunction)

Registers observer for a specified variable. Wrapper for Story.ObserveVariable.

atrament.ink.goTo(ref)

Go to the specified Ink knot or stitch. Wrapper for Story.ChoosePathString.

Event: 'ink/goTo', { knot: ref }

atrament.ink.onError(errorCallback)

When an Ink error occurs, it emits ink/onError event and calls the errorCallback function with the error event object as an argument.

Event: 'ink/onError', errorEvent

atrament.ink.getScene()

Returns Scene object.

Event: 'ink/getScene', { scene: sceneObject }

Settings methods

Application settings for your application. Loading, saving, and setting values changes the settings section of the Atrament state.

However, if you need to perform additional actions when the setting is changed, you can define a handler for it - see below. By default, Atrament handles mute and volume settings this way, muting and setting sound volume respectively.

async atrament.settings.load()

Load settings from persistent storage to Atrament state.

Event: 'settings/load'

async atrament.settings.save()

Save settings to persistent storage.

Event: 'settings/save'

atrament.settings.get(parameter)

Returns value of the setting.

Event: 'settings/get', { name: parameter }

atrament.settings.set(parameter, value)

Sets value of setting.

Event: 'settings/set', { name: parameter, value: value }

atrament.settings.toggle(parameter)

Toggles setting (sets true to false and vice versa).

atrament.settings.defineHandler(parameter, handlerFunction)

Defines a settings handler.

For example, you have to run some JavaScript code to toggle fullscreen mode in your app.

const fullscreenHandler = (oldValue, newValue) => {
    // do some actions
}

atrament.settings.defineHandler('fullscreen', fullscreenHandler);

// later...

atrament.toggle('fullscreen');
// or
atrament.set('fullscreen', true);

// both these methods will change the setting and run the corresponding handler

Scene object

{
  content: [],
  text: [],
  tags: {},
  choices: [],
  images: [],
  sounds: [],
  music: [],
  uuid: Number
}

Key	Description
`content`	Array of Ink paragraphs: `{text: '', tags: {}, images: [], sounds: [], music: []}`
`text`	Array of all story text from all paragraphs of this scene
`tags`	Array of all tags from all paragraphs of this scene
`choices`	Array of choice objects: `{ id: 0, choice: 'Choice Text', tags: {}}`
`images`	Array of all images from all paragraphs of this scene
`sound`	Array of all sounds from all paragraphs of this scene
`music`	Array of all music tracks from all paragraphs of this scene
`uuid`	Unique ID of the scene (`Date.now()`)

State structure

{
  settings: {},
  game: {},
  metadata: {},
  scenes: [],
  vars: {} 
}

Key	Description
`settings`	Single-level key-value store for application settings
`game`	Single-level game-specific data. Atrament populates the following keys: $pathToInkFile, $inkFile, $gameUUID
`metadata`	Data loaded from Ink file global tags
`scenes`	Array of game scenes
`vars`	Names and values of auto-observed variables

Save structure

{ id, date, state, game, scenes }

Key	Description
`id`	Save slot ID
`date`	Save timestamp
`state`	JSON structure of Ink state
`game`	Content of `game` from Atrament state
`scenes`	Content of `scenes` from Atrament state

Please note that metadata and vars from the Atrament state are not included in the save. However, they are automatically populated from the Ink state after loading from a save.

Interfaces

atrament-core uses dependency injection. It uses inkjs Story constructor 'as-is', and uses custom interfaces for other libraries.

There are four interfaces in atrament-core. Their implementation is not included, so developers can use atrament-core with the libraries they like.

loader

Interface to file operations. The function init will be called first, taking the path to the game as a parameter. The function getAssetPath should return the full path of a given file. The async function loadInk should return the content of a given Ink file, located in the folder defined at the initialization time.

{
    async init(path)
    getAssetPath(filename)
    async loadInk(filename)
}

persistent

Interface to persistent storage library.

{
  init()
  async exists(key)
  async get()
  async set(key)
  async remove(key)
  async keys()
}

state

Interface to state management library.

{
  store()
  get()
  setKey(key, value)
  toggleKey(key)
  appendKey(key, value)
  setSubkey(key, subkey, value)
  toggleSubkey(key, subkey)
  appendSubkey(key, subkey, value)
}

sound

Interface to sound management library.

{
  init(defaultSettings)
  mute(flag)
  isMuted()
  setVolume(volume)
  getVolume()
  playSound(soundFile)
  stopSound(soundFile|undefined)
  playMusic(musicFile)
  stopMusic(musicFile|undefined)
}