Starclock — Engine-Agnostic Combat Reference

Starclock is a deterministic, engine-agnostic Rust combat and activity simulator. This directory is its execution reference for mechanics inspired by Honkai: Star Rail. It deliberately excludes rendering, animation, audio, input widgets, networking, account systems, real-time exploration movement, gacha, account inventory, and copyrighted game assets.

The target is a headless battle kernel plus a generic activity orchestrator that can later be driven by Bevy, another engine, the starclock CLI, tests, or a simulation service.

Current repository status: See Repository state. Git records past iterations; this documentation describes the current mechanics, content, architecture and authoring model only.

Research baseline

• The general mechanics baseline was reviewed on 2026-07-17; the Version 4.4 character release-state and action-flow addendum was reviewed on 2026-08-05.
• HoYoverse does not publish a complete combat specification. Exact formulas are therefore based primarily on current community-maintained references, cross-checked where possible against in-game tutorial transcriptions and independent calculations.
• A formula marked verified has consistent support in at least two established references or an established reference plus a worked in-game result.
• A rule marked observed is widely documented but may contain edge cases.
• A rule marked project policy is an explicit implementation choice where the original game's behavior is unpublished, unstable, or unnecessary for the first milestone.

Treat the date, not an assumed game version number, as the baseline. Character kits and newer mode-specific systems change frequently; the underlying engine must express exceptions without hard-coding them into shared formulas.

Document map

1. Core battle model — scope, entities, targeting, lifecycle, and event semantics.
2. Action order and turns — Speed, Action Gauge, interrupts, duration timing, and cycles.
3. Damage and sustain formulas — ordinary damage, DEF, RES, CRIT, healing, and shields.
4. Toughness and Weakness Break — Toughness reduction, elemental breaks, Break DoT, and Super Break.
5. Effects and resources — buffs, debuffs, effect chance, Skill Points, Energy, and aggro.
6. Rust architecture — pure-core boundaries, data model, command/event API, RNG, and test plan.
7. Excel and Sora configuration pipeline — Excel authoring, Sora schema/code generation/export, runtime bundle loading, and CI policy.
8. Rust engineering standards — file-size limits, responsibility-based modules, visibility/re-export policy, errors, testing, linting, and review gates.
9. Cross-platform determinism and numeric policy — fixed-point arithmetic, rounding, RNG, stable ordering, state hashing, command atomicity, and platform verification.
10. Lifecycle and resolution — command atomicity, action phases, defeat, presence, waves, faults, and event causality.
11. Rule IR and native handlers — typed conditions, selectors, operations, triggers, state slots, scopes, and the exceptional-code boundary.
12. Modifier and snapshot pipeline — stat-query stages, stacking groups, applicability, snapshots, and cycle detection.
13. Enemy AI and encounters — enemy definitions, deterministic behavior graphs, boss phases, variants, waves, and encounter validation.
14. Universe mode profiles — Standard SU, Swarm Disaster, Gold and Gears, Unknowable Domain, and Divergent Universe over the generic activity core.
15. Content data and coverage — bilingual/provenance fields, character/equipment/enemy/mode schemas, completeness states, and the Version 4.4 manifest policy.
16. Replay, CLI, and engine integration — canonical replay format, planned CLI contracts, baseline controllers, and Bevy/engine adapters.
17. Documentation coverage matrix — current normative coverage, research gaps, data-import status, and terminal gates.
18. Standard and challenge modes — ordinary battles plus Memory of Chaos, Pure Fiction, and Apocalyptic Shadow orchestration, clocks, scoring, and seasonal data.
19. Activity core and mode extension — unified graphs, scopes, rosters, persistence, clocks, metrics, battle handoff, and future-mode extension.
20. Core implementation design — concrete Rust ownership, identities, stores, action lowering, operations, events, transactions, modules, and implementation order.
21. Character builds, Traces, and equipment — independent starclock-build, build selection/compilation, ability levels, Traces, Eidolons, Light Cones, relics, affixes, generic combat output, and validation.
22. Reference data — constants and the attacker-level multiplier table.
23. Sources and confidence — source provenance and known uncertainties.
24. Public character mechanics — the public Version 4.4 combat-form catalog, behavioral contracts, engine-feature matrix, and 90-form action-flow audit.
25. Combat content reference pack — prepared Version 4.4 character, Trace, Eidolon, Light Cone, enemy, ability, and ordinary-encounter facts used before Excel/Sora authoring.
26. Dependency and tool policy — exact active package/tool versions, licenses, deterministic impact, compile-cost records and rejected alternatives.
27. Sora 0.3.0 capability lock — checksum-bound installation, executed CLI/schema/codegen/export surface and pinned limitations.
28. CI verification — direct Cargo formatting, lint and workspace-test commands for the current tree.
29. Common configuration schema — stable identity, localization, version, provenance, evidence and canonical-decimal transport contracts.
30. Character and build configuration schema — Sora contracts for abilities, hit plans, characters, Traces, Eidolons, build patches and Light Cones.
31. Typed Rule IR configuration schema — transport contracts for rules, slots, triggers, expressions, selectors, operations, effects, modifiers and native-handler metadata.
32. Enemy, encounter and Standard configuration schema — enemy variants, deterministic AI, waves and the minimum generic Activity/BattleBinding/result-projection seam for Standard battles.
33. Production configuration pipeline — authoritative .xlsx workbooks, deterministic no-overwrite bootstrap, Sora exports/readers and the private data conversion boundary.
34. Catalog construction boundary — validated real-bundle loading, empty/representative private definitions and clean-regeneration evidence.
35. Authoritative numeric implementation — checked six-decimal domain types, six explicit rounding modes, typed faults and no-float enforcement.
36. Combat catalog implementation — fixed-width identity domains, immutable ordered definition tables and deterministic graph validation.
37. Deterministic RNG implementation — canonical SHA-256 substreams, pinned ChaCha8 words, integer mappings and draw-consumption policy.
38. Canonical replay/codec implementation — versioned header/record framing, typed digests, bounded decoding and streaming state hashing.
39. Property-test harness — fixed-seed shrinking and persisted regression contracts for arithmetic, RNG, ordering, codec and malformed replay input.
40. Battle aggregate boundary — generic battle inputs, canonical runtime stores, phases, commands, decisions, resolutions and immutable query views.
41. Battle transaction boundary — reusable semantic-copy scratch, forward journal, rollback/commit-fault settlement, complete event causes and streaming canonical state hashes.
42. Action and timeline boundary — exact Action Gauge selection, structural action lowering, synchronous phase/hit events and deterministic interrupt ordering.
43. Target and action-resource boundary — canonical target commitments/invalidation, multi-hit locks and Basic/Skill/Ultimate Skill Point/Energy semantics.
44. Damage, healing, defeat and wave boundary — typed HP operations, fixed-point formula goldens, defeat/terminal settlement and ordered AfterAction waves.
45. Synthetic Standard CLI and replay boundary — smoke-only Standard fixture, low-level command/hash replay payloads and deterministic CLI run/verify evidence.
46. Phase 3 performance benchmark baseline — versioned apply/hash/replay/concurrency workloads, allocation and transaction instrumentation, CI smoke ceilings and strict stable-runner evidence.
47. Phase 3 command and replay property contract — fixed-seed mixed command streams, rollback convergence, deterministic hashes and replay envelope/domain corruption.
48. Typed Rule IR runtime boundary — validated expressions/programs, trigger indexes, once scopes, evaluation budgets and the immutable native-handler registry contract.
49. Toughness, Break and Super Break runtime boundary — ordered non-spilling layers, weakness lifetimes, base Break effects, Super Break samples and the source-bound Firefly probe.
50. Shared Elation runtime boundary — independent ability/damage tags, keyed team resources, holder/provider attribution, forced Skill payment and generic shared actors.
51. Enemy AI and encounter runtime boundary — finite controller graphs, exact wave slots/boundaries, boss-phase replacement and canonical orchestration state.
52. Native-handler and content-branch audit — zero-handler V1a review, exact static/Sora metadata agreement and mechanical rejection of scattered content-ID branches.
53. Build catalog and compilation boundary — independent build catalog/spec ownership, exact cross-catalog compatibility, typed validation reports and generic combat-only output.
54. Ability-level and Trace compilation — exact level tables, canonical Trace graphs, typed unlock/stat/rule patches and order-invariant build output.
55. Eidolon compilation — exact E0-E6 selection, complete rank sets, ordered patches and deterministic replacement/conflict validation.
56. Light Cone compilation — exact level/promotion stats, explicit applicability, S1-S5 passive selection and valid/invalid wearer fixtures.
57. Build identity and locking — canonical definition/catalog/build/spec digests, generic source attribution, named presets and stale-lock rejection.
58. Activity replay and controller diagnostics — versioned Activity command/result payloads, exact nested battle boundaries, controller score diagnostics and first-divergence verification.
59. Headless CLI contract — production Sora bundle validation, frozen Goal 01 coverage, baseline synthetic battle runs, replay verification, JSON schemas and exit classes.
60. Goal 01 release contract — frozen CLI/library surfaces, coverage identity, hardening reports and clean-checkout acceptance.
61. Agent control and MCP integration — protocol-neutral deterministic sessions plus stdio and authorized Streamable HTTP adapters.
62. Agent integration contract — runnable in-process, stdio and authorized HTTP embedding examples, frozen public surfaces and MCP suitability guidance.
63. Agent security and architecture audit — dependency/API direction, unsafe/source/license review, secret/log safety and remote control limits.
64. Agent cross-platform contract — native schema/trace execution and explicitly compile-only alternate targets.
65. Agent clean-checkout acceptance — isolated staged-tree gate, strict runner identity and retained capability/conformance/performance digests.
66. Mode extension and evolution contract — ordered child tasks, logical scopes, static handler bundles, component digests, experimental promotion, and immutable historical release evidence.
67. Standard Universe end-to-end runtime integration — real nested combat, atomic run effects, logical domain ownership, composed registries and component-aware replay migration.
68. Goal 05 integration probes — machine-readable Goal 04 integration-debt baseline and the focused three-minute execution budget.
69. Standard Universe integration coverage — exact-once Goal 05 dispositions, real 33-run battle/replay matrix and explicit enemy/rule approximation boundaries.
70. Combat identity and dynamic assembly — combat-owned input identity, opaque assembly provenance, current-Activity per-battle assembly, cache/rollback rules and replay-v3 migration.
71. Goal 06 identity and assembly debt probes — machine-checked caller-supplied digest, entry-time materialization, production-surface migration and representative transition baseline.
72. Goal 06 Phase 0 baseline — frozen replay v2/v3 compatibility, assembly/cache performance workloads, dependency identity and release scaffold.
73. Goal 06 combat-input identity evidence — combat-owned canonical input codec, computed digest and separate opaque assembly provenance.
74. Goal 06 Activity battle identity evidence — dual-digest pending handoff, battle seed, result and settlement identity with Activity state v3/v5.
75. Goal 06 replay v3 evidence — component-addressed replay v3, six-field nested identity and ordered first-divergence verification.
76. Goal 06 construction and event codec — unified battle construction and replay event-payload v2 migration.
77. Goal 06 assembly key and cache — immutable catalog composition, canonical assembly keys and bounded non-authoritative caching.
78. Goal 06 current Activity snapshot — typed contribution, lifecycle, progression and participant-carry projection.
79. Goal 06 atomic dynamic battle start — snapshot assembly and atomic pending-battle sealing.
80. Goal 06 assembly failure hardening — stale, invalid, budget, cache and retry state/RNG preservation.
81. Goal 06 transition battle fixtures — representative inventory, lifecycle, progression, carry and provenance transitions.
82. Goal 06 dynamic CLI and replay — dynamic-only baseline execution and CLI replay-v3 round trips.
83. Goal 06 Agent and MCP migration — shared per-battle assembly without changing transport authority.
84. Goal 06 replay reconstruction parity — fresh per-battle reconstruction and CLI/Agent/MCP trace parity.
85. Goal 06 performance hardening — identity, cold/warm assembly, eviction and concurrent-service baselines.
86. Goal 06 native matrix hardening — 33-run replay-v3 matrix, corruption corpus and native CI contract.
87. Goal 06 release contract — frozen runtime revisions, evidence denominators and retained Goal 07 scope.
88. Goal 07 foundation — Goal 06 prerequisite, inherited 2,201/786/78 denominator and Excel/openpyxl/Sora authoring contract.
89. Goal 07 retained-mechanic audit — exact-once family, primitive, evidence-gap and terminal-disposition audit for content, rules, fixtures, enemies and encounters.
90. Goal 07 content partitions — 104 bounded generated content batches and the exact-once 121-batch execution denominator.
91. Goal 07 Phase 0 baseline — external decisions, named enemy numeric approximation, six performance workloads, zero-new-dependency baseline and release scaffold.
92. Goal 07 trigger timing and cause runtime — executable phase/point matrix, bounded once scopes, complete cause attribution and fail-closed replacement proposals.
93. Selector and target-set runtime boundary — executable predicates, snapshots, deterministic ordering, weighted draws and empty-pool control.
94. Goal 07 modifier-stage and snapshot runtime — executable stat/formula stages, authored stacking comparators, lifecycle snapshots and production Excel/Sora evidence.
95. Goal 07 effect, state and lifecycle runtime — authoritative slot resets, effect stacking, DoT ticks/detonations, duration clocks, teardown and formal Excel/Sora evidence.
96. Goal 07 action, reaction, Break and boundary runtime — persistent extra turns, semantic reaction ordering, Break hooks, executable wave/phase programs and compatibility revisions.
97. Goal 07 shared capability and content gates — executable shared-probe matrix, zero-handler admission contract and ordered exact-coverage receipts for all 104 content batches.
98. Goal 07 Ability Tree partition S01 — first Ability Tree partition authoring and executable run/battle capabilities.
99. Goal 07 Ability Tree partition S02 — battle modifiers, Resonance resources and Formation-boundary execution.
100. Goal 07 Ability Tree partition S03 — generic Formation capacity, Reviver carry and consumable authorization.
101. Goal 07 Preservation partition S01 — exact Quake composition, Macrosegregation shield lifecycle, splash, Bleed and shared core primitives.
102. Goal 07 Preservation partition S02 — dynamic shield-to-ATK, turn-end and provider shields, directional shield modifiers and Blessing-count DEF.
103. Goal 07 Preservation partition S03 — battle-start and action-loss shields, Break-triggered team shields, shield-gated mitigation and bounded cleansing.
104. Goal 07 Preservation partition S04 — shield-conditioned critical stats, Resonance and all Preservation Formations.
105. Goal 07 Remembrance partition S01 — Freeze, Dissociation, effect resistance and duration behavior.
106. Goal 07 Remembrance partition S02 — adjacent damage, timed Weakness, resistance reduction and battle-start effects.
107. Goal 07 Remembrance partition S03 — HP thresholds, action-scoped modifiers and shared critical draws.
108. Goal 07 Remembrance partition S04 — Resonance, Eonian Freeze, Energy and Shield Formations.
109. Goal 07 Nihility partition S01 — Suspicion lifecycle, DoT detonation/transfer and stack-backed debuffs.
110. Goal 07 Nihility partition S02 — Break efficiency/propagation, random DoTs, selected detonation and Blessing-count DoT scaling.
111. Goal 07 Nihility partition S03 — Break damage, Effect RES, DoT vulnerability/duration and dynamic DoT-stack vulnerability.
112. Goal 07 Nihility partition S04 — team healing/Energy from DoTs, Resonance statuses, Confusion, Devoid and all Nihility Formations.
113. Goal 07 release contract — frozen 121-batch ledger, terminal mechanics denominators, audit/native/performance evidence and immutable completion boundary.
114. Goal 14 release contract — complete Gold and Gears runtime coverage, replay/surface parity, hardening, performance, native CI and immutable completion boundary.
115. Gold and Gears public API migration — pre-1.0 facade contraction, retained caller surface and exact public re-export drift enforcement.
116. Goal 20 coverage and release contract — frozen Swarm Disaster matrix, policy owners, performance workloads, native CI and release gates.
117. Goal 20 release contract — complete Swarm Disaster runtime coverage, replay/surface parity, hardening, performance and immutable completion boundary.

Delivery boundary

The documentation target covers the complete core model even when implementation is staged. A playable headless vertical slice should exercise:

• two teams, waves, defeat, victory, and deterministic target selection;
• Basic ATK, Skill, Ultimate, passive triggers, follow-up actions, and enemy actions;
• HP, ATK, DEF, SPD, CRIT, DMG Boost, RES, Effect Hit Rate/RES, Break Effect, Energy, and Skill Points;
• the Action Gauge timeline and action advance/delay;
• single-target, Blast, AoE, and Bounce target patterns;
• multi-hit attacks, per-hit CRIT, damage, healing, shields, buffs, debuffs, and DoT;
• elemental weaknesses, Toughness, Weakness Break, and the seven base break effects;
• replayable seeded RNG and a serializable battle log;
• at least one summon or memosprite, transformation, special resource, Exo-Toughness interaction, multi-phase boss, and mode-supplied rule bundle;
• a Standard encounter and representative Memory of Chaos, Pure Fiction, and Apocalyptic Shadow challenge stages using the same combat core.

Multi-layer Toughness, Exo-Toughness, summons/memosprites, special resources, Super Break providers, boss phases, and universe-mode rules are no longer deferred from the architecture. They may be delivered after the first vertical slice, but their data and lifecycle contracts are normative now. A feature is not considered implemented merely because an ID or short profile exists; use the coverage states in Content data and coverage.

Intellectual-property boundary

Use these documents as a mechanics study and implementation reference. Do not copy proprietary assets, story text, voice, extracted client code, or redistributed game data. Prefer original identifiers and test fixtures in the implementation.