hitstun-recover · diff
git:20260912.28c7171 to git:20260912.329d840
24 added, 22 removed. Audit A to A.
---
name: hitstun-recover
- description: How long the victim cannot act after a hit. Hitstop freezes two clocks. Hitstun is only the victim. Ask light-stun vs knockdown vs juggle vs none. Tune so a punish exists and a combo still ends.
+ description: Use when hitstun, blockstun, frame advantage, knockdown recovery or a suspected infinite combo needs an explicit timing contract.
---
# Hitstun and recover
- Ask the column:
+ Resolve the column from the project before tuning:
| Column | After the hit |
|---|---|
- | none | flinch pose only |
- | light-stun | short no-act, then turn |
- | knockdown | downed + wakeup |
- | juggle | air state until ground |
+ | none | flinch presentation, no action lock |
+ | light-stun | timed action lock, then legal actions |
+ | knockdown | downed state plus authored wakeup options |
+ | juggle | airborne state with explicit landing and escape rules |
- Hitstop ≠ hitstun. Hitstop is the freeze on both colliding ActorClocks (`action-feel`). Hitstun starts when that freeze hits 0.
+ Hitstop and hitstun are different. Under [action-feel](../action-feel/SKILL.md), each affected actor pauses its move clock during hitstop while simulation input sampling continues. Count that actor's remaining stun or recovery on its advancing ticks, not render frames. Publish exceptions for asymmetric hitstop or other clock policies.
- ## Numbers are data, not a franchise
+ ## Timing contract
- Write on the attack: hitstop, hitstun, blockstun, knockdown time, wakeup invuln.
- A starting band at 60 Hz (change per column):
+ Record hitstop per participant, hitstun, blockstun, remaining active/recovery at impact, knockdown duration and wakeup invulnerability. Use half-open intervals `[start, end)` and a declared logical frequency. Do not assume wakeup invulnerability or blockstun shorter than hitstun for every design.
- - light poke: hitstop 6-10f, hitstun 10-16f
- - medium: hitstop 10-14f, hitstun 16-24f
- - heavy / launcher: hitstop 12-20f, hitstun or launch 24-40f
- - wakeup: 4-10f invuln then punishable
+ Frame advantage = victim first-action tick minus attacker first-action tick, measured on the same global simulation timeline. Positive means the attacker can act first. Only with equal freezes and matching interval conventions can this simplify to stun minus the attacker's remaining commitment at impact; total move recovery alone can miss remaining active frames.
- If hitstun ≥ attacker recovery + walk-in, the victim never gets a turn. That is only legal on a published combo column with an ender.
+ Positive advantage is not proof of a true combo or an infinite. Also check follow-up startup, walk-in time, range, cancel conditions, target state and escape options. Resolve simultaneous contact/action boundaries with the project's explicit priority rule.
- ## Rules
+ Example: an attacker is free at tick 108, the victim at 116, but the next attack first contacts at 120. The attacker has eight ticks of advantage and still leaves a four-tick gap:
- 1. Same logic frame as pose, box, and SFX.
- 2. Blockstun is shorter than hitstun unless the column is guard-crush.
- 3. Armor / hyper-armor cuts or ignores hitstun. Publish which moves have it. See enemy-kit-balance.
- 4. Status freeze is not hitstun. See status-ailment.
- 5. Do not balance an enemy by secretly growing player hitstun. Patch the enemy kit.
+ ```json
+ {
+ "attacker_first_action_tick": 108,
+ "victim_first_action_tick": 116,
+ "followup_first_contact_tick": 120,
+ "advantage_ticks": 8,
+ "gap_ticks": 4
+ }
+ ```
+ An infinite requires a repeatable route with no escape or terminating resource/state condition; one inequality or damage scaling alone does not establish that.
+
## Accept
- A light hit lets the victim block or walk before the next heavy. A dropped combo returns turn inside published recovery. Turning juice off does not change the counts.
+ Log both first-action ticks, follow-up contact and the defender's earliest legal reply. Test a true link, a gap, a whiff, asymmetric hitstop, knockdown and recovery after interruption. Turning visual effects off must not change the counts. Document which scenarios ran; arithmetic/documentation checks alone do not prove engine behavior.