Add combatant side assignment for encounter difficulty
All checks were successful
CI / check (push) Successful in 2m18s
CI / build-image (push) Successful in 17s

Combatants can now be assigned to party or enemy side via a toggle
in the difficulty breakdown panel. Party-side NPCs subtract their XP
from the encounter total, letting allied NPCs reduce difficulty.
PCs default to party, non-PCs to enemy — users who don't use sides
see no change. Side persists across reload and export/import.

Closes #22

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lukas
2026-04-03 14:15:12 +02:00
parent 30e7ed4121
commit 94e1806112
23 changed files with 1359 additions and 455 deletions

View File

@@ -106,7 +106,7 @@ describe("useDifficultyBreakdown", () => {
expect(result.current).toBeNull();
});
it("returns per-combatant entries with correct data", async () => {
it("returns per-combatant entries split by side", async () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
@@ -145,29 +145,34 @@ describe("useDifficultyBreakdown", () => {
const breakdown = result.current;
expect(breakdown).not.toBeNull();
expect(breakdown?.pcCount).toBe(1);
// CR 1/4 = 50 + CR 2 = 450 total 500
// CR 1/4 = 50 + CR 2 = 450 -> total 500
expect(breakdown?.totalMonsterXp).toBe(500);
expect(breakdown?.combatants).toHaveLength(3);
// Bestiary combatant
const goblin = breakdown?.combatants[0];
// PC in party column
expect(breakdown?.partyCombatants).toHaveLength(1);
expect(breakdown?.partyCombatants[0].combatant.name).toBe("Hero");
expect(breakdown?.partyCombatants[0].side).toBe("party");
expect(breakdown?.partyCombatants[0].level).toBe(5);
// Enemies: goblin, thug, bandit
expect(breakdown?.enemyCombatants).toHaveLength(3);
const goblin = breakdown?.enemyCombatants[0];
expect(goblin?.cr).toBe("1/4");
expect(goblin?.xp).toBe(50);
expect(goblin?.source).toBe("SRD");
expect(goblin?.editable).toBe(false);
expect(goblin?.side).toBe("enemy");
// Custom with CR
const thug = breakdown?.combatants[1];
const thug = breakdown?.enemyCombatants[1];
expect(thug?.cr).toBe("2");
expect(thug?.xp).toBe(450);
expect(thug?.source).toBeNull();
expect(thug?.editable).toBe(true);
// Custom without CR
const bandit = breakdown?.combatants[2];
const bandit = breakdown?.enemyCombatants[2];
expect(bandit?.cr).toBeNull();
expect(bandit?.xp).toBeNull();
expect(bandit?.source).toBeNull();
expect(bandit?.editable).toBe(true);
});
});
@@ -203,16 +208,15 @@ describe("useDifficultyBreakdown", () => {
wrapper,
});
// With no bestiary creatures loaded, the Ghost has null CR
const breakdown = result.current;
expect(breakdown).not.toBeNull();
const ghost = breakdown?.combatants[0];
const ghost = breakdown?.enemyCombatants[0];
expect(ghost?.cr).toBeNull();
expect(ghost?.xp).toBeNull();
expect(ghost?.editable).toBe(false);
});
it("excludes PC combatants from breakdown entries", async () => {
it("PC combatants appear in partyCombatants with level", async () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
@@ -239,8 +243,53 @@ describe("useDifficultyBreakdown", () => {
});
await waitFor(() => {
expect(result.current?.combatants).toHaveLength(1);
expect(result.current?.combatants[0].combatant.name).toBe("Goblin");
expect(result.current?.partyCombatants).toHaveLength(1);
expect(result.current?.partyCombatants[0].combatant.name).toBe("Hero");
expect(result.current?.partyCombatants[0].level).toBe(1);
expect(result.current?.partyCombatants[0].side).toBe("party");
});
});
it("combatant with explicit side override is placed correctly", () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c-1"),
name: "Hero",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c-2"),
name: "Allied Guard",
creatureId: goblinCreature.id,
side: "party",
}),
buildCombatant({
id: combatantId("c-3"),
name: "Thug",
cr: "1",
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
],
creatures: new Map([[goblinCreature.id, goblinCreature]]),
});
const { result } = renderHook(() => useDifficultyBreakdown(), {
wrapper,
});
const breakdown = result.current;
expect(breakdown).not.toBeNull();
// Allied Guard should be in party column
expect(breakdown?.partyCombatants).toHaveLength(2);
expect(breakdown?.partyCombatants[1].combatant.name).toBe("Allied Guard");
expect(breakdown?.partyCombatants[1].side).toBe("party");
// Thug in enemy column
expect(breakdown?.enemyCombatants).toHaveLength(1);
expect(breakdown?.enemyCombatants[0].combatant.name).toBe("Thug");
});
});

View File

@@ -1,220 +0,0 @@
// @vitest-environment jsdom
import type {
Combatant,
CreatureId,
Encounter,
PlayerCharacter,
} from "@initiative/domain";
import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
import { renderHook } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
vi.mock("../../contexts/encounter-context.js", () => ({
useEncounterContext: vi.fn(),
}));
vi.mock("../../contexts/player-characters-context.js", () => ({
usePlayerCharactersContext: vi.fn(),
}));
vi.mock("../../contexts/bestiary-context.js", () => ({
useBestiaryContext: vi.fn(),
}));
import { useBestiaryContext } from "../../contexts/bestiary-context.js";
import { useEncounterContext } from "../../contexts/encounter-context.js";
import { usePlayerCharactersContext } from "../../contexts/player-characters-context.js";
import { useDifficulty } from "../use-difficulty.js";
const mockEncounterContext = vi.mocked(useEncounterContext);
const mockPlayerCharactersContext = vi.mocked(usePlayerCharactersContext);
const mockBestiaryContext = vi.mocked(useBestiaryContext);
const pcId1 = playerCharacterId("pc-1");
const pcId2 = playerCharacterId("pc-2");
const crId1 = creatureId("creature-1");
const _crId2 = creatureId("creature-2");
function setup(options: {
combatants: Combatant[];
characters: PlayerCharacter[];
creatures: Map<CreatureId, { cr: string }>;
}) {
const encounter = {
combatants: options.combatants,
activeIndex: 0,
roundNumber: 1,
} as Encounter;
mockEncounterContext.mockReturnValue({
encounter,
} as ReturnType<typeof useEncounterContext>);
mockPlayerCharactersContext.mockReturnValue({
characters: options.characters,
} as ReturnType<typeof usePlayerCharactersContext>);
mockBestiaryContext.mockReturnValue({
getCreature: (id: CreatureId) => options.creatures.get(id),
} as ReturnType<typeof useBestiaryContext>);
}
beforeEach(() => {
vi.clearAllMocks();
});
describe("useDifficulty", () => {
it("returns difficulty result for leveled PCs and bestiary monsters", () => {
setup({
combatants: [
{ id: combatantId("c1"), name: "Hero", playerCharacterId: pcId1 },
{ id: combatantId("c2"), name: "Goblin", creatureId: crId1 },
],
characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }],
creatures: new Map([[crId1, { cr: "1/4" }]]),
});
const { result } = renderHook(() => useDifficulty());
expect(result.current).not.toBeNull();
expect(result.current?.tier).toBe("low");
expect(result.current?.totalMonsterXp).toBe(50);
});
describe("returns null when data is insufficient (ED-2)", () => {
it("returns null when encounter has no combatants", () => {
setup({ combatants: [], characters: [], creatures: new Map() });
const { result } = renderHook(() => useDifficulty());
expect(result.current).toBeNull();
});
it("returns null when only custom combatants (no creatureId)", () => {
setup({
combatants: [
{
id: combatantId("c1"),
name: "Custom",
playerCharacterId: pcId1,
},
],
characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 }],
creatures: new Map(),
});
const { result } = renderHook(() => useDifficulty());
expect(result.current).toBeNull();
});
it("returns null when bestiary monsters present but no PC combatants", () => {
setup({
combatants: [
{ id: combatantId("c1"), name: "Goblin", creatureId: crId1 },
],
characters: [],
creatures: new Map([[crId1, { cr: "1" }]]),
});
const { result } = renderHook(() => useDifficulty());
expect(result.current).toBeNull();
});
it("returns null when PC combatants have no level", () => {
setup({
combatants: [
{
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId1,
},
{ id: combatantId("c2"), name: "Goblin", creatureId: crId1 },
],
characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30 }],
creatures: new Map([[crId1, { cr: "1" }]]),
});
const { result } = renderHook(() => useDifficulty());
expect(result.current).toBeNull();
});
it("returns null when PC combatant references unknown player character", () => {
setup({
combatants: [
{
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId2,
},
{ id: combatantId("c2"), name: "Goblin", creatureId: crId1 },
],
characters: [{ id: pcId1, name: "Other", ac: 15, maxHp: 30, level: 5 }],
creatures: new Map([[crId1, { cr: "1" }]]),
});
const { result } = renderHook(() => useDifficulty());
expect(result.current).toBeNull();
});
});
it("handles mixed combatants: only leveled PCs and bestiary monsters contribute", () => {
// Party: one leveled PC, one without level (excluded)
// Monsters: one bestiary creature, one custom (excluded)
setup({
combatants: [
{
id: combatantId("c1"),
name: "Leveled",
playerCharacterId: pcId1,
},
{
id: combatantId("c2"),
name: "No Level",
playerCharacterId: pcId2,
},
{ id: combatantId("c3"), name: "Goblin", creatureId: crId1 },
{ id: combatantId("c4"), name: "Custom Monster" },
],
characters: [
{ id: pcId1, name: "Leveled", ac: 15, maxHp: 30, level: 1 },
{ id: pcId2, name: "No Level", ac: 12, maxHp: 20 },
],
creatures: new Map([[crId1, { cr: "1" }]]),
});
const { result } = renderHook(() => useDifficulty());
expect(result.current).not.toBeNull();
// 1 level-1 PC: budget low=50, mod=75, high=100
// 1 CR 1 monster: 200 XP → high (200 >= 100)
expect(result.current?.tier).toBe("high");
expect(result.current?.totalMonsterXp).toBe(200);
expect(result.current?.partyBudget.low).toBe(50);
});
it("includes duplicate PC combatants in budget", () => {
// Same PC added twice → counts twice
setup({
combatants: [
{
id: combatantId("c1"),
name: "Hero 1",
playerCharacterId: pcId1,
},
{
id: combatantId("c2"),
name: "Hero 2",
playerCharacterId: pcId1,
},
{ id: combatantId("c3"), name: "Goblin", creatureId: crId1 },
],
characters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 }],
creatures: new Map([[crId1, { cr: "1/4" }]]),
});
const { result } = renderHook(() => useDifficulty());
expect(result.current).not.toBeNull();
// 2x level 1: budget low=100
expect(result.current?.partyBudget.low).toBe(100);
});
});

View File

@@ -0,0 +1,381 @@
// @vitest-environment jsdom
import type { Creature, CreatureId, PlayerCharacter } from "@initiative/domain";
import { combatantId, creatureId, playerCharacterId } from "@initiative/domain";
import { renderHook, waitFor } from "@testing-library/react";
import type { ReactNode } from "react";
import { beforeAll, describe, expect, it, vi } from "vitest";
import { createTestAdapters } from "../../__tests__/adapters/in-memory-adapters.js";
import {
buildCombatant,
buildCreature,
buildEncounter,
} from "../../__tests__/factories/index.js";
import { AllProviders } from "../../__tests__/test-providers.js";
import { useDifficulty } from "../use-difficulty.js";
beforeAll(() => {
Object.defineProperty(globalThis, "matchMedia", {
writable: true,
value: vi.fn().mockImplementation((query: string) => ({
matches: false,
media: query,
onchange: null,
addListener: vi.fn(),
removeListener: vi.fn(),
addEventListener: vi.fn(),
removeEventListener: vi.fn(),
dispatchEvent: vi.fn(),
})),
});
});
const pcId1 = playerCharacterId("pc-1");
const pcId2 = playerCharacterId("pc-2");
const crId1 = creatureId("srd:goblin");
const goblinCreature = buildCreature({
id: crId1,
name: "Goblin",
cr: "1/4",
});
function makeWrapper(options: {
encounter: ReturnType<typeof buildEncounter>;
playerCharacters?: PlayerCharacter[];
creatures?: Map<CreatureId, Creature>;
}) {
const adapters = createTestAdapters({
encounter: options.encounter,
playerCharacters: options.playerCharacters ?? [],
creatures: options.creatures,
});
return ({ children }: { children: ReactNode }) => (
<AllProviders adapters={adapters}>{children}</AllProviders>
);
}
describe("useDifficulty", () => {
it("returns difficulty result for leveled PCs and bestiary monsters", async () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c2"),
name: "Goblin",
creatureId: crId1,
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 },
],
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
await waitFor(() => {
expect(result.current).not.toBeNull();
expect(result.current?.tier).toBe("low");
expect(result.current?.totalMonsterXp).toBe(50);
});
});
describe("returns null when data is insufficient (ED-2)", () => {
it("returns null when encounter has no combatants", () => {
const wrapper = makeWrapper({
encounter: buildEncounter({ combatants: [] }),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
expect(result.current).toBeNull();
});
it("returns null when only custom combatants (no creatureId)", () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Custom",
playerCharacterId: pcId1,
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
],
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
expect(result.current).toBeNull();
});
it("returns null when bestiary monsters present but no PC combatants", () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Goblin",
creatureId: crId1,
}),
],
}),
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
expect(result.current).toBeNull();
});
it("returns null when PC combatants have no level", () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c2"),
name: "Goblin",
creatureId: crId1,
}),
],
}),
playerCharacters: [{ id: pcId1, name: "Hero", ac: 15, maxHp: 30 }],
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
expect(result.current).toBeNull();
});
it("returns null when PC combatant references unknown player character", () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId2,
}),
buildCombatant({
id: combatantId("c2"),
name: "Goblin",
creatureId: crId1,
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Other", ac: 15, maxHp: 30, level: 5 },
],
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
expect(result.current).toBeNull();
});
});
it("handles mixed combatants: only leveled PCs and CR-bearing monsters contribute", async () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Leveled",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c2"),
name: "No Level",
playerCharacterId: pcId2,
}),
buildCombatant({
id: combatantId("c3"),
name: "Goblin",
creatureId: crId1,
}),
buildCombatant({
id: combatantId("c4"),
name: "Custom Monster",
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Leveled", ac: 15, maxHp: 30, level: 1 },
{ id: pcId2, name: "No Level", ac: 12, maxHp: 20 },
],
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
await waitFor(() => {
expect(result.current).not.toBeNull();
// 1 level-1 PC: budget low=50, mod=75, high=100
// CR 1/4 = 50 XP -> low (50 >= 50)
expect(result.current?.tier).toBe("low");
expect(result.current?.totalMonsterXp).toBe(50);
expect(result.current?.partyBudget.low).toBe(50);
});
});
it("includes duplicate PC combatants in budget", async () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Hero 1",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c2"),
name: "Hero 2",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c3"),
name: "Goblin",
creatureId: crId1,
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 },
],
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
await waitFor(() => {
expect(result.current).not.toBeNull();
// 2x level 1: budget low=100
expect(result.current?.partyBudget.low).toBe(100);
});
});
it("combatant toggled to party side subtracts XP", async () => {
const bugbear = buildCreature({
id: creatureId("srd:bugbear"),
name: "Bugbear",
cr: "1",
});
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c2"),
name: "Allied Guard",
creatureId: bugbear.id,
side: "party",
}),
buildCombatant({
id: combatantId("c3"),
name: "Thug",
cr: "1",
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 1 },
],
creatures: new Map([[bugbear.id, bugbear]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
await waitFor(() => {
expect(result.current).not.toBeNull();
// Thug CR 1 = 200 XP, Allied Guard CR 1 = 200 XP subtracted, net = 0
expect(result.current?.totalMonsterXp).toBe(0);
expect(result.current?.tier).toBe("trivial");
});
});
it("default side resolution: PC -> party, non-PC -> enemy", async () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c2"),
name: "Goblin",
creatureId: crId1,
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 3 },
],
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
await waitFor(() => {
expect(result.current).not.toBeNull();
// Level 3 budget: low=150, mod=225, high=400
// CR 1/4 = 50 XP -> trivial
expect(result.current?.partyBudget.low).toBe(150);
expect(result.current?.totalMonsterXp).toBe(50);
expect(result.current?.tier).toBe("trivial");
});
});
it("custom combatant with CR on party side subtracts XP", async () => {
const wrapper = makeWrapper({
encounter: buildEncounter({
combatants: [
buildCombatant({
id: combatantId("c1"),
name: "Hero",
playerCharacterId: pcId1,
}),
buildCombatant({
id: combatantId("c2"),
name: "Ally",
cr: "2",
side: "party",
}),
buildCombatant({
id: combatantId("c3"),
name: "Goblin",
creatureId: crId1,
}),
],
}),
playerCharacters: [
{ id: pcId1, name: "Hero", ac: 15, maxHp: 30, level: 5 },
],
creatures: new Map([[crId1, goblinCreature]]),
});
const { result } = renderHook(() => useDifficulty(), { wrapper });
await waitFor(() => {
expect(result.current).not.toBeNull();
// CR 1/4 = 50 XP enemy, CR 2 = 450 XP ally subtracted, net = 0 (floored)
expect(result.current?.totalMonsterXp).toBe(0);
});
});
});