Bard Legends Framework

1.4.0 verified Sat Apr 25 auth: no javascript

Bard Legends Framework v1.4.0 enables rapid development of interactive text-based narratives with branching storylines and dynamic character management. Built on actions-lib ^3.2.1, helpers-lib ^2.1.1, and script-engine-lib ^1.1.1, it provides a plugin-based architecture for defining game actions, NPC behavior, and plot branching. Unlike generic game engines, it focuses on narrative-driven storytelling with minimal boilerplate.

Common errors

error Error: Cannot find module 'bard-legends-framework/narrative' ↓

cause The NarrativeEngine module path was removed in v1.4.0.

fix

Change import to: import { NarrativeEngine } from 'bard-legends-framework';

error TypeError: game.plugins.add is not a function ↓

cause The .plugins.add method was removed in v1.3.0 in favor of .registerPlugin().

fix

Use game.registerPlugin(plugin) instead of game.plugins.add(plugin).

error SyntaxError: Unexpected token 'export' ↓

cause The package is ESM-only; using require() or an older Node version (< 16) causes this.

fix

Use import syntax and ensure Node.js >= 16.

Warnings

breaking The import path for NarrativeEngine changed from 'bard-legends-framework/narrative' to 'bard-legends-framework' in v1.4.0. ↓

fix Update import to: import { NarrativeEngine } from 'bard-legends-framework';

deprecated Legacy plugin registration using `game.plugins.add(plugin)` is deprecated; use `game.registerPlugin(plugin)` instead. ↓

fix Replace .plugins.add() with .registerPlugin().

gotcha The framework requires Node.js >= 16.0.0 due to ESM-only distribution. ↓

fix Upgrade Node.js to version 16 or later.

Install

npm install bard-legends-framework

yarn add bard-legends-framework

pnpm add bard-legends-framework

Imports

BardLegends

wrong

import { BardLegends } from 'bard-legends-framework'

correct

import BardLegends from 'bard-legends-framework'

Default export for the main framework class.

ActionPlugin

wrong

import ActionPlugin from 'bard-legends-framework'

correct

import { ActionPlugin } from 'bard-legends-framework/plugins'

Named export from the plugins submodule since v1.3.0.

NarrativeEngine

wrong

import NarrativeEngine from 'bard-legends-framework/narrative'

correct

import { NarrativeEngine } from 'bard-legends-framework'

Named export from the main package (deprecated submodule path in v1.4.0).

Quickstart

Initializes a Bard Legends game instance, registers a custom action plugin that greets the player, and starts the narrative engine.

import BardLegends from 'bard-legends-framework';
import { ActionPlugin } from 'bard-legends-framework/plugins';

const game = new BardLegends({
  apiKey: process.env.LEGENDS_API_KEY ?? ''
});

// Define a custom action plugin
class GreetPlugin extends ActionPlugin {
  constructor() {
    super('greet');
  }
  execute(context) {
    console.log(`Hello, ${context.player.name}!`);
    return context;
  }
}

game.registerPlugin(new GreetPlugin());

game.start();