Modding Doc: Combat Log

Records, formats, and displays per-player combat events in real-time on the HUD, plus a /hyforged combatlog command for history review.

Architecture / Data Flow

Damage event fires (ECS pipeline)
    |
    v
HyforgedCombatLogSystem (DamageEventSystem in inspectDamageGroup)
    |- reads final damage state, quality, crit, block, miss
    |- builds CombatEvent via builder
    v
CombatLogService (singleton, thread-safe)
    |- stores events per-player in CombatEncounter objects
    |- auto-groups events within 10s timeout
    v
CombatLogHudSystem (DelayedEntitySystem, 200ms tick)
    |- polls CombatLogService for recent events
    |- formats via CombatLogFormatter.formatEventMessage()
    |- appends extra lines (XP, death messages)
    |- pushes rich-text to HyforgedHud

Additional entry points:

• •CombatServiceImpl.recordToCombatLogImmediate() — programmatic damage (non-ECS path)
• •PlayerDeathCombatLogSystem — adds death lines via CombatLogHudSystem.addExtraLine()
• •XPAwardSystem / HyforgedPlugin — adds XP gain lines via addExtraLine()

Key Files

CombatEvent Record Fields

CombatLogService API

Singleton via CombatLogService.get(). Thread-safe (ConcurrentHashMap + synchronized inner class).

Constants: MAX_ENCOUNTERS_PER_PLAYER = 5

CombatEncounter API

Constants: ENCOUNTER_TIMEOUT_MS = 10_000, MAX_EVENTS_PER_ENCOUNTER = 1000

CombatLogFormatter

Static utility. All user-facing text uses ASCII only (no Unicode).

Color Constants

Message Formats

• •Normal damage: CRIT {AttackerName} => {DefenderName}: {dmg} (DamageType)
• •Block: BLOCK {DefenderName} blocked {AttackerName} (dmg)
• •Miss: {AttackerName}'s attack missed {DefenderName}
• •Death: YOU DIED -- [Quality] KillerName Lv.X (N damage)

NPC names with quality show as [Epic] Eye Void with tier-colored bracket tag. Quality colors resolved from ItemQuality.getAssetMap().getAsset(qualityId).getTextColor().

Key Methods

CombatLogHudSystem

DelayedEntitySystem<EntityStore>, ticks every 200ms. Query: Query.and(Player, PlayerRef, UUIDComponent).

Constants

• •UPDATE_INTERVAL_SEC = 0.2f
• •MAX_DISPLAY_EVENTS = 12
• •MAX_EXTRA_LINES = 8

Static API

tick() Flow

1. •Skip if HUD invisible
2. •Gather recent events across encounters (sorted by timestamp)
3. •Dirty check (skip if unchanged)
4. •Calculate DPS from current encounter
5. •Format events via CombatLogFormatter.formatEventMessage()
6. •Append extra lines
7. •Trim to MAX_DISPLAY_EVENTS
8. •Push to HUD: hud.updateCombatLog(lines, dps, hits, crits)

HyforgedCombatLogSystem

DamageEventSystem in inspectDamageGroup. Runs after HyforgedCriticalHitSystem, before DamageSystems.EntityUIEvents.

Constructor

new HyforgedCombatLogSystem(npcQualityComponentType)

Takes ComponentType<EntityStore, HyforgedNPCQualityComponent> for quality resolution.

handle() reads these meta keys

Entity Name Resolution Order

1. •Player.getDisplayName() (player name)
2. •DisplayNameComponent.getDisplayName().getRawText() (clean base name)
3. •NPCEntity.getRoleName() (NPC role)
4. •Nameplate.getText() with stripNameplateDecorations() (fallback)
5. •UUID substring (8 chars)
6. •"Unknown"

PlayerDeathCombatLogSystem

DeathSystems.OnDeathSystem (RefChangeSystem). Query: Query.and(DeathComponent, Player).

Death line formats:

• •Entity killer: YOU DIED -- [Quality] KillerName Lv.X (N damage) (quality suppressed for Common)
• •Environment: YOU DIED -- Environment (N damage)

Adds line via CombatLogHudSystem.addExtraLine().

Plugin Registration

// In HyforgedPlugin.start():
entityStoreRegistry.registerSystem(new HyforgedCombatLogSystem(npcQualityComponentType));
entityStoreRegistry.registerSystem(new CombatLogHudSystem());
entityStoreRegistry.registerSystem(new PlayerDeathCombatLogSystem());

// Cleanup on disconnect:
CombatLogService.get().onPlayerDisconnect(uuid);
CombatLogHudSystem.clearPlayerState(uuid);

HUD Integration

HyforgedHud UI element IDs:

• •#CombatLog.Visible — show/hide the combat log panel
• •#LogEntry0 through #LogEntry11 — .TextSpans for rich text, .Text for clear
• •#DpsLabel.Text, #HitsLabel.Text, #CritsLabel.Text — summary stats

Common Patterns

Recording a custom combat event

CombatEvent event = CombatEvent.builder()
    .timestamp(System.currentTimeMillis())
    .attackerUuid(attackerUuid)
    .defenderUuid(defenderUuid)
    .attackerName("Skeleton")
    .defenderName("Pandaros")
    .damageCauseId("Physical")
    .baseDamage(100f)
    .finalDamage(75f)
    .criticalHit(true)
    .critMultiplierBps(15000)
    .attackerQuality("rare")
    .build();
CombatLogService.get().recordEvent(playerUuid, event);

Adding extra lines to the HUD

Message xpLine = Message.raw("+500 XP").color("#55AAFF");
CombatLogHudSystem.addExtraLine(playerUuid, xpLine);

Toggling HUD visibility

boolean newState = CombatLogHudSystem.toggleHudVisibility(playerUuid);

Querying combat history

List<CombatEncounter> encounters = CombatLogService.get().getRecentEncounters(playerUuid);
CombatEncounter current = CombatLogService.get().getCurrentEncounter(playerUuid);
float dps = current != null ? current.getTotalDamageByAttacker(playerUuid) / (current.getDuration() / 1000f) : 0;

Cleanup on disconnect

CombatLogService.get().onPlayerDisconnect(uuid);
CombatLogHudSystem.clearPlayerState(uuid);

Important Rules

• •No Unicode in user-facing text. Use ASCII alternatives (e.g., CRIT not ✦, => not →, -- not ∞).
• •Quality colors are resolved dynamically from ItemQuality.getAssetMap() — do not hard-code tier colors.
• •Common quality is suppressed in display (not shown on nameplates, death lines, or combat log).
• •displayName() replaces underscores with spaces — all entity names go through this.
• •Use CombatEvent.builder() — never construct the record directly.
• •Record events for both attacker and defender when both are players.
• •Extra lines are capped at MAX_EXTRA_LINES = 8 per player.
• •Encounters auto-group within 10s; max 5 encounters retained per player.

Test Coverage

• •CombatEventTest — Builder, defaults, miss/crit events, equality
• •CombatLogServiceTest — Singleton, encounter grouping, timeout splits, limits, cleanup
• •CombatEncounterTest — Event tracking, timeout logic, statistics, defensive copies