imsc-script

v1.0.1

Published

7 days ago

JS library to play dialogs/scripts created in IMS Creators

0High
0Medium
0Low

nordth

ImscScript JS

A JavaScript library to play dialogs and visual scripts created with IMS Creators (Desktop version)

Works with any web game engine (Phaser, PixiJS, or vanilla JS) and provides full control over dialog flow, branching, variables, triggers, and serialization.

Features

🎭 Speech nodes with optional choices (branching dialogs)
🔀 Conditional branching based on variables or expressions
📦 Variable management – set, get, and use in conditions
⚡ Trigger nodes – invoke game logic and receive outputs
💾 Serializable state – save/load, undo/redo, replay
🔌 Framework agnostic – works with Phaser, PixiJS, or any rendering engine
📝 Expression evaluation – math, comparison, and logical operators
🧩 Async support – triggers can be asynchronous
⏸️ Pause/Resume – pause execution during triggers or user input

Installation

npm install imsc-script

or include from CDN

<script src="https://cdn.jsdelivr.net/gh/ImStocker/imsc-script-js@main/dist-browser/index.iife.js"></script>

and use new ImscScript.ImscScriptPlayer to create player

Usage

1. Create a script asset in IMS Creators

Export your dialog graph as JSON or just use saved file from Desktop version. The asset must contain at least one block of type "script"

Example minimal asset:

{
  "id": "my_dialog",
  "blocks": [
    {
      "id": "block1",
      "type": "script",
      "name": "content",
      "computed": {
        "start": "greeting",
        "nodes": {
          "greeting": {
            "type": "speech",
            "values": {
              "character": "Guard",
              "text": "Hello!"
            },
            "next": "ask"
          },
          "ask": {
            "type": "speech",
            "values": {
              "character": "Guard",
              "text": "What do you want?"
            },
            "options": [
              { "values": { "text": "I seek adventure." }, "next": "adventure" },
              { "values": { "text": "I want to trade." }, "next": "trade" },
              { "values": { "text": "Nothing, goodbye." }, "next": "end" }
            ]
          },
          "trade": {
            "type": "trigger",
            "subject": "trade",
            "next": "ask"
          },
          "adventure": {
            "type": "speech",
            "values": {
              "character": "Guard",
              "text": "Then go east, brave soul!"
            },
            "next": "end"
          },
          "end": { "id": "end", "type": "end" }
        }
      }
    }
  ]
}

2. Initialize and play

import { ImscScriptPlayer } from 'imsc-script';
import myDialogAsset from './myDialog.json';

const player = new ImscScriptPlayer(myDialogAsset, {
  blockName: 'content',                // optional, uses first script block if omitted
  initialVariables: { customVar: 42 }, // overrides defaults values of variables
  events: {
    onSpeech: (speech) => {
      // Render speech bubble 
      console.log(`${speech.character}: ${speech.text}`);
      if (speech.options.length) {
        // Show choice buttons (option.text - text of option)
        // ...
        // buttons should call player.continue(option.index)
      } else {
        // Show "Continue" button
        // ...
        // button should call player.continue()
      }
    },
    onTrigger: async (subject, inputs, node) => {
      // Handle game logic (e.g., give item, play sound)
      console.log(`Trigger: ${subject}`, inputs);
      // Return outputs that can be bound to other nodes
      return { success: true, reward: 100 };
    },
    onEnd: () => {
      console.log('Dialog finished');
    }
  }
});

// Start the dialog (returns a Promise that resolves when dialog ends)
await player.play();

See browser usage in tests/browser.html

3. Control the dialog from your UI

When a speech node without options appears, call player.continue() after the user clicks "Continue".
When a speech node with options appears, call player.continue(selectedIndex) when the user picks an option.
Use player.pause() to pause execution (e.g., during a trigger animation), and player.continue() to resume.
Jump to any node using player.goto(nodeId).

// Example: button click handlers
continueButton.onclick = () => player.continue();
choiceButton.onclick = () => player.continue(0);

// Pause during a long animation
player.pause();
await playAnimation();
player.continue();

API Reference

Constructor

new ImscScriptPlayer(asset: ImscAsset, options?: ImscScriptPlayerOptions)

Properties

Methods

Events

State Serialization (Save / Load)

You can save the exact dialog state at any time and restore it later:

// Save
const savedState = player.serialize();
localStorage.setItem('dialogSave', JSON.stringify(savedState));

// Load later
const loadedState = JSON.parse(localStorage.getItem('dialogSave'));
player.load(loadedState);

License

MIT

Contributing

Issues and pull requests are welcome. Please ensure your code passes the existing tests and follows the coding style.