Creating a Plugin

my-plugin/
  plugin.json              # Plugin manifest (required)
  plugin.wasm              # WASM module (for WASM plugins)
  panels/                  # Frontend panel HTML files
    main-panel.html
  widgets/                 # Field widget HTML files (optional)
    my-widget.html
  assets/                  # Icons, screenshots (optional)
    icon.png
  README.md                # Plugin documentation (optional)

my-plugin/
  plugin.json              # Plugin manifest (required)
  backend/
    routes.py              # FastAPI route handlers
    events.py              # Event handler registrations
  panels/
    main-panel.html

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A short description of what the plugin does",
  "author": "Your Name or Organization",
  "license": "MIT",
  "homepage": "https://github.com/you/my-plugin",
  "repository": "https://github.com/you/my-plugin",
  "icon": "Puzzle",
  "platforms": ["cloud", "desktop", "core"],
  "min_studiobrain_version": "2026.4",
 
  "wasm": {
    "module": "plugin.wasm"
  },
 
  "capabilities": {
    "host_functions": [
      "entity_read",
      "entity_write",
      "asset_read",
      "asset_write",
      "http_request",
      "ai_generate",
      "ui_notify",
      "get_config",
      "set_config"
    ],
    "http_domains": [
      "api.example.com",
      "*.example.org"
    ],
    "frontend": {
      "panels": [
        {
          "id": "main-panel",
          "title": "My Panel",
          "location": "entity-sidebar",
          "url": "/panels/main-panel.html",
          "entity_types": ["character", "location"],
          "default_collapsed": false
        }
      ],
      "tabs": [
        {
          "id": "analytics",
          "title": "Analytics",
          "url": "/panels/analytics.html",
          "entity_types": ["*"]
        }
      ],
      "pages": [
        {
          "id": "dashboard",
          "title": "Plugin Dashboard",
          "url": "/panels/dashboard.html",
          "nav_section": "tools"
        }
      ],
      "field_widgets": [
        {
          "id": "my-widget",
          "label": "My Widget",
          "category": "text",
          "value_type": "string",
          "accepts_options": false
        }
      ]
    },
    "settings": {
      "global": [
        {
          "key": "api_key",
          "label": "API Key",
          "type": "password",
          "required": true,
          "description": "Your external service API key"
        }
      ],
      "user": [
        {
          "key": "show_notifications",
          "label": "Show Notifications",
          "type": "boolean",
          "default": true
        }
      ]
    }
  }
}

{
  "capabilities": {
    "host_functions": ["entity_read", "asset_read"]
  }
}

{
  "capabilities": {
    "host_functions": ["entity_read", "entity_write", "ui_notify"]
  }
}

{
  "capabilities": {
    "host_functions": ["entity_read", "http_request"],
    "http_domains": ["api.openai.com", "api.anthropic.com"]
  }
}

{
  "capabilities": {
    "host_functions": ["entity_read", "ai_generate", "entity_write"]
  }
}

{
  "platforms": ["cloud", "desktop", "core"]
}

{
  "platforms": ["desktop", "core"],
  "capabilities": {
    "host_functions": ["entity_read", "file_read"]
  }
}

{
  "frontend": {
    "panels": [
      {
        "id": "my-panel",
        "title": "My Panel",
        "location": "entity-sidebar",
        "url": "/panels/my-panel.html",
        "entity_types": ["character", "location"],
        "default_collapsed": false
      }
    ]
  }
}

{
  "frontend": {
    "tabs": [
      {
        "id": "analytics",
        "title": "Analytics",
        "url": "/panels/analytics.html",
        "entity_types": ["*"]
      }
    ]
  }
}

{
  "frontend": {
    "pages": [
      {
        "id": "dashboard",
        "title": "Plugin Dashboard",
        "url": "/panels/dashboard.html",
        "nav_section": "tools"
      }
    ]
  }
}

# Scaffold the project
npx @biloxistudios/create-plugin my-plugin --template rust
cd my-plugin
 
# Edit src/lib.rs with your plugin logic
 
# Build
cargo build --target wasm32-wasi --release
 
# The output is at target/wasm32-wasi/release/my_plugin.wasm
# Copy or symlink it to plugin.wasm in the project root
cp target/wasm32-wasi/release/my_plugin.wasm plugin.wasm

use studiobrain_plugin_sdk::*;
 
#[export]
fn on_entity_created(entity: Entity) -> Result<(), PluginError> {
    let name = entity.field("name").unwrap_or_default();
    host::log("info", &format!("Entity created: {}", name));
    host::ui_notify("New Entity", &format!("{} was created", name), "info");
    Ok(())
}

npx @biloxistudios/create-plugin my-plugin --template assemblyscript
cd my-plugin
 
# Edit assembly/index.ts
 
# Build
npm run build
# Output: build/plugin.wasm

import { Entity, host } from "@biloxistudios/plugin-sdk-as";
 
export function on_entity_created(entity: Entity): void {
  const name = entity.field("name");
  host.log("info", `Entity created: ${name}`);
  host.ui_notify("New Entity", `${name} was created`, "info");
}

npx @biloxistudios/create-plugin my-plugin --template python
cd my-plugin
 
# Edit src/my_plugin.py
 
# Build
componentize-py -d plugin.wit -w plugin componentize my_plugin -o plugin.wasm

my-plugin/
  plugin.json
  backend/
    routes.py
    events.py
  panels/
    main-panel.html

from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from database import get_db
 
router = APIRouter()
 
@router.get("/status")
async def get_status(db: Session = Depends(get_db)):
    return {"status": "ok", "plugin": "my-plugin"}
 
@router.post("/process")
async def process_entity(request: dict, db: Session = Depends(get_db)):
    entity_type = request.get("entity_type", "character")
    # Plugin logic here
    return {"processed": True}

from services.event_bus import EventBus, EntityEvent
 
def register(event_bus: EventBus):
    @event_bus.on("entity_created")
    async def on_entity_created(event: EntityEvent):
        print(f"Entity created: {event.entity_type}/{event.entity_id}")

# Copy plugin to project
cp -r my-plugin/ ~/StudioBrain/MyProject/_Plugins/my-plugin/
 
# Or symlink during development
ln -s $(pwd)/my-plugin ~/StudioBrain/MyProject/_Plugins/my-plugin

# Web (development server)
cd /path/to/studiobrain-core
npm run dev
# Navigate to Settings > Plugins > Install Local
 
# Desktop (Tauri dev mode)
cd /path/to/studiobrain-app/packages/desktop
cargo tauri dev
# Plugin loads via wasmtime

[plugin:my-plugin] Error: Host function 'entity_write' not declared in capabilities