How to Use Local AI (poor to fair)
1. Select Options: Choose a Race, Occupation, and Settlement Tier.
2. Generate: Click "Generate NPC" to let the local AI create a unique character.
Tip: You can use an external AI provider (like Ollama or LM Studio) in Settings > General Settings.
How to Use External AI (Ollama / ChatGPT)
You can connect this app to a powerful AI running on your own computer (like Ollama) or a remote API.
- Go to Settings (Gear Icon) > General Settings.
- Toggle "Use External AI API" on.
- Enter your API URL (e.g.,
https://localhost:11434/v1 for Ollama).
- Enter the Model Name (e.g.,
llama3) and API Key if needed.
- Adjust the Context Window Threshold (default 32k) to match your hardware's capacity.
How to Use AI of your choice (Manual)
1. Select Options: Choose a Race, Occupation, and Settlement Tier.
2. Show Prompt: Click "Show Prompt" to see the exact text sent to the AI. Useful if you want to use the prompt elsewhere.
3. Mobile - Share:Share to the AI app of choice on your mobile device
3. OR - Copy: Copy and paste into the AI tool of choice.
Features
- Offline Capable: Once loaded, the local AI runs entirely on your device (assuming a powerful enough device). No internet required for generation.
- Device Check: The app automatically checks if your device supports WebGPU for local AI processing.
- Model Selection: Use the Settings (gear icon) to switch between different local AI models and manage storage.
- Share: Share the generated NPC directly to other apps such as your prefered AI tool.
- NPC Details: Use the "Advanced Options" to add specific names, traits, or plot hooks to your NPC prompt.
Settlement Features
Organize your NPCs into persistent settlements to create a cohesive world context.
- Manager (Castle Icon): Create and switch between settlements. Define their core identity, economy, and conflicts in the "Worksheet" tab.
- Bag It: Save a generated NPC to your active settlement using the "Bag It" button.
- Auto-Summarize: Use the "✨ Auto-Summarize" button when bagging an NPC to automatically extract their name, role, and secrets.
- Context Injection: The active settlement's details and any "checked" NPCs in "The Bag" are automatically added to the AI prompt, ensuring new characters fit the setting and know their neighbors.
Troubleshooting
If the AI is slow or fails to load, try selecting a smaller model (e.g., Qwen2.5-0.5B) in the Settings. Ensure your browser is up to date.
Alternativly generate the Prompt and use that with your favorite AI tool.
Download the Guide
Get the full near 500 page PDF guide used to build this tool.
▶ Advanced Features
Deep Linking
You can link directly to a specific configuration of the app using the Link button (🔗). This copies a URL with your current selections.
Fuzzy Search: The occupation parameter supports "contains" matching. For example, using ?occupation=Baker in the URL will automatically select "The Baker".
Untouched dropdowns (defaults) are excluded from the link.
Export/Import
Backup your settlements or move them to another device using the buttons in the Settlement Manager sidebar. Data is saved as a JSON file.
Model Context Protocol (MCP)
This app provides dual-tier access for AI agents (like Claude Desktop, Cursor, or your own scripts) to browse medieval lore and generate NPCs.
Tier 1: Public Lore Access (Basic)
Instant access to 130+ occupation backgrounds. No token required. AI agents can browse the full research database directly from our static API endpoint.
Endpoint: /mcp
Tier 2: Private Bridge (Advanced)
Enables stateful tools like generateNPC and saveBaggedNPC. Requires a Pairing Token generated in Settings.
How it Works: The token acts as a secure rendezvous key. Requests are routed through a real-time tunnel directly to your browser. Your local PWA session then performs the logic and sends it back. No lore or generation data is ever stored on our servers.
- 1. Pair: Go to Settings and click Generate. This creates a unique pairing token and establishes a persistent connection to the relay.
- 2. Configure: In your AI agent's MCP settings, use the endpoint:
https://npc.bagsoffolding.com/mcp
- 3. Authenticate: Provide your token using one of two methods:
- Append it to the URL:
?token=YOUR_TOKEN
- Or send an
Authorization: Bearer YOUR_TOKEN header.
- 4. Stay Active: Keep this browser tab open. The bridge relies on your active session to access the lore. If you close the tab, the AI agent will lose access.
Available tools: getOccupations, getOccupationLore, getNPCTemplate.
