QSP code wasm bindings that allow to run QSP engine in browser or on Node.js server.
npm install --save @qsp/wasm-engine
This library has separate builds for running in browser or on server. Use
import { initQspEngine } from '@qsp/wasm-engine';
import qspWasmUrl from '@qsp/wasm-engine/qsp-engine.wasm';
const wasm = await fetch(wasmPath).then((r) => r.arrayBuffer());
const api = await init(qspWasmUrl);
or
const { initQspEngine } = require('@qsp/wasm-engine');
const fsp = require('fs/promises');
const wasm = await fsp.readFile(require.resolve('@qsp/wasm-engine/qsp-engine.wasm'));
const api = await initQspEngine(wasm.buffer);
depending on your environment.
As first argument you need to pass URL of wasm module in browser (you might need to configure your bundler to handle wasm module as URL) or path to wasm module in node.
initQspEngine
returns a promise that resolves with API wrapper abstracting away all low level interactions with wasm.
// subscribing for engine events (see below)
api.on(event: string, callback: Function): void;
// unsubscribing from engine events
api.off(event: string, callback: Function): void;
// returns current core version
api.version(): string;
// loads game or library code into engine
api.openGame(data: ArrayBuffer, isNewGame: boolean): void;
// returns save data representing current game state
api.saveGame(): ArrayBuffer | null;
// restores game state from save data
api.loadSave(data: ArrayBuffer): void;
// restarts game currently loaded in engine
api.restartGame(): void;
// selects action by index
api.selectAction(index: number): void;
// executes code of currently selected action
api.execSelectedAction(): void;
// selects object by index
api.selectObject(index: number): void;
// updates user input variable
api.updateUserInput(code: string): void;
// executes arbitrary QSP code
api.execCode(code: string): void;
// executes code of $counter location
api.execCounter(): void;
// executes code from some location by name
api.execLoc(name: string): void;
// reads content of some variable by index (0 by default)
api.readVariable(name: string, index?: number): string | number;
// reads content of some variable by string key
api.readVariableByKey(name: string, key: string): string | number;
// reads size of some variable
api.readVariableSize(name: string): number;
// allows to subscribe to variable changes (main intention is to watch UI related variables)
api.watchVariable(
name: string,
index: number,
callback: (value: string | number) => void
): () => void;
// allows to subscribe to variable key changes (main intention is to watch UI related variables)
api.watchVariableByKey(
name: string,
key: string,
callback: (value: string | number) => void
): () => void;
API triggers several events when engine provides updates on current state of game or needs to receive some input from user.
Here is the list of currently supported events.
-
main_changed
- event is triggered whenever text in main panel changes. Arguments:-
text
- current content of main panel
-
-
stats_changed
- event is triggered whenever text in stats panel changes. Arguments:-
text
- current content of stats panel
-
-
actions_changed
- event is triggered whenever list of actions changes. Arguments:-
actions
- array of actions (every action has two fields -name
andimage
)
-
-
objects_changed
- event is triggered whenever list of objects changes. Arguments:-
objects
- array of objects (every object has two fields -name
andimage
)
-
-
panel_visibility
- event is triggered whenever one of panels is shown/hidden. Arguments:-
type
- code of panel that changed -
isShown
- if panel is shown now
-
-
user_input
- event is triggered whenever user input is changed (either from game of usingapi.updateUserInput
) Arguments:-
text
- current user input
-
-
menu
- event is triggered whenMENU
operator is called in game Arguments:
-
items
- array of menu items (every object has two fields -name
andimage
) -
callback
- function to be called after user selected some menu item (passing index).-1
should be passed ff no item has been selected.
-
msg
- event is triggered whenMSG
operator is called in game Arguments:-
text
- content of message -
callback
- function to be called when game should resume (pressing ok in MSG dialog)
-
-
input
- event is triggered whenINPUT
function is called in game Arguments:-
text
- content of message -
callback
- function to be called when game should resume (pressing ok in MSG dialog). Text entered by user should be passed as first parameter.
-
-
wait
- event is triggered whenWAIT
operator is called in game Arguments:-
ms
- delay of milliseconds -
callback
- function to be called after delay signaling that game can resume
-
-
timer
- event is triggered whenSETTIMER
operator is called in game Arguments:-
ms
- delay of milliseconds between counter calls
-
-
view
- event is triggered wheneverVIEW
operator is called in game Arguments:-
path
- path to image to be shown (may be empty string)
-
-
version
- event is triggered when$QSPVER
function is called in game Arguments:-
type
- type of version to be returned (currentlyplayer
orplatform
) -
callback
- function to be called passing needed version data
-
-
open_game
- event is triggered whenOPENQST
orINCLIB
operator is called in game Arguments:-
path
- path to game file -
isNewGame
- true forOPENQST
and false forINCLIB
-
callback
- function to be called after game data was loaded into engine usingapi.openGame
-
-
save_game
- event is triggered whenSAVEGAME
operator is called in game Arguments:-
path
- path where game should be saved (may be empty - it is expected that player asks user to provide this path in such case) -
callback
- function to be called after game state was received usingapi.saveGame
and stored at needed path
-
-
load_save
- event is triggered whenOPENGAME
operator is called in game
Arguments:-
path
- path to save (may be empty - it is expected that player asks user to provide this path in such case) -
callback
- function to be called after game state has been loaded usingapi.loadSave
-
-
is_play
- event is triggered whenISPLAY
function is called in game Arguments:-
path
- path to audio file -
callback
- function to be called with boolean argument indicating whether corresponding audio file is currently playing
-
-
play_file
- event is triggered whenPLAY
operator is called in game Arguments:-
path
- path to audio file -
volume
- current volume (if file is already playing should just change its volume) -
callback
- function to be called when player is ready with changes
-
-
close_file
- event is triggered whenCLOSE
operator is called in game Arguments:-
path
- path to audio file (empty string ifCLOSE ALL
was called) -
callback
- function to be called when player is ready with changes
-
-
system_cmd
- event is triggered whenEXEC
operator is called in game Arguments:-
cmd
- command string (depends on player)
-
-
error
- event is triggered whenever error has happened while executing QSP code: Arguments:-
errorData
- object containing information about error
-