A calendar and timekeeping module for Foundry VTT v13+ with clean integration APIs and extensible architecture.
Full calendar interface showing monthly view with navigation, notes, and time controls
Compact mini widget showing weather integration and calendar builder access
- Modern UI: Clean, responsive calendar interface with ApplicationV2 architecture
- Multiple Calendar Views: Full calendar widget, compact mini widget, and monthly grid view
- Customizable Mini Widget: Right-click context menu for toggling display options (time, weekday, moon phases, controls, extensions), plus drag-and-drop positioning with pin/unpin functionality
- Configurable Quick Time Buttons: Customizable time advancement buttons with live preview and smart mini widget selection
- Real-Time Time Advancement: Automatic time progression with pause/resume controls synced to Foundry's game pause state
- Smart Year Navigation: Click year to jump instantly instead of clicking arrows repeatedly
- Convenient Defaults: Gregorian calendars can initialize with current date/time
- Module Integration: Clean APIs for weather modules and other integrations via compatibility bridges
- SmallTime Integration: Seamless positioning and visual consistency. Time display intelligently hidden when SmallTime is present (configurable). Mini widget provides drag-and-drop positioning with persistent storage.
- 16+ Available Calendars: Switch between core calendars (Gregorian, Golarion PF2e) and calendar pack collections featuring fantasy calendars (D&D, Critical Role, etc.), sci-fi calendars (Star Trek, Starfinder, Traveller), and custom formats based on official game sources
- Calendar Pack Auto-Detection: Automatically discovers and loads calendar modules following the
seasons-and-stars-*naming convention - no JavaScript required, just JSON data files - External Calendar Registration: New hook system (v0.8.0+) allows modules to register calendars programmatically for dynamic calendar loading
- Advanced Date Formatting: Handlebars-based templates with mathematical operations, format embedding, and era-specific calculations (like Star Trek stardates)
- Canonical Hours: Time period naming system for fantasy settings (e.g., "Strange's Bells" for 3-6 AM, medieval monastery hours)
- Calendar Variants System: Cultural and regional calendar variations (e.g., Golarion has Absalom Reckoning, Imperial, Varisian, and Earth Historical variants)
- Game Pause Sync: Automatically pause/resume time advancement when Foundry's game is paused/unpaused with smart multi-source coordination and intuitive single-click button controls
- Moon Phase Tracking: Multi-moon support with accurate phase calculations for fantasy worlds
- Note Creation: Functional note creation interface via calendar grid (GMs only - click plus button)
- Visual Indicators: Calendar shows colored borders for days with notes
- Backend API: CRUD operations available for module developers (note editing via API, not UI)
- Simple Calendar Compatibility: API compatibility via separate compatibility bridge module
- Note Editing: While notes can be created with calendar-specific metadata (categories, tags, dates), editing only opens the basic Foundry journal interface which cannot modify calendar-specific fields
- Metadata Management: Tags, categories, and date associations cannot be changed after creation
- Limited UI: No dedicated note management interface - relies on basic Foundry journal sheets
Visual JSON editor for creating and editing custom calendars
- Visual Calendar Editor: Create and modify calendars through an intuitive interface
- JSON Schema Validation: Real-time validation with helpful error messages
- Import/Export: Load existing calendars or create new ones from scratch
- Available as:
seasons-and-stars-calendar-buildermodule
- Complete Notes UI: Note viewing, editing, and management interface
- Simple Calendar Migration Tools: Automated import of Simple Calendar data
- Advanced Configuration: Enhanced calendar customization and validation
- Extended Integrations: Additional module compatibility and hook enhancements
Foundry Module Browser (Recommended)
- Install from Foundry VTT module browser:
- Seasons & Stars - Core module (required)
- Seasons & Stars - Fantasy Calendar Pack - Fantasy RPG calendars (optional)
- Seasons & Stars - Sci-Fi Calendar Pack - Science fiction calendars (optional)
- Seasons & Stars - Pathfinder 2e Pack - PF2e integration and Golarion calendars (optional)
- Seasons & Stars - Calendar Builder - Visual calendar editor (optional)
- Enable the modules in your world
- Configure your preferred calendar in module settings
Manual Installation
- In Foundry VTT, go to Add-on Modules → Install Module
- Use manifest URL:
https://github.com/rayners/fvtt-seasons-and-stars/releases/latest/download/module.json - Enable the module in your world
Right-click the mini widget for display options and quick access to features
- Open Calendar: Click the calendar button in the journal notes controls (left sidebar)
- Change Date: GMs can click on calendar dates to set world time
- Quick Time Controls: Use the mini widget for rapid time advancement
- Real-Time Mode: Toggle automatic time progression with the play/pause button
- Calendar Selection: Switch between different calendar systems anytime
- Customize Display: Right-click mini widget to toggle time, weekday, moons, and extension buttons
- User Guide - Complete usage instructions and calendar sources
- Developer Guide - API reference and integration guide
- System Integration Guide - Game system compatibility and time source integration
- Migration Guide - Moving from Simple Calendar
- Roadmap - Development timeline and planned features
- Known Issues - Current limitations and workarounds
- Discord: Join the Seasons & Stars community on discord.gg/tqZnxAdEqE for questions, feedback, and playtest coordination.
- GitHub: Report bugs or request features through Issues or Discussions.
- Inline Calendar Variants - Cultural and regional calendar variations within the same file
- External Calendar Variants - Themed calendar collections in separate files
- Module developers wanting to integrate calendar functionality
- GMs who need reliable timekeeping with clean UI
- Communities wanting to test cutting-edge calendar features
- Users seeking a calendar solution built for Foundry v13+
- Users wanting enhanced SmallTime integration
- Communities needing custom calendar support
Seasons & Stars provides clean integration APIs for calendar-aware modules:
// Direct API access
const currentDate = game.seasonsStars.api.getCurrentDate();
const worldTime = game.seasonsStars.api.dateToWorldTime(currentDate);
const formatted = game.seasonsStars.api.formatDate(currentDate);
// Hook integration for module updates
Hooks.on('seasons-stars:dateChanged', data => {
// Respond to date changes in your module
console.log('Date changed:', data.newDate);
});Compatibility bridges available for seamless migration from other calendar systems.
- Foundry VTT: v13 or higher
- Compatibility: Designed to work with D&D 5e, PF2e, Dragonbane, and other systems. PF2e includes dedicated integration features.
- Permissions: GM required for time changes
The Seasons & Stars ecosystem includes multiple modules you can install separately:
| Module | Description | Status |
|---|---|---|
| Seasons & Stars | Core calendar and timekeeping system | ✅ Required |
| Fantasy Calendar Pack | D&D, Pathfinder, Critical Role, and other fantasy calendars | 📦 Optional |
| Sci-Fi Calendar Pack | Star Trek, Starfinder, Traveller, and other sci-fi calendars | 📦 Optional |
| Pathfinder 2e Pack | PF2e system integration and Golarion calendar variants | 📦 Optional |
| Calendar Builder | Visual editor for creating and modifying calendars | 🛠️ Optional |
All optional packs require the core Seasons & Stars module to function.
// Access the Seasons & Stars API
const currentDate = game.seasonsStars.api.getCurrentDate();
await game.seasonsStars.api.advanceDays(1);
// Listen for date changes
Hooks.on('seasons-stars:dateChanged', data => {
console.log('Date changed:', data.newDate);
});See the Developer Guide for complete API reference.
Calendar packs are pure data modules that provide additional calendars without requiring any JavaScript:
seasons-and-stars-fantasy/
├── module.json # Standard Foundry module
└── calendars/
├── index.json # Collection metadata
├── dragonlance.json # Individual calendar files
└── forgotten-realms.json
Collection Format (calendars/index.json):
{
"name": "Fantasy Calendar Pack",
"calendars": [
{
"id": "dragonlance",
"name": "Dragonlance Calendar",
"file": "dragonlance.json",
"preview": "15th of Autumn Twilight, 421 AC"
}
]
}Modules with IDs starting with seasons-and-stars- are automatically detected and loaded. No registration required!
📖 Complete Guide: See Calendar Pack Development Guide for detailed instructions.
git clone https://github.com/rayners/fvtt-seasons-and-stars
cd fvtt-seasons-and-stars
npm install
npm run buildThis module is developed with the help of AI tools, particularly Claude (Anthropic's large language model). As a solo developer juggling planning, coding, documentation, and testing, AI helps me:
- Move faster: Generate boilerplate code and tests so I can focus on design decisions
- Debug efficiently: Work through edge cases without getting stuck for hours
- Write better docs: Create clear user guides and API documentation
- Test thoroughly: Generate regression tests to prevent bugs from creeping back
- Respond quicker: Faster turnarounds on updates and community feedback
What this means for you: More frequent updates, better documentation, and faster responses to issues and feature requests.
What it doesn't mean: I don't just ship whatever AI generates. Every line of code is reviewed, tested, and refined. Think of AI as a very helpful assistant, not an autopilot - I'm often correcting and redirecting it throughout the development process.
You'll see Claude credited as a co-author in commits because it genuinely contributes to the development process. Transparency matters, and I want to be open about the tools that help make this module possible.
Learn more: How and Why I Use AI in Development
Curious about the broader workflow, guardrails, and review process? The companion repository rayners/dev-context documents the standards and practices that guide this AI-assisted development approach.
- Basic calendar system and UI
- Simple Calendar compatibility layer
- Essential user features
- Calendar editor and creation tools
- Simple Calendar import and migration assistant
- Enhanced calendar validation and customization
- Complete notes editing interface
- Advanced note management and search
- Enhanced weather module integration
See the complete Roadmap for detailed timelines.
Love using Seasons & Stars? Consider supporting continued development:
Your support helps fund:
- 🚀 New Features: Advanced calendar tools and integrations
- 🐛 Bug Fixes: Faster resolution of issues and compatibility updates
- 📚 Documentation: Comprehensive guides and tutorials
- 🎯 Community Requests: Implementation of user-requested features
The 16 available calendar systems are designed to work with popular RPG settings including D&D, Pathfinder, Critical Role, and other systems. These implementations focus on practical gameplay functionality and may be simplified from official sources.
🤝 Community Contributions Welcome: We welcome submissions to make calendar configurations more accurate to their official sources. If you have access to official publications and notice discrepancies, please open an issue or submit a pull request with corrections and proper source citations.
MIT License - Free for personal and commercial use.
If you're experiencing date synchronization problems between Seasons & Stars and other modules (especially PF2e), please include this diagnostic information when reporting your issue:
Open your browser console (F12) and run these commands:
// Basic system information
console.log('=== Seasons & Stars Diagnostic ===');
console.log('System ID:', game.system?.id);
console.log('World Time:', game.time?.worldTime);
console.log('Active Calendar:', game.seasonsStars?.manager?.getActiveCalendar()?.id);
// S&S current date
const ssDate = game.seasonsStars?.manager?.timeConverter?.getCurrentDate();
console.log('S&S Date:', ssDate?.year, ssDate?.month, ssDate?.day, ssDate?.time);
// For PF2e systems, include this data
if (game.system?.id === 'pf2e') {
console.log('PF2e worldCreatedOn:', game.pf2e?.settings?.worldClock?.worldCreatedOn);
const baseDate = game.seasonsStars?.compatibilityManager?.getSystemData('pf2e', 'systemBaseDate');
console.log('PF2e Base Date:', baseDate);
}
// Module versions
console.log('S&S Version:', game.modules.get('seasons-and-stars')?.version);
console.log('Browser:', navigator.userAgent);Copy the console output and include it in your issue report.
This diagnostic information helps us quickly identify the root cause of date synchronization issues and provide targeted solutions.
- Issues: GitHub Issues (include diagnostic data!)
- Documentation: Complete Guides
- Discord: Foundry VTT Community -
#moduleschannel
Ready to try a calendar system built for Foundry v13+? Install Seasons & Stars today and help shape its development through feedback and testing!