An AI-powered Campaign Copilot for Foundry Virtual Tabletop that helps Game Masters manage their campaigns through natural language conversation.
Simulacrum is an intelligent agent that lives inside your Foundry VTT sidebar. Unlike simple text generators, Simulacrum is a Campaign Copilot—it can understand your requests, plan multi-step operations, and directly interact with your game world.
Ask it to:
- Create NPCs, items, journal entries, and other documents
- Search and read existing campaign content
- Update documents with new information
- Execute complex multi-step tasks
- Run custom macros and JavaScript automation
Simulacrum understands Foundry VTT'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.
The AI uses a set of tools to interact with your world:
- Document Tools: Create, read, update, delete, search, and list documents
- Compendium Tools: Lock/unlock packs, manage document ownership
- Asset Search: Find images, audio, and other assets in your data
- Schema Introspection: Understands your game system's data structures
- Macro Execution: Run any macro in your world
- JavaScript Execution: Advanced automation capabilities
Destructive operations (update, delete, macro/JS execution) require confirmation before executing. Configure per-tool permissions with Allow, Deny, Always Allow, or Blacklist options.
For complex operations, Simulacrum can create and manage tasks, tracking progress across multiple steps and reporting when complete.
Connect to any OpenAI-compatible API endpoint:
- OpenAI (GPT-4o, etc.)
- Google Gemini (via OpenAI-compatible endpoint)
- Anthropic Claude (via proxy or OpenRouter)
- OpenRouter, LLM7, and other aggregators
- Local models (Ollama, LM Studio, etc.)
Simulacrum is restricted to Game Masters only—players cannot access the AI interface or execute commands.
- Open Foundry VTT and navigate to Add-on Modules
- Click Install Module
- Search for "Simulacrum"
- Click Install
- Download the latest release from GitHub Releases
- Extract to your
Data/modules/directory - Restart Foundry VTT
- Enable the module in your world
- Open Module Settings → Simulacrum
- Configure your API Base URL and API Key
- Access Simulacrum from the sidebar tab
- Select a model from the dropdown in the sidebar header
- API Base URL: Your provider's OpenAI-compatible endpoint (e.g.,
https://api.openai.com/v1) - API Key: Your provider's API key
The model selector in the sidebar automatically fetches available models from your configured endpoint.
For detailed setup instructions, including free tier options and troubleshooting, see the Getting Started Guide.
Click the Simulacrum tab in the sidebar and start chatting. Examples:
"Create a goblin warrior named Grunk with 15 HP and a rusty shortsword"
"Find all journal entries about the Kingdom of Eldoria"
"Update the Dragon's Lair scene to add a treasure hoard in the corner"
"Create a task to build out the entire merchant guild, including 5 NPCs and their shop inventory"
You can create custom tools for Simulacrum by creating a standard Foundry VTT Macro. To expose a macro as a tool, add a const tool configuration object to your macro code:
// Tool Configuration - This tells Simulacrum how to use this macro
const tool = {
name: "my_custom_tool",
description: "A description of what this tool does",
parameters: {
type: "object",
properties: {
parameterName: {
type: "string",
description: "Description of the parameter"
}
},
required: ["parameterName"]
},
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;Important notes:
- A
responseparameter is automatically added to all macro-tools, allowing the AI to explain what it's doing to the user - Return a value from your macro to provide output to the AI (strings or objects work)
- If you don't return anything, the AI sees "No output"
- Simulacrum automatically discovers any macro with this configuration and makes it available to the AI
For advanced users, Simulacrum can execute arbitrary JavaScript, enabling complex automation workflows.
- Foundry VTT v13.0.0 or higher
- An OpenAI-compatible API endpoint with tool/function calling support
Important
Simulacrum requires models that support tool/function calling. This is how the AI interacts with your Foundry world. Models without tool support will produce errors or fail to respond. See Choosing a Model below.
Simulacrum works with any OpenAI-compatible endpoint that supports tool calling. Below are some common options, but any compatible provider will work:
Perfect for trying Simulacrum or light usage.
| Provider | Setup |
|---|---|
| Google AI Studio | Base URL: https://generativelanguage.googleapis.com/v1beta/openaiGet API key: aistudio.google.com/apikey Model: gemini-3-flash-preview or gemini-3-pro-preview |
| OpenRouter Free | Base URL: https://openrouter.ai/api/v1Get API key: openrouter.ai/keys Model: openrouter/auto (auto-selects free models with tool support) |
Free tiers have rate limits (typically 50-250 requests/day). Sufficient for testing and occasional use.
Best balance of cost, speed, and capability.
| Provider | Setup |
|---|---|
| OpenAI | Base URL: https://api.openai.com/v1Models: gpt-5-nano (cheapest), gpt-5-mini, gpt-5.2 |
| Anthropic | Requires OpenRouter or compatible proxy Models: claude-haiku-4.5, claude-sonnet-4.5, claude-opus-4.5 |
| OpenRouter | Access to 100+ models from one API key Browse models with tool support |
Run models privately on your own hardware.
| Component | Recommendation |
|---|---|
| Software | Ollama — see their model library for tool-capable models |
| Model Size | 20B+ parameters recommended for complex tasks |
| GPU VRAM | 24GB+ for best experience (16GB minimum with quantization) |
| Hardware Cost | Used RTX 3090 ( |
Warning
Small models (7B-14B) will struggle with Simulacrum's multi-tool workflows. Expect slow responses and frequent errors. If your hardware is limited, cloud APIs provide a better experience.
Not sure if your model supports tools? Check these resources:
- OpenRouter: Models with tool support
- Ollama: Model pages indicate "Tools" support in capabilities
- Provider docs: Search for "function calling" or "tool use" in your provider's documentation
- Issues: GitHub Issues
- Source: GitHub Repository
- Donate: Buy Me a Coffee
MIT License - see LICENSE for details.
Created by Daxiongmao87