Fighting Game · Guides & deep dives

Hathor LLM NPC Integration

V2 delegates live NPC dialogue and behavior for these open-world and semi-open-world surfaces to @hathor/llm-npc through @v2/hathor-npc-adapter:

5sections2 minread1table
Markdown source
On this page

Scope#

V2 delegates live NPC dialogue and behavior for these open-world and semi-open-world surfaces to @hathor/llm-npc through @v2/hathor-npc-adapter:

  • World Tour
  • Tekken Force
  • Devil Within
  • DJ street
  • MyCAREER backstage
  • SC Chronicles overworld

Fighting-match dialogue that can appear in rollback replays uses prebaked @hathor/lore-compiler banks. Live LLM NPC output is not allowed to influence deterministic simulation state.

Runtime Contract#

The V2 bridge accepts these hooks:

Hook V2 input Hathor output
npc.encounter.start NPC id, location, faction, player history hash Greeting, behavior intent vector, tone, emotional-state delta
npc.dialogue.request Player utterance, scene context, party history hash NPC line, tone tag, emotion, suggested actions, memory ids
npc.behavior.tick World-state delta on a low-frequency open-world tick Behavior tree node, targeted action, decision reason
npc.combat.barks HP delta, near-KO, KO, last move, arena hazard Short bark line, style hint, emotional-state delta

Every request must carry:

  • rollbackPolicy: "off-rollback-only"
  • deterministicGameplay: false
  • seed
  • contextHash
  • playerHistoryHash

The bridge returns every response on v2.npc.off_rollback with rollbackResultPolicy: "ignored_by_rollback" and includes the Hathor package identifier @hathor/llm-npc in the output metadata.

Before a dialogue response is returned or cached, the bridge validates the Hathor persona identity, declared intent and emotion, bounded suggested actions, validated memory attribution, response/abstention state, and calibrated confidence evidence. Triggered memories must exactly match attributed retrieved memories, confidenceScore must match the calibrated score, and answered output must clear its threshold. Abstentions cannot carry actions or triggered memories.

Dialogue Cache#

Dialogue-like outputs from npc.encounter.start, npc.dialogue.request, and npc.combat.barks are cached by seed plus context hash under V2/ue/Content/Generated/NPCDialogue/. The file-backed adapter path is:

<mode>/<hook>/<seed-context-hash-prefix>/<seed-context-hash>.json

where seed-context-hash is sha256(seed + "\n" + contextHash). Cache entries carry the original seed, contextHash, mode, hook, NPC id, player id, output, and rationale tags:

  • cross_platform_consistency
  • cost_containment
  • qa_repeatability

The cache is not a replay-determinism feature. Open-world modes are not rollback replay-recorded; the cache exists so identical seed/context pairs produce identical reviewed NPC replies across platforms. In plain terms, the cache exists for cross-platform consistency, cost containment, and repeatable QA/localization review.

Failure Behavior#

Invalid mode ids, unsupported hooks, missing required identity fields, or any attempt to mark a request as deterministic fail before calling Hathor. Upstream provider failures are wrapped as V2HathorNpcBridgeError with code: "runtime_failure" so client-server open-world systems can retry, degrade dialogue, or surface outage telemetry without touching rollback state. Missing, foreign, malformed, or contradictory dialogue evidence fails closed with code: "invalid_runtime_output".

npc.behavior.tick requires a Hathor behavior selector. Encounter starts and combat barks can fall back through Hathor dialogue generation until the richer combat-bark runtime is available in Hathor.

Unreal Registration#

V2Services registers two Hathor adapters:

  • hathor for @hathor/lore-compiler compiled narrative exports
  • hathor-llm-npc for @hathor/llm-npc live open-world NPC calls

Both descriptors set bMayInfluenceRollback = false; the automation spec asserts the LLM NPC descriptor is registered, client-server available, and off-rollback only.