godot-genre-fighting

NEVER Do (Expert Anti-Patterns)

Frame-Data & Logic

• NEVER use variable framerates; strictly lock logic to a Deterministic Fixed Loop (using _physics_process with a frame-counter) and call reset_physics_interpolation() on teleport.
• NEVER use standard Physics for hit detection; strictly use PhysicsDirectSpaceState.intersect_shape() to query hitboxes instantly without Area2D signal lag.
• NEVER skip Damage Scaling; strictly apply 10% reduction per hit in a combo to prevent infinite matches.
• NEVER make all moves safe on block; strictly ensure high-reward moves have Recovery Windows where the attacker is punishable.
• NEVER rely on Area2D.get_overlapping_areas(); strictly use intersect_shape() for immediate, frame-perfect resolution.
• NEVER forget Hitbox Proximity (Proximity Guard); strictly trigger guard states when a hitbox enters a nearby zone, even if it hasn't landed.

Character & Animation

• NEVER use simple parenting (scale.x = -1) for character flip; strictly adjust the dedicated Visuals node while managing hitbox offsets programmatically.
• NEVER use string-based animation triggers; strictly use AnimationMixer with ADVANCE_MANUAL for frame-synced playback.
• NEVER use yield or await for frame-critical logic; strictly use Integer Frame Counting within state machines to manage recovery/startup windows perfectly.
• NEVER store frame data in raw scripts; strictly use Resource files (.tres) with delegated logic for damage scaling, cancels, and combo-state tracking.
• NEVER use deep node hierarchies for character parts; strictly keep skeletons shallow to reduce transformation overhead.

Input & Networking

• NEVER skip Input Buffering; strictly implement a 5-10 frame buffer to ensure lenient, responsive execution for the player.
• NEVER leave Input.use_accumulated_input enabled; strictly disable it to preserve sub-frame timing for precise combo links.
• NEVER use client-side hit detection for netplay; strictly use rollback netcode or server validation to prevent desyncs.
• NEVER use standard TCP for multiplayer; strictly use UDP/ENet to avoid head-of-line blocking during latency spikes.
• NEVER rely on the SceneTree for fighter transforms in netplay; strictly manage positions in a serializable data buffer.

---

🛠 Expert Components (scripts/)

MANDATORY reads before implementing the matching system:

1. fighting_input_buffer.gd — buffers + motion (QCF/DP)
2. direct_hitbox_query.gd — exclusive hit resolution path (intersect_shape)
3. rollback_state_serializer.gd — snapshot/restore for netplay

Original Expert Patterns

• fighting_input_buffer.gd - Frame-locked input engine (60fps) with motion command fuzzy matching (QCF/DP).
• hitbox_component.gd - Hitbox/hurtbox volume helper (layers High/Low/Throw) — resolve hits via direct_hitbox_query, not Area signals.

Modular Components

• deterministic_physics_loop.gd - Custom loop pattern for frame-perfect game state progression.
• direct_hitbox_query.gd - PhysicsServer shape-casting for immediate collision resolution.
• hit_stop_controller.gd - Dynamic time-scale manipulation for "impact" feel.
• manual_animation_advancer.gd - Frame-synced animation control via manual delta processing.
• rollback_state_serializer.gd - Serialization logic for managing discrete game state snapshots.
• bitwise_state_flags.gd - High-performance bitwise flags for fighter state tracking.
• input_accumulation_control.gd - Toggle for disabling Godot's input accumulation for sub-frame timing.
• raw_byte_network_sync.gd - UDP-based state synchronization for netplay efficiency.
• string_name_optimization.gd - Pattern for using pointer-level StringName comparisons in AI states.
• round_timer_logic.gd - Logic for frame-synced match timers and timeout triggers.

Restored from baseline (load on demand)

• attack_resource.gd - .tres frame-data Resource (startup/active/recovery, advantage).
• combo_tracker.gd - Damage scaling (~10%/hit) and combo state.
• fighter_state_machine.gd - IDLE/ATTACKING/HITSTUN with integer state_frame.
• fight_game_state.gd - Serializable rollback snapshot shell (pair with rollback_state_serializer.gd).
• move_set_loader.gd - JSON move-list loader for designer iteration.
• frame_advancer.gd - @tool editor frame scrubber for hitbox alignment.
• fighter_balance_profile.gd - Per-roster damage/movement/defense scaling Resource.

---

Core Loop

Neutral → Confirm Hit → Combo → Advantage → Repeat

Decision Trees (no Area2D / inline system dumps)

Frames & fixed loop

Need	Action
Attack timing Resource	.tres with startup/active/recovery/advantage — not script constants
60fps sim step	deterministic_physics_loop.gd
Anim sync to frames	manual_animation_advancer.gd (ADVANCE_MANUAL)

Input

Need	Action
5–10f buffer + QCF/DP	MANDATORY fighting_input_buffer.gd
Sub-frame links	input_accumulation_control.gd — disable accumulated input

Hitboxes

Need	Action
Frame-perfect hit	MANDATORY exclusively direct_hitbox_query.gd
Volume authoring helper	hitbox_component.gd for shapes/layers — never area_entered / get_overlapping_areas for resolution
Proximity guard	Query expanded shape before active frames land

Combos / cancels

Need	Action
Damage scaling ~10%/hit	Track in combo state; store cancel hierarchy on Attack Resources
States	IDLE/ATTACKING/HITSTUN/BLOCKSTUN… with integer state_frame — peer godot-state-machine-advanced

Netcode

Need	Action
Snapshots	MANDATORY rollback_state_serializer.gd
Transport	UDP/ENet via raw_byte_network_sync.gd; peer godot-multiplayer-networking

---

Balance Guidelines

Element	Guideline
Health	10,000-15,000 for ~20 second rounds
Combo damage	Max 30-40% of health per touch
Fastest moves	3-5 frames startup (jabs)
Slowest moves	20-40 frames (supers, overheads)
Throw range	Short but reliable
Meter gain	Full bar in ~2 combos received

For roster / matchup simulation, use godot-monte-carlo-balancer.

Common Pitfalls

Pitfall	Solution
Infinite combos	Hitstun decay + gravity scaling
Area2D signal hits	Replace with direct_hitbox_query.gd
Lag input drops	Buffer 8+ frames
Desync	Deterministic loop + rollback serializer

Expert knowledge (on demand)

LLM-ignorance rule: If a general agent would not know it before reading, load the reference — never delete expert deltas.

• expert-fighting-patterns.md — restored baseline pedagogy (architecture, WHY, implementation depth)
• attack_resource.gd
• combo_tracker.gd
• fighter_state_machine.gd
• fight_game_state.gd
• move_set_loader.gd
• frame_advancer.gd
• fighter_balance_profile.gd

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing work to a peer domain — do not preload the whole lattice.

Official Documentation

• Idle and physics processing — Fighting logic must run on a fixed physics tick (or custom frame counter), not variable _process deltas.
• Input — Disable use_accumulated_input and sample actions per frame so buffers and motion windows stay deterministic.
• Input examples — Action maps and event handling patterns behind 5–10 frame buffers and motion detection.
• Controllers, gamepads, and joysticks — Stick deadzones and digital gate thresholds for clean QCF/DP direction history.
• Using Area2D — Hitbox/hurtbox volumes, monitoring vs monitorable, and why signal lag is often too late for frame-perfect trades.
• Physics introduction — Collision layers/masks for High/Low/Throw filtering instead of string groups in the hot path.
• PhysicsDirectSpaceState2D — Immediate intersect_shape hit resolution without waiting on Area2D overlap signals.
• PhysicsShapeQueryParameters2D — Shape query setup (mask, exclude, collide_with_areas) for direct hitbox checks.
• AnimationMixer — ADVANCE_MANUAL / callback mode so attack clips advance in lockstep with integer frame data.
• Resources — Store startup/active/recovery, cancels, and balance profiles as .tres data—not hardcoded script constants.
• High-level multiplayer — Authority, RPCs, and peer roles when adding netplay around a deterministic fighter sim.
• ENetMultiplayerPeer — UDP/ENet transport for rollback-friendly input exchange without TCP head-of-line blocking.

Related Skills

Prerequisites

• godot-project-foundations — Physics tick rate, input map, and project defaults must be locked before frame-data systems stay deterministic.
• godot-input-handling — Action sampling, device mapping, and buffer-friendly input plumbing under motion commands and cancels.
• godot-2d-physics — Layers/masks and direct space queries are the substrate for hitbox/hurtbox resolution without Area signal lag.
• godot-characterbody-2d — Grounded movement, facing, and teleport/reset_physics_interpolation contracts fighters still need outside pure hit detection.

Complements

• godot-combat-system — Shared DamageData / hit confirm patterns that fighting frame data specializes into startup-active-recovery windows.
• godot-animation-player — Hitbox enable tracks, cancel frames, and recovery locks driven from animation rather than free-running timers.
• godot-state-machine-advanced — IDLE/ATTACKING/HITSTUN/BLOCKSTUN FSMs with integer state_frame counters instead of await-based recovery.
• godot-resource-data-patterns — Move lists, cancel tables, and FighterBalanceProfile resources with safe duplication per fighter instance.
• godot-signal-architecture — Hit confirm, round end, and HUD events without coupling the sim loop to presentation nodes.
• godot-multiplayer-networking — Peer sync, RPC discipline, and authoritative validation around rollback or delayed-input netcode.
• godot-adapt-single-to-multiplayer — Prediction, reconciliation, and lobby/late-join patterns when a local fighter becomes netplay-ready.

Downstream / consumers

• godot-monte-carlo-balancer — Simulate matchup matrices, damage scaling, and punish windows across the roster instead of guessing from AFK→pro PvE bands.

Master

• godot-master — Library router and mirrored module entry for discovering fighting peers and syncing shared script mirrors.