System_Docs
///Installation guides, map building best practices, and technical details.
1. Extension Installation
Before installing any custom locations, you need to add the base extension to your SillyTavern client.
- Download the latest extension release:
- Extract the downloaded archive.
- Move the extracted folder into your SillyTavern extensions directory:
.../SillyTavern/public/scripts/extensions/ - Restart SillyTavern and enable the extension in the Extensions menu (API connections icon).
2. Map Installation Guide
> Method 1: The One-Click Install
Chromium Browsers OnlyWorks on Chrome, Edge, Brave, Opera, etc.
If you are using a supported browser, installing maps is incredibly easy. When using the external Map Builder, you can directly select your extension's assets folder (.../SillyTavern/public/scripts/extensions/silly-map/assets). The browser will automatically save the new location right where it belongs. Refresh SillyTavern, and you're good to go!
> Method 2: Manual Install
For Firefox, Safari, Mobile
- Download the location as a ZIP archive.
- Extract the folder and place it inside
.../silly-map/assets/locations/. - Go to SillyTavern, open the map extension, click "+ Add location", and type the exact name of the folder.
Important Note for Mobile/Multi-Device Users
When you use the "+ Add location" button, the extension remembers your maps using your browser's local storage. If you switch devices (e.g., from PC to Phone) or clear your browser cache, the map will disappear from the list.Your files are not deleted! You just need to click "+ Add location" and type the folder name again to make it visible. For a permanent, cross-device solution, you can manually add the folder's name to the locations_index.json file inside the assets folder.
3. Map Building Best Practices
Remember: The AI can't see the map; it relies entirely on the text descriptions you provide in the Builder. To get the best character logic and movement, follow these rules:
- [+]Location & Room Descriptions: Be clear and specific. If the location description is ambiguous, the AI might struggle to pick the right context. Name your rooms logically (e.g., "Main Tavern Hall" instead of just "Room 1") so the AI understands the layout and vibe of the current space.
- [+]Keep Objects Static: The interactive points on your map (Objects) are static. Characters are tethered to them, but the objects themselves don't move.
- [+]Name Objects Clearly: Give objects distinct, recognizable names. "Heavy Oak Desk" is much better for the AI to interact with than "Table 2".
- [+]Don't Clutter (Object Count): Less is more. Try to limit the number of objects per room to the most important points of interest. Adding 30 random chairs and barrels will confuse the AI and unnecessarily bloat the prompt. Stick to the key areas where characters might actually sit, stand, or interact.
4. Token Usage & Context Size
When you build a massive location with multiple rooms and objects, you might notice the total token count getting high. Don't panic!
Only active rooms load
The extension is optimized so that the AI does not receive the entire map data at once. It only loads the context of the specific room the character is currently in.
Prompt Weight
Just keep in mind that the system prompts, room descriptions, and object names in that specific active room will be sent to the AI. Keeping descriptions concise but descriptive is the best way to save tokens.