v2.1.0

[2.1.0] - 2026-04-30

Added

• GM Companion Linking (System-Agnostic): GM can link one or more companion actors to a parent actor so companions share the parent’s movement turn
  • Companions are collapsed out of the turn order (no separate companion turns)
  • During the parent’s turn, players who own both parent and companion can move both tokens
  • Links are stored as Actor flags (persist across scenes/maps and Foundry restarts)
  • Turn order panel shows grouped turns like Parent (with: Companion1, Companion2)

v2.0.1

[2.0.1] - 2026-02-05

Added

• Debug Mode Setting (GM only): New world setting to enable turn order diagnostics
  • When enabled with attribute-based ordering, sends a GM-whispered chat message showing each token's initiative value, tiebreaker value, and final sort position in an HTML table
  • Skipped entirely for random order (no useful diagnostic info)
• Available Attributes Listing: When a configured attribute path is not found on a token (N/A), the debug message now lists all available system.* attribute paths from a sample token so the GM can identify the correct path

v2.0.0

[2.0.0] - 2025-12-16

BREAKING CHANGES

• Foundry v13+ Required: This version only supports Foundry VTT v13 and later
  • Dropped support for Foundry v11 and v12
  • Complete rewrite of controls system for v13 API compatibility
  • If you need v11/v12 support, use version 1.1.0

Added

• Game Master Turn: New GM placeholder at the start of every turn order
  • Always appears first in turn order regardless of random/attribute sorting
  • Displayed as "Game Master" with purple highlighting in the turn order panel
  • Allows GM to move tokens freely and adjust turn order before players start
  • No visual indicators or player notifications during GM turn
  • GM entry is draggable/reorderable like other turn entries
  • Provides setup time for GM at the start of each round
• Always-Visible Control Buttons: All turn management buttons now visible at all times
  • Pass Turn, Delay Turn, and Reset buttons always shown (no page reload needed)
  • Buttons check if TBM is enabled when clicked
  • Warning notification shown if buttons clicked while TBM disabled
  • Improved UX: No need to reload page when enabling/disabling TBM

Changed

• Foundry v13 API Compatibility: Complete rewrite for new controls system
  • getSceneControlButtons hook now uses object-based API (was array-based)
  • Controls accessed via controls.tokens instead of controls.find()
  • Tools defined as object properties instead of array push
  • Tool definitions require name property matching the key
  • Changed onClick to onChange callback (deprecated API)
  • Updated ui.controls access patterns to v13 standards
• Control Button Behavior: Buttons remain visible regardless of TBM state
  • Previous behavior: Buttons only visible when TBM enabled
  • New behavior: Buttons always visible, check state on click
  • Better discoverability for new users
  • Consistent UI experience

Fixed

• Scene Controls Rendering: Fixed controls not appearing in Foundry v13
  • controls parameter is now an object, not an array
  • tools is now an object where each tool is a keyed property
  • Updated tool registration to use property assignment
• Deprecated API Warnings: Removed all deprecated v12 API usage
  • Fixed ui.controls.activeControl → ui.controls.control?.name
  • Fixed ui.controls.activeTool → ui.controls.tool?.name
  • Fixed ui.controls.initialize() → ui.controls.render()
  • Fixed onClick → onChange for tool callbacks

Technical Changes

• Module Manifest: Updated compatibility to v13 minimum, v13 verified
• Controls Hook: Refactored getSceneControlButtons for v13 object-based API
• Turn Order Logic: Added 'GM' string placeholder handling throughout codebase
  • getCurrentToken() returns null for GM turn
  • getNextToken() returns null for GM turn
  • announceCurrentTurn() skips announcements during GM turn
  • refreshVisuals() skips visual indicators during GM turn
  • renderTurnOrderUI() displays GM entry with special styling
• CSS Styling: Added .gm-entry styles for GM placeholder in turn order panel
• Documentation: Updated CLAUDE.md with v13 API changes and gotchas

Removed

• Support for Foundry VTT v11 and v12
• Backward compatibility code for v12 controls API
• Dynamic button visibility logic (buttons now always visible)

v1.1.0: Adds turn history and improves notifications

[1.1.0]

Added

• Go Back Button (GM only): New button in turn order panel to undo turn advancement
  • Only visible and enabled for GM
  • Disabled when no turn history is available
  • Restores previous turn state including round number, delayed tokens, and turn index
• Turn History Tracking: Complete state history for undo functionality
  • Tracks index, round, delayed tokens, and delayed-this-round state
  • History saved before each turn advance or delay action
  • History cleared when turn order is reset or TBM is disabled
  • Prevents going back before any turns have been passed

Changed

• Notification System Improvements:
  • Removed "Pass turn request sent..." notification (silent action)
  • Removed "Delay turn request sent..." notification (silent action)
  • Fixed duplicate "It's your turn" / "You're up next" messages
  • Notifications only trigger when turn index or round actually changes
  • Token name only shown in notifications when player controls multiple tokens
  • Added state tracking to prevent duplicate announcements

Fixed

• Turn Order Filtering: Only tokens with player ownership are added to turn order
  • GM-only tokens are excluded from turn order
  • Unowned tokens are excluded from turn order
  • Uses actor.hasPlayerOwner check to determine eligibility
• Panel Position Persistence: Turn order panel now remembers position per-user
  • Position saved to user flags when dragging ends
  • Position restored when TBM is re-enabled
  • Each user (GM and players) can have their own panel position
  • Position persists across TBM enable/disable cycles
• Duplicate Notifications: Players no longer receive multiple copies of the same turn notification
  • Added state hash tracking (round-index) to prevent duplicates
  • announceCurrentTurn() only called when currentIndex or currentRound flags change
  • Prevents showing both "You're up next" and "It's your turn" when turn advances
• Notification Spam: Reduced unnecessary notification messages during turn advancement

Technical Changes

• Added TURN_HISTORY scene flag for undo functionality
• Added PANEL_POSITION user flag for per-user panel positioning
• Added _lastAnnouncedState static property to track announcement state
• Modified nextTurn() and processDelayTurn() to save state before advancing
• Added getTurnHistory() method for history retrieval
• Improved updateScene hook to filter announcements by flag changes
• Enhanced previousTurn() with complete state restoration logic

v1.0.0

[1.0.0]

Added

Core Features

• Turn-Based Movement System: Complete turn-based token movement with permission-based control
• Token Movement Restrictions: Players can only move their tokens during their turn, GMs have full override
• Two Turn Order Modes:
  • Random order (shuffled)
  • Attribute-based order (highest value first)
• Tiebreaker System: Optional secondary attribute to break ties in turn order
  • If tiebreaker is empty or still tied, uses random ordering for tied tokens

Visual Features

• Turn Order UI Panel:
  • Draggable panel showing complete turn order with round counter
  • Current turn highlighted in green, next turn in yellow
  • Completed turns dimmed for visual feedback
  • Delayed tokens highlighted in orange with "(Delayed)" label
  • Click any token name to pan camera to it (if visible)
  • Panel remembers position across refreshes
• Icon Indicators Above Tokens:
  • Green chevron (▼) for current turn
  • Yellow pause symbol (II) for next turn
  • Pulsing animation for visibility
  • Scaled appropriately (16px font)
  • Positioned 10 pixels above tokens

Turn Management Features

• Round Counter: Automatic tracking starting at Round 1, increments when turn order completes
• Pass Turn: Advance to the next token in order
  • GM can pass directly
  • Players send requests to GM via user flags
• Delay Turn: Move current token to end of round
  • Can only delay once per round
  • Cannot delay if you're the last non-delayed token (unless others already delayed)
  • Delayed tokens act at end of round in their original order
  • Round increments after last delayed token acts
  • GM processes player delay requests via user flags
• Reset Turn Order: Regenerate turn order and reset round to 1
• Drag-and-Drop Reordering (GM only): Click and drag token names in UI panel to manually reorder permanently

Combat Integration

• Auto-Disable on Combat Start: TBM automatically disables when combat begins
• Auto-Resume After Combat: Optional setting to resume TBM when combat ends (if it was enabled before)
• State Persistence: Remembers if TBM was enabled before combat for proper resume behavior

UI/UX Features

• Draggable Turn Order Panel: Click and hold header to move panel anywhere, position is saved
• Visual State Indicators:
  • Green highlight: Current turn
  • Yellow highlight: Next turn
  • Orange highlight: Delayed tokens
  • Dimmed: Completed turns this round
• Camera Pan on Click: Click token names in panel to center camera on that token
• Notification System:
  • Players notified when it's their turn (GM excluded from these notifications)
  • Players notified when they're up next
  • Notifications for enable/disable TBM (not chat messages)
  • Warnings for invalid actions (not your turn, can't delay, etc.)

Technical Features

• Scene Flag Storage: All state persisted in scene flags
  • Turn order array
  • Current index
  • Current round
  • Delayed tokens list
  • Delayed this round list (prevents multiple delays)
• User Flag Communication: Permission-safe player-to-GM communication via user flags
  • Pass turn requests
  • Delay turn requests
  • GM validates and processes all player requests
• Permission-Based Security:
  • Players can only affect their own tokens
  • All state changes require GM or token ownership
  • Validation on both client and GM side

Module Settings

• Enable Turn-Based Movement: Toggle system on/off
• Turn Order Type: Random or By Token Attribute
• Attribute Path: Primary attribute for turn order (e.g., system.attributes.init.value)
• Tiebreaker Attribute Path: Optional secondary attribute for breaking ties
• Show Visual Indicators: Enable/disable icon indicators above tokens
• Resume After Combat: Automatically resume TBM when combat ends

Localization

• Full English localization support
• All UI strings externalized to lang/en.json
• Strings for settings, controls, notifications, and UI labels

Compatibility

• Foundry VTT: v11 minimum, verified up to v12
• Game Systems: System-agnostic, works with all game systems
• Module Compatibility: No known conflicts

Developer Features

• Clean, documented code structure
• Single-class design for maintainability
• Static methods for easy access
• Scene flag-based state management
• Hook-based reactivity
• PIXI.js for canvas rendering

Technical Implementation Details

Architecture

• Client-Side Only: No server-side code required
• Static Class Design: TurnBasedMovement class with static methods
• Event-Driven: Uses Foundry hooks for reactivity
• Flag-Based State: Scene and user flags for data storage

Key Files

• scripts/turn-based-movement.js: Main module code
• styles/turn-based-movement.css: UI styling
• lang/en.json: English localization strings
• module.json: Module manifest

Data Flow

1. GM Actions: Directly modify scene flags
2. Player Actions: Set user flags, GM watches updateUser hook and processes
3. State Changes: Trigger updateScene hook, all clients refresh
4. Visual Updates: refreshVisuals() called on state changes

Performance Optimizations

• Panel position saved and restored on refresh (no flicker)
• Icons only recreated when needed
• Efficient token lookup via scene.tokens.get()
• Minimal DOM manipulation

Known Limitations

• Players require active GM connection to pass/delay turns (uses request system)
• Turn order limited to tokens with linked actors
• Single scene at a time (scene-specific state)