Scope#
V2AICommentary routes live match commentary cues through
@v2/iris-commentary-orchestration, which calls createMatchCommentaryStream
from @iris/conversation-orchestration.
Rollback Contract#
The contract is hard-coded to determinismMode: "off-rollback-only".
fromRollbackFrame cues are rejected before Iris is called. Accepted commentary
outputs are audio/subtitle only; they never feed simulation state, AI Director
hints, balance counters, replay input bytes, or rollback decisions.
Record And Replay#
Iris records generated output by (matchId, cueId, cueTriggerFrame, branchId).
Replay and replay-takeover paths use the recorded line for the same branch. A
new takeover branch can request fresh commentary without changing deterministic
combat state.
Latency Fallback#
KO-trigger commentary has an 800 ms end-to-end budget documented at
V2/docs/integration/commentary-latency.md. V2 reserves 420 ms of that envelope
for the Iris LLM round trip, 240 ms for persona TTS render, 100 ms for Psyche
lipsync/expression render, and 40 ms for safety margin.
If the low-latency Iris call misses its reserved budget, the Iris stream falls
back to a pre-recorded @calliope/persona-live bank line. Fallback selection is
deterministic by (cueKind,ruleset,commentatorId,seed), but live LLM output is
treated as recorded output, not regenerated from seed.
Unreal Plugin#
V2/ue/Plugins/V2AICommentary/ exposes the same contract to Unreal automation:
@iris/conversation-orchestration, @v2/iris-commentary-orchestration,
off-rollback-only, and audio/subtitle-only output channels.