module.json

{
  "id": "simulacrum",
  "title": "Simulacrum: AI Campaign Copilot",
  "description": "<p align=\"center\"> <a href=\"https://foundryvtt.com/packages/simulacrum\"><img src=\"https://img.shields.io/badge/FoundryVTT-Install%20Package-e67e22?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAFjSURBVDhPYxgFxAAmJqb/QBo5jBQAygQpRQb4NMI0wTUyMDD8h9JYMYpGmCYGJiamB1A5OI0kDQE0jQxAza+gNFwzugagRmagxgdQ6QdQjf+hGv8zMzM/gEojawRqegCl/zMxMT2AaQTRf5mYGB4wMjLeB2kA0f+Zn0JNAND/mR9C7YJphNFQDf+ZgZoeMDExPGBkYrgPchLIJJC9IAwEQP4TcCBI439mpvtQOxjugzTCNMJoEAbRQLX3mZiYQE4FagQFEchJYA0wTQgMchKS5vtY5SGGwjXCaKgmkPP+A8kHUI0PYHYxMTHch2nEhmEa/zM/hWq6z/AQ6lSYRhAN1YgLIzT+Z4Y67T/I5UB9D0Ca/sPcCKOhGmGy+DXCNLhBnXafgenZfZBGsJP+g5yKYi8DTDMjE9N/qBQ8bqAqYXpxarxPTDiD8qCMIBmkBlU1UhpGayQmjJE1wjSgJAgGBgCmJJx6XoJdXwAAAABJRU5ErkJggg==\" alt=\"Install on FoundryVTT\"></a> <a href=\"https://discord.gg/VSs8jZBgmP\"><img src=\"https://img.shields.io/discord/1466476707522543742?style=for-the-badge&logo=discord&logoColor=white&label=Discord&color=5865F2\" alt=\"Discord\"></a> <a href=\"https://buymeacoffee.com/daxiongmao87\"><img src=\"https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?style=for-the-badge&logo=buymeacoffee\" alt=\"Buy Me a Coffee\"></a> </p><p align=\"center\"> <a href=\"https://foundryvtt.com/\"><img src=\"https://img.shields.io/endpoint?url=https://foundryshields.com/version?url=https://github.com/Daxiongmao87/simulacrum-foundry/releases/latest/download/module.json\" alt=\"Foundry Version\"></a> <a href=\"https://forge-vtt.com/bazaar#package=simulacrum\"><img src=\"https://img.shields.io/badge/dynamic/json?label=Forge%20Installs&query=package.installs&suffix=%25&url=https://forge-vtt.com/api/bazaar/package/simulacrum&colorB=4aa94a\" alt=\"Forge Installs\"></a> <a href=\"https://github.com/Daxiongmao87/simulacrum-foundry/releases\"><img src=\"https://img.shields.io/github/downloads/Daxiongmao87/simulacrum-foundry/total?logo=GitHub\" alt=\"GitHub Downloads\"></a> <a href=\"https://github.com/Daxiongmao87/simulacrum-foundry/releases/latest\"><img src=\"https://img.shields.io/github/v/release/Daxiongmao87/simulacrum-foundry\" alt=\"Latest Release\"></a> <a href=\"LICENSE\"><img src=\"https://img.shields.io/github/license/Daxiongmao87/simulacrum-foundry\" alt=\"License\"></a> </p><p>An AI-powered Campaign Copilot for <a href=\"https://foundryvtt.com/\">Foundry Virtual Tabletop</a> that helps Game Masters manage their campaigns through natural language conversation.</p> <p align=\"center\"> <a href=\"https://www.youtube.com/watch?v=tu1EZ57aNW8\"><strong>Video: Grunk Test</strong></a><br> <img src=\"assets/simulacrum-demo.gif\" alt=\"Simulacrum AI Assistant Demo\" width=\"600\"> </p><h2>What is Simulacrum?</h2> <p>Simulacrum is an intelligent agent that lives inside your Foundry VTT sidebar. Unlike simple text generators, Simulacrum is a <strong>Campaign Copilot</strong>—it can understand your requests, plan multi-step operations, and directly interact with your game world.</p> <p><strong>Ask it to:</strong></p> <ul> <li>Create NPCs, items, journal entries, and other documents</li> <li>Search and read existing campaign content</li> <li>Update documents with new information</li> <li>Execute complex multi-step tasks</li> <li>Run custom macros and JavaScript automation</li> </ul> <h2>Features</h2> <h3>Intelligent Document Management</h3> <p>Simulacrum understands Foundry VTT&#39;s document structure. Create an actor, and it knows about abilities, items, and system-specific fields. Ask for a magic sword, and it builds one with proper stats.</p> <h3>Extensible Tool System</h3> <p>The AI uses a set of tools to interact with your world:</p> <ul> <li><strong>Document Tools</strong>: Create, read, update, delete, search, and list documents</li> <li><strong>Compendium Tools</strong>: Lock/unlock packs, manage document ownership</li> <li><strong>Asset Search</strong>: Find images, audio, and other assets in your data</li> <li><strong>Schema Introspection</strong>: Understands your game system&#39;s data structures</li> <li><strong>Macro Execution</strong>: Run any macro in your world</li> <li><strong>JavaScript Execution</strong>: Advanced automation capabilities</li> </ul> <h3>Tool Permission Controls</h3> <p>Destructive operations (update, delete, macro/JS execution) require confirmation before executing. Configure per-tool permissions with Allow, Deny, Always Allow, or Blacklist options.</p> <h3>Task Tracking</h3> <p>For complex operations, Simulacrum can create and manage tasks, tracking progress across multiple steps and reporting when complete.</p> <h3>Multi-Provider Support</h3> <p>Connect to any OpenAI-compatible API endpoint:</p> <ul> <li>OpenAI (GPT-4o, etc.)</li> <li>Google Gemini (via <a href=\"https://ai.google.dev/gemini-api/docs/openai\">OpenAI-compatible endpoint</a>)</li> <li>Anthropic Claude (via proxy or OpenRouter)</li> <li>OpenRouter, LLM7, and other aggregators</li> <li>Local models (Ollama, LM Studio, etc.)</li> </ul> <h3>GM-Only Access</h3> <p>Simulacrum is restricted to Game Masters only—players cannot access the AI interface or execute commands.</p> <h2>Installation</h2> <h3>From Foundry VTT</h3> <ol> <li>Open Foundry VTT and navigate to <strong>Add-on Modules</strong></li> <li>Click <strong>Install Module</strong></li> <li>Search for &quot;Simulacrum&quot;</li> <li>Click <strong>Install</strong></li> </ol> <h3>Manual Installation</h3> <ol> <li>Download the latest release from <a href=\"https://github.com/Daxiongmao87/simulacrum-foundry/releases\">GitHub Releases</a></li> <li>Extract to your <code>Data/modules/</code> directory</li> <li>Restart Foundry VTT</li> </ol> <h2>Configuration</h2> <ol> <li>Enable the module in your world</li> <li>Open <strong>Module Settings</strong> → <strong>Simulacrum</strong></li> <li>Configure your API Base URL and API Key</li> <li>Access Simulacrum from the sidebar tab</li> <li>Select a model from the dropdown in the sidebar header</li> </ol> <h3>Required Settings</h3> <ul> <li><strong>API Base URL</strong>: Your provider&#39;s OpenAI-compatible endpoint (e.g., <code>https://api.openai.com/v1</code>)</li> <li><strong>API Key</strong>: Your provider&#39;s API key</li> </ul> <p>The model selector in the sidebar automatically fetches available models from your configured endpoint.</p> <p>For detailed setup instructions, including free tier options and troubleshooting, see the <strong><a href=\"https://raw.githubusercontent.com/Daxiongmao87/simulacrum-foundry/main/docs/GETTING-STARTED.md\">Getting Started Guide</a></strong>.</p> <h2>Usage</h2> <p>Click the Simulacrum tab in the sidebar and start chatting. Examples:</p> <blockquote> <p>&quot;Create a goblin warrior named Grunk with 15 HP and a rusty shortsword&quot;</p> </blockquote> <blockquote> <p>&quot;Find all journal entries about the Kingdom of Eldoria&quot;</p> </blockquote> <blockquote> <p>&quot;Update the Dragon&#39;s Lair scene to add a treasure hoard in the corner&quot;</p> </blockquote> <blockquote> <p>&quot;Create a task to build out the entire merchant guild, including 5 NPCs and their shop inventory&quot;</p> </blockquote> <h2>Extending Simulacrum</h2> <h3>Custom Macro Tools</h3> <p>You can create custom tools for Simulacrum by creating a standard Foundry VTT Macro. To expose a macro as a tool, add a <code>const tool</code> configuration object to your macro code:</p> <pre><code class=\"language-javascript\">// Tool Configuration - This tells Simulacrum how to use this macro const tool = { name: &quot;my_custom_tool&quot;, description: &quot;A description of what this tool does&quot;, parameters: { type: &quot;object&quot;, properties: { parameterName: { type: &quot;string&quot;, description: &quot;Description of the parameter&quot; } }, required: [&quot;parameterName&quot;] }, enabled: true }; // Your macro logic here // Access parameters via: this.args.parameterName const result = `Processed: ${this.args.parameterName}`; // Return a value to send output back to the AI return result; </code></pre> <p><strong>Important notes:</strong></p> <ul> <li>A <code>response</code> parameter is automatically added to all macro-tools, allowing the AI to explain what it&#39;s doing to the user</li> <li><strong>Return a value</strong> from your macro to provide output to the AI (strings or objects work)</li> <li>If you don&#39;t return anything, the AI sees &quot;No output&quot;</li> <li>Simulacrum automatically discovers any macro with this configuration and makes it available to the AI</li> </ul> <h3>JavaScript Execution</h3> <p>For advanced users, Simulacrum can execute arbitrary JavaScript, enabling complex automation workflows.</p> <h2>Requirements</h2> <ul> <li>Foundry VTT v13.0.0 or higher</li> <li>An OpenAI-compatible API endpoint with <strong>tool/function calling support</strong></li> </ul> <blockquote> <p>[!IMPORTANT] <strong>Simulacrum requires models that support tool/function calling.</strong> This is how the AI interacts with your Foundry world. Models without tool support will produce errors or fail to respond. See <a href=\"#choosing-a-model\">Choosing a Model</a> below.</p> </blockquote> <h3>Choosing a Model</h3> <p>Simulacrum works with any OpenAI-compatible endpoint that supports tool calling. Below are some common options, but any compatible provider will work:</p> <h4>Free Tier (~$0)</h4> <p>Perfect for trying Simulacrum or light usage.</p> <table> <thead> <tr> <th>Provider</th> <th>Setup</th> </tr> </thead> <tbody><tr> <td><strong>Google AI Studio</strong></td> <td>Base URL: <code>https://generativelanguage.googleapis.com/v1beta/openai</code><br>Get API key: <a href=\"https://aistudio.google.com/apikey\">aistudio.google.com/apikey</a><br>Model: <code>gemini-3-flash-preview</code> or <code>gemini-3-pro-preview</code></td> </tr> <tr> <td><strong>OpenRouter Free</strong></td> <td>Base URL: <code>https://openrouter.ai/api/v1</code><br>Get API key: <a href=\"https://openrouter.ai/keys\">openrouter.ai/keys</a><br>Model: <code>openrouter/auto</code> (auto-selects free models with tool support)</td> </tr> </tbody></table> <p><em>Free tiers have rate limits (typically 50-250 requests/day). Sufficient for testing and occasional use.</em></p> <h4>Pay-Per-Use (~$0.01-0.10 per session)</h4> <p>Best balance of cost, speed, and capability.</p> <table> <thead> <tr> <th>Provider</th> <th>Setup</th> </tr> </thead> <tbody><tr> <td><strong>OpenAI</strong></td> <td>Base URL: <code>https://api.openai.com/v1</code><br>Models: <code>gpt-5-nano</code> (cheapest), <code>gpt-5-mini</code>, <code>gpt-5.2</code></td> </tr> <tr> <td><strong>Anthropic</strong></td> <td>Requires <a href=\"https://openrouter.ai\">OpenRouter</a> or compatible proxy<br>Models: <code>claude-haiku-4.5</code>, <code>claude-sonnet-4.5</code>, <code>claude-opus-4.5</code></td> </tr> <tr> <td><strong>OpenRouter</strong></td> <td>Access to 100+ models from one API key<br><a href=\"https://openrouter.ai/models?supported_parameters=tools\">Browse models with tool support</a></td> </tr> </tbody></table> <h4>Local Inference (Hardware Investment)</h4> <p>Run models privately on your own hardware.</p> <table> <thead> <tr> <th>Component</th> <th>Recommendation</th> </tr> </thead> <tbody><tr> <td><strong>Software</strong></td> <td><a href=\"https://ollama.com\">Ollama</a> — see their <a href=\"https://ollama.com/library\">model library</a> for tool-capable models</td> </tr> <tr> <td><strong>Model Size</strong></td> <td>20B+ parameters recommended for complex tasks</td> </tr> <tr> <td><strong>GPU VRAM</strong></td> <td>24GB+ for best experience (16GB minimum with quantization)</td> </tr> <tr> <td><strong>Hardware Cost</strong></td> <td>Used RTX 3090 (<del>$800-1300) or RTX 4090 (</del>$2200)</td> </tr> </tbody></table> <blockquote> <p>[!WARNING] <strong>Small models (7B-14B) will struggle</strong> with Simulacrum&#39;s multi-tool workflows. Expect slow responses and frequent errors. If your hardware is limited, cloud APIs provide a better experience.</p> </blockquote> <h3>Verifying Tool Support</h3> <p>Not sure if your model supports tools? Check these resources:</p> <ul> <li><strong>OpenRouter</strong>: <a href=\"https://openrouter.ai/models?supported_parameters=tools\">Models with tool support</a></li> <li><strong>Ollama</strong>: Model pages indicate &quot;Tools&quot; support in capabilities</li> <li><strong>Provider docs</strong>: Search for &quot;function calling&quot; or &quot;tool use&quot; in your provider&#39;s documentation</li> </ul> <h2>Support</h2> <ul> <li><strong>Issues</strong>: <a href=\"https://github.com/Daxiongmao87/simulacrum-foundry/issues\">GitHub Issues</a></li> <li><strong>Source</strong>: <a href=\"https://github.com/Daxiongmao87/simulacrum-foundry\">GitHub Repository</a></li> <li><strong>Donate</strong>: <a href=\"https://buymeacoffee.com/daxiongmao87\">Buy Me a Coffee</a></li> </ul> <h2>License</h2> <p>MIT License - see <a href=\"LICENSE\">LICENSE</a> for details.</p> <h2>Credits</h2> <p>Created by <a href=\"https://github.com/Daxiongmao87\">Daxiongmao87</a></p>",
  "authors": [
    {
      "name": "Daxiongmao87",
      "url": "https://github.com/Daxiongmao87"
    }
  ],
  "version": "1.1.0",
  "compatibility": {
    "minimum": 13,
    "verified": "14"
  },
  "relationships": {
    "systems": [],
    "requires": [],
    "conflicts": [],
    "flags": {}
  },
  "esmodules": ["scripts/simulacrum.js"],
  "styles": ["styles/simulacrum.css"],
  "languages": [
    {
      "lang": "en",
      "name": "English",
      "path": "lang/en.json"
    }
  ],
  "packs": [
    {
      "name": "simulacrum-tools",
      "label": "Simulacrum Tools",
      "path": "packs/simulacrum-tools",
      "type": "Macro",
      "ownership": {
        "PLAYER": "OBSERVER",
        "ASSISTANT": "OBSERVER"
      }
    }
  ],
  "socket": false,
  "manifest": "https://github.com/Daxiongmao87/simulacrum-foundry/releases/download/1.1.0/module.json",
  "download": "https://github.com/Daxiongmao87/simulacrum-foundry/releases/download/1.1.0/simulacrum.zip",
  "url": "https://github.com/Daxiongmao87/simulacrum-foundry",
  "bugs": "https://github.com/Daxiongmao87/simulacrum-foundry/issues",
  "changelog": "https://github.com/Daxiongmao87/simulacrum-foundry/blob/main/CHANGELOG.md",
  "readme": "https://github.com/Daxiongmao87/simulacrum-foundry/blob/main/README.md",
  "license": "https://github.com/Daxiongmao87/simulacrum-foundry/blob/main/LICENSE",
  "media": [
    {
      "type": "icon",
      "url": "https://github.com/Daxiongmao87/simulacrum-foundry/raw/main/media/icon.png"
    },
    {
      "type": "cover",
      "url": "https://github.com/Daxiongmao87/simulacrum-foundry/raw/main/media/cover.png"
    }
  ]
}