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

Input

Hitboxes

Combos / cancels

Netcode

---

Balance Guidelines

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

Common Pitfalls