Godot Genre Sports

NEVER Do (Expert Anti-Patterns)

Physics & Ball Interaction

• NEVER parent the ball directly to a player Transform; strictly keep it a standalone RigidBody3D and use apply_central_impulse() for realistic dribble physics.
• NEVER allow the ball to "Tunnel" through goals; strictly enable Continuous CD (continuous_cd = true) on the ball's properties for high-velocity validation.
• NEVER scale a CollisionShape3D non-uniformly; strictly adjust the resource radius to preserve the internal moment of inertia.
• NEVER apply impulses in _process(); strictly use _physics_process() or _integrate_forces() to prevent visual jitter.
• NEVER use a single collision shape for characters; strictly use layered shapes for Head, Torso, and Legs to enable headers and chest-traps.

Match & Team AI

• NEVER allow all AI to chase the ball ("Kindergarten Soccer"); strictly implement Formation Slots (Defense/Attack) where only the closest 1-2 players engage.
• NEVER use perfect goalkeeper reflexes; strictly add a Reaction Delay (0.2s-0.5s) and an "Error Rate" based on shot angle and velocity.
• NEVER ignore Root Motion for movement; strictly use AnimationTree with root motion to ensure momentum and turns are visually grounded.
• NEVER trust client-side goal validations; strictly require the Authoritative Server to validate physics and score logic.

Implementation & Sync

• NEVER rely on the default physics tick rate (60 TPS) for fast-moving ballistics; strictly increase physics_ticks_per_second (e.g., to 120 or 240) to prevent tunneling.
• NEVER leave Physics Interpolation disabled if you want broadcast-quality smoothness; enable it in Project Settings to smooth ball transforms between ticks on high-refresh monitors.
• NEVER skip vector normalization on joystick input; strictly normalize to prevent diagonal movement from being 1.4x faster.
• NEVER handle contextual buttons with is_action_pressed(); strictly use a ContextManager to determine if Button A means "Pass", "Tackle", or "Switch".
• NEVER evaluate an Area3D goal trigger immediately; strictly await get_tree().physics_frame to allow the Physics Server to sync.

Ball Possession Decision Tree

Default for this skill: impulse dribble. Magnetic stickiness is a last resort for pure arcade genres and must remain a free RigidBody.

🛠 Expert Components (scripts/)

MANDATORY — read the script that matches the task before coding:

• Goals / match phases → sports_umpire_logic.gd
• Full flight model (drag + Magnus via _integrate_forces) → sports_ball_physics.gd
• Lean Magnus-only curve (simpler attach) → magnus_ball_physics.gd — choose one ball script, not both
• Formations / kindergarten-soccer fix → team_manager.gd
• Temporary buffs / powerups → stat_modifier_powerup.gd
• Shared impulse/score helpers → sports_patterns.gd

Broadcast camera: not implemented in this skill’s scripts/. Use peer godot-camera-systems for broadcast framing / zoom-on-action.

Do NOT Load every sports script for one task.

Ball Physics (pick one)

• sports_ball_physics.gd - High-fidelity Magnus + air drag via custom integrator (continuous_cd ready).
• magnus_ball_physics.gd - Leaner Magnus-only force helper when drag is handled elsewhere.

Match / Team / Meta

• sports_umpire_logic.gd - Goal Area3D + match state machine (PRE_GAME / ACTIVE / POST_GOAL).
• team_manager.gd - Formation Slots and team strategy switching.
• stat_modifier_powerup.gd - Temporary player/stat modifiers for arcade powerups.
• sports_patterns.gd - Physics-safe impulses and authoritative scoring helpers.

Skill Chain

Architecture Overview

1. The Ball (Physics Core)

The most important object. Must feel right.

# ball.gd
extends RigidBody3D

@export var drag_coefficient: float = 0.5
@export var magnus_effect_strength: float = 2.0

func _integrate_forces(state: PhysicsDirectBodyState3D) -> void:
    # Apply Air Drag
    var velocity = state.linear_velocity
    var speed = velocity.length()
    var drag_force = -velocity.normalized() * (drag_coefficient * speed * speed)
    state.apply_central_force(drag_force)
    
    # Magnus Effect (Curve)
    var spin = state.angular_velocity
    var magnus_force = spin.cross(velocity) * magnus_effect_strength
    state.apply_central_force(magnus_force)

2. Team AI (Formations)

AI players don't just run at the ball. They run to positions relative to the ball/field.

# team_manager.gd
extends Node

enum Strategy { ATTACK, DEFEND }
var current_strategy: Strategy = Strategy.DEFEND
var formation_slots: Array[Node3D] # Markers parented to a "Formation Anchor"

func update_tactics(ball_pos: Vector3) -> void:
    # Move the entire formation anchor
    formation_anchor.position = lerp(formation_anchor.position, ball_pos, 0.5)
    
    # Assign best player to each slot
    for player in players:
        var best_slot = find_closest_slot(player)
        player.set_target(best_slot.global_position)

3. Match Manager

The referee logic.

# match_manager.gd
var score_team_a: int = 0
var score_team_b: int = 0
var match_timer: float = 300.0
enum State { KICKOFF, PLAYING, GOAL, END }

func goal_scored(team: int) -> void:
    if team == 0: score_team_a += 1
    else: score_team_b += 1
    current_state = State.GOAL
    play_celebration()
    await get_tree().create_timer(5.0).timeout
    reset_positions()
    current_state = State.KICKOFF

Key Mechanics Implementation

Contextual Input

"A" button does different things depending on context.

func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("action_main"):
        if has_ball:
            pass_ball()
        elif is_near_ball:
            slide_tackle()
        else:
            switch_player()

Steering Behaviors

For natural movement (Seek, Flee, Arrive).

func seek(target_pos: Vector3) -> Vector3:
    var desired_velocity = (target_pos - global_position).normalized() * max_speed
    var steering = desired_velocity - velocity
    return steering.limit_length(max_force)

Godot-Specific Tips

• NavigationServer3D: Essential for avoiding obstacles (other players/referee).
• AnimationTree (BlendSpace2D): Crucial for sports. You need smooth blending between Idle -> Walk -> Jog -> Sprint in all directions.
• PhysicsMaterial: Tune bounce and friction on the Ball and Field colliders carefully.

Common Pitfalls

1. AI Bunching: All 22 players running at the ball (Kindergarten Soccer). Fix: Use Formation Slots. Only 1-2 players "Press" the ball; others cover space.
2. Magnetic Ball: Ball sticks to player too perfectly. Fix: Use a "Dribble" mechanic where the player kicks the ball slightly ahead physics-wise, rather than parenting it.
3. Unfair Goalies: Goalie reacts instantly. Fix: Add a "Reaction Time" delay and "Error Rate" based on shot speed/stats.

Advanced Sports Meta-Systems

Professional implementation of animation synchronization, spatial intelligence, and collision filtering.

1. Root-Motion-Transition (AnimationTree)

Utilize the AnimationMixer class (and its derivatives like AnimationTree) to extract root motion from complex animations. This ensures that the character's physical displacement is driven directly by the animation data, preventing "skating" and ensuring momentum is visually grounded during high-speed turns or shots.

class_name SportsCharacter extends CharacterBody3D

@onready var anim_tree: AnimationTree = $AnimationTree

func _physics_process(_delta: float) -> void:
    # Extract root motion from the current animation state
    var root_motion := anim_tree.get_root_motion_position()
    # Apply to velocity for physics-synced movement
    velocity = (global_transform.basis * root_motion) / _delta
    move_and_slide()