tea0s_multimuse-tracker/README.md

Multimuse Obsidian

For use with the BRAT Plugin for the best experiance.

An Obsidian plugin for seamless integration with the MultiMuse Discord bot. Track Discord roleplay threads, send messages as muses directly from Obsidian, and automatically sync scene states.

Features

• ✅ Automatic Thread Tracking: Automatically tracks Discord threads linked in your scene files
• ✅ Send as Muse: Right-click selected text to post as a muse to Discord threads
• ✅ Auto-Detected User ID: Automatically detects your Discord user ID from your API key (no manual configuration needed)
• ✅ Scene Creation: Create new scene files with muse selection, folder organization, and automatic property tracking
• ✅ Sync from Tracker: Import tracked threads from the bot and create scene files
• ✅ Property Tracking: Automatically adds "Roleplay" and "Is Active?" properties based on folder structure
• ✅ Configurable Polling: Automatically checks Discord threads for new replies (5-60 minute intervals)
• ✅ Frontmatter Updates: Automatically updates Replied? and Participants fields based on thread state

Installation

Manual Installation

Install via BRAT with https://github.com/BackstagePassGroup/multimuse-obsidian

Setup

1. Get Your API Key

1. Open Discord DMs with the MultiMuse bot
2. Use the command: /api generate
3. Copy the generated API key (starts with mm_)

2. Configure Plugin

1. Open Obsidian Settings → Multimuse Obsidian
2. Paste your API key in the "API Key" field
3. Your Discord user ID will be automatically detected from the API key
4. Configure other settings:
   • Enable Polling: Turn automatic checking on/off
   • Poll Interval: How often to check for new replies (5-60 minutes)
   • Scenes Folder: Folder containing your scene files (default: "RP Scenes")
   • Obsidian Base Path: Optional path to Base file for scene tracking
   • Track Roleplay Property: Automatically extract "Roleplay" from folder path
   • Track Is Active? Property: Automatically add "Is Active?" property (defaults to true)

Usage

Creating New Scenes

1. Use the command "Create New Scene" (Command Palette or ribbon button)
2. Select a muse from the list
3. Enter the Discord thread/channel URL
4. Select the folder location (or create a new one)
5. Enter the scene name
6. Set the number of participants
7. The scene file will be created with all necessary frontmatter

Syncing from Tracker

1. Use the command "Sync from Tracker"
2. For each tracked thread, select the folder location
3. Scene files will be created automatically with frontmatter populated from the bot

Sending Messages as Muse

1. Open a scene file in Obsidian
2. Select the text you want to send
3. Right-click → "Send as Muse"
4. If multiple characters are in the frontmatter, select which muse to post as
5. The message will be automatically posted to the Discord thread

Scene File Format

Your scene files should have frontmatter like this:

---
Link: https://discord.com/channels/123456789/987654321/111222333444555666
Characters:
  - Bel
  - Another Character
Roleplay: For The Greeks
Participants: 2
Replied?: false
Is Active?: true
Created: 2024-01-15
---

[Scene content here]

Required fields:

• Link: Full Discord thread URL
• Characters: Array of character/muse names (used for "Send as Muse")

Auto-updated fields:

• Replied?: Automatically updated by the plugin (true = your turn, false = not your turn)
• Participants: Automatically updated with thread participant count

Auto-added fields (if enabled in settings):

• Roleplay: Extracted from folder path (e.g., "For The Greeks" from "RP Scenes/For The Greeks/Twin Flames")
• Is Active?: Automatically set to true for new scenes

Commands

• Check Discord Threads Now: Manually trigger a check for all scenes
• Toggle Discord Polling: Enable/disable automatic polling
• Create New Scene: Create a new scene file with muse selection
• Sync from Tracker: Sync scenes from bot tracker to Obsidian

Settings

Core Settings

• Enable Polling: Turn automatic checking on/off
• API Key: Your MultiMuse API key (auto-detects user ID)
• Poll Interval: How often to check (5-60 minutes)
• Scenes Folder: Folder containing your scene files
• Obsidian Base Path: Optional path to Base file for scene tracking

Scene Properties

• Track Roleplay Property: Automatically add "Roleplay" property from folder path
• Track Is Active? Property: Automatically add "Is Active?" property (defaults to true)

Read-Only Information

• Detected User ID: Your Discord user ID (automatically detected from API key)

How It Works

Thread Tracking

1. The plugin scans all .md files in your scenes folder
2. For each file with a Link and Characters field in frontmatter:
   • Extracts the Discord thread ID from the URL
   • Queries the MultiMuse API for thread state
   • Updates Replied? field (true = your turn, false = not your turn)
   • Updates Participants field

Send as Muse

1. Selected text is extracted from the editor
2. Frontmatter is read to get Link and Characters
3. Thread ID is extracted from the Discord URL
4. If multiple characters, a selection modal appears
5. Message is posted via the MultiMuse API
6. Long messages are automatically split to respect Discord's limits

Scene Creation

1. Muse is selected from available muses (fetched from API)
2. Discord thread URL is validated
3. Folder location is selected (with context showing which muse)
4. Scene file is created with frontmatter
5. Scene is registered with the MultiMuse API
6. File is marked as "recently created" to prevent immediate state updates

Troubleshooting

"API authentication failed" error

• Make sure your API key is correct (starts with mm_)
• Verify the API key was generated using /api generate in Discord
• Check that the API key hasn't been revoked

"Failed to get user ID from API key"

• Verify your API key is valid
• Check your internet connection
• Ensure the MultiMuse bot API is accessible

"Muse not found or not accessible"

• Make sure the muse name in your frontmatter matches exactly (case-insensitive)
• Verify the muse exists in Discord
• Check that the muse is owned by you or shared with you

Files not updating

• Check that your scene files have Link and Characters fields in frontmatter
• Verify the link contains a valid Discord thread URL
• Make sure polling is enabled
• Check the console (Ctrl+Shift+I) for errors

"Send as Muse" not working

• Ensure text is selected before right-clicking
• Verify the file has Link and Characters in frontmatter
• Check that the selected muse exists and is accessible
• Verify your API key is configured correctly

Scenes marked as "Replied?" incorrectly

• This can happen if the bot doesn't have access to the channel (403 Forbidden)
• The plugin includes safeguards to prevent incorrect updates
• Newly created scenes are protected from immediate updates for 60 seconds
• Check the bot console for access errors

Rate Limiting

• Discord API has rate limits
• If you hit limits, increase the poll interval
• The plugin handles rate limits gracefully

Privacy & Security

• Your API key is stored locally in Obsidian's settings
• The plugin only accesses threads you've linked in your scene files
• All communication goes through the MultiMuse bot API
• User ID is automatically detected from API key (no manual entry needed)
• No data is sent to external servers except the MultiMuse bot API

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Credits

• Author: BackstagePass Group
• Plugin: Multimuse Obsidian