Plugins

Inkweaver can be extended with plugins. Plugins can modify existing functionality, or introduce completely new behavior and systems. This includes new special effects, custom UI, or entirely new mechanics.

Using a plugin is simple. Just drop it anywhere in your workspace and Inkweaver will pick it up automatically.

The rest of this page covers how to build your own. Inkweaver’s engine is itself built entirely from plugins, which means you have the same system privileges as the core engine does. It’s plugins all the way down.

Note

The remainder of this page is aimed at professional software developers. Familiarity with npm and JavaScript build systems will be helpful.

Anatomy of a Plugin

Plugins are distributed as “bottle” archives (.inkb ). When you novel is built, these archives are unpacked and included in the build as if they were part of the novel workspace.

Plugins interact with core features using the middleware pattern. If you’ve worked with Express or similar frameworks, this will feel familiar.

Creating a Plugin

The easiest way to get started is to use the Inkweaver CLI to generate a bootstrap project:

ink init-plugin my-first-plugin
cd my-first-plugin
npm install

Exploring the Bootstrap Files

The structure created by the init-plugin command is ready for you to get to work:

• Directoryassets

  • plugin.json
• Directorysrc

  • index.ts
• project.json
• tsconfig.json

assets

The assets folder contains the non-script files from your plugin.

At a minimum, this will include the plugin.json, but you can put any other file that you want in here, including .psd and .fountain or .fdx screenplay files.

plugin.json

The plugin.json file tells Inkweaver where to find your plugin’s entry point:

{
  "main": "index.ts"
}

There’s more that plugin.json can do. See the plugin guide for details.

index.ts

The index.ts file is the main entry point for your plugin’s logic. It exports shoul export a createPlugin function that creates your plugin.

The bootstrap includes middleware that decorates the core init command, adding behavior to the chain:

import {
  bindContext,
  ContextKey,
  decorateCommand,
} from "@inkweaverdev/inkweaver-sdk";

export const pluginName = "my-first-plugin";

export function createPlugin(key: ContextKey) {
  bindContext(key);

  decorateCommand("init", (next) => {
    console.log(`Hello, from ${pluginName}!`);
    next();
  });
}

Testing Your Plugin

To test your plugin against a real novel, open the .env file and update the novel field to point to your novel’s workspace folder:

novel=path/to/your/novel/workspace

Then, with your novel already running via ink watch in one terminal, run npm run dev in another. The project will automatically build and deploy your plugin whenever you make a change.

Next Steps

The bootstrap plugin is a starting point, but there’s a lot more to explore.

• The Inkweaver SDK documents every tool available for building plugins.
• The Plugin Guide goes deeper. It covers the full application architecture, the commands and selectors you can hook into with middleware, and the update cycle that drives the novel beat by beat.