Realms & Reaches Documentation
Complete documentation for the Realms & Reaches Foundry VTT module
Welcome to the comprehensive documentation for Realms & Reaches! This module provides a queryable biome and terrain layer for narrative-driven gameplay, exploration mechanics, and system integration.
📚 Documentation Overview
For New Users
- Complete walkthrough for first-time users
- Step-by-step tutorial creating your first realm
- Basic concepts and common patterns
- Troubleshooting for beginners
Perfect for: First-time users, quick onboarding, learning the basics
For Regular Users
- Comprehensive feature reference
- Advanced techniques and workflows
- Campaign integration strategies
- Best practices and optimization tips
Perfect for: GMs using the module regularly, advanced features, campaign integration
For Developers
- Complete programming interface documentation
- Integration examples and patterns
- Event system and data formats
- Performance considerations
Perfect for: Module developers, custom integrations, programmatic usage
🎯 Quick Navigation
By Task
| I want to... | Read this |
|---|---|
| Install and set up the module | Getting Started → Installation |
| Draw my first realm | Getting Started → Your First Realm |
| Understand the tag system | User Guide → Tag Management |
| Integrate with other modules | API Reference → Module Integration |
| Share realm data | User Guide → Data Management |
| Optimize performance | User Guide → Best Practices |
| Report a bug | User Guide → Troubleshooting |
By Experience Level
Beginner (New to the module)
- Getting Started Guide - Complete walkthrough
- User Guide Examples - Quick reference
- User Guide → Interface Overview - UI familiarization
Intermediate (Using regularly)
- User Guide → Advanced Techniques - Complex workflows
- User Guide → Campaign Integration - Module synergy
- User Guide → Best Practices - Optimization
Advanced (Power user/Developer)
- API Reference - Complete programming guide
- User Guide → Performance Optimization - Large datasets
- GitHub Issues - Feature requests
🎮 Feature Overview
Core Features
✅ Visual Realm Drawing
- Polygon, rectangle, and circle tools
- Real-time preview with grid snapping
- Color-coded biome display
- Documented in: User Guide → Drawing and Editing
✅ Tag-Based Data System
- Flexible
key:valuetag format - 8 core namespaces (biome, terrain, climate, etc.)
- Real-time validation and autocomplete
- Documented in: User Guide → Tag Management
✅ Spatial Query System
- Fast point-in-polygon detection (< 1ms)
- API for other modules to query realm data
- Efficient spatial indexing for large datasets
- Documented in: API Reference → Spatial Queries
✅ Data Import/Export
- JSON-based portable format
- Community data sharing support
- Version-compatible migrations
- Documented in: User Guide → Data Management
✅ Module Integration
- Public API for developers
- Event system for real-time updates
- Soft dependency patterns for graceful degradation
- Documented in: API Reference
🏷️ Tag System Reference
Quick Reference
| Namespace | Purpose | Example Values |
|---|---|---|
biome: | Ecosystem type | forest, desert, mountain, swamp |
terrain: | Movement conditions | dense, sparse, rocky, marshy |
climate: | Weather patterns | temperate, arctic, tropical, arid |
travel_speed: | Speed modifier | 0.5 (slow), 1.0 (normal), 1.5 (fast) |
resources: | Available materials | timber, game, minerals, water |
elevation: | Altitude category | lowland, highland, mountain |
custom: | Unique properties | haunted, sacred, dangerous |
module: | Module-specific | module:jj:encounter_chance:0.3 |
Full documentation: User Guide → Tag Management
🔗 Integration Examples
Journeys & Jamborees
// Automatic travel speed modification
const realm = realmsAPI.getRealmAt(party.x, party.y);
const speedMod = parseFloat(realm?.getTag('travel_speed')) || 1.0;
adjustedSpeed *= speedMod;
Weather Systems
// Climate-based weather effects
const climate = realm?.getTag('climate');
const weatherTable = getWeatherTable(climate);
Encounter Generation
// Biome-specific encounters
const biome = realm?.getTag('biome');
const encounterTable = `encounters-${biome}`;
Full examples: API Reference → Examples
🛠️ Development Resources
For Module Developers
- API Reference - Complete programming interface
- GitHub Repository - Source code and issues
- Module Template - Integration examples
Community
- Discord - #modules channel for questions
- GitHub Discussions - Community sharing
- Reddit - General Foundry community
📋 Common Workflows
Session Preparation
- Draw key areas for upcoming locations
- Add appropriate tags for travel and encounters
- Test integrations with other modules
- Export data for backup
During Play
- Select realms to check properties
- Reference tags for mechanical effects
- Add new areas discovered in play
- Update properties based on events
Post-Session
- Review and update realm data
- Add story elements as custom tags
- Export changes for backup
- Plan future areas to detail
🎯 Version Information
Current Status: Alpha Release
- Version: 0.1.0
- Status: ✅ Feature complete for MVP
- Compatibility: Foundry VTT v13+
- Stability: Ready for testing and feedback
What's Included
- ✅ Complete drawing and editing tools
- ✅ Comprehensive tag system
- ✅ Real-time properties editor
- ✅ Data import/export
- ✅ Developer API
- ✅ Full documentation
What's Next
- 🔄 J&J integration (FOU-71)
- 📋 Community features
- 📋 Performance optimizations
- 📋 Additional drawing tools
See GitHub Repository for development roadmap details
💡 Tips for Success
Getting Started
- Start simple: Begin with basic biome and terrain tags
- Use examples: Follow the patterns in the Getting Started guide
- Practice first: Try the tools on a test scene before your main campaign
Scaling Up
- Plan your system: Decide on tag conventions early
- Document choices: Keep notes on your tagging decisions
- Regular backups: Export data frequently
Performance
- Keep it simple: Complex polygons slow down rendering
- Focus on gameplay: Only tag what affects mechanics
- Test regularly: Check performance with your typical usage
Community
- Share your work: Export and share interesting realm datasets
- Learn from others: Import community-created content
- Contribute back: Report bugs and suggest improvements
📞 Getting Help
Self-Help Resources
- Troubleshooting sections in each guide
- FAQ patterns in Getting Started
- GitHub Issues for known problems
Community Support
- Foundry Discord - #modules channel
- GitHub Discussions - Q&A
- Reddit r/FoundryVTT - General community
Bug Reports
Create an issue with:
- Steps to reproduce the problem
- Your Foundry VTT version and browser
- Console error messages (if any)
- Screenshots (for visual issues)
Welcome to Realms & Reaches! 🗺️
This documentation represents the complete feature set available in version 0.1.0. The module is ready for alpha testing and feedback. Start with the Getting Started guide and work your way through the features at your own pace.
Happy realm building!