How relic-repo/crux works
1. What this repository is
- CRUX is a Foundry VTT add-on module for the dnd5e system.
- Its core job is to replace part of the normal left-side play workflow with a tabbed tray UI: an Actions panel and an Actor panel, plus related token/combat tools.
2. Top-level architectural boundary
- The module is structured around a clear separation between:
- Foundry/runtime access
- system-specific dnd5e adaptation
- UI presentation
- interaction controllers
- shared state/settings
- This makes the module portable across Foundry versions while keeping dnd5e-specific logic isolated.
3. Entry point and bootstrap
- scripts/index.js is the module entry.
- Startup behavior is coordinated through scripts/hooks/CruxHooksManager.js, which is the integration layer for Foundry lifecycle events.
- The hooks layer likely wires up settings, UI injection, app registration, controller setup, and any Foundry event listeners.
4. Runtime abstraction layer
- scripts/runtime/CruxFoundryAccess.js and scripts/runtime/CruxFoundryPaths.js isolate Foundry API/version concerns.
- scripts/runtime/dnd5e/CruxDnd5eAccess.js and scripts/runtime/dnd5e/CruxDnd5ePaths.js do the same for dnd5e-specific data shapes and paths.
- This is an important architectural seam: the rest of the module can depend on these wrappers instead of directly binding to Foundry or system internals.
5. System adapter boundary
- scripts/systems/CruxSystemRegistry.js and scripts/systems/dnd5e/CruxDnd5eSystemAdapter.js define the system plug-in model.
- For this repo, dnd5e is the active adapter, which supplies the logic for:
- item/action grouping
- actor summary data
- basic action behavior
- spell/resource indicators
- optional compatibility with common automation flows
- This is the main place where the module becomes “dnd5e-aware” rather than generic Foundry UI.
6. Main UI surfaces
- The module exposes at least two primary UI surfaces implemented as Foundry apps:
- scripts/apps/CruxTrayAppV2.js for the left-side tray
- scripts/apps/CruxMovementAppV2.js, CruxElevationAppV2.js, CruxEffectsAppV2.js for specialized flyout/tool windows
- scripts/apps/CruxTrayAppV2.js is the core shell that hosts the tabbed experience and orchestrates tray content.
7. Tray composition and panel structure
- The tray is built from reusable panel and bubble systems:
- scripts/panels/CruxPanelRegistry.js
- scripts/bubbles/CruxBubbleRegistry.js
- These registries suggest a composition model where small UI units are registered and assembled into larger tray sections.
- The tray also has dedicated controllers for render/state behavior, indicating the UI is not purely template-driven.
8. Interaction controllers
- Most user behavior is centralized in controllers:
- CruxActorInteractionController
- CruxItemInteractionController
- CruxCombatController
- CruxFlyoutController
- CruxTrayRenderController
- CruxTrayStateController
- These controllers likely separate concerns such as:
- clicking actions/items
- handling combat and token actions
- opening/closing flyouts
- syncing tray state with Foundry selection and keybinds
- rendering refresh logic
- This is a key diagram boundary: templates render UI, controllers manage behavior.
9. Shared state and settings
- scripts/state/CruxStateManager.js centralizes runtime UI state.
- scripts/settings/CruxSettings.js, CruxSettingDefinitions.js, CruxVisualPresets.js, and CruxThemeVariables.js manage configurable behavior and appearance.
- The architecture treats settings as a first-class subsystem because tray size, icon sizing, visibility, default expansion, font choices, and similar options materially affect how the tray is composed and rendered.
10. Template and presentation layer
- Handlebars templates under templates/ define the visual structure:
- templates/crux.hbs is the main shell
- templates/flyouts/ contains focused tool windows
- templates/partials/ contains reusable sections for controls, actor data, items, and dnd5e-specific views
- The templates/partials/dnd5e/... tree indicates the module is assembled from many small partials rather than one monolithic sheet.
- styles/crux.css is the single main style sheet for tray and panel presentation.
11. User interaction utilities
- scripts/utils/ contains shared infrastructure for drag/drop, DOM manipulation, inline editing, template helpers, and tray resolution.
- Notable helpers include:
- drag-and-drop support
- anchored flyouts
- drop portals
- inline editor injection
- item form injection
- These utilities support the tray’s interaction-heavy design and reduce duplication across controllers and apps.
12. Key data flows
- The main data path is:
- Foundry event / keybinding / actor selection
- hooks and controllers interpret context
- system adapter resolves dnd5e actor/item data
- state/settings determine what sections are visible and how they behave
- templates render the tray/panels
- controllers handle clicks, rolls, item use, token tools, and updates back into Foundry
- A second important flow is actor/item activation:
- the tray triggers dnd5e item or action use
- when needed, it falls back to chat-card style actions
- this keeps compatibility with automation-oriented workflows.
13. Compatibility and optional integrations
- The README shows the module targets Foundry v13+ and is verified for v14, with dnd5e 3.0+.
- Optional support exists for Tidy 5e Sheets and taskbar-style compatibility.
- These integrations are not the core architecture, but they explain why the module has adapters, compatibility utilities, and section registries rather than hardcoded assumptions.
14. Localized and distributable module packaging
- module.json is the Foundry manifest that defines distribution and module metadata.
- lang/en.json and lang/pt-BR.json indicate built-in localization.
- The repo also includes GitHub Actions, which suggests the module is packaged/released as a distributable Foundry module rather than an installed app service.
15. How to draw the architecture
- The clean diagram should show:
- Foundry VTT and dnd5e as external dependencies
- a bootstrap/hooks layer
- a runtime/system adapter layer
- state/settings
- tray/apps/controllers
- template/style presentation
- utilities as shared support across the UI
- The most important boundary is between generic module infrastructure and dnd5e-specific behavior, with the adapter layer bridging them.
Main entry points: CruxTrayAppV2.js Tray app · CruxHooksManager.js Hooks · CruxUtilityManager.js Utility manager · CruxDnd5eSystemAdapter.js dnd5e adapter
Components 34
Bootstrap
Module entry and Foundry lifecycle integration.
- Entry point · Module bootstrap and export surface.
scripts/index.js - Hooks · Wires Foundry events into module setup.
scripts/hooks/CruxHooksManager.js
Runtime
Foundry and dnd5e abstraction layers.
- Foundry VTT · Host application API and lifecycle.
- Foundry access · Version-safe access to Foundry APIs.
scripts/runtime/CruxFoundryAccess.js - Foundry paths · Centralized Foundry path resolution.
scripts/runtime/CruxFoundryPaths.js - dnd5e access · Version-safe access to dnd5e data.
scripts/runtime/dnd5e/CruxDnd5eAccess.js - dnd5e paths · Centralized dnd5e path resolution.
scripts/runtime/dnd5e/CruxDnd5ePaths.js
Systems
System registry and dnd5e adapter.
- dnd5e · Target game system and data model.
- System registry · Selects the active game-system adapter.
scripts/systems/CruxSystemRegistry.js - dnd5e adapter · Implements dnd5e-specific tray and actor behavior.
scripts/systems/dnd5e/CruxDnd5eSystemAdapter.js
State
Shared settings and runtime UI state.
- Settings · Module options and persisted preferences.
scripts/settings/CruxSettings.js - Setting defs · Defines configurable module options.
scripts/settings/CruxSettingDefinitions.js - Visual presets · Preset sizing and style choices.
scripts/settings/CruxVisualPresets.js - Theme vars · Theme variables used by the tray UI.
scripts/settings/CruxThemeVariables.js - State manager · Central UI state for tray and panels.
scripts/state/CruxStateManager.js
UI
Tray apps, flyouts, controllers, and composition registries.
- Tray app · Main tabbed tray shell and host.
scripts/apps/CruxTrayAppV2.js - Flyout apps · Specialized tool windows for movement, elevation, and effects.
scripts/apps/CruxMovementAppV2.js - Tray controller · Coordinates tray render and refresh behavior.
scripts/controllers/CruxTrayRenderController.js - Tray state · Syncs tray state with selection and UI events.
scripts/controllers/CruxTrayStateController.js - Actor control · Handles actor clicks and actor-level actions.
scripts/controllers/CruxActorInteractionController.js - Item control · Handles item use, actions, and item interactions.
scripts/controllers/CruxItemInteractionController.js - Combat control · Coordinates combat and token-oriented actions.
scripts/controllers/CruxCombatController.js - Flyout control · Opens and manages auxiliary flyout windows.
scripts/controllers/CruxFlyoutController.js - Panel registry · Registers reusable tray panels.
scripts/panels/CruxPanelRegistry.js - Bubble registry · Registers compact tray bubbles and controls.
scripts/bubbles/CruxBubbleRegistry.js - Workspace API · Workspace-oriented module API surface.
scripts/api/CruxWorkspaceApi.js
Support
Shared utilities and compatibility helpers.
- Utility manager · Shared UI helpers and utility coordination.
scripts/utils/CruxUtilityManager.js - Compatibility · Optional integration and behavior checks.
scripts/utils/CruxCompatibility.js - Drag/drop utils · Drag, targeting, and drop handling.
scripts/utils/CruxDragDropUtils.js - DOM utils · DOM manipulation helpers for tray rendering.
scripts/utils/CruxDomUtils.js - Template utils · Partial registration and template support.
scripts/utils/CruxTemplatePartials.js - Tray resolver · Resolves tray placement and anchoring.
scripts/utils/CruxTrayResolver.js - Anchored flyout · Positions flyouts relative to tray context.
scripts/utils/CruxAnchoredFlyout.js - Inline editor · Injects inline edit behavior into tray UI.
scripts/utils/CruxInlineEditor.js
Connections 45
- Entry point → Hooks: boots · Starts module initialization through Foundry hooks.
- Hooks → Settings: loads · Registers and applies module settings.
- Hooks → System registry: selects · Chooses the active system adapter.
- Hooks → Tray app: registers · Injects the main tray app into Foundry.
- Hooks → State manager: initializes · Creates shared runtime state.
- Hooks → Flyout control: wires · Connects lifecycle events to flyout behavior.
- System registry → dnd5e adapter: hosts · Provides the active dnd5e implementation.
- dnd5e adapter → dnd5e access: uses · Reads system data through the adapter layer.
- dnd5e adapter → dnd5e paths: uses · Resolves dnd5e-specific paths.
- dnd5e adapter → Panel registry: feeds · Supplies tray section composition for the system.
- dnd5e adapter → Bubble registry: feeds · Supplies bubble composition for the system.
- Tray app → Tray controller: renders · Delegates refresh and render coordination.
- Tray app → Tray state: binds · Keeps tray state synchronized.
- Tray app → Panel registry: assembles · Builds the tabbed tray from reusable panels.
- Tray app → Bubble registry: assembles · Adds compact bubble controls.
- Tray app → Actor control: delegates · Routes actor interactions to controller logic.
- Tray app → Item control: delegates · Routes item interactions to controller logic.
- Tray app → Combat control: delegates · Routes combat and token actions.
- Tray app → Flyout control: opens · Launches auxiliary flyout windows.
- Tray app → Workspace API: exposes · Provides a workspace-facing API surface.
- Tray controller → State manager: reads · Uses shared state to drive rendering.
- Tray state → State manager: updates · Mutates tray and selection state.
- Actor control → dnd5e adapter: uses · Resolves actor-specific dnd5e behavior.
- Item control → dnd5e adapter: uses · Resolves item/action behavior.
- Combat control → dnd5e adapter: uses · Resolves combat-related actions.
- Flyout control → Anchored flyout: positions · Manages anchored tool windows.
- Settings → Setting defs: defines · Uses the setting schema.
- Settings → Visual presets: applies · Applies visual presets.
- Settings → Theme vars: styles · Feeds theme variables into presentation.
- Utility manager → Compatibility: checks · Handles optional compatibility behavior.
- Utility manager → Drag/drop utils: uses · Supports drag and drop interactions.
- Utility manager → DOM utils: uses · Supports DOM-level UI manipulation.
- Utility manager → Template utils: uses · Supports partial registration and template helpers.
- Utility manager → Tray resolver: uses · Resolves tray placement and sizing.
- Utility manager → Inline editor: uses · Enables inline editing affordances.
- Tray app → Utility manager: depends on · Shares common UI infrastructure.
- Flyout control → Utility manager: depends on · Reuses shared support utilities.
- Hooks → Foundry access: abstracts · Isolates Foundry API/version differences.
- Hooks → Foundry paths: abstracts · Centralizes Foundry path concerns.
- Hooks → dnd5e access: abstracts · Isolates dnd5e data-shape differences.
- Hooks → dnd5e paths: abstracts · Centralizes dnd5e path concerns.
- Foundry access → Foundry VTT: wraps · Bridges the module to the host runtime.
- dnd5e access → dnd5e: wraps · Bridges the module to the game system.
- Panel registry → Tray app: composes · Supplies the tray with structured sections.
- Bubble registry → Tray app: composes · Supplies bubble widgets for the tray.