SC - Combat Wheel

Overview

SC - Combat Wheel shows who is acting and who comes next in a movable display beside your Foundry VTT scene. GMs can run an encounter from its control bar; players can roll their own initiative and end their turns.

Choose a half-circle Wheel, a Carousel, or a Slider. The display follows Foundry's combat order. Inspecting another portrait changes your view of the encounter; it does not advance the turn.

Compatibility and Installation

This module is free. This page documents version 1.0.2.

• Foundry VTT: minimum v13; verified for v14.
• Game systems: system agnostic. The display and controls use Foundry's Combat and Combatant documents. Health detection depends on your system's data or the source configured by the GM.
• Dependencies: no companion module is required. The SC integrations below are optional.
• Languages: English and Brazilian Portuguese.

Install and enable

1. In Foundry's setup screen, open Add-on Modules > Install Module.
2. Paste this URL into Manifest URL and install the module:

https://github.com/Shattered-Codex/sc-combat-wheel/releases/latest/download/module.json

3. Launch your world and enable SC - Combat Wheel in Manage Modules.
4. Under Configure Settings > Module Settings > SC - Combat Wheel, use Open settings for behavior and world rules, or Edit appearance for the display, announcements, and sounds.

The default configuration opens the wheel automatically when a combat has a participant visible to you. You can also open or close it with its button in the token controls.

What You Can Do

• Follow initiative in three layouts and move the display away from important parts of the scene.
• Roll initiative, start combat, and advance turns through permission-aware controls.
• Inspect everyone in the encounter, return to the active turn, and reorder participants as the GM.
• Create a personal appearance or share selected appearance options with the table.
• Announce turns with portraits, effects, and sounds.
• Limit enemy health and name information shown to players.
• Insert actorless turns for lair actions, reminders, and automated encounter events.
• Display shared phases when using SC - Venaerys's Initiative.

Run Your First Combat

The GM creates and starts the encounter. Players need ownership of their combatants to roll initiative or end their turns.

1. Add tokens to a combat as usual. With Open automatically enabled, the wheel appears before the encounter starts. Players focus on one of their own participants for initiative.
2. Roll initiative. The GM's roll menu offers Everyone, NPCs only, Characters only, and Clear initiatives. Roll actions fill pending initiatives; clearing removes existing rolls. Players can roll their own pending initiatives.
3. As the GM, select Start combat.
4. Use End turn to advance and Previous turn to go back. Players see End my turn while an owned combatant is acting.
5. Drag the control bar's handle to move the widget. Lock its position when it is where you want it.
6. As the GM, use End combat when finished. Foundry handles the confirmation and ending the encounter.

Tools may be gathered under More, depending on Bar tools. The default compact bar hides the details, direction, and appearance items; Edit appearance remains available from module settings.

Your position, lock state, and expanded details follow your user account across devices. If you close the wheel during setup, automatic opening shows it again when combat starts. Deleting the encounter closes its wheel and dismisses its announcement.

Tap to expand

Inspect Portraits and the Turn Order

Choose a layout

Open Edit appearance and select a Format at the top of the editor.

Use Layout to change size, spacing, scale, direction, and where the active turn sits. Direction places the portraits above, below, or beside the bar; side orientations turn the bar into a vertical rail. Bar shape can split controls into two side columns. The split layout has no details panel.

Tap to expand

Use portrait controls

By default:

• Click centers the camera on the combatant's visible token in the current scene.
• Double-click opens the actor sheet when you have permission. The single-click action runs first.
• Right-click opens a menu of available camera, token selection, and sheet actions. The GM can also remove the combatant or clear its recorded movement when that action is available.
• Hover highlights the corresponding visible token.

Change the three click actions in Open settings > Behaviour. Token and sheet actions still respect Foundry permissions. Camera follows the turn is optional and off by default.

See everyone and return to the turn

Select See everyone to open an overview of participants visible to you. Choose a portrait to bring it into focus without changing the turn. Use Back to turn to return to the active participant.

In ordinary, turn-based encounters, the GM can also drag portraits to change initiative order, use + between portraits to insert a virtual position, or remove a virtual position with ×. Players can inspect portraits but do not receive these editing controls. Hidden participants stay out of player overviews.

Read character and encounter details

In Edit appearance > Bar > Items in the bar, enable Details panel and keep Bar shape set to One bar. Expand the panel to see the focused participant's initiative, permitted health information, and temporary effects, including remaining rounds when available. Its previous and next controls inspect participants without advancing combat.

The encounter summary shows participant counts, who is standing, elapsed game time, who is next, and effects expiring this round. Health totals by disposition are shown only to the GM. Seconds per round controls this elapsed-time calculation; it does not change Foundry's world time.

Customize and Share the Appearance

Preview and save a look

1. Open Configure Settings > Module Settings > SC - Combat Wheel > Edit appearance.
2. Choose a Format and Theme, or start with a Ready-made look.
3. Preview with Sample or This combat. The sample's turn buttons let you check transitions.
4. Adjust the relevant tabs. Switch from Essential to All to reveal fine-tuning options.
5. Select Save changes to apply the result.

Layout controls the display's dimensions and placement. Portraits controls artwork, names, initiative, and health overlays. Bar controls the tools and details. Visual controls colors, typography, panels, borders, and virtual-position message styling. Effects controls highlights, waves, particles, and motion.

Color fields inherit the theme until overridden. Palette from one colour builds a dark or light palette from a seed color; the editor also reports low contrast. Effects respect your operating system's reduced-motion preference.

Tap to expand

Share a table look

Each user has a saved appearance across devices. Whenever the GM saves an appearance, it also becomes the table look. The GM chooses how players use it through Table look:

The table look does not replace browser sound preferences or world combat rules.

Save styles and transfer a look

As the GM, save named looks in Styles. Use Switch style… from the wheel, token controls, or Combat Tracker menu to apply one. Applying a saved style updates the GM's look and the table look according to the sharing mode.

Export saves the appearance currently shown in the editor as JSON. Import loads an appearance into the editor for preview; select Save changes to apply it. Appearance files exclude browser sounds and world rules.

Announce Turns and Play Sounds

Configure the turn display

1. Open Edit appearance > Turn display.
2. Set Show it to Automatic, Only on my turn, On everyone's turn, or Off. Automatic announces every turn to the GM and owned turns to a player.
3. Choose the picture, frame, border, shape, position, size, and duration. Leave Title of your turn empty to use the default.
4. Choose effects and particles, then use Test the announcement.
5. Select Save changes.

Announcements can be a Card, Cinematic band, or Corner display. The default is a centered card lasting three seconds; click an announcement to dismiss it sooner. Also when I am next adds a smaller up-next announcement when allowed by the GM.

Tap to expand

Turn announcement

The card identifies the acting combatant with a portrait and title.

1 / 2

Share a player's announcement card

Enable Show my card to the table to share your announcement design on your character's turn. Recipients retain their own choice of which turns to announce, title, placement, size, and duration. Disable See each player's card to use your own design for every announcement.

Choose sounds

In Edit appearance > Sounds, choose a sound separately for combat start, any turn change, your turn, being up next, a new round, going back, and combat end. Each event can use a preset, Your own file, or Off. Test individual choices or use Hear a combat to hear a sequence.

Sound preferences apply only to the current browser. Wheel volume defaults to 60% and is multiplied by Foundry's interface volume. The GM can disable module sounds for everyone through Allow wheel sounds (whole table). Turn sounds and announcements still work while the wheel is closed.

Foundry combat sounds in this tab edits Foundry's own browser sound theme. It can play alongside Combat Wheel sounds; choose None for that theme or disable overlapping module events if you hear two sounds.

Control Health and Player Visibility

The GM manages these rules in Open settings > What players see and Combat rules. They control information in Combat Wheel; Foundry's native tracker and game system retain their own behavior.

Choose how much health players see

Enemy hit points for players defaults to Descriptive state. Other choices are Exact number, Bar only, or Nothing. Owners, the GM, and viewers of friendly combatants receive exact health when a usable health source exists.

Descriptive states distinguish full health, wounded, half health or less, one-quarter health or less, and zero health. Health overlays use those bands when only descriptive information is allowed; they do not reveal an exact percentage through the fill.

For a system whose automatic detection does not work:

1. Set Hit points come from to Token bar 1, Token bar 2, or Attribute path (below).
2. For an attribute, enter the parent of its value and max fields relative to the actor's system data. For example, attributes.hp reads actor.system.attributes.hp.value and .max.
3. Enable The value counts damage for a custom attribute that records damage taken. Remaining health is then maximum minus value. Automatic system presets already define their own inversion.
4. Save and check the display with a combatant that has a valid maximum above zero.

Automatic detection includes presets for D&D 5e, Pathfinder 2e, Daggerheart, Call of Cthulhu 7e, SWADE, Imperium Maledictum, and Fabula Ultima, with a token-bar fallback for other systems. These presets do not imply verified compatibility with every version of those systems; use an explicit source when needed.

Conceal combatants and names

Combatants hidden in the tracker are always excluded from player displays. Hidden from players defaults to also excluding tokens hidden on the map; its strictest choice also excludes combatants with the invisible status. The GM can see concealed participants with a crossed-out eye.

Combatant names for players can always show names or follow token name-display settings. Actor artwork is shown to players only with at least Limited actor permission; otherwise the module uses token art.

Handle defeated combatants

Dead combatants keeps defeated or visibly zero-health participants in black and white by default, or removes them from the wheel. Removing a portrait does not delete the combatant or automatically skip its turn.

Skip dead combatants' turns is a separate rule, off by default. Skip NPCs only skips defeated or zero-health combatants without player owners, leaving player turns available for actions such as death saves. Skip everyone who is dead applies to all combatants. Automatic skipping runs on the active GM and never applies when going backward.

Add Virtual Positions and Encounter Events

A virtual position is a turn without an actor or token. Use one for a lair action, a ritual pulse, reinforcements, or a reminder at a specific place in initiative. The GM creates and configures these positions.

Create a reusable template

1. Open Open settings > Virtual positions and select New virtual position.
2. Set Name, Initiative, and Image.
3. Optionally enable Hidden from players, Add to every new combat, or Advance on its own.
4. Under Consequences, select + Add a consequence… and configure the action. Use On to enable or disable each row.
5. Select Save changes. Use Add to current combat, or the wheel's virtual-position menu, to add the template to the encounter.

For a manual lair action, leave Advance on its own disabled so the GM can resolve it before advancing. For a reminder, add Message on screen, enter its text and duration, and enable automatic advancement if the position should not wait for a manual turn change.

Virtual positions keep a fixed initiative. Clearing initiatives restores that value rather than leaving them pending a roll.

Insert an event between portraits

1. Open See everyone and select + at the desired gap.
2. Enter a title, message, and optional picture. Choose a template if you want its configured consequences instead of a simple on-screen message.
3. Select Add. Use the form's settings shortcut if you need to manage templates first.

The position enters initiative at that gap. An image chosen in the insertion form overrides its template's image. With a template selected, the template supplies the consequences; the message field is used for a position created without a template.

Tap to expand

Insert a position

Use a gap's plus control to place an event in the current order.

1 / 3

Choose what happens on the turn

Consequences run when combat advances into the position. Going back does not replay them. Advancing into the position again can run them again; this is not a once-per-round trigger for every action.

Messages, sounds, and hooks run on each client that can see the position. Chat, macros, RollTable draws, and companion-module actions run once on the active GM. Hiding a position does not cancel those GM-side actions. Keep an active GM connected for automation and automatic advancement.

Optional integrations add these actions:

• SC - Jump Scare: play a configured scare by ID.
• SC - Puzzle Engine: open, arm, or trigger a puzzle page by UUID.
• SC - Resources: add, subtract, set, or restore a configured resource for player characters in combat, every combatant's actor, or one actor by UUID.

Virtual-position messages use Visual > Virtual position message for shape, placement, size, and picture visibility. They are separate from Turn display announcements.

Use Phased Initiative

When SC - Venaerys's Initiative is active and the encounter uses phases, Combat Wheel displays phases in place of individual turns. An acting strip shows the current phase's members and their progress.

Players can mark their owned participants done from the strip. With movement and actions split, they mark movement first. The GM navigates phases; Venaerys manages progression. Turn announcements can show the phase and its members together.

The appearance editor's Phases tab controls the acting strip's position, artwork, frame, size, and names. It appears only while Venaerys is active.

Initiative reordering in See everyone, Combat Wheel's virtual-position automation, and dead-turn skipping are not used in phased encounters. Configure event phases and their actions in Venaerys instead. Ordinary encounters retain Combat Wheel's turn-based behavior.

Settings Reference

Open Configure Settings > Module Settings > SC - Combat Wheel. Open settings contains behavior, visibility, rules, virtual templates, and Foundry combat controls. Edit appearance contains the display and sound tabs. Select Save changes after editing.

The references below use the module's English labels and default values. Conditional controls appear only for the relevant format or parent choice; use All in the appearance editor for advanced options. Theme-inherited color fields are empty until overridden. Virtual templates and sharing modes are described in their workflows above.

Keyboard Shortcuts and Macros

Assign shortcuts

No keys are assigned by default. In Foundry's Configure Controls, bind:

• Show or hide the wheel.
• Next turn and Previous turn — GM only.
• Lock or unlock the wheel position.
• See everyone.
• Back to the current turn.
• Reset wheel position.

Turn navigation, overview, and lock actions use the open wheel. Resetting the position is also available in Behaviour, the token controls, and the GM's Combat Tracker menu.

Control the wheel from a script macro

Run these after the world is ready with SC - Combat Wheel enabled. Display actions affect the current user's client.

const wheel = game.modules.get("sc-combat-wheel")?.api;
if (wheel) wheel.toggle();

The public API also provides:

For example, open the virtual-template settings as the GM:

game.modules.get("sc-combat-wheel")?.api?.openSettings("virtual");

Set a custom actor portrait

As the GM, set Open settings > Table > Portrait source to Custom portrait (module flag), then token. The module reads the actor's sc-combat-wheel.portrait flag. With the actor's token controlled, this script macro sets a portrait and crop position:

const actor = canvas.tokens.controlled[0]?.actor;
if (actor) {
  await actor.setFlag("sc-combat-wheel", "portrait", {
    src: "worlds/my-world/images/portrait.webp",
    position: "50% 20%",
  });
}

Replace the example path with an image in your Foundry data. A string containing only the image path is also supported. Personal Portrait image overrides and actor-art permissions still apply. Use await actor.unsetFlag("sc-combat-wheel", "portrait") to clear the override.

Listen for a virtual-position hook

Add Fire a hook to a virtual template and set Hook name to myTable.lairPulse. Register a listener on each client that needs to react, after the world is ready:

Hooks.on("myTable.lairPulse", ({ combat, combatant, config }) => {
  console.log(`${config.name}: round ${combat.round}`, combatant);
});

The listener runs locally only where the position is visible. Register it once per session; rerunning the registration adds another listener. For a single GM-side action, use Run a macro instead.

Troubleshooting and Limitations

Keep one active browser session for the designated active GM when relying on automation. Foundry selects an active GM user; multiple sessions under that same account can receive the same events.

Related Modules and Support

• SC - Venaerys's Initiative — shared phases and phase actions.
• SC - Jump Scare, SC - Puzzle Engine, and SC - Resources — optional virtual-position consequences.
• SC - Wheel Menu — a separate module for radial scene and sidebar navigation.
• Source code and releases.
• Report a problem or ask in Discord.

For support, include your Foundry version, system and version, module version, active integrations, whether the issue affects the GM or players, and steps to reproduce it. Add a screenshot or relevant console error when available.