godot-genre-fighting

NEVER Do (Expert Anti-Patterns)

Frame-Data & Logic

• NEVER use variable framerates; strictly lock logic to a Deterministic Fixed Loop (using physicsprocess with a frame-counter) and call resetphysicsinterpolation() 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.getoverlappingareas(); 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.useaccumulatedinput 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. [fightinginputbuffer.gd](scripts/fightinginputbuffer.gd) — buffers + motion (QCF/DP)
2. [directhitboxquery.gd](scripts/directhitboxquery.gd) — exclusive hit resolution path (intersect_shape)
3. [rollbackstateserializer.gd](scripts/rollbackstateserializer.gd) — snapshot/restore for netplay

Original Expert Patterns

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

Modular Components

• [deterministicphysicsloop.gd](scripts/deterministicphysicsloop.gd) - Custom loop pattern for frame-perfect game state progression.
• [directhitboxquery.gd](scripts/directhitboxquery.gd) - PhysicsServer shape-casting for immediate collision resolution.
• [hitstopcontroller.gd](scripts/hitstopcontroller.gd) - Dynamic time-scale manipulation for "impact" feel.
• [manualanimationadvancer.gd](scripts/manualanimationadvancer.gd) - Frame-synced animation control via manual delta processing.
• [rollbackstateserializer.gd](scripts/rollbackstateserializer.gd) - Serialization logic for managing discrete game state snapshots.
• [bitwisestateflags.gd](scripts/bitwisestateflags.gd) - High-performance bitwise flags for fighter state tracking.
• [inputaccumulationcontrol.gd](scripts/inputaccumulationcontrol.gd) - Toggle for disabling Godot's input accumulation for sub-frame timing.
• [rawbytenetworksync.gd](scripts/rawbytenetworksync.gd) - UDP-based state synchronization for netplay efficiency.
• [stringnameoptimization.gd](scripts/stringnameoptimization.gd) - Pattern for using pointer-level StringName comparisons in AI states.
• [roundtimerlogic.gd](scripts/roundtimerlogic.gd) - Logic for frame-synced match timers and timeout triggers.

Restored from baseline (load on demand)

• [attackresource.gd](scripts/attackresource.gd) - .tres frame-data Resource (startup/active/recovery, advantage).
• [combotracker.gd](scripts/combotracker.gd) - Damage scaling (~10%/hit) and combo state.
• [fighterstatemachine.gd](scripts/fighterstatemachine.gd) - IDLE/ATTACKING/HITSTUN with integer state_frame.
• [fightgamestate.gd](scripts/fightgamestate.gd) - Serializable rollback snapshot shell (pair with [rollbackstateserializer.gd](scripts/rollbackstateserializer.gd)).
• [movesetloader.gd](scripts/movesetloader.gd) - JSON move-list loader for designer iteration.
• [frameadvancer.gd](scripts/frameadvancer.gd) - @tool editor frame scrubber for hitbox alignment.
• [fighterbalanceprofile.gd](scripts/fighterbalanceprofile.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

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](references/expert-fighting-patterns.md) — restored baseline pedagogy (architecture, WHY, implementation depth)
• [attackresource.gd](scripts/attackresource.gd)
• [combotracker.gd](scripts/combotracker.gd)
• [fighterstatemachine.gd](scripts/fighterstatemachine.gd)
• [fightgamestate.gd](scripts/fightgamestate.gd)
• [movesetloader.gd](scripts/movesetloader.gd)
• [frameadvancer.gd](scripts/frameadvancer.gd)
• [fighterbalanceprofile.gd](scripts/fighterbalanceprofile.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 useaccumulated_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 intersectshape hit resolution without waiting on Area2D overlap signals.
• PhysicsShapeQueryParameters2D — Shape query setup (mask, exclude, collidewith_areas) for direct hitbox checks.
• AnimationMixer — ADVANCEMANUAL / 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/resetphysicsinterpolation 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.