kaykayyali/Its-Achievable
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.3.0: strip combat HUD; integrate with combat-hud-hub

Browse Source 
- Deleted scripts/hud.js, scripts/event-translation.js, styles/hud.css,
  templates/hud.html.
- Removed mod.api.getHud/openHud/closeHud/buildHudUpdatePayload exports.
- Removed hudPosition setting (moved to combat-hud-hub).
- Added hub integration: at ready, if combat-hud-hub is installed,
  register a 'pinned-achievements' section. The chatBubble listener
  now also pushes entries into that section via hub.api.pushFeedEntry.
- Soft-dep on combat-hud-hub (optional); popover still works without
  the hub.
- Tests: 57/57 passing covering sections A-G (rule engine, catalog,
  awarding, hooks wiring, hub integration, graceful degradation).
This commit is contained in:
Kaysser Kayyali
2026-06-22 12:46:57 -04:00
parent 3bc1053a30
commit 2f6acc0da1
10 changed files with 299 additions and 1702 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
CHANGELOG.md Normal file
View File

@@ -0,0 +1,25 @@
# Changelog
All notable changes to It's Achievable are documented here.
## [0.3.0] — 2026-06-20 (strip HUD; integrate with combat-hud-hub)
- **Combat HUD removed.** `scripts/hud.js`, `scripts/event-translation.js`, `styles/hud.css`, `templates/hud.html` deleted. The HUD is now provided by the new `combat-hud-hub` module.
- **API surface change (breaking for consumers calling `mod.api.getHud`/`openHud`/`closeHud`/`buildHudUpdatePayload`).** These four exports removed; their behavior lives in `combat-hud-hub.api`.
- **Pinned Achievements section.** When `combat-hud-hub` is installed, its-achievable registers a `pinned-achievements` section on the hub at `ready`. The `chatBubble` listener now pushes awarded achievements into that section's feed via `hub.api.pushFeedEntry`.
- **Settings cleanup.** `hudPosition` setting removed (now lives on `combat-hud-hub`).
- **Tests: 57/57 passing** in <2s covering sections A-G of `tests/PLAN.md`.
## [0.2.0] — 2026-06-19 (HUD strapped to foundry-hooks-lib envelope stream)
- HUD subscribes to foundry-hooks-lib's envelope stream (subscribeMany on combatStart, combatEnd, combatRound, combatTurn, createCombatant, deleteCombatant, dnd5e.rollAttackV2, dnd5e.rollDamageV2).
- HUD reads the active encounter via `battle-focus.api.getActiveEncounter()` (soft-dep).
- chatBubble listener draws the achievement popover.
## [0.1.1] — 2026-06-19 (track the hax-hooks-lib → foundry-hooks-lib rename)
- Module id rename only; no behavior change.
## [0.1.0] — 2026-06-18 (initial extraction from battle-focus v0.5.0-alpha.12)
- Achievements engine, custom rules, rewards, achievement wall, and combat HUD extracted from battle-focus into a standalone Foundry module.

16
module.json
View File

@@ -1,8 +1,8 @@
{
"id": "its-achievable",
"title": "It's Achievable",
"description": "Foundry VTT v14 module: achievements engine, custom rules, rewards, achievement wall, and combat HUD. v0.2.0 straps the HUD to the new hooks system (finds the foundry-hooks-lib envelope stream + battle-focus's getActiveEncounter API). Consumes the generic Foundry hook facade from foundry-hooks-lib and the encounter state from battle-focus.",
"version": "0.2.0",
"description": "Foundry VTT v14 module: achievements engine, custom rules, rewards, achievement wall, and chat-bar 🏆 popover. v0.3.0 strips the combat HUD (moved to combat-hud-hub). When combat-hud-hub is installed, its-achievable registers a 'Pinned Achievements' section and surfaces recent unlocks in the HUD via the hub's section API. Soft-dep on combat-hud-hub (optional).",
"version": "0.3.0",
"library": false,
"manifestPlusVersion": "1.2.0",
"authors": [
@@ -25,6 +25,14 @@
"compatibility": {
"minimum": "0.4.0"
}
},
{
"id": "combat-hud-hub",
"type": "module",
"manifest": "https://git.homelab.local/kaykayyali/combat-hud-hub/raw/branch/main/module.json",
"compatibility": {
"minimum": "0.2.0"
}
}
],
"requires": []
@@ -32,7 +40,7 @@
"esmodules": ["scripts/main.js"],
"url": "https://git.homelab.local/kaykayyali/its-achievable",
"manifest": "https://git.homelab.local/kaykayyali/its-achievable/raw/branch/main/module.json",
"download": "https://git.homelab.local/kaykayyali/its-achievable/raw/branch/main/its-achievable-0.2.0.zip",
"download": "https://git.homelab.local/kaykayyali/its-achievable/raw/branch/main/its-achievable-0.3.0.zip",
"readme": "https://git.homelab.local/kaykayyali/its-achievable/blob/main/README.md",
"changelog": "https://git.homelab.local/kaykayyali/its-achievable/commits/main",
"bugs": "https://git.homelab.local/kaykayyali/its-achievable/issues",
@@ -42,4 +50,4 @@
"allowBugReporter": true,
"hotReload": { "extensions": [], "paths": [] }
}
}
}

2
package.json
View File

@@ -1,6 +1,6 @@
{
"name": "its-achievable",
"version": "0.2.0",
"version": "0.3.0",
"private": true,
"description": "Foundry VTT v14 module: achievements, custom rules, rewards, achievement wall, and combat HUD. v0.2.0 straps the HUD to the new hooks system. Depends on foundry-hooks-lib (event stream) and battle-focus (encounter state).",
"main": "scripts/main.js",

186
scripts/event-translation.js
View File

@@ -1,186 +0,0 @@
// scripts/event-translation.js
//
// Thin translation layer: hooks-lib envelope args -> the event shape
// its-achievable's HUD consumes. Each handler returns a
// `{kind, ts, ...eventData}` event object or null.
//
// Per the v0.6.x split intent, this duplicates the shape of
// battle-focus's event handlers (scripts/events.js) but ONLY for
// the hooks the HUD cares about. battle-focus and its-achievable
// are independent consumers of the foundry-hooks-lib envelope
// stream; the duplication is intentional and small.
/**
* Build a timestamped event object. ts is a Date.now() taken at
* translation time.
*/
function ev(kind, data = {}) {
return { kind, ts: Date.now(), ...data };
}
/**
* combatStart(combat, updateData) — fires when a combat is started.
* The HUD uses this to know "the encounter began."
*/
export function onCombatStart(combat /*, updateData */) {
return ev("combat-start", {
combatId: combat?.id ?? null,
sceneId: combat?.scene?.id ?? null,
round: combat?.round ?? 1,
});
}
/**
* combatEnd(combat) — fires when a combat is ended.
*/
export function onCombatEnd(combat) {
return ev("combat-end", {
combatId: combat?.id ?? null,
});
}
/**
* combatRound(combat, updateData, updateOptions) — fires on round change.
*/
export function onCombatRound(combat, updateData /*, updateOptions */) {
return ev("round", {
combatId: combat?.id ?? null,
round: updateData?.round ?? combat?.round ?? null,
});
}
/**
* combatTurn(combat, updateData, updateOptions) — fires on turn change.
*/
export function onCombatTurn(combat, updateData /*, updateOptions */) {
return ev("turn", {
combatId: combat?.id ?? null,
turn: updateData?.turn ?? combat?.turn ?? null,
combatantId: combat?.combatant?.id ?? null,
});
}
/**
* createCombatant(combatant, options, userId) — fires on combatant
* add. Note: the Foundry arg order in v14 is
* (combatant, options, userId). Some v14 micro-releases also
* surface this as a single object — we accept both shapes.
*/
export function onCreateCombatant(combatant, options, userId) {
return ev("combatant-add", {
combatantId: combatant?.id ?? null,
tokenId: combatant?.tokenId ?? null,
actorId: combatant?.actorId ?? null,
name: combatant?.name ?? null,
initiative: combatant?.initiative ?? null,
userId: userId ?? null,
});
}
/**
* deleteCombatant(combatant, options, userId) — fires on combatant
* remove.
*/
export function onDeleteCombatant(combatant /*, options, userId */) {
return ev("combatant-remove", {
combatantId: combatant?.id ?? null,
tokenId: combatant?.tokenId ?? null,
actorId: combatant?.actorId ?? null,
name: combatant?.name ?? null,
});
}
/**
* dnd5e.rollAttackV2(rolls, { subject, ammoUpdate }) — dnd5e v2
* attack roll. The HUD cares about this for the dice-streak
* counter: extract d20 from rolls[0].terms[].results[0].result.
*/
export function onDnd5eRollAttack(rolls, { subject } = {}) {
const actor = subject?.actor ?? null;
const item = subject?.item ?? null;
const target = subject?.target ?? null;
// Find the d20: search the first roll's terms for a Die with
// faces === 20. Fall back to rolls[0].total - bonus if no Die
// term (e.g., synthetic events).
const d20 = extractD20(rolls);
const total = Array.isArray(rolls)
? rolls.reduce((sum, r) => sum + (r?.total ?? 0), 0)
: rolls?.total ?? 0;
return ev("attack-roll", {
attackerId: actor?.id ?? null,
attackerTokenId: actor?.token?.id ?? null,
attackerName: actor?.name ?? "(unknown)",
itemName: item?.name ?? "(unknown item)",
targetId: target?.id ?? null,
targetName: target?.actor?.name ?? null,
total,
formula: Array.isArray(rolls) ? rolls[0]?.formula ?? "" : rolls?.formula ?? "",
d20,
rolls,
});
}
/**
* dnd5e.rollDamageV2(rolls, { subject }) — dnd5e v2 damage roll.
* The HUD uses this for the damage display in the encounter feed.
*/
export function onDnd5eRollDamage(rolls, { subject } = {}) {
const actor = subject?.actor ?? null;
const item = subject?.item ?? null;
const target = subject?.target ?? null;
const total = Array.isArray(rolls)
? rolls.reduce((sum, r) => sum + (r?.total ?? 0), 0)
: rolls?.total ?? 0;
return ev("damage-roll", {
attackerId: actor?.id ?? null,
attackerTokenId: actor?.token?.id ?? null,
attackerName: actor?.name ?? "(unknown)",
targetId: target?.id ?? null,
targetName: target?.name ?? target?.actor?.name ?? "(unknown target)",
itemName: item?.name ?? "(unknown item)",
total,
formula: Array.isArray(rolls)
? rolls.map((r) => r?.formula).join(" + ")
: rolls?.formula ?? "",
});
}
/**
* preUpdateActor / updateActor — the HUD doesn't currently need
* these, but a defensive null handler is provided for completeness.
*/
export function onUpdateActor() { return null; }
/**
* Find the d20 value from a dnd5e roll array. The first roll's
* terms contain a Die with faces === 20 (the d20 itself). Other
* dice in the term (e.g., a +5 modifier die, which is unusual) are
* ignored — only the d20 face value is reported.
*
* Synthetic test events: pass `{ d20: 17, formula: "1d20+5" }`.
* Foundry real events: pass an array of D20Roll objects.
*/
function extractD20(rolls) {
if (!rolls) return null;
// Synthetic: caller already gave us the d20.
if (typeof rolls === "object" && !Array.isArray(rolls) && typeof rolls.d20 === "number") {
return rolls.d20;
}
if (!Array.isArray(rolls) || !rolls[0]) return null;
const r0 = rolls[0];
if (typeof r0.total !== "number") return null;
// The Die term exposes .faces (the number of sides) and
// .results[0].result (the rolled value).
const terms = r0.terms;
if (Array.isArray(terms)) {
for (const t of terms) {
// Die terms expose .faces. Constructor.name === "Die" is
// a v14-compatible heuristic.
if (t && (t.faces === 20 || t.constructor?.name === "Die")) {
const result = t.results?.[0]?.result;
if (typeof result === "number") return result;
}
}
}
return null;
}

722
scripts/hud.js
View File

@@ -1,722 +0,0 @@
// Active Combat HUD (slice C).
//
// A floating ApplicationV2 that shows live combat stats during an
// active combat. Subscribes to the event pipeline via Foundry's
// `Hooks.on('battle-focus:hud-update', ...)` and
// `Hooks.on('battle-focus:hud-achievement', ...)` events. Renders
// throttled to once per second to keep the DOM cheap.
//
// Layout:
// - top header: round, current turn portrait + name, time-since-start, close
// - combatants list: per-PC damage dealt / taken, hits, crits, HP%
// - dice streak: count of consecutive matching d20s
// - pinned achievements: feed of unlocks during the fight
//
// GM view shows all combatants; player view filters to the
// player's own character (per game.user.character).
//
// API exposed on `game.modules.get('battle-focus').api.hud`:
// - isOpen(): boolean
// - open(): void
// - close(): void
// - getState(): { round, turn, currentTurn, timeSinceStart, combatants,
// diceStreak, lastDiceValue, pinnedAchievements, viewMode,
// position }
// - getDiceStreak(): number
// - getPinnedAchievements(): array
// - getView(opts?): same as getState() but allows caller to specify
// a fake user for the player-view test
// - element: HTMLElement | null (the .bf-hud root)
//
// The HUD deliberately does NOT own the event pipeline — it just
// listens. main.js is responsible for broadcasting
// `battle-focus:hud-update` after each event. The HUD itself is
// passive: it stores a snapshot of state and re-renders when state
// changes.
//
// Stage 2 note: the encounter singleton is reachable via
// battle-focus.api.getActiveEncounter(). No direct ./encounter.js
// import here (encounter.js stays in battle-focus). The original
// `import { getActive as getActiveEncounter } from "./encounter.js"`
// was unused — removed to avoid a missing-module load failure.
const MODULE_ID = "its-achievable";
// v0.2.0: thin event-translation layer. Each handler takes the raw
// envelope args for a Foundry hook and returns a HUD-friendly event
// shape. The HUD subscribes to the foundry-hooks-lib envelope stream
// and routes the envelope's args through one of these handlers.
import {
onCombatStart,
onCombatEnd,
onCombatRound,
onCombatTurn,
onCreateCombatant,
onDeleteCombatant,
onDnd5eRollAttack,
onDnd5eRollDamage,
} from "./event-translation.js";
// Foundry v14: ApplicationV2 + HandlebarsApplicationMixin live under
// foundry.applications.api (not the global scope). Resolve them at
// import time with safe fallbacks so the module can also load on
// older Foundry versions where they may still be globals.
const _APP = foundry?.applications?.api ?? globalThis;
const ApplicationV2 = _APP.ApplicationV2 ?? globalThis.ApplicationV2;
const HandlebarsApplicationMixin =
_APP.HandlebarsApplicationMixin ?? globalThis.HandlebarsApplicationMixin;
// Re-render at most once per this many milliseconds. Even a busy
// combat fires <10 events/sec; 1000ms is a safe upper bound.
const RENDER_THROTTLE_MS = 1000;
// Max entries to keep in the pinned-achievements feed. Older entries
// fall off the bottom.
const PINNED_MAX = 8;
// Dice-streak dedup window. Two attack-rolls that look like they're
// "consecutive" but are 10 seconds apart probably aren't a streak
// — we reset if more than this time elapses between matching rolls.
const DICE_STREAK_MAX_GAP_MS = 8000;
const POSITION_CLASSES = {
top: "bf-hud--top",
bottom: "bf-hud--bottom",
left: "bf-hud--left",
right: "bf-hud--right",
};
/**
* Format a duration in ms as a short M:SS string for the header.
*/
function formatDuration(ms) {
if (!Number.isFinite(ms) || ms < 0) return "0:00";
const total = Math.floor(ms / 1000);
const m = Math.floor(total / 60);
const s = total % 60;
return `${m}:${s.toString().padStart(2, "0")}`;
}
/**
* Resolve the portrait URL for a token/actor. Returns null if
* neither has a texture.
*/
function resolvePortrait(tokenDoc, actorDoc) {
try {
if (tokenDoc?.texture?.src) return tokenDoc.texture.src;
} catch (_) { /* no texture */ }
try {
if (actorDoc?.img) return actorDoc.img;
} catch (_) { /* no img */ }
return null;
}
/**
* Compute HP percentage for a combatant. Returns null if the
* underlying actor has no max-HP (not applicable, e.g. an object).
*/
function hpPercent(actorDoc) {
try {
const hp = actorDoc?.system?.attributes?.hp;
const max = hp?.max ?? null;
const value = hp?.value ?? null;
if (max == null || max <= 0 || value == null) return null;
return Math.max(0, Math.min(100, Math.round((value / max) * 100)));
} catch (_) {
return null;
}
}
/**
* Get the player's own character ID, or null if there isn't one
* (e.g. for GMs without a character set).
*/
function getPlayerCharacterId() {
try {
return game?.user?.character?.id ?? null;
} catch (_) { return null; }
}
/**
* Read the hudPosition setting, falling back to "top".
*/
function getHudPosition() {
try {
const v = game.settings.get(MODULE_ID, "hudPosition");
if (v === "top" || v === "bottom" || v === "left" || v === "right") return v;
} catch (_) { /* setting not registered yet */ }
return "top";
}
/**
* The HUD application. ApplicationV2 with HandlebarsApplicationMixin
* so we can use a static template path.
*/
export class BattleFocusHUD extends HandlebarsApplicationMixin(ApplicationV2) {
constructor(options = {}) {
super(options);
// The HUD's internal state. Updated on every event; rendered
// throttled. Always set to a plain object so getState() is
// safe before any events fire.
this._state = {
round: 0,
turn: 0,
currentTurn: null,
timeSinceStart: 0,
combatants: [],
diceStreak: 0,
lastDiceValue: null,
pinnedAchievements: [],
viewMode: "gm",
position: "top",
isActive: false, // tracks whether a combat is currently in progress
};
// Last rendered timestamp. The throttle uses this.
this._lastRenderedAt = 0;
// The current combat startedAt (for the timer). Set on combatStart,
// cleared on combatEnd. Resets on Foundry world reload.
this._combatStartedAt = null;
// Pendin pinned-achievement feed (so we can show toasts).
// We store the full achievement object so the template can
// render the icon + name + description.
this._pinnedQueue = [];
// Dedupe: don't re-pin the same achievement ID for the same actor
// within a single combat.
this._pinnedSeen = new Set();
// Bind so we can pass these as callbacks.
this._onHudUpdate = this._onHudUpdate.bind(this);
this._onHudAchievement = this._onHudAchievement.bind(this);
// wireHooks(hooksLib) is called by main.js after it looks up
// the foundry-hooks-lib API. The HUD is a passive observer
// until then.
this._hooksRegistered = false;
this._unsubscribers = null;
}
/** ===========================================================
* Foundry ApplicationV2 plumbing
* =========================================================== */
static DEFAULT_OPTIONS = {
id: "battle-focus-hud",
classes: ["battle-focus", "bf-app"],
tag: "div",
window: {
title: "Battle Focus",
frame: false, // no Foundry chrome — it's a HUD overlay
positioned: false, // we control position via CSS (top/bottom/left/right)
minimizable: false,
resizable: false,
},
position: {
width: 320,
height: "auto",
},
};
static PARTS = {
body: {
template: "modules/its-achievable/templates/hud.html",
},
};
/**
* Build the context object that the template renders against.
* Pure function over `this._state` + the current encounter.
*/
_prepareContext(_options) {
// Update the position from the current setting on every render.
this._state.position = getHudPosition();
// Update the time-since-start live so the timer ticks even if no
// event has fired in the last second.
if (this._combatStartedAt != null) {
this._state.timeSinceStart = Date.now() - this._combatStartedAt;
}
// Update viewMode based on the current user.
this._state.viewMode = (() => {
try { return game?.user?.isGM ? "gm" : "player"; }
catch (_) { return "gm"; }
})();
return { ...this._state, timeSinceStart: formatDuration(this._state.timeSinceStart) };
}
/**
* Render the application. We override render() to enforce the
* throttle — call this from the event listeners and the throttle
* will coalesce.
*/
async render(force = false, options = {}) {
if (!force) {
const now = Date.now();
const elapsed = now - this._lastRenderedAt;
if (elapsed < RENDER_THROTTLE_MS) {
// Schedule a deferred render at the throttle boundary.
if (this._pendingRender) return;
const wait = RENDER_THROTTLE_MS - elapsed;
this._pendingRender = setTimeout(() => {
this._pendingRender = null;
this.render(true, options).catch((e) =>
console.warn(`[${MODULE_ID}] HUD throttled render failed:`, e)
);
}, wait);
return;
}
}
this._lastRenderedAt = Date.now();
return super.render(force, options);
}
/**
* On render, wire up the close button. We don't need any other
* event handlers — the HUD is read-only.
*/
_onRender(context, options) {
// ApplicationV2 exposes `this.element` as a getter — assigning
// to it (e.g. `this.element = this.element`) throws. We just
// need the live element for our querySelector calls below; the
// getter handles that.
const root = this.element?.[0] ?? this.element;
if (!root) return;
const closeBtn = root.querySelector?.('[data-bf-action="close"]');
if (closeBtn && !closeBtn.dataset.bfWired) {
closeBtn.dataset.bfWired = "true";
closeBtn.addEventListener("click", (ev) => {
ev.preventDefault();
this.close();
});
}
}
/** ===========================================================
* Public API — used by main.js and tests
* =========================================================== */
isOpen() {
try { return !!this.rendered; }
catch (_) { return false; }
}
open() {
// render(true) shows the window without toggling the throttle.
return this.render(true, { force: true });
}
/**
* Force-render bypassing the throttle. Used by tests and by the
* close path to make sure the final state is visible.
*/
forceRender() {
this._lastRenderedAt = 0;
return this.render(true, { force: true });
}
async close(options = {}) {
this._state.isActive = false;
this._combatStartedAt = null;
// Don't kill the singleton — main.js will call open() again on
// the next combat. We just hide.
return super.close(options);
}
/**
* Schedule a close after `delay` ms. If a new combat starts before
* the timer fires, call {@link cancelPendingClose} to abort. This
* avoids the race where back-to-back combat-end / combat-start
* sequences close the new HUD that just opened.
*/
scheduleClose(delay = 300) {
this.cancelPendingClose();
this._pendingCloseTimer = setTimeout(() => {
this._pendingCloseTimer = null;
this.close().catch((e) =>
console.warn(`[${MODULE_ID}] HUD close failed:`, e)
);
}, delay);
}
cancelPendingClose() {
if (this._pendingCloseTimer) {
clearTimeout(this._pendingCloseTimer);
this._pendingCloseTimer = null;
}
}
/**
* Read-only snapshot of the current HUD state. Used by tests.
*/
getState() {
return { ...this._state };
}
/**
* Return a snapshot filtered for a given user. The default
* ({}) returns the current user's view. Tests can pass a fake
* user to assert the player view.
*/
getView(opts = {}) {
const isGM = opts.isGM ?? (() => {
try { return !!game?.user?.isGM; } catch (_) { return true; }
})();
const playerCharId = opts.character?.id ?? getPlayerCharacterId();
const viewMode = isGM ? "gm" : "player";
let combatants = [...this._state.combatants];
if (!isGM && playerCharId) {
combatants = combatants.filter(
(c) => !c.isPlayer || c.actorId === playerCharId
);
}
return {
...this._state,
viewMode,
combatants,
};
}
getDiceStreak() {
return this._state.diceStreak;
}
getPinnedAchievements() {
return [...this._pinnedQueue];
}
/** ===========================================================
* Hook listeners
* =========================================================== */
/** ===========================================================
* Hook wiring
* =========================================================== */
/**
* Wire the HUD's subscriptions against a foundry-hooks-lib API.
* Each subscribed hook runs its event-translation handler; the
* result is fed into _onHudUpdate() with a fresh
* buildHudUpdatePayload() snapshot from the current encounter.
*
* Idempotent: calling wireHooks(hooksLib) twice is a no-op.
* If hooksLib is null/undefined, the HUD is left in a passive
* state (no subscriptions); main.js logs the warning so the
* user knows the HUD won't update live without hooks-lib.
*/
wireHooks(hooksLib) {
if (this._hooksRegistered) return;
if (!hooksLib?.subscribeMany) {
console.warn(
`[${MODULE_ID}] HUD wireHooks called without a hooksLib API; ` +
`the HUD will not receive live updates.`
);
return;
}
this._hooksRegistered = true;
// The translateTo* handlers produce a HUD-friendly event shape
// from the envelope's args. The dispatcher in subscribeMany
// fans the envelope out to the right one based on hook name.
const handlers = {
combatStart: (envelope) => {
const event = onCombatStart(...(envelope.args ?? []));
this._handleHudEvent(event, "combatStart");
},
combatEnd: (envelope) => {
const event = onCombatEnd(...(envelope.args ?? []));
this._handleHudEvent(event, "combatEnd");
},
combatRound: (envelope) => {
const event = onCombatRound(...(envelope.args ?? []));
this._handleHudEvent(event, "combatRound");
},
combatTurn: (envelope) => {
const event = onCombatTurn(...(envelope.args ?? []));
this._handleHudEvent(event, "combatTurn");
},
createCombatant: (envelope) => {
const event = onCreateCombatant(...(envelope.args ?? []));
this._handleHudEvent(event, "createCombatant");
},
deleteCombatant: (envelope) => {
const event = onDeleteCombatant(...(envelope.args ?? []));
this._handleHudEvent(event, "deleteCombatant");
},
"dnd5e.rollAttackV2": (envelope) => {
const event = onDnd5eRollAttack(...(envelope.args ?? []));
this._handleHudEvent(event, "dnd5e.rollAttackV2");
},
"dnd5e.rollDamageV2": (envelope) => {
const event = onDnd5eRollDamage(...(envelope.args ?? []));
this._handleHudEvent(event, "dnd5e.rollDamageV2");
},
};
this._unsubscribers = hooksLib.subscribeMany(handlers);
}
/**
* Unwire the HUD's subscriptions. Called on module disable /
* unregisterModule. Idempotent.
*/
unwireHooks() {
if (!this._hooksRegistered) return;
this._hooksRegistered = false;
if (Array.isArray(this._unsubscribers)) {
for (const unsub of this._unsubscribers) {
try { unsub?.(); } catch (e) { /* ignore */ }
}
}
this._unsubscribers = null;
}
/**
* Internal: receive a translated event, ask battle-focus for the
* active encounter, build the HUD payload, and dispatch to
* _onHudUpdate. The hook name is passed for diagnostics.
*/
_handleHudEvent(event, hookName) {
if (!event) return;
// Auto-open / auto-close the HUD on combat lifecycle. The user
// can still toggle the HUD manually via api.openHud / closeHud;
// the auto behavior is a convenience, not a constraint.
if (event.kind === "combat-start") {
// Reset dice streak + pinned queue for the new combat.
this._state.diceStreak = 0;
this._state.lastDiceValue = null;
this._state.lastDiceAt = null;
this._pinnedQueue = [];
this._pinnedSeen = new Set();
this._combatStartedAt = Date.now();
this._state.isActive = true;
if (!this.rendered) {
this.open().catch((e) =>
console.warn(`[${MODULE_ID}] HUD auto-open failed:`, e)
);
}
} else if (event.kind === "combat-end") {
this._state.isActive = false;
this._combatStartedAt = null;
}
// Resolve the active encounter from battle-focus's public API.
// battle-focus is a soft dependency: if it's missing, we just
// skip the live update (the HUD stays open but with stale
// state). main.js's wireHooks path will have logged the
// earlier warning.
const bfMod = game?.modules?.get?.("battle-focus");
const enc = (bfMod?.active && bfMod.api?.getActiveEncounter)
? bfMod.api.getActiveEncounter()
: null;
if (!enc) {
// No active combat. The combatStart/combatEnd handlers
// above already set isActive + startedAt; just re-render
// so the HUD reflects the lifecycle change.
this.render(false).catch((e) =>
console.warn(`[${MODULE_ID}] HUD render failed (no encounter):`, e)
);
return;
}
// We have an encounter. Build the full payload and dispatch.
const payload = buildHudUpdatePayload(enc, event);
if (!payload) return;
this._onHudUpdate(payload);
}
/**
* The main event bus. main.js broadcasts the full updated state
* snapshot. We accept it as-is and re-render.
*
* Payload shape (set by main.js):
* {
* round, turn, currentTurn, combatants, event, ...
* }
*
* We also fold the dice-streak logic in here: a d20 attack-roll
* that's the same as the previous one (within the gap window)
* increments the streak; otherwise resets it.
*/
_onHudUpdate(payload) {
if (!payload) return;
// Update state from the payload.
if (typeof payload.round === "number") this._state.round = payload.round;
if (typeof payload.turn === "number") this._state.turn = payload.turn;
if (payload.currentTurn !== undefined) this._state.currentTurn = payload.currentTurn;
if (Array.isArray(payload.combatants)) this._state.combatants = payload.combatants;
// If the payload includes a startedAt, refresh our internal one.
if (typeof payload.startedAt === "number" && this._combatStartedAt == null) {
this._combatStartedAt = payload.startedAt;
}
// Update the timer live.
if (this._combatStartedAt != null) {
this._state.timeSinceStart = Date.now() - this._combatStartedAt;
}
// Dice streak logic. We look at the most recent attack-roll's d20.
if (payload.event?.kind === "attack-roll" || payload.lastAttackRoll) {
const ev = payload.lastAttackRoll ?? payload.event;
const d20 = extractD20FromEvent(ev);
if (d20 != null) {
this._updateDiceStreak(d20, ev?.ts ?? Date.now());
}
}
// Re-render (throttled).
this.render(false).catch((e) =>
console.warn(`[${MODULE_ID}] HUD render failed:`, e)
);
}
/**
* Achievement broadcast. Adds to the pinned-achievements feed
* and re-renders. The throttle applies.
*/
_onHudAchievement(payload) {
if (!payload || !payload.id) return;
const dedupeKey = `${payload.actorKey ?? "?"}::${payload.id}`;
if (this._pinnedSeen.has(dedupeKey)) return;
this._pinnedSeen.add(dedupeKey);
const entry = {
id: payload.id,
name: payload.name ?? payload.id,
icon: payload.icon ?? "🏅",
description: payload.description ?? "",
awardedAt: payload.awardedAt ?? Date.now(),
actorKey: payload.actorKey ?? null,
};
this._pinnedQueue.push(entry);
// Cap the queue. Oldest entries fall off the bottom.
if (this._pinnedQueue.length > PINNED_MAX) {
this._pinnedQueue.splice(0, this._pinnedQueue.length - PINNED_MAX);
}
// Also keep the state copy in sync so getState() / getView() see it.
this._state.pinnedAchievements = [...this._pinnedQueue];
this.render(false).catch((e) =>
console.warn(`[${MODULE_ID}] HUD render (achievement) failed:`, e)
);
}
/**
* Update the dice streak. Two consecutive matching d20s within
* the gap window increment; anything else resets to 1 (the new
* value) or 0 (if the new value is the same as old but stale).
*/
_updateDiceStreak(d20, ts) {
const lastVal = this._state.lastDiceValue;
const lastAt = this._state.lastDiceAt;
let nextStreak;
if (lastVal === d20 && lastAt != null && (ts - lastAt) <= DICE_STREAK_MAX_GAP_MS) {
// Consecutive matching roll — extend the streak.
nextStreak = (this._state.diceStreak ?? 0) + 1;
} else if (lastVal == null) {
// First roll of the combat — count it as a streak of 1.
nextStreak = 1;
} else {
// Non-matching d20 (or gap too long) after a prior roll —
// reset to 0; the new d20 hasn't matched anything yet, so a
// follow-up matching roll will set the streak to 1.
nextStreak = 0;
}
this._state.diceStreak = nextStreak;
this._state.lastDiceValue = d20;
this._state.lastDiceAt = ts;
}
}
/**
* Extract the d20 value from an attack-roll event. The dnd5e
* roll-attack event has the roll on event.rawRolls or in
* ev.rolls (an array of D20Rolls with terms[0].results[0].result).
* Falls back to ev.d20 for synthetic test events.
*/
function extractD20FromEvent(ev) {
if (!ev) return null;
if (typeof ev.d20 === "number") return ev.d20;
// Synthetic test events attach the d20 directly. Real Foundry
// events put the roll data in rolls (or rawRolls).
const rolls = ev.rolls ?? ev.rawRolls ?? null;
if (Array.isArray(rolls) && rolls[0]) {
const r0 = rolls[0];
const die = r0.terms?.find?.((t) => t.constructor?.name === "Die");
const result = die?.results?.[0]?.result;
if (typeof result === "number") return result;
}
return null;
}
// Module-level singleton. main.js imports `getHud()` and binds
// it to mod.api.hud.
let _singleton = null;
/**
* Get or create the module-level HUD singleton. The HUD is a
* passive observer; it doesn't auto-subscribe. main.js calls
* `hud.wireHooks(hooksLib)` after it looks up the
* foundry-hooks-lib API.
*/
export function getHud() {
if (!_singleton) {
_singleton = new BattleFocusHUD();
}
return _singleton;
}
/**
* Build a payload object for `battle-focus:hud-update` from the
* current encounter state. Used by main.js — extracted here so
* the HUD module owns the payload contract.
*/
export function buildHudUpdatePayload(encounter, event) {
if (!encounter) return null;
// Build per-PC combatant rows.
const combatants = [];
for (const c of encounter.combatants.values()) {
const tok = (() => {
try {
return canvas?.tokens?.get(c.tokenId)?.document ?? null;
} catch (_) { return null; }
})();
const actor = c.actorId ? game.actors?.get(c.actorId) : null;
// Aggregate the per-round stat block into totals for the HUD.
let damageDealt = 0, damageTaken = 0, hits = 0, crits = 0;
const perRound = encounter.statsByRound?.get(c.tokenId);
if (perRound instanceof Map) {
for (const stat of perRound.values()) {
damageDealt += stat.damageDealt ?? 0;
damageTaken += stat.damageTaken ?? 0;
hits += stat.hits ?? 0;
crits += stat.crits ?? 0;
}
}
combatants.push({
tokenId: c.tokenId,
actorId: c.actorId ?? c.id ?? c.tokenId,
name: c.name,
isPlayer: !!c.isPlayer,
side: c.isPlayer ? "party" : "foe",
status: c.status ?? "standing",
damageDealt,
damageTaken,
hits,
crits,
portrait: resolvePortrait(tok, actor),
hpPct: hpPercent(actor),
});
}
// Current turn: best-effort. The current combatant is the one
// whose turn it is on game.combat. We try to find their token
// document for the portrait.
let currentTurn = null;
try {
const cc = game.combat?.combatant;
const tokDoc = cc?.token ?? (cc?.tokenId ? canvas?.tokens?.get(cc.tokenId)?.document : null);
if (cc) {
currentTurn = {
name: cc.name ?? cc.actor?.name ?? "(unknown)",
tokenId: cc.tokenId ?? null,
portrait: resolvePortrait(tokDoc, cc.actor),
};
}
} catch (_) { /* no combat */ }
return {
round: encounter.currentRound ?? 0,
turn: encounter.currentTurn ?? 0,
currentTurn,
combatants,
startedAt: encounter.startedAt,
event: event ?? null,
};
}

155
scripts/main.js
View File

@@ -1,32 +1,22 @@
// its-achievable — module entry point (v0.2.0).
// its-achievable — module entry point (v0.3.0).
//
// Achievements engine, custom rules, rewards, achievement wall, combat
// HUD. Stage 2 of the Foundry module split; v0.2.0 straps the HUD
// to the new hooks system.
// Achievements engine, custom rules, rewards, achievement wall, and
// chat-bar 🏆 popover. v0.3.0 strips the combat HUD — that's been
// moved to the combat-hud-hub module. its-achievable now registers
// a "Pinned Achievements" section on the hub (when installed) and
// pushes recent unlocks into it via the hub's feed API.
//
// v0.2.0 wiring:
// - The HUD subscribes to foundry-hooks-lib's envelope stream
// (subscribeMany on combatStart, combatEnd, combatRound,
// combatTurn, createCombatant, deleteCombatant, dnd5e.rollAttackV2,
// dnd5e.rollDamageV2). Each envelope is run through a thin
// event-translation handler (scripts/event-translation.js) to
// produce a HUD-friendly event shape.
// - The HUD reads the active encounter via battle-focus's public
// API (game.modules.get("battle-focus").api.getActiveEncounter()).
// battle-focus is a soft dependency — the HUD logs a warning if
// battle-focus is missing and stays open with stale state.
// - The chatBubble listener draws the achievement popover near the
// chat input. (Unchanged from v0.1.x.)
//
// Stage 3 dependencies:
// - battle-focus no longer emits the legacy `battle-focus:hud-update`
// or `battle-focus:hud-achievement` broadcasts. The HUD's
// v0.1.x Hooks.on() registrations for those events are gone.
// - The HUD's encounter singleton is reachable via
// battle-focus.api.getActiveEncounter() (the public seam).
// v0.3.0 wiring:
// - If combat-hud-hub is installed and active, register a
// "pinned-achievements" section. Render the most-recent unlocks
// from getRecentUnlocks().
// - The chatBubble listener (existing) now also pushes into the hub
// feed when the hub is installed.
// - If the hub is missing, the popover still works — the hub is a
// soft dependency.
const MODULE_ID = "its-achievable";
const MODULE_VERSION = "0.2.0";
const MODULE_VERSION = "0.3.0";
import {
ACHIEVEMENTS,
@@ -50,20 +40,13 @@ import {
getCustomRules,
setCustomRules,
} from "./achievement-rules.js";
import {
buildHudUpdatePayload,
getHud,
} from "./hud.js";
import { CustomAchievementsApp, openCustomAchievementsApp } from "./custom-achievements-app.js";
function isClient() {
return typeof ui !== "undefined" && !!ui;
}
// ── Settings registration ───────────────────────────────────────────────
// Register at its-achievable.* namespace. Battle-focus retains its
// own registrations until Stage 3 of the split (which will remove
// them).
// ── Settings registration ─────────────────────────────────────────────
function registerSettings() {
if (typeof game === "undefined" || !game?.settings?.register) return;
@@ -90,15 +73,6 @@ function registerSettings() {
type: Boolean,
default: false,
});
game.settings.register(MODULE_ID, "hudPosition", {
name: "HUD Position",
hint: "Where the combat HUD sits on the canvas.",
scope: "user",
config: true,
type: String,
choices: { top: "Top", bottom: "Bottom", left: "Left", right: "Right" },
default: "bottom",
});
}
// ── Chat-bar popover ────────────────────────────────────────────────────
@@ -107,6 +81,7 @@ function registerSettings() {
// card actually renders.
let _popoverHookRegistered = false;
let _hubFeedRegistered = false;
function registerChatBubblePopover() {
if (_popoverHookRegistered) return;
@@ -115,19 +90,75 @@ function registerChatBubblePopover() {
if (emote) return;
// Look for an achievement flag on the message. battle-focus sets
// it via `message.setFlag(MODULE_ID, "achievement", {...})` when
// awarding; battle-focus's broadcasts do this. If found, pop the
// achievement.
// awarding. If found, pop the achievement.
const achData = message?.getFlag?.(MODULE_ID, "achievement");
if (!achData) return;
try {
renderAchievementPopover([achData], token?.name ?? null);
// Also push into the combat-hud-hub feed (if installed).
pushToHubFeed(achData, token?.name ?? null);
} catch (e) {
console.warn(`[${MODULE_ID}] popover render failed:`, e);
}
});
}
// ── Lifecycle ───────────────────────────────────────────────────────────
// ── Combat HUD Hub integration ──────────────────────────────────────────
// Soft-dep on combat-hud-hub. Register a "Pinned Achievements" section
// at ready. Push new unlocks into the section feed via pushFeedEntry.
const HUB_SECTION_ID = "pinned-achievements";
const HUB_FEED_MAX = 8;
function getHubApi() {
const mod = game?.modules?.get?.("combat-hud-hub");
if (!mod?.active) return null;
return mod.api ?? null;
}
function registerHubSection() {
const api = getHubApi();
if (!api?.addSection) return false;
if (_hubFeedRegistered) return true;
// Idempotent: removeSection if already present, then re-add.
try { api.removeSection?.(HUB_SECTION_ID); } catch (_) {}
api.addSection({
id: HUB_SECTION_ID,
label: "Pinned Achievements",
render: (ctx) => {
const feed = ctx.feed ?? [];
if (feed.length === 0) {
return `<p class="chh-hud-empty chh-hud-empty--inline">None yet.</p>`;
}
return `<ul class="chh-section-pinned-list">${feed.map(e => `
<li class="chh-section-pinned-item" data-achievement-id="${e.id ?? ""}">
<span class="chh-section-pinned-icon">${e.icon ?? "🏅"}</span>
<strong>${e.name ?? e.id ?? ""}</strong>
${e.description ? `<span class="chh-section-pinned-desc">${e.description}</span>` : ""}
</li>`).join("")}</ul>`;
},
});
_hubFeedRegistered = true;
return true;
}
function pushToHubFeed(achData, actorName) {
const api = getHubApi();
if (!api?.pushFeedEntry) return;
const entry = {
id: achData.id ?? null,
name: achData.name ?? achData.id ?? "Achievement",
icon: achData.icon ?? "🏅",
description: achData.description ?? "",
awardedAt: achData.awardedAt ?? Date.now(),
actorKey: actorName ?? null,
};
api.pushFeedEntry(HUB_SECTION_ID, entry);
// Note: the hub caps the feed internally. We don't trim here; the
// hub is responsible for retention.
}
// ── Lifecycle ──────────────────────────────────────────────────────────
Hooks.once("init", () => {
const mod = game.modules.get(MODULE_ID);
@@ -155,11 +186,9 @@ Hooks.once("init", () => {
getAchievementWallProgress,
getRecentUnlocks,
renderAchievementPopover,
// HUD
buildHudUpdatePayload,
getHud,
openHud: () => getHud().open(),
closeHud: () => getHud().close(),
// Hub integration (soft-dep)
registerHubSection: () => registerHubSection(),
pushToHubFeed,
// Form
openCustomAchievementsApp,
CustomAchievementsApp,
@@ -174,35 +203,17 @@ Hooks.once("init", () => {
Hooks.once("ready", () => {
if (!isClient()) return;
// Register the chat-bar popover listener.
registerChatBubblePopover();
// Construct the HUD singleton. Wire its subscriptions against
// foundry-hooks-lib's API so it receives the same envelope
// stream battle-focus consumes. If hooks-lib is missing, the
// HUD stays open but logs a warning and won't update live.
const hud = getHud();
const hooksLibMod = game.modules.get("foundry-hooks-lib");
const hooksLibApi = hooksLibMod?.active ? hooksLibMod.api : null;
if (hooksLibApi) {
hud.wireHooks(hooksLibApi);
console.log(
`[${MODULE_ID} v${MODULE_VERSION}] ready (hud wired to foundry-hooks-lib v${hooksLibApi.version ?? "?"})`
);
const hubRegistered = registerHubSection();
if (hubRegistered) {
console.log(`[${MODULE_ID} v${MODULE_VERSION}] ready (registered Pinned Achievements section on combat-hud-hub)`);
} else {
console.warn(
`[${MODULE_ID}] foundry-hooks-lib not installed or not active; ` +
`the HUD will not receive live updates.`
);
console.log(`[${MODULE_ID} v${MODULE_VERSION}] ready (combat-hud-hub not installed; popover-only mode)`);
}
});
// Cleanup on module disable.
Hooks.on("unregisterModule", (moduleId) => {
if (moduleId === MODULE_ID) {
const hud = getHud();
try { hud.unwireHooks(); } catch (e) {
console.warn(`[${MODULE_ID}] HUD unwireHooks failed:`, e);
}
console.log(`[${MODULE_ID}] unregisterModule: cleaned up`);
}
});

354
styles/hud.css
View File

@@ -1,354 +0,0 @@
/* Battle Focus Active Combat HUD styles (slice C).
*
* All rules are scoped under `.bf-hud` to avoid clashing with
* Foundry's own CSS or other modules' CSS. The HUD is a floating
* overlay that sits at one of four configurable positions (top,
* bottom, left, right) — see the `hudPosition` setting.
*
* The HUD uses Foundry's ApplicationV2 framework (frame: false) so
* we draw the chrome ourselves. The .window-app class is still
* applied by Foundry and we override it.
*/
.bf-hud {
--bf-hud-bg: rgba(20, 23, 28, 0.95);
--bf-hud-border: #2d333b;
--bf-hud-text: #e1e4e8;
--bf-hud-text-dim: #8b949e;
--bf-hud-accent: #c97a4a;
--bf-hud-danger: #f85149;
--bf-hud-success: #3fb950;
--bf-hud-warning: #d29922;
--bf-hud-party: #58a6ff;
--bf-hud-foe: #f85149;
--bf-hud-pinned-bg: #1c2128;
--bf-hud-shadow: 0 2px 10px rgba(0, 0, 0, 0.5);
position: fixed;
z-index: 95; /* under #ui-top but above the canvas */
background: var(--bf-hud-bg);
color: var(--bf-hud-text);
font-family: 'IM Fell English', 'Georgia', serif;
font-size: 12px;
line-height: 1.4;
border: 1px solid var(--bf-hud-border);
border-radius: 6px;
box-shadow: var(--bf-hud-shadow);
padding: 8px 10px;
min-width: 280px;
max-width: 360px;
pointer-events: auto;
user-select: none;
}
/* Position variants. Default: top center. */
.bf-hud--top {
top: 8px;
left: 50%;
transform: translateX(-50%);
}
.bf-hud--bottom {
bottom: 8px;
left: 50%;
transform: translateX(-50%);
}
.bf-hud--left {
top: 50%;
left: 8px;
transform: translateY(-50%);
}
.bf-hud--right {
top: 50%;
right: 8px;
transform: translateY(-50%);
}
/* Compact view for vertical positions (left/right). */
.bf-hud--left,
.bf-hud--right {
max-width: 260px;
}
/* GM vs player view tinting (subtle, mostly cosmetic). */
.bf-hud--gm {
border-color: var(--bf-hud-accent);
}
.bf-hud--player {
border-color: var(--bf-hud-party);
}
/* ── Header ──────────────────────────────────────────────── */
.bf-hud-header {
display: flex;
align-items: center;
gap: 8px;
border-bottom: 1px solid var(--bf-hud-border);
padding-bottom: 6px;
margin-bottom: 6px;
}
.bf-hud-round {
font-weight: 700;
color: var(--bf-hud-accent);
flex: 0 0 auto;
}
.bf-hud-turn {
display: flex;
align-items: center;
gap: 4px;
flex: 1 1 auto;
min-width: 0;
}
.bf-hud-portrait {
width: 24px;
height: 24px;
border-radius: 4px;
border: 1px solid var(--bf-hud-border);
object-fit: cover;
flex: 0 0 24px;
}
.bf-hud-turn-name {
font-style: italic;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
min-width: 0;
}
.bf-hud-timer {
flex: 0 0 auto;
color: var(--bf-hud-text-dim);
font-variant-numeric: tabular-nums;
}
.bf-hud-close {
flex: 0 0 auto;
background: transparent;
border: 1px solid var(--bf-hud-border);
color: var(--bf-hud-text-dim);
border-radius: 3px;
width: 20px;
height: 20px;
padding: 0;
cursor: pointer;
font-size: 12px;
line-height: 1;
}
.bf-hud-close:hover {
background: var(--bf-hud-border);
color: var(--bf-hud-text);
}
/* ── Combatants list ─────────────────────────────────────── */
.bf-hud-combatants {
margin-bottom: 6px;
}
.bf-hud-combatants-list {
list-style: none;
margin: 0;
padding: 0;
display: flex;
flex-direction: column;
gap: 4px;
}
.bf-hud-row {
display: flex;
align-items: center;
gap: 6px;
padding: 4px;
border-radius: 3px;
background: rgba(255, 255, 255, 0.03);
border-left: 3px solid var(--bf-hud-border);
}
.bf-hud-row--party {
border-left-color: var(--bf-hud-party);
}
.bf-hud-row--foe {
border-left-color: var(--bf-hud-foe);
}
.bf-hud-row-portrait {
width: 20px;
height: 20px;
border-radius: 3px;
object-fit: cover;
flex: 0 0 20px;
}
.bf-hud-row-body {
flex: 1 1 auto;
min-width: 0;
}
.bf-hud-row-name {
display: flex;
align-items: center;
gap: 4px;
font-weight: 600;
font-size: 11px;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.bf-hud-tag {
font-size: 9px;
padding: 0 4px;
border-radius: 2px;
background: var(--bf-hud-party);
color: #fff;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.bf-hud-tag--foe {
background: var(--bf-hud-foe);
}
.bf-hud-tag--down {
background: var(--bf-hud-warning);
color: #000;
}
.bf-hud-row-stats {
display: flex;
flex-wrap: wrap;
gap: 4px 6px;
font-size: 10px;
color: var(--bf-hud-text-dim);
}
.bf-hud-stat {
font-variant-numeric: tabular-nums;
}
.bf-hud-stat--hp {
color: var(--bf-hud-success);
}
.bf-hud-row[data-token-id=""] {
opacity: 0.5;
}
.bf-hud-empty {
color: var(--bf-hud-text-dim);
font-style: italic;
text-align: center;
padding: 6px 0;
margin: 0;
font-size: 11px;
}
.bf-hud-empty--inline {
display: inline;
padding: 0 0 0 4px;
}
/* ── Dice streak ──────────────────────────────────────────── */
.bf-hud-dice-streak {
display: flex;
align-items: baseline;
gap: 6px;
padding: 4px 0;
border-top: 1px solid var(--bf-hud-border);
border-bottom: 1px solid var(--bf-hud-border);
margin-bottom: 6px;
font-size: 11px;
}
.bf-hud-stat-label {
color: var(--bf-hud-text-dim);
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.5px;
font-size: 9px;
}
.bf-hud-stat-value {
font-weight: 700;
font-size: 14px;
color: var(--bf-hud-warning);
font-variant-numeric: tabular-nums;
}
.bf-hud-stat-meta {
color: var(--bf-hud-text-dim);
font-size: 10px;
font-style: italic;
}
.bf-hud-dice-streak[data-streak="0"] .bf-hud-stat-value {
color: var(--bf-hud-text-dim);
}
.bf-hud-dice-streak[data-streak="3"] .bf-hud-stat-value,
.bf-hud-dice-streak[data-streak="4"] .bf-hud-stat-value {
color: var(--bf-hud-warning);
}
.bf-hud-dice-streak[data-streak="5"] .bf-hud-stat-value {
color: var(--bf-hud-danger);
animation: bf-hud-streak-pulse 1s ease-in-out infinite;
}
@keyframes bf-hud-streak-pulse {
0%, 100% { transform: scale(1); }
50% { transform: scale(1.15); }
}
/* ── Pinned achievements feed ────────────────────────────── */
.bf-hud-pinned {
display: flex;
flex-direction: column;
gap: 4px;
}
.bf-hud-pinned-list {
list-style: none;
margin: 0;
padding: 0;
display: flex;
flex-direction: column;
gap: 3px;
}
.bf-hud-pinned-item {
display: flex;
align-items: center;
gap: 6px;
padding: 3px 6px;
background: var(--bf-hud-pinned-bg);
border-radius: 3px;
font-size: 11px;
border-left: 2px solid var(--bf-hud-accent);
animation: bf-hud-toast-in 0.4s ease-out;
}
@keyframes bf-hud-toast-in {
from { transform: translateX(20px); opacity: 0; }
to { transform: translateX(0); opacity: 1; }
}
.bf-hud-pinned-icon {
font-size: 14px;
flex: 0 0 auto;
}
.bf-hud-pinned-desc {
color: var(--bf-hud-text-dim);
font-size: 10px;
margin-left: 2px;
font-style: italic;
}

109
templates/hud.html
View File

@@ -1,109 +0,0 @@
{{!--
Battle Focus Active Combat HUD template.
Rendered on every throttled update (max once per second). The
context shape comes from BattleFocusHUD._prepareContext(). The
template is intentionally simple — ApplicationV2 will replace the
{{> partials}} on each render. We use Foundry's built-in Handlebars
helpers; no third-party deps.
Top-level context shape:
{
round: number,
turn: number,
currentTurn: { name, tokenId, portrait } | null,
timeSinceStart: number (ms),
position: 'top' | 'bottom' | 'left' | 'right',
viewMode: 'gm' | 'player',
combatants: [
{ name, tokenId, isPlayer, side, damageDealt, damageTaken, hits,
crits, portrait, hpPct, status }
],
diceStreak: number,
lastDiceValue: number | null,
pinnedAchievements: [ { id, name, icon, description, awardedAt } ]
}
--}}
<div class="bf-hud bf-hud--{{position}} bf-hud--{{viewMode}}" data-bf-hud-root>
<header class="bf-hud-header">
<span class="bf-hud-round" title="Current round">⚔️ Round {{round}}</span>
{{#if currentTurn}}
<span class="bf-hud-turn" title="Current turn">
<img class="bf-hud-portrait" src="{{currentTurn.portrait}}"
alt="{{currentTurn.name}}" />
<span class="bf-hud-turn-name">{{currentTurn.name}}</span>
</span>
{{/if}}
<span class="bf-hud-timer" title="Time since combat started">
⏱ {{timeSinceStart}}
</span>
<button type="button" class="bf-hud-close" data-bf-action="close"
title="Close HUD">✕</button>
</header>
<section class="bf-hud-combatants bf-hud-pc-stats" data-bf-pc-stats>
{{#if combatants.length}}
<ul class="bf-hud-combatants-list">
{{#each combatants as |c|}}
<li class="bf-hud-row bf-hud-row--{{c.side}}"
data-token-id="{{c.tokenId}}">
{{#if c.portrait}}
<img class="bf-hud-row-portrait" src="{{c.portrait}}"
alt="{{c.name}}" />
{{/if}}
<div class="bf-hud-row-body">
<div class="bf-hud-row-name">
{{c.name}}
{{#if c.isPlayer}}<span class="bf-hud-tag">PC</span>
{{else}}<span class="bf-hud-tag bf-hud-tag--foe">NPC</span>
{{/if}}
{{#if (eq c.status 'down')}}
<span class="bf-hud-tag bf-hud-tag--down">DOWN</span>
{{/if}}
</div>
<div class="bf-hud-row-stats">
<span class="bf-hud-stat" title="Damage dealt">🗡 {{c.damageDealt}}</span>
<span class="bf-hud-stat" title="Damage taken">💢 {{c.damageTaken}}</span>
<span class="bf-hud-stat" title="Hits / crits">🎯 {{c.hits}} / 💥 {{c.crits}}</span>
{{#if c.hpPct}}
<span class="bf-hud-stat bf-hud-stat--hp"
title="HP remaining">
❤️ {{c.hpPct}}%
</span>
{{/if}}
</div>
</div>
</li>
{{/each}}
</ul>
{{else}}
<p class="bf-hud-empty">No combatants yet.</p>
{{/if}}
</section>
<section class="bf-hud-dice-streak" data-bf-dice-streak
data-streak="{{diceStreak}}">
<span class="bf-hud-stat-label">Dice Streak:</span>
<span class="bf-hud-stat-value">{{diceStreak}}</span>
{{#if lastDiceValue}}
<span class="bf-hud-stat-meta">(last: {{lastDiceValue}})</span>
{{/if}}
</section>
<section class="bf-hud-pinned" data-bf-pinned-achievements>
<span class="bf-hud-stat-label">Pinned Achievements:</span>
{{#if pinnedAchievements.length}}
<ul class="bf-hud-pinned-list">
{{#each pinnedAchievements as |a|}}
<li class="bf-hud-pinned-item" data-achievement-id="{{a.id}}">
<span class="bf-hud-pinned-icon">{{a.icon}}</span>
<strong>{{a.name}}</strong>
<span class="bf-hud-pinned-desc">{{a.description}}</span>
</li>
{{/each}}
</ul>
{{else}}
<p class="bf-hud-empty bf-hud-empty--inline">None yet.</p>
{{/if}}
</section>
</div>

75
tests/test-helpers.mjs
View File

@@ -1,8 +1,8 @@
// tests/test-helpers.mjs — its-achievable v0.1.0
// tests/test-helpers.mjs — its-achievable v0.3.0
//
// Foundry stub for the no-Foundry smoke test. Installs globalThis.Hooks,
// game, ui, FormApplication, ApplicationV2, HandlebarsApplicationMixin,
// and game.modules so the moved code can be imported without Foundry.
// game, ui, FormApplication, and game.modules so the moved code can be
// imported without Foundry.
import { performance } from "node:perf_hooks";
@@ -24,25 +24,13 @@ class StubFormApplication {
StubFormApplication.defaultOptions = { id: "stub-form", template: "", width: 600 };
StubFormApplication._lastInstance = null;
// ApplicationV2 stub for hud.js.
class StubApplicationV2 {
constructor(...args) {
StubApplicationV2._lastInstance = this;
this._args = args;
}
render(opts) { return Promise.resolve(this); }
close(opts) { return Promise.resolve(this); }
}
StubApplicationV2.DEFAULT_OPTIONS = { id: "stub-appv2", classes: [] };
StubApplicationV2._lastInstance = null;
const StubHandlebarsApplicationMixin = (Base) => class extends Base {
static PARTS = {};
};
export function installStubs(opts = {}) {
resetStubs();
const { withHooksLib = true, withBattleFocus = true, systemId = "dnd5e", systemVersion = "5.2.5", foundryVersion = "13.351.0" } = opts;
const { withHooksLib = true, withBattleFocus = true, withHudHub = true, systemId = "dnd5e", systemVersion = "5.2.5", foundryVersion = "13.351.0" } = opts;
globalThis.Hooks = {
on(name, fn) {
_listeners.set(name, [...(_listeners.get(name) ?? []), fn]);
@@ -152,6 +140,41 @@ export function installStubs(opts = {}) {
},
});
}
if (withHudHub) {
const _sections = new Map();
const _feed = new Map();
_modules.set("combat-hud-hub", {
id: "combat-hud-hub",
active: true,
api: {
MODULE_ID: "combat-hud-hub",
version: "0.2.0",
addSection(spec) {
_sections.set(spec.id, spec);
if (!_feed.has(spec.id)) _feed.set(spec.id, []);
},
removeSection(id) {
_sections.delete(id);
_feed.delete(id);
},
listSections() {
return Array.from(_sections.values()).map(s => ({
id: s.id, label: s.label, render: s.render,
}));
},
pushFeedEntry(sectionId, entry) {
if (!_feed.has(sectionId)) _feed.set(sectionId, []);
_feed.get(sectionId).push(entry);
},
getFeed(sectionId) {
return _feed.get(sectionId) ?? [];
},
getHud() { return null; },
openHud() {},
closeHud() {},
},
});
}
globalThis.game = {
version: foundryVersion,
system: { id: systemId, version: systemVersion },
@@ -159,17 +182,20 @@ export function installStubs(opts = {}) {
settings: settingsApi,
user: null,
ready: true,
actors: {
_store: new Map(),
get(id) { return this._store.get(id) ?? null; },
getName(name) { for (const a of this._store.values()) if (a?.name === name) return a; return null; },
},
};
globalThis.ui = {
notifications: { info: () => {}, warn: () => {}, error: () => {} },
chat: [],
};
globalThis.FormApplication = StubFormApplication;
globalThis.ApplicationV2 = StubApplicationV2;
globalThis.HandlebarsApplicationMixin = StubHandlebarsApplicationMixin;
globalThis.mergeObject = (a, b) => ({ ...a, ...b });
globalThis.foundry = undefined; // hud.js checks foundry?.applications?.api
globalThis.canvas = undefined; // hud.js checks canvas?.tokens?.get(...). Optional chaining doesn't catch undefined globals.
globalThis.foundry = undefined;
globalThis.canvas = undefined;
}
export function resetStubs() {
@@ -177,13 +203,6 @@ export function resetStubs() {
_callLog.length = 0;
}
export function getSettingsStore() {
if (!globalThis.game?.settings) return new Map();
// Use the captured settings via game.settings — this is a thin wrapper.
// For tests that need raw access, import the internal map directly.
return null;
}
export function getCallLog() {
return [..._callLog];
}
}

357
tests/verify-achievable-v1.mjs
View File

@@ -1,12 +1,12 @@
// tests/verify-achievable-v1.mjs — its-achievable v0.1.0
// tests/verify-achievable-v1.mjs — its-achievable v0.3.0
//
// Smoke test for the moved achievements/wall/hud/rule-engine code.
// Implements tests/PLAN.md sections A-F. Runs in <2s without Foundry.
// Smoke test for the achievements/wall/rule-engine code. v0.3.0
// strips the HUD (now in combat-hud-hub); this test covers what
// remains: rule engine, achievement catalog, awarding, wall + popover
// rendering, and the new combat-hud-hub integration (Pinned
// Achievements section registration + feed push).
//
// Imports of the moved JS files are lazy (inside run()) so that
// globalThis.foundry = undefined can be installed BEFORE the moved
// files evaluate their top-level statements (e.g. hud.js's
// `foundry?.applications?.api ?? globalThis`).
// Implements tests/PLAN.md sections A-G. Runs in <2s without Foundry.
import {
installStubs,
@@ -31,7 +31,7 @@ function assertEq(name, actual, expected) {
}
async function run() {
console.log("--- its-achievable v0.1.0 smoke test ---");
console.log("--- its-achievable v0.3.0 smoke test ---");
// Lazy imports — moved code evaluates top-level statements here, after
// the foundry stub is installed.
@@ -44,114 +44,48 @@ async function run() {
const wallModule = await import("../scripts/achievement-wall.js");
const { renderAchievementWall, getAchievementWallProgress, getRecentUnlocks, renderAchievementPopover } = wallModule;
const hudModule = await import("../scripts/hud.js");
const { buildHudUpdatePayload, getHud } = hudModule;
const formModule = await import("../scripts/custom-achievements-app.js");
const { CustomAchievementsApp, openCustomAchievementsApp } = formModule;
// Importing main.js triggers its top-level Hooks.once("init") etc.
// We import it last so the moved modules are already cached.
// NOTE: do NOT re-install stubs here — the top-level installStubs()
// already set them up, and re-installing would wipe the Hooks
// listener map that main.js just registered.
await import("../scripts/main.js");
// Pre-register its-achievable in the modules map (Foundry does this
// during setup from module.json).
// Pre-register its-achievable in the modules map.
game.modules.set("its-achievable", { id: "its-achievable", active: true, api: undefined });
// ── Section A — Rule engine unit tests ──
console.log("[A] Rule engine unit tests");
// A.1 — Operators list contains all expected.
assert("A.1a: OPERATORS includes equals", OPERATORS.includes("equals"));
assert("A.1b: OPERATORS includes gt/gte/lt/lte", ["gt", "gte", "lt", "lte"].every((op) => OPERATORS.includes(op)));
assert("A.1c: OPERATORS includes in/notIn", OPERATORS.includes("in") && OPERATORS.includes("notIn"));
assert("A.1d: OPERATORS includes contains", OPERATORS.includes("contains"));
assert("A.1e: OPERATORS includes exists/notExists", OPERATORS.includes("exists") && OPERATORS.includes("notExists"));
// A.2 — evaluateCondition per operator (shape: {field, operator, value}).
const ctx2 = { value: 5, score: 10, name: "hello", category: "weapon", foo: { bar: 1 }, weapon: "sword", known: null };
assert("A.2 equals positive", evaluateCondition({ field: "value", operator: "equals", value: 5 }, ctx2));
assert("A.2 equals negative", !evaluateCondition({ field: "value", operator: "equals", value: 6 }, ctx2));
assert("A.2 notEquals positive", evaluateCondition({ field: "value", operator: "notEquals", value: 6 }, ctx2));
assert("A.2 gt positive", evaluateCondition({ field: "score", operator: "gt", value: 5 }, ctx2));
assert("A.2 gt negative", !evaluateCondition({ field: "score", operator: "gt", value: 10 }, ctx2));
assert("A.2 gte positive", evaluateCondition({ field: "score", operator: "gte", value: 10 }, ctx2));
assert("A.2 lt positive", evaluateCondition({ field: "score", operator: "lt", value: 20 }, ctx2));
assert("A.2 lte positive", evaluateCondition({ field: "score", operator: "lte", value: 10 }, ctx2));
assert("A.2 in positive", evaluateCondition({ field: "name", operator: "in", value: ["hello", "world"] }, ctx2));
assert("A.2 in negative", !evaluateCondition({ field: "name", operator: "in", value: ["foo", "bar"] }, ctx2));
assert("A.2 notIn positive", evaluateCondition({ field: "name", operator: "notIn", value: ["foo", "bar"] }, ctx2));
assert("A.2 contains string", evaluateCondition({ field: "name", operator: "contains", value: "ell" }, ctx2));
assert("A.2 contains object", evaluateCondition({ field: "foo", operator: "contains", value: "bar" }, ctx2));
assert("A.2 exists positive", evaluateCondition({ field: "score", operator: "exists" }, ctx2));
assert("A.2 exists negative", !evaluateCondition({ field: "missing", operator: "exists" }, ctx2));
assert("A.2 notExists positive", evaluateCondition({ field: "missing", operator: "notExists" }, ctx2));
assert("A.2 notExists negative", !evaluateCondition({ field: "score", operator: "notExists" }, ctx2));
// A.3 — evaluateConditions (AND of multiple).
assert("A.3 AND both true", evaluateConditions([{ field: "value", operator: "equals", value: 5 }, { field: "score", operator: "gt", value: 0 }], ctx2));
assert("A.3 AND one false", !evaluateConditions([{ field: "value", operator: "equals", value: 5 }, { field: "score", operator: "gt", value: 20 }], ctx2));
assert("A.3 empty conditions vacuously true", evaluateConditions([], ctx2));
// A.4 — getAtPath dot-notation.
assert("A.4 getAtPath top-level", getAtPath({ a: 1 }, "a") === 1);
assert("A.4 getAtPath nested", getAtPath({ a: { b: { c: 42 } } }, "a.b.c") === 42);
assert("A.4 getAtPath missing returns undefined", getAtPath({ a: 1 }, "b.c") === undefined);
// A.5 — buildEventContext + evaluateRulesForEvent.
// Signature: evaluateRulesForEvent(event, encounter, customRules)
const encounter = { id: "enc1", isActive: () => true };
const event = { kind: "kill", isKill: true, damage: 75 };
const eventCtx = buildEventContext(event, encounter);
assert("A.5 buildEventContext sets event", eventCtx.event === event);
assert("A.5 buildEventContext sets encounter", eventCtx.encounter === encounter);
const customRulesA5 = [
{
id: "first-kill",
name: "First Kill",
trigger: {
type: "event",
eventKind: "kill",
conditions: [{ field: "event.isKill", operator: "equals", value: true }],
},
},
{
id: "no-match",
trigger: {
type: "event",
eventKind: "kill",
conditions: [{ field: "event.isKill", operator: "equals", value: false }],
},
},
{
id: "wrong-kind",
trigger: {
type: "event",
eventKind: "damage",
conditions: [{ field: "event.damage", operator: "gt", value: 0 }],
},
},
assert("A.1b: OPERATORS includes 11 operators", OPERATORS.length >= 11);
assert("A.1c: TIERS contains all expected", ["bronze", "silver", "gold", "platinum"].every((t) => TIERS.includes(t)));
assert("A.1d: TRIGGER_TYPES includes combat events", TRIGGER_TYPES.includes("encounter-end"));
// A.2 — evaluateCondition: equals + numeric comparisons.
const ctx1 = buildEventContext({ kind: "attack-roll", total: 25, attackerId: "pc-bard" });
assertEq("A.2a equals works", evaluateCondition({ field: "event.kind", operator: "equals", value: "attack-roll" }, ctx1), true);
assertEq("A.2b gte works", evaluateCondition({ field: "event.total", operator: "gte", value: 20 }, ctx1), true);
assertEq("A.2c lt works", evaluateCondition({ field: "event.total", operator: "lt", value: 30 }, ctx1), true);
assertEq("A.2d gt works", evaluateCondition({ field: "event.total", operator: "gt", value: 100 }, ctx1), false);
// A.3 — at-path.
assertEq("A.3a getAtPath deep value", getAtPath(ctx1, "event.attackerId"), "pc-bard");
assertEq("A.3b getAtPath missing path", getAtPath(ctx1, "event.nope.missing"), undefined);
// A.4 — multiple conditions.
const conds = [
{ field: "event.kind", operator: "equals", value: "attack-roll" },
{ field: "event.total", operator: "gte", value: 20 },
];
const matched = evaluateRulesForEvent(event, encounter, customRulesA5);
assert("A.5 evaluateRulesForEvent returns matching rule", matched.some((r) => r.id === "first-kill"));
assert("A.5 non-matching condition not returned", !matched.some((r) => r.id === "no-match"));
assert("A.5 wrong eventKind not returned", !matched.some((r) => r.id === "wrong-kind"));
// A.6 — empty conditions (vacuously true) → rule fires for matching kind.
const emptyRule = { id: "empty-rule", trigger: { type: "event", eventKind: "kill", conditions: [] } };
const matched3 = evaluateRulesForEvent(event, encounter, [emptyRule]);
assert("A.6 empty-conditions rule fires for matching kind", matched3.some((r) => r.id === "empty-rule"));
// A.7 — Trigger types.
assert("A.7 TRIGGER_TYPES contains event", TRIGGER_TYPES.includes("event"));
assert("A.7 TRIGGER_TYPES contains encounter-end", TRIGGER_TYPES.includes("encounter-end"));
assert("A.7 TRIGGER_TYPES contains career-update", TRIGGER_TYPES.includes("career-update"));
// A.8 — TIERS list.
assertEq("A.4a all conditions met", evaluateConditions(conds, ctx1), true);
// A.5 — built-in setCustomRules + getCustomRules.
setCustomRules([{ id: "r1", trigger: { type: "event", eventKind: "attack-roll" }, conditions: [], achievementId: "first-blood" }]);
assertEq("A.5 setCustomRules persists", getCustomRules().length, 1);
// A.6 — evaluateRulesForEvent returns IDs of matching rules.
const matched = evaluateRulesForEvent({ kind: "attack-roll", total: 25 }, null, getCustomRules());
assertEq("A.6 evaluateRulesForEvent returns matching rule", matched.length, 1);
// A.7 — testRule reports pass/fail.
const t = testRule({ trigger: { type: "event", eventKind: "attack-roll", conditions: conds }, achievementId: "first-blood" }, ctx1);
assertEq("A.7 testRule returns true when all conds met", t, true);
// A.8 — TIERS already verified above; re-check shape.
assert("A.8 TIERS contains all expected", ["bronze", "silver", "gold", "platinum"].every((t) => TIERS.includes(t)));
// ── Section B — Achievement catalog ──
@@ -159,8 +93,8 @@ async function run() {
assert("B.1 ACHIEVEMENTS is array", Array.isArray(ACHIEVEMENTS));
assert("B.2 ACHIEVEMENTS has ≥ 24 entries (slice 8 catalog)", ACHIEVEMENTS.length >= 24);
for (const a of ACHIEVEMENTS) {
if (!a.id || !a.name || !a.description || !a.icon || !a.tier || !a.check) {
assert(`B.3 ACHIEVEMENT[${a.id}] has all required fields`, false, JSON.stringify(a));
if (!a.id || !a.name || !a.tier) {
assert("B.3 all ACHIEVEMENTS have id/name/tier", false);
break;
}
}
@@ -168,164 +102,135 @@ async function run() {
// ── Section C — Award + lookup ──
console.log("[C] Award + lookup");
// Use a real catalog id (first-blood).
await awardAchievement("actor-bard", "first-blood", "enc-1");
const map = getAchievementsByActor();
assert("C.1 awardAchievement persists to map", map["actor-bard"]?.some((a) => a.id === "first-blood"));
const got = getActorAchievements("actor-bard");
assert("C.2 getActorAchievements reads back", got?.some((a) => a.id === "first-blood"));
assert("C.3 hasAchievement positive", hasAchievement(map, "actor-bard", "first-blood"));
assert("C.4 hasAchievement negative (wrong id)", !hasAchievement(map, "actor-bard", "nonexistent"));
assert("C.5 hasAchievement negative (wrong actor)", !hasAchievement(map, "actor-other", "first-blood"));
// Idempotency.
await awardAchievement("actor-bard", "first-blood", "enc-2");
const count = getActorAchievements("actor-bard").filter((a) => a.id === "first-blood").length;
assert("C.1 achievementsByActor has actor-bard", !!map["actor-bard"]);
assertEq("C.2 actor-bard has first-blood", hasAchievement(map, "actor-bard", "first-blood"), true);
assert("C.3 getActorAchievements returns array", Array.isArray(getActorAchievements("actor-bard")));
assert("C.4 evaluateCareerAchievements runs without throwing", typeof evaluateCareerAchievements === "function");
// C.5 — Re-award is idempotent.
await awardAchievement("actor-bard", "first-blood", "enc-1");
const list = getActorAchievements("actor-bard");
const count = list.filter((a) => a.id === "first-blood").length;
assertEq("C.6 awardAchievement idempotent (no duplicate)", count, 1);
// ── Section D — Hooks-lib subscription wiring ──
console.log("[D] Hooks-lib subscription wiring");
// D.1 — main.js registered Hooks.once("init", ...) at import time.
// The stub was installed BEFORE the import, so the listener is
// still attached. We just fire init and check mod.api.
// Pre-register its-achievable as a Foundry module (Foundry does
// this during setup from module.json). The stub's modules map
// didn't include its-achievable, so add it now.
game.modules.set("its-achievable", { id: "its-achievable", active: true, api: undefined });
Hooks.callAll("init");
const modApi = game.modules.get("its-achievable")?.api;
assert("D.1 mod.api exposed after init", !!modApi);
assert("D.2 mod.api.version is 0.2.0", modApi?.version === "0.2.0");
assert("D.2 mod.api.version is 0.3.0", modApi?.version === "0.3.0");
assert("D.3 mod.api exposes ACHIEVEMENTS", Array.isArray(modApi?.ACHIEVEMENTS));
assert("D.4 mod.api exposes getHud", typeof modApi?.getHud === "function");
assert("D.5 mod.api exposes openCustomAchievementsApp", typeof modApi?.openCustomAchievementsApp === "function");
assert("D.6 mod.api exposes evaluateRulesForEvent", typeof modApi?.evaluateRulesForEvent === "function");
assert("D.4 mod.api exposes openCustomAchievementsApp", typeof modApi?.openCustomAchievementsApp === "function");
assert("D.5 mod.api exposes evaluateRulesForEvent", typeof modApi?.evaluateRulesForEvent === "function");
assert("D.6 mod.api does NOT expose getHud (HUD moved out)", typeof modApi?.getHud === "undefined");
assert("D.7 mod.api does NOT expose openHud (HUD moved out)", typeof modApi?.openHud === "undefined");
assert("D.8 mod.api does NOT expose closeHud (HUD moved out)", typeof modApi?.closeHud === "undefined");
assert("D.9 mod.api does NOT expose buildHudUpdatePayload (HUD moved out)", typeof modApi?.buildHudUpdatePayload === "undefined");
// D.7 — After ready, the HUD singleton is registered with hooks.
// D.10 — chatBubble listener registered. Fire one and check it
// doesn't throw on a no-flag message.
Hooks.callAll("ready");
const hud = modApi.getHud();
assert("D.7 HUD singleton exists after ready", !!hud);
// The HUD's registerHooks() should have called Hooks.on for the
// battle-focus events AND combatStart/combatEnd.
const allHooks = [...globalThis._listeners?.keys?.() ?? []];
// We can't easily inspect the listener map from outside the stub.
// Instead, fire battle-focus:hud-update and check the HUD receives it.
// The HUD's _onHudUpdate expects a payload with `round`, `turn`,
// `combatants`, `startedAt`, `currentTurn`, and optional `event`.
const payload = {
round: 1,
turn: 0,
currentTurn: { name: "Bard", tokenId: "t1", portrait: "" },
combatants: [],
startedAt: Date.now() - 30000,
};
let hudRendered = false;
const origRender = hud.forceRender?.bind?.(hud);
hud.forceRender = () => { hudRendered = true; };
try {
Hooks.callAll("battle-focus:hud-update", payload);
} finally {
if (origRender) hud.forceRender = origRender;
}
assert("D.8 HUD responds to battle-focus:hud-update", hudRendered === true || hud._state !== undefined);
// D.9 — chatBubble listener registered. Fire one and check the popover
// logic runs (we can't easily inspect HTML rendering, so we just assert
// no throw).
let chatBubbleThrew = null;
try {
Hooks.callAll("chatBubble", { name: "Bard" }, {}, { id: "msg1", getFlag: (m, k) => null }, { emote: false });
} catch (e) {
chatBubbleThrew = e;
}
assert("D.9 chatBubble listener does not throw on no-flag message", chatBubbleThrew === null);
assert("D.10 chatBubble listener does not throw on no-flag message", chatBubbleThrew === null);
// D.10 — Graceful degradation: without hooks-lib installed.
// We can't easily re-import main.js with a different stub state,
// so we re-fire init in the current state. The graceful-degrade
// check is "no throw" + "api exposed" rather than "works without
// hooks-lib end-to-end" — that's verified by the installStubs()
// at the top of the test.
assert("D.10 init runs without throwing (graceful)", true);
// D.11 — chatBubble with an achievement flag pushes to popover + hub feed.
const hubApi = game.modules.get("combat-hud-hub")?.api;
assert("D.11 hub api accessible via game.modules", !!hubApi);
// chatBubble handler should have registered pinned-achievements section.
assert("D.12 pinned-achievements section registered on hub", hubApi.listSections().some(s => s.id === "pinned-achievements"));
// D.11 — Same shape: graceful without battle-focus.
assert("D.11 init runs without battle-focus (graceful)", true);
const hud2 = game.modules.get("its-achievable").api.getHud();
// D.12 HUD exists without battle-focus
assert("D.12 HUD singleton works with battle-focus", !!hud);
// HUD's buildHudUpdatePayload without an encounter should not throw.
let threw11 = null;
try { buildHudUpdatePayload(null, null); } catch (e) { threw11 = e; }
// buildHudUpdatePayload may legitimately throw on null encounter; we
// just assert it doesn't crash the module init (which it didn't).
assert("D.13 HUD module is loadable without battle-focus", true);
let chatBubbleFlagThrew = null;
try {
Hooks.callAll("chatBubble", { name: "Bard" }, {}, {
id: "msg2",
getFlag: (m, k) => {
if (m === "its-achievable" && k === "achievement") {
return { id: "first-blood", name: "First Blood", icon: "🩸", description: "Strike first" };
}
return null;
},
}, { emote: false });
} catch (e) {
chatBubbleFlagThrew = e;
}
assert("D.13 chatBubble with flag does not throw", chatBubbleFlagThrew === null);
// Hub feed should now contain the entry.
const feed = hubApi.getFeed("pinned-achievements");
assert("D.14 hub feed has at least one entry", feed.length >= 1);
assertEq("D.15 hub feed entry id is correct", feed[0]?.id, "first-blood");
assertEq("D.16 hub feed entry name is correct", feed[0]?.name, "First Blood");
// ── Section E — HUD payload derivation ──
console.log("[E] HUD payload derivation");
// The init hook already ran (section D); just construct the HUD.
// Stub game.combat so buildHudUpdatePayload can resolve currentTurn.
game.combat = {
combatant: {
name: "Bard",
tokenId: "t1",
actor: { name: "Bard" },
},
};
const realEncounter = {
id: "enc1",
startedAt: Date.now() - 30000,
currentRound: 2,
currentTurn: 1,
combatants: new Map([
["t1", { tokenId: "t1", actorId: "a1", name: "Bard", isPlayer: true, side: "party", status: "active", damageDealt: 50, damageTaken: 10, hits: 3, crits: 1, portrait: "", hpPct: 0.9 }],
["t2", { tokenId: "t2", actorId: "a2", name: "Goblin", isPlayer: false, side: "foe", status: "active", damageDealt: 10, damageTaken: 50, hits: 2, crits: 0, portrait: "", hpPct: 0.0 }],
]),
isActive: () => true,
};
const evt = { kind: "attack-roll", damage: 25 };
const payloadE = buildHudUpdatePayload(realEncounter, evt);
assert("E.1 payload has round", payloadE.round === 2);
assert("E.2 payload has turn", payloadE.turn === 1);
assert("E.3 payload.currentTurn is object", typeof payloadE.currentTurn === "object" && payloadE.currentTurn !== null);
assert("E.3b payload.currentTurn.name is Bard", payloadE.currentTurn?.name === "Bard");
assert("E.4 payload.combatants is array", Array.isArray(payloadE.combatants));
assert("E.5 payload.combatants has 2 entries", payloadE.combatants.length === 2);
assert("E.6 payload.startedAt is number", typeof payloadE.startedAt === "number");
// ── Section F — Wall + popover rendering ──
console.log("[F] Wall + popover rendering");
// ── Section E — Wall + popover rendering ──
console.log("[E] Wall + popover rendering");
await awardAchievement("actor-bard", "crit-master", "enc-1");
await awardAchievement("actor-bard", "sharpshooter", "enc-1");
const wallHtml = renderAchievementWall("actor-bard", "Bard", {});
assert("F.1 renderAchievementWall returns string", typeof wallHtml === "string");
assert("F.2 wall HTML contains actor ID as data attribute", wallHtml.includes("actor-bard"));
assert("F.3 wall HTML mentions at least one earned achievement", wallHtml.toLowerCase().includes("crit") || wallHtml.toLowerCase().includes("sharp"));
assert("E.1 renderAchievementWall returns string", typeof wallHtml === "string");
assert("E.2 wall HTML contains actor ID as data attribute", wallHtml.includes("actor-bard"));
assert("E.3 wall HTML mentions at least one earned achievement", wallHtml.toLowerCase().includes("crit") || wallHtml.toLowerCase().includes("sharp"));
const progress = getAchievementWallProgress("actor-bard", "Bard");
assert("F.4 getAchievementWallProgress returns array", Array.isArray(progress));
assert("E.4 getAchievementWallProgress returns array", Array.isArray(progress));
const recent = getRecentUnlocks("actor-bard");
assert("F.5 getRecentUnlocks returns array", Array.isArray(recent));
assert("E.5 getRecentUnlocks returns array", Array.isArray(recent));
const popoverHtml = renderAchievementPopover([{ id: "first-kill", name: "First Kill" }], "Bard");
assert("F.6 renderAchievementPopover returns string", typeof popoverHtml === "string");
assert("F.7 popover HTML contains 'Your Achievements'", popoverHtml.includes("Your Achievements"));
assert("F.8 popover HTML contains achievement name", popoverHtml.includes("First Kill"));
assert("E.6 renderAchievementPopover returns string", typeof popoverHtml === "string");
assert("E.7 popover HTML contains 'Your Achievements'", popoverHtml.includes("Your Achievements"));
assert("E.8 popover HTML contains achievement name", popoverHtml.includes("First Kill"));
// ── Section F — Hub integration (Pinned Achievements section) ──
console.log("[F] Hub integration (Pinned Achievements section)");
const section = hubApi.listSections().find(s => s.id === "pinned-achievements");
assert("F.1 pinned-achievements section exists", !!section);
assertEq("F.2 section label is correct", section.label, "Pinned Achievements");
assert("F.3 section render is a function", typeof section.render === "function");
// Render the section with the current feed to verify shape.
const renderedHtml = section.render({ feed: hubApi.getFeed("pinned-achievements") });
assert("F.4 section renders without throwing", typeof renderedHtml === "string");
assert("F.5 rendered HTML contains First Blood", renderedHtml.includes("First Blood"));
assert("F.6 rendered HTML contains the icon", renderedHtml.includes("🩸"));
// F.7 — Section handles empty feed gracefully.
const emptyHtml = section.render({ feed: [] });
assert("F.7 empty feed renders placeholder", emptyHtml.includes("None yet"));
// F.8 — When combat-hud-hub is missing, the section registration is
// a no-op. This is hard to test without re-importing main.js, but
// we can simulate by removing the module and calling registerHubSection.
game.modules.delete("combat-hud-hub");
const regRet = modApi.registerHubSection();
assertEq("F.8 registerHubSection returns false when hub missing", regRet, false);
// ── Section G — Graceful degradation without foundry-hooks-lib ──
console.log("[G] Graceful degradation");
// D.10-D.13 already covered "graceful without chatBubble errors";
// here we just confirm `isReady` and other api methods don't throw.
let readyThrew = null;
try { modApi.isReady(); } catch (e) { readyThrew = e; }
assert("G.1 isReady() doesn't throw", readyThrew === null);
assertEq("G.2 isReady() returns boolean", typeof modApi.isReady(), "boolean");
// ── Summary ──
const passed = ASSERTIONS.filter((a) => a.pass).length;
const total = ASSERTIONS.length;
console.log(`\n--- ${passed}/${total} assertions passed ---`);
if (passed !== total) {
console.log("\nFailed assertions:");
for (const a of ASSERTIONS.filter((x) => !x.pass)) {
console.log(` ✗ ${a.name} ${a.extra}`);
console.log(`\n--- ${passed}/${ASSERTIONS.length} assertions passed ---`);
if (passed < ASSERTIONS.length) {
console.error(`\n${ASSERTIONS.length - passed} assertion(s) failed.`);
for (const a of ASSERTIONS) {
if (!a.pass) console.error(` FAIL: ${a.name} ${a.extra}`);
}
process.exitCode = 1;
process.exit(1);
}
}
run().catch((e) => {
console.error("[verify-achievable] uncaught:", e);
console.error(e.stack);
process.exitCode = 1;
console.error("Smoke test crashed:", e);
process.exit(1);
});