Hockey Faceoff System Documentation

Overview

A complete faceoff and puck possession system for your hockey game with realistic physics, visual indicators, and AI-ready mechanics.

📦 Components Created

1. PuckController.cs

Controls the puck physics and possession mechanics.

Features:

Realistic hockey puck physics (170g mass, low friction)
Automatic possession detection via trigger colliders
Visual feedback (different materials for possessed/free states)
Smooth carrying while player has possession
Physics-based shooting and passing

Key Properties:

possessionRadius: Distance within which players can pick up the puck (default: 1.5m)
carrierOffset: How far in front of player the puck stays when carried (default: 1.0m)

2. FaceoffManager.cs

Manages the entire faceoff sequence and outcome determination.

Faceoff Outcomes:

Home Win: Home center wins cleanly, puck passed to teammate (usually defender)
Away Win: Away center wins cleanly, puck passed to teammate (usually defender)
Struggle: Close contest, puck bounces loose, scramble ensues

How Outcomes Are Determined:

Faceoff Strength = (Strength × 0.3) + (Stick Handling × 0.3) + 
                   (Awareness × 0.2) + (Agility × 0.2)

Plus random variation (±10 points) for unpredictability.

Testing: Press F key during play mode to trigger a faceoff.

3. PlayerController.cs (Updated)

Enhanced with puck interaction methods.

New Methods:

GainPuck(PuckController): Called when player gains possession
ReleasePuck(): Called when player loses possession
CanPickupPuck(): Checks if player can currently pick up puck
SetFrozen(bool): Freeze/unfreeze player during faceoff
Shoot(direction, power): Fire the puck with physics
Pass(targetPlayer): Pass to specific teammate
Check(targetPlayer): Body check opponent to dislodge puck

Visual Feedback:

Yellow rotating ring appears around player with possession
Makes it instantly clear who controls the puck

🎮 Setup Instructions

Method 1: Manual Setup

Create the Puck:

- Create GameObject → name it "Puck"
- Add PuckController component
- Position at center ice (y ≈ 0.5 for ice level)

Tag Your Players:

- Edit → Project Settings → Tags & Layers
- Add tags: "HomeTeam" and "AwayTeam"
- Select home team players → Inspector → Tag: "HomeTeam"
- Select away team players → Inspector → Tag: "AwayTeam"

Create Faceoff Manager:

- Create Empty GameObject → name it "FaceoffManager"
- Add FaceoffManager component
- Drag Puck into the "Puck" field in Inspector

Verify Centers:
- Ensure one player on each team has Position = "C" (Center)
- The FaceoffManager auto-detects centers by tag and position

Method 2: Auto Setup (Recommended)

Create an empty GameObject
Add FaceoffSetupGuide component
Drag home team players into "Home Team Players" array
Drag away team players into "Away Team Players" array
Right-click component → "Auto-Setup Faceoff System"
Right-click component → "Validate Setup" to check everything

🏒 How It Works

Possession System

Puck States:

Loose: No one has possession, slides freely on ice
Carried: Attached to a player, moves with them

Gaining Possession: Player automatically picks up puck when:

Player is within possessionRadius (1.5m)
Puck is loose (not carried by anyone)
Player can pickup (not on cooldown, not frozen)
Puck enters player's trigger collider

Visual Indicator:

Yellow ring with emission around player = has puck
Ring rotates continuously for visibility

Faceoff Sequence

1. FaceoffManager.StartFaceoff() called
   ↓
2. Puck positioned at faceoff spot
   ↓
3. All players frozen (prevent movement)
   ↓
4. Calculate outcome based on center stats
   ↓
5. Execute outcome:
   - Clean Win: Puck passed to defender
   - Struggle: Puck bounces loose
   ↓
6. Unfreeze all players
   ↓
7. Game continues

Timing:

Wind-up: 1 second
Faceoff duration: 2 seconds
Struggle duration: 3 additional seconds

Physics Details

Puck Properties:

Mass: 0.17 kg (170g, regulation weight)
Radius: 0.038m (76mm diameter)
Friction: 0.3 (simulates ice)
Bounciness: 0.2 (minimal bounce)

Force Ranges:

Pass: 10-25 N (scales with distance)
Shot: ~30 N × power stat
Faceoff launch: 5-15 N

🎯 Integration Examples

Example 1: Start Faceoff at Game Start

public class GameManager : MonoBehaviour
{
    private FaceoffManager faceoffManager;
    
    void Start()
    {
        faceoffManager = FindObjectOfType<FaceoffManager>();
        
        // Start game with center ice faceoff
        Vector3 centerIce = new Vector3(0, 0.5f, 0);
        faceoffManager.InitiateFaceoff(centerIce);
    }
}

Example 2: Player Shoots on Goal

public class PlayerAI : MonoBehaviour
{
    private PlayerController playerController;
    private Transform goal;
    
    void ShootAtGoal()
    {
        if (playerController.HasPuck())
        {
            Vector3 shootDirection = (goal.position - transform.position).normalized;
            playerController.Shoot(shootDirection, powerMultiplier: 1.0f);
        }
    }
}

Example 3: Pass to Open Teammate

public void PassToOpenPlayer()
{
    if (!playerController.HasPuck()) return;
    
    PlayerController[] teammates = FindTeammates();
    PlayerController bestTarget = FindMostOpen(teammates);
    
    if (bestTarget != null)
    {
        playerController.Pass(bestTarget);
    }
}

Example 4: Defensive Check

void OnCollisionEnter(Collision collision)
{
    PlayerController opponent = collision.gameObject.GetComponent<PlayerController>();
    
    if (opponent != null && opponent.HasPuck() && IsOpponent(opponent))
    {
        playerController.Check(opponent);
    }
}

🔧 Customization

Adjust Faceoff Difficulty

In FaceoffManager.cs:

[SerializeField] private float struggleChance = 0.3f; // 30% base struggle chance
[SerializeField] private float winThreshold = 0.7f;    // Higher = more clear wins needed

Change Puck Physics

In PuckController.cs:

[SerializeField] private float friction = 0.3f;  // Lower = slides further
[SerializeField] private float drag = 0.5f;      // Higher = stops faster

Modify Possession Range

In PuckController.cs:

[SerializeField] private float possessionRadius = 1.5f; // Detection range

🐛 Troubleshooting

Puck doesn't get picked up

Check that player has trigger collider
Verify CanPickupPuck() returns true
Check pickup cooldown hasn't expired

Faceoff doesn't start

Verify both centers are tagged correctly
Check console for error messages
Run "Validate Setup" in FaceoffSetupGuide

Players don't freeze during faceoff

Ensure PlayerController has SetFrozen() method
Check that player movement script respects frozen state

Possession indicator doesn't show

Verify possessionIndicator GameObject is created in PlayerController.Start()
Check that Update() is being called

📊 Stats That Matter

For Faceoffs:

Strength (30%): Physical dominance
Stick Handling (30%): Puck control
Awareness (20%): Reading the drop
Agility (20%): Quick reactions

For Shooting:

Shot Accuracy: Determines spread angle
Shot Power: Determines puck velocity

For Passing:

Pass Accuracy: Determines pass precision

For Checking:

Checking: Success rate of dislodging puck

🎨 Visual Enhancements (Optional)

Add Trail to Puck:

TrailRenderer trail = puck.gameObject.AddComponent<TrailRenderer>();
trail.time = 0.5f;
trail.startWidth = 0.1f;
trail.endWidth = 0.02f;

Add Particles When Puck is Hit:

// In PuckController.OnCollisionEnter()
ParticleSystem.Emit(5); // Ice spray effect

Change Possession Ring Color by Team:

if (CompareTag("HomeTeam"))
    possessionIndicator.GetComponent<Renderer>().material.color = Color.blue;
else
    possessionIndicator.GetComponent<Renderer>().material.color = Color.red;

🚀 Next Steps

Add Goalie: Extend PlayerController for goalie-specific behavior
Implement Offsides: Check puck/player positions
Add Icing: Detect long-range clears
Improve AI: Use puck position in decision-making
Add Penalties: Faceoff after penalty ends
Post-Goal Faceoffs: Return to center after scoring

Summary

You now have: ✅ Physics-based puck with realistic ice behavior
✅ Clear visual indication of possession (yellow ring)
✅ Faceoff system with 3 outcomes based on player stats
✅ Ready-to-use shooting, passing, and checking mechanics
✅ Easy integration with your existing player system

Test it: Press F in play mode to see a faceoff in action!

FACEOFF_SYSTEM_README.md 8.9 KB 文件歷史 原始文件