This package contains art, text, or software code produced using generative AI.
Some code of this module has been generated by AI
StoryFrame
A FoundryVTT module that enhances narrative gameplay and skill check coordination. StoryFrame provides GMs with intelligent tools for managing speakers and coordinating skill checks, while players receive synchronized displays showing active NPCs, pending rolls, and multi-option challenges.
Supports Pathfinder 2e and D&D 5e with system-specific features including proficiency levels, actions, DC tables, and lore skills.
📚 Documentation
Quick Links:
✨ Features Overview
🎭 Speaker Management
For GMs:
- Smart NPC Detection - Automatically detects NPCs from journal images and actor references
- Multiple Add Methods - Drag & drop actors, click journal actors/images, or manual entry
- Active Speaker Selection - Click portraits to highlight active speaker for all players
- Speaker Wheel - Radial quick-selection menu (keybind) for rapid speaker switching
- Scene Management - Save and load speaker configurations for recurring locations/NPCs
For Players:
- Synchronized Gallery - See all NPCs with active speaker highlighted in real-time
- Auto-Open - Player Viewer opens automatically when GM sends content
- Layout Options - Grid, list, or horizontal display modes
📖 Speaker Management Documentation
🎲 Skill Check Coordination
For GMs:
- PC Management - Add all PCs, party members, or individuals
- Batch Operations - Select multiple PCs and request multiple checks at once
- DC Management:
- Manual DC entry (1-60)
- DC Presets - Save frequently-used DCs
- System DC Tables - Auto-calculated difficulty based on party level
- Secret Rolls - GM-only results for Perception, Insight, Stealth checks
- Quick Skill Buttons - Customizable quick-access buttons for common skills
- Skill Categories - Physical, Magical, Social, Utility
- Journal Parsing - Select text with skill checks and auto-request rolls (keybind)
For Players:
- Player Sidebar - Dedicated panel for pending roll requests
- One-Click Rolls - Click to execute checks directly from sidebar
- Persistent Requests - Rolls persist until completed, no dialogs blocking
- Multi-PC Support - See all pending rolls when controlling multiple characters
🏆 Challenge System
Create multi-option skill challenges where players choose their approach:
Features:
- Multiple Options - 2-4 different approaches per challenge (climb, sneak, persuade, etc.)
- Varied Skills - Each option can require different skills at different DCs
- Proficiency Requirements (PF2e) - Lock options requiring Trained/Expert/Master/Legendary
- Challenge Library - Save challenges for reuse
- Auto-Creation - Create challenges from selected journal text (keybind)
- Visual Interface - Players see all options and choose their approach
Example Challenge:
"Infiltrate the Castle"
Option 1: Climb the Wall - Athletics DC 15
Option 2: Pick the Lock - Sleight of Hand DC 18, Investigation DC 15
Option 3: Bluff Past Guards - Deception DC 16, Persuasion DC 14
📖 Challenge System Documentation
💾 Scene Management
Save speaker configurations for quick loading:
- Save Current Speakers - One-click save of current NPC gallery
- Scene Editor - Visual editor for building speaker scenes
- Quick Loading - Click scene name to instantly load all speakers
- Perfect for: Recurring taverns, councils, shops, party groups
⚡ Speaker Wheel
Radial quick-selection for rapid speaker switching:
- Hold keybind to show wheel
- Move mouse toward speaker portrait
- Release to select
- Perfect for fast-paced dialogue and dramatic moments
🎮 System Support
Pathfinder 2e
- Skills: All 17 standard skills + custom lore skills
- Actions: Right-click skills for specific actions (Demoralize, Seek, Recall Knowledge, etc.)
- Proficiency System: Untrained, Trained, Expert, Master, Legendary
- DC Tables: Level-based DCs (0-25) with difficulty modifiers (Trivial to Extreme)
- Degree of Success: Critical success/success/failure/critical failure
- Lore Skills: Full support for character-specific lore (Academia Lore, Warfare Lore, etc.)
- Party Integration: One-click to add all party members
D&D 5e
- Skills: All 18 standard skills
- Ability Saves: Strength Save, Dexterity Save, etc.
- DC Tables: Very Easy (5) to Nearly Impossible (30)
- Proficiency: Proficient/Expertise (basic support)
- Advantage/Disadvantage: Applied via standard roll dialog
📋 Requirements
- FoundryVTT: Version 13 or higher
- Required Module: socketlib
- Supported Systems: D&D 5e or Pathfinder 2e
🚀 Installation
From Module Browser (Recommended)
- In FoundryVTT, go to Add-on Modules > Install Module
- Search for "StoryFrame"
- Click Install
- Enable in your world settings
From Manifest URL
Manifest URL coming soon
🎯 Quick Start
For Game Masters
-
Open GM Sidebar
- Open any journal entry
- Click the StoryFrame toggle button
- Sidebar appears docked to journal
-
Add Speakers
- Drag actors from Actors sidebar
- Click journal actors/images
- Or use "Add NPC" button
-
Select Active Speaker
- Click any portrait to set as active
- All players see highlighted speaker
-
Request Skill Checks (Optional)
- Add PCs to participant list
- Select which PCs should roll
- Set DC and click skill button
For Players
-
Open Player Viewer
- Click StoryFrame button in token controls
- Or wait for auto-open when GM sends content
-
View Active Speaker
- See all NPCs in gallery
- Active speaker is highlighted
-
Respond to Skill Checks
- Pending rolls appear in Player Sidebar
- Click to roll
- Request clears after rolling
⌨️ Keybinds
Configure in FoundryVTT Settings > Configure Controls > Module Keybindings:
- Speaker Selection Wheel - Hold to show radial speaker menu
- Request Rolls from Selection - Parse journal text and request rolls
- Create Challenge from Selection - Auto-create challenge from journal checks
🎨 Interface Overview
GM Sidebar (Docks to Journals)
Tabs:
- NPCs - Speaker gallery and active speaker selection
- PCs - Participant management and skill check requests
- Rolls - Monitor pending roll requests
- Challenges - View and manage active challenges
Sections:
- Journal Images - Click images to add as speakers
- Journal Actors - Click actor references to add
- Saved Scenes - Quick-load saved speaker groups
- DC Presets - Saved difficulty configurations
- Challenge Library - Reusable challenges
Player Viewer (Auto-Opens)
Main Area:
- Speaker gallery with active speaker highlighted
- Layout toggle (grid/list/horizontal)
Player Sidebar:
- Pending roll requests
- Active challenges with multiple options
- Grouped by character (if controlling multiple)
🔧 Technical Details
Architecture
- System-Specific Implementations: Dedicated subclasses for PF2e and D&D 5e
- Real-Time Sync: socketlib-based communication for instant updates
- Scene Flags: State stored in scene flags for persistence
- ApplicationV2: Modern Foundry application architecture
State Management
- Per-Scene: Speakers and participants stored per Foundry scene
- World Settings: DC presets, challenge library, saved scenes
- Client Settings: UI positions, layouts, preferences
🤝 Contributing
Contributions welcome! See the GitHub repository for:
- Feature requests
- Bug reports
- Pull requests
🐛 Troubleshooting
Module won't enable?
- Enable socketlib first (required dependency)
- Verify FoundryVTT v13+
Players not seeing updates?
- Check socketlib is enabled on both ends
- Verify network connection
Speaker Wheel not working?
- Configure keybind in settings
- Must hold key, not tap
- Need at least one speaker added
❓ FAQ
Q: Does StoryFrame work with other systems? A: Currently only D&D 5e and PF2e have full support. Basic speaker functionality may work with other systems.
Q: Can I use StoryFrame with Theatre Inserts or ConversationHUD? A: Not recommended - may conflict. Test in separate world first.
Q: Is the Player Viewer required? A: No, it's optional. Players can ignore it and just use character sheets normally.
Q: Can I save speaker groups for recurring NPCs? A: Yes! Use the Scene Editor to save and load speaker configurations.
📦 Version
Current Version: 1.6.1
See Releases for changelog.
📄 License
See repository for license details.
👤 Author
RoiLeaf
🔗 Links
Enhance your storytelling with StoryFrame! 🎭