@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/multiplayer-master/SKILL.md

@@ -0,0 +1,727 @@
+---
+name: multiplayer-master
+description: Complete multiplayer game development. Unity Netcode, Photon Fusion, Mirror, real-time sync, lag compensation, matchmaking, and anti-cheat patterns.
+allowed-tools: Read, Write, Edit, Bash, Grep, WebSearch
+---
+
+# Multiplayer Master Skill
+
+> Build production-ready multiplayer games with proper networking architecture.
+
+---
+
+## When to Use
+
+- Building real-time multiplayer games
+- Implementing player synchronization
+- Setting up dedicated servers
+- Creating matchmaking systems
+- Handling lag compensation
+
+---
+
+## Architecture Selection
+
+### Decision Matrix
+
+```
+What type of multiplayer?
+│
+├── Real-time Competitive (FPS, Fighting)
+│   └── Dedicated Server + Netcode/Photon Fusion
+│   └── Tick rate: 64-128 Hz
+│   └── Lag compensation: CRITICAL
+│
+├── Real-time Cooperative (Co-op, MMO)
+│   └── Dedicated Server or Host-based
+│   └── Tick rate: 20-60 Hz
+│   └── Lag compensation: IMPORTANT
+│
+├── Turn-based (Card games, Strategy)
+│   └── Client-Server REST/WebSocket
+│   └── No tick rate needed
+│   └── Lag compensation: NOT NEEDED
+│
+└── Casual/Social
+    └── Host-based (P2P)
+    └── Tick rate: 10-30 Hz
+    └── Lag compensation: MINIMAL
+```
+
+### Framework Comparison
+
+| Framework | Best For | Pros | Cons |
+|-----------|----------|------|------|
+| **Netcode for GameObjects** | Unity-first | Official, well documented | Learning curve |
+| **Photon Fusion** | Fast iteration | Great tools, cloud hosting | Costs at scale |
+| **Mirror** | Self-hosted | Free, flexible | More manual work |
+| **FishNet** | Performance | Fast, modern | Smaller community |
+
+---
+
+## Unity Netcode for GameObjects
+
+### Project Setup
+
+```csharp
+// 1. Install via Package Manager:
+// com.unity.netcode.gameobjects
+
+// 2. Create NetworkManager
+public class GameNetworkManager : NetworkManager
+{
+    public static GameNetworkManager Instance { get; private set; }
+    
+    private void Awake()
+    {
+        Instance = this;
+    }
+    
+    public override void OnServerStarted()
+    {
+        Debug.Log("Server started!");
+        NetworkManager.Singleton.SceneManager.LoadScene("GameScene", LoadSceneMode.Single);
+    }
+    
+    public override void OnClientConnectedCallback(ulong clientId)
+    {
+        Debug.Log($"Client {clientId} connected");
+    }
+}
+```
+
+### NetworkObject & NetworkBehaviour
+
+```csharp
+public class PlayerController : NetworkBehaviour
+{
+    [Header("Movement")]
+    [SerializeField] private float moveSpeed = 5f;
+    
+    // Synced variable - server authoritative
+    private NetworkVariable<Vector3> _networkPosition = new NetworkVariable<Vector3>(
+        readPerm: NetworkVariableReadPermission.Everyone,
+        writePerm: NetworkVariableWritePermission.Server
+    );
+    
+    private NetworkVariable<int> _health = new NetworkVariable<int>(100);
+    
+    public override void OnNetworkSpawn()
+    {
+        if (IsOwner)
+        {
+            // Setup local player
+            Camera.main.GetComponent<CameraFollow>().SetTarget(transform);
+        }
+        
+        _health.OnValueChanged += OnHealthChanged;
+    }
+    
+    void Update()
+    {
+        if (!IsOwner) return;
+        
+        // Client-side input
+        float h = Input.GetAxisRaw("Horizontal");
+        float v = Input.GetAxisRaw("Vertical");
+        Vector3 moveInput = new Vector3(h, 0, v).normalized;
+        
+        if (moveInput.magnitude > 0.1f)
+        {
+            MoveServerRpc(moveInput);
+        }
+    }
+    
+    [ServerRpc]
+    private void MoveServerRpc(Vector3 direction)
+    {
+        // Server validates and applies movement
+        Vector3 newPos = transform.position + direction * moveSpeed * Time.deltaTime;
+        
+        // Validate movement (anti-cheat)
+        if (IsValidMovement(transform.position, newPos))
+        {
+            transform.position = newPos;
+            _networkPosition.Value = newPos;
+        }
+    }
+    
+    private bool IsValidMovement(Vector3 from, Vector3 to)
+    {
+        float maxDistance = moveSpeed * Time.deltaTime * 1.5f; // Allow some tolerance
+        return Vector3.Distance(from, to) <= maxDistance;
+    }
+    
+    private void OnHealthChanged(int oldValue, int newValue)
+    {
+        // Update UI
+        UIManager.Instance.UpdateHealthBar(newValue);
+        
+        if (newValue <= 0)
+        {
+            HandleDeath();
+        }
+    }
+    
+    [ServerRpc]
+    public void TakeDamageServerRpc(int damage, ServerRpcParams rpcParams = default)
+    {
+        _health.Value -= damage;
+        
+        // Notify all clients of damage
+        TakeDamageClientRpc(damage);
+    }
+    
+    [ClientRpc]
+    private void TakeDamageClientRpc(int damage)
+    {
+        // Play damage effects on all clients
+        PlayDamageEffect();
+    }
+}
+```
+
+### NetworkTransform (Position Sync)
+
+```csharp
+// For smooth interpolation, use NetworkTransform component
+// Settings for different game types:
+
+// FPS/Action Game:
+// - Interpolate: ON
+// - Sync Position: X, Y, Z
+// - Sync Rotation: Y only (or X,Y for full aim)
+// - Threshold: 0.001 (high precision)
+
+// Casual Game:
+// - Interpolate: ON
+// - Sync Position: X, Z (no Y if grounded)
+// - Threshold: 0.1 (lower precision OK)
+```
+
+---
+
+## Photon Fusion
+
+### Setup
+
+```csharp
+// 1. Install Photon Fusion from Asset Store
+// 2. Create App ID at photonengine.com
+
+public class FusionBootstrap : MonoBehaviour
+{
+    [SerializeField] private NetworkRunner _runnerPrefab;
+    
+    async void Start()
+    {
+        var runner = Instantiate(_runnerPrefab);
+        
+        await runner.StartGame(new StartGameArgs
+        {
+            GameMode = GameMode.AutoHostOrClient,
+            SessionName = "MyGame",
+            Scene = SceneManager.GetActiveScene().buildIndex,
+            SceneManager = gameObject.AddComponent<NetworkSceneManagerDefault>()
+        });
+    }
+}
+```
+
+### NetworkBehaviour (Fusion style)
+
+```csharp
+public class FusionPlayer : NetworkBehaviour
+{
+    [Networked] public int Health { get; set; } = 100;
+    [Networked] public NetworkString<_32> PlayerName { get; set; }
+    
+    // Tick-aligned input
+    [Networked] private NetworkButtons _buttons { get; set; }
+    
+    public override void FixedUpdateNetwork()
+    {
+        if (GetInput(out NetworkInputData input))
+        {
+            // Process input (runs on both client and server)
+            Vector3 move = new Vector3(input.Direction.x, 0, input.Direction.y);
+            transform.position += move * Runner.DeltaTime * 5f;
+        }
+    }
+    
+    // State change callback
+    public static void OnHealthChanged(Changed<FusionPlayer> changed)
+    {
+        changed.Behaviour.OnHealthChangedLocal();
+    }
+    
+    private void OnHealthChangedLocal()
+    {
+        // Update UI
+    }
+}
+
+// Input structure
+public struct NetworkInputData : INetworkInput
+{
+    public Vector2 Direction;
+    public NetworkButtons Buttons;
+}
+```
+
+---
+
+## Mirror (Open Source)
+
+### Basic Setup
+
+```csharp
+// 1. Install Mirror from Asset Store (FREE)
+
+public class MirrorPlayer : NetworkBehaviour
+{
+    [SyncVar(hook = nameof(OnHealthChanged))]
+    public int health = 100;
+    
+    [SyncVar]
+    public string playerName;
+    
+    void Update()
+    {
+        if (!isLocalPlayer) return;
+        
+        float h = Input.GetAxisRaw("Horizontal");
+        float v = Input.GetAxisRaw("Vertical");
+        
+        if (h != 0 || v != 0)
+        {
+            CmdMove(new Vector3(h, 0, v));
+        }
+    }
+    
+    [Command] // Client → Server
+    void CmdMove(Vector3 direction)
+    {
+        transform.position += direction.normalized * 5f * Time.deltaTime;
+    }
+    
+    [Command]
+    void CmdShoot(Vector3 origin, Vector3 direction)
+    {
+        // Server validates and processes
+        if (Physics.Raycast(origin, direction, out RaycastHit hit, 100f))
+        {
+            if (hit.collider.TryGetComponent<MirrorPlayer>(out var target))
+            {
+                target.TakeDamage(25);
+            }
+        }
+        
+        // Tell all clients to show effect
+        RpcShowShootEffect(origin, direction);
+    }
+    
+    [ClientRpc] // Server → All Clients
+    void RpcShowShootEffect(Vector3 origin, Vector3 direction)
+    {
+        // Spawn tracer, play sound
+    }
+    
+    [Server]
+    public void TakeDamage(int amount)
+    {
+        health -= amount;
+        if (health <= 0)
+        {
+            RpcDie();
+        }
+    }
+    
+    void OnHealthChanged(int oldValue, int newValue)
+    {
+        // Update health UI
+    }
+}
+```
+
+---
+
+## Lag Compensation
+
+### Client-Side Prediction
+
+```csharp
+public class PredictedMovement : NetworkBehaviour
+{
+    private Queue<InputFrame> _inputHistory = new();
+    private Vector3 _lastServerPosition;
+    
+    struct InputFrame
+    {
+        public uint Tick;
+        public Vector3 Input;
+        public Vector3 PredictedPosition;
+    }
+    
+    void Update()
+    {
+        if (!IsOwner) return;
+        
+        // 1. Capture input
+        Vector3 input = new Vector3(
+            Input.GetAxisRaw("Horizontal"),
+            0,
+            Input.GetAxisRaw("Vertical")
+        );
+        
+        // 2. Predict locally
+        Vector3 predictedPos = transform.position + input * moveSpeed * Time.deltaTime;
+        transform.position = predictedPos;
+        
+        // 3. Store for reconciliation
+        _inputHistory.Enqueue(new InputFrame
+        {
+            Tick = NetworkManager.Singleton.LocalTime.Tick,
+            Input = input,
+            PredictedPosition = predictedPos
+        });
+        
+        // 4. Send to server
+        MoveServerRpc(input, NetworkManager.Singleton.LocalTime.Tick);
+    }
+    
+    // When server confirms position
+    private void OnServerPositionReceived(Vector3 serverPos, uint serverTick)
+    {
+        _lastServerPosition = serverPos;
+        
+        // Reconciliation: replay inputs since server tick
+        Vector3 reconciledPos = serverPos;
+        
+        foreach (var frame in _inputHistory.Where(f => f.Tick > serverTick))
+        {
+            reconciledPos += frame.Input * moveSpeed * Time.fixedDeltaTime;
+        }
+        
+        // Check for misprediction
+        if (Vector3.Distance(reconciledPos, transform.position) > 0.01f)
+        {
+            // Correct position smoothly
+            transform.position = Vector3.Lerp(transform.position, reconciledPos, 0.5f);
+        }
+        
+        // Clean old history
+        while (_inputHistory.Count > 0 && _inputHistory.Peek().Tick <= serverTick)
+        {
+            _inputHistory.Dequeue();
+        }
+    }
+}
+```
+
+### Server-Side Rewind (Hit Detection)
+
+```csharp
+public class LagCompensatedCombat : NetworkBehaviour
+{
+    // Store position history for rewind
+    private class PositionSnapshot
+    {
+        public float Timestamp;
+        public Vector3 Position;
+        public Quaternion Rotation;
+    }
+    
+    private Queue<PositionSnapshot> _positionHistory = new();
+    private const int MAX_HISTORY = 64;
+    private const float MAX_REWIND_TIME = 0.5f; // 500ms max
+    
+    void FixedUpdate()
+    {
+        if (IsServer)
+        {
+            // Record position history
+            _positionHistory.Enqueue(new PositionSnapshot
+            {
+                Timestamp = Time.time,
+                Position = transform.position,
+                Rotation = transform.rotation
+            });
+            
+            while (_positionHistory.Count > MAX_HISTORY)
+                _positionHistory.Dequeue();
+        }
+    }
+    
+    [ServerRpc]
+    public void ShootServerRpc(Vector3 origin, Vector3 direction, float clientTimestamp)
+    {
+        // Calculate client's RTT
+        float rtt = NetworkManager.Singleton.NetworkConfig.NetworkTransport.GetCurrentRtt(OwnerClientId) / 1000f;
+        float rewindTime = Mathf.Min(rtt + 0.1f, MAX_REWIND_TIME);
+        
+        // Rewind all players to client's perspective
+        var originalPositions = new Dictionary<NetworkObject, Vector3>();
+        
+        foreach (var player in FindObjectsOfType<LagCompensatedCombat>())
+        {
+            if (player == this) continue;
+            
+            originalPositions[player.NetworkObject] = player.transform.position;
+            player.RewindTo(Time.time - rewindTime);
+        }
+        
+        // Perform raycast in rewound state
+        if (Physics.Raycast(origin, direction, out RaycastHit hit, 100f))
+        {
+            if (hit.collider.TryGetComponent<LagCompensatedCombat>(out var target))
+            {
+                target.TakeDamage(25);
+            }
+        }
+        
+        // Restore positions
+        foreach (var kvp in originalPositions)
+        {
+            kvp.Key.transform.position = kvp.Value;
+        }
+    }
+    
+    private void RewindTo(float targetTime)
+    {
+        var snapshot = _positionHistory
+            .Where(s => s.Timestamp <= targetTime)
+            .LastOrDefault();
+            
+        if (snapshot != null)
+        {
+            transform.position = snapshot.Position;
+            transform.rotation = snapshot.Rotation;
+        }
+    }
+}
+```
+
+---
+
+## Matchmaking
+
+### Simple Lobby System
+
+```csharp
+public class LobbyManager : NetworkBehaviour
+{
+    public static LobbyManager Instance;
+    
+    private NetworkList<LobbyPlayerData> _players;
+    
+    public struct LobbyPlayerData : INetworkSerializable, IEquatable<LobbyPlayerData>
+    {
+        public ulong ClientId;
+        public FixedString32Bytes PlayerName;
+        public bool IsReady;
+        
+        public void NetworkSerialize<T>(BufferSerializer<T> serializer) where T : IReaderWriter
+        {
+            serializer.SerializeValue(ref ClientId);
+            serializer.SerializeValue(ref PlayerName);
+            serializer.SerializeValue(ref IsReady);
+        }
+        
+        public bool Equals(LobbyPlayerData other) => ClientId == other.ClientId;
+    }
+    
+    private void Awake()
+    {
+        Instance = this;
+        _players = new NetworkList<LobbyPlayerData>();
+    }
+    
+    public override void OnNetworkSpawn()
+    {
+        if (IsServer)
+        {
+            NetworkManager.Singleton.OnClientConnectedCallback += OnClientConnected;
+            NetworkManager.Singleton.OnClientDisconnectCallback += OnClientDisconnected;
+        }
+        
+        _players.OnListChanged += OnPlayersChanged;
+    }
+    
+    private void OnClientConnected(ulong clientId)
+    {
+        _players.Add(new LobbyPlayerData
+        {
+            ClientId = clientId,
+            PlayerName = $"Player {clientId}",
+            IsReady = false
+        });
+    }
+    
+    private void OnClientDisconnected(ulong clientId)
+    {
+        for (int i = 0; i < _players.Count; i++)
+        {
+            if (_players[i].ClientId == clientId)
+            {
+                _players.RemoveAt(i);
+                break;
+            }
+        }
+    }
+    
+    [ServerRpc(RequireOwnership = false)]
+    public void SetReadyServerRpc(bool ready, ServerRpcParams rpcParams = default)
+    {
+        ulong clientId = rpcParams.Receive.SenderClientId;
+        
+        for (int i = 0; i < _players.Count; i++)
+        {
+            if (_players[i].ClientId == clientId)
+            {
+                var player = _players[i];
+                player.IsReady = ready;
+                _players[i] = player;
+                break;
+            }
+        }
+        
+        CheckAllReady();
+    }
+    
+    private void CheckAllReady()
+    {
+        if (_players.Count >= 2 && _players.All(p => p.IsReady))
+        {
+            StartGame();
+        }
+    }
+    
+    private void StartGame()
+    {
+        NetworkManager.Singleton.SceneManager.LoadScene("GameScene", LoadSceneMode.Single);
+    }
+}
+```
+
+---
+
+## Anti-Cheat Patterns
+
+### Server Authority
+
+```csharp
+public class ServerAuthorityExample : NetworkBehaviour
+{
+    [ServerRpc]
+    private void AttackServerRpc(ulong targetId, ServerRpcParams rpcParams = default)
+    {
+        ulong attackerId = rpcParams.Receive.SenderClientId;
+        
+        // 1. Validate attacker state
+        var attacker = NetworkManager.Singleton.SpawnManager.GetPlayerNetworkObject(attackerId);
+        if (!IsValidAttackState(attacker))
+        {
+            LogCheatAttempt(attackerId, "Invalid attack state");
+            return;
+        }
+        
+        // 2. Validate target exists and is in range
+        var target = NetworkManager.Singleton.SpawnManager.SpawnedObjects[targetId];
+        if (target == null)
+        {
+            return;
+        }
+        
+        float distance = Vector3.Distance(attacker.transform.position, target.transform.position);
+        if (distance > maxAttackRange * 1.2f) // Allow small tolerance
+        {
+            LogCheatAttempt(attackerId, $"Attack range exceeded: {distance}");
+            return;
+        }
+        
+        // 3. Validate cooldown
+        if (!CanAttack(attackerId))
+        {
+            return;
+        }
+        
+        // 4. Apply damage
+        target.GetComponent<Health>().TakeDamage(attackDamage);
+    }
+    
+    private void LogCheatAttempt(ulong clientId, string reason)
+    {
+        Debug.LogWarning($"[ANTI-CHEAT] Client {clientId}: {reason}");
+        
+        // Increment strike counter
+        if (++_cheatStrikes[clientId] >= 3)
+        {
+            // Kick player
+            NetworkManager.Singleton.DisconnectClient(clientId);
+        }
+    }
+}
+```
+
+### Rate Limiting
+
+```csharp
+public class RateLimiter
+{
+    private Dictionary<ulong, Queue<float>> _actionTimestamps = new();
+    
+    public bool IsAllowed(ulong clientId, int maxActions, float timeWindow)
+    {
+        if (!_actionTimestamps.ContainsKey(clientId))
+        {
+            _actionTimestamps[clientId] = new Queue<float>();
+        }
+        
+        var timestamps = _actionTimestamps[clientId];
+        float now = Time.time;
+        
+        // Remove old timestamps
+        while (timestamps.Count > 0 && now - timestamps.Peek() > timeWindow)
+        {
+            timestamps.Dequeue();
+        }
+        
+        // Check limit
+        if (timestamps.Count >= maxActions)
+        {
+            return false;
+        }
+        
+        timestamps.Enqueue(now);
+        return true;
+    }
+}
+```
+
+---
+
+## Quick Reference
+
+| Concept | Netcode | Photon Fusion | Mirror |
+|---------|---------|---------------|--------|
+| **Sync Variable** | NetworkVariable<T> | [Networked] | [SyncVar] |
+| **Client → Server** | [ServerRpc] | RPC, Input | [Command] |
+| **Server → Clients** | [ClientRpc] | RPC | [ClientRpc] |
+| **Object Spawning** | NetworkObject.Spawn() | Runner.Spawn() | NetworkServer.Spawn() |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Trust client position | Server validates movement |
+| Send full state every frame | Delta compression |
+| No lag compensation | Implement prediction + reconciliation |
+| Ignore bandwidth | Prioritize important data |
+| Client-side hit detection | Server authoritative hits |
+
+---
+
+> **Remember:** The server is the source of truth. Clients lie.