@musashishao/agent-kit 1.9.0 → 1.9.1

package/.agent/skills/game-development/character-controller-3d/SKILL.md

@@ -0,0 +1,908 @@
+---
+name: character-controller-3d
+description: Advanced 3D character movement. First-person, third-person controllers, advanced mechanics like dash, wall-run, swimming. Complete implementation patterns.
+allowed-tools: Read, Write, Edit, Bash, Grep, WebSearch
+---
+
+# 3D Character Controller Skill
+
+> Build responsive, polished character movement for any 3D game.
+
+---
+
+## When to Use
+
+- Implementing 3D player movement
+- Building FPS or TPS controllers
+- Advanced mechanics (dash, wall-run, climb)
+- Root motion integration
+- Platformer movement
+
+---
+
+## Controller Type Selection
+
+| Type | Best For | Pros | Cons |
+|------|----------|------|------|
+| **CharacterController** | Most games | Simple, built-in | No physics reactions |
+| **Rigidbody** | Physics puzzles | Reacts to forces | Harder to control |
+| **Custom** | Specific needs | Full control | Time investment |
+
+---
+
+## Third-Person Controller
+
+### Complete Implementation
+
+```csharp
+[RequireComponent(typeof(CharacterController))]
+public class ThirdPersonController : MonoBehaviour
+{
+    [Header("Movement")]
+    [SerializeField] private float walkSpeed = 4f;
+    [SerializeField] private float runSpeed = 8f;
+    [SerializeField] private float rotationSpeed = 10f;
+    [SerializeField] private float acceleration = 10f;
+    
+    [Header("Jump")]
+    [SerializeField] private float jumpHeight = 1.5f;
+    [SerializeField] private float gravity = -20f;
+    [SerializeField] private float coyoteTime = 0.15f;
+    [SerializeField] private float jumpBufferTime = 0.15f;
+    
+    [Header("Ground Check")]
+    [SerializeField] private LayerMask groundMask;
+    [SerializeField] private float groundCheckRadius = 0.3f;
+    [SerializeField] private Transform groundCheck;
+    
+    [Header("Slope Handling")]
+    [SerializeField] private float maxSlopeAngle = 45f;
+    [SerializeField] private float slopeSlideSpeed = 5f;
+    
+    [Header("Camera")]
+    [SerializeField] private Transform cameraTransform;
+    
+    // Components
+    private CharacterController _controller;
+    private Animator _animator;
+    
+    // State
+    private Vector3 _velocity;
+    private Vector3 _moveDirection;
+    private float _currentSpeed;
+    private bool _isGrounded;
+    private bool _wasGrounded;
+    private float _lastGroundedTime;
+    private float _jumpBufferedTime;
+    private bool _isRunning;
+    
+    // Animator hashes
+    private static readonly int SpeedHash = Animator.StringToHash("Speed");
+    private static readonly int GroundedHash = Animator.StringToHash("Grounded");
+    private static readonly int JumpHash = Animator.StringToHash("Jump");
+    private static readonly int FallHash = Animator.StringToHash("Fall");
+    
+    void Awake()
+    {
+        _controller = GetComponent<CharacterController>();
+        _animator = GetComponent<Animator>();
+    }
+    
+    void Update()
+    {
+        GroundCheck();
+        HandleMovement();
+        HandleJump();
+        ApplyGravity();
+        HandleSlope();
+        
+        // Apply final movement
+        _controller.Move(_velocity * Time.deltaTime);
+        
+        UpdateAnimator();
+    }
+    
+    #region Ground Check
+    
+    private void GroundCheck()
+    {
+        _wasGrounded = _isGrounded;
+        _isGrounded = Physics.CheckSphere(
+            groundCheck.position, 
+            groundCheckRadius, 
+            groundMask
+        );
+        
+        // Update coyote time
+        if (_isGrounded)
+        {
+            _lastGroundedTime = Time.time;
+        }
+        
+        // Landing
+        if (!_wasGrounded && _isGrounded && _velocity.y < 0)
+        {
+            OnLand();
+        }
+    }
+    
+    private bool CanCoyoteJump()
+    {
+        return Time.time - _lastGroundedTime <= coyoteTime;
+    }
+    
+    #endregion
+    
+    #region Movement
+    
+    private void HandleMovement()
+    {
+        // Input
+        float h = Input.GetAxisRaw("Horizontal");
+        float v = Input.GetAxisRaw("Vertical");
+        Vector3 inputDir = new Vector3(h, 0, v).normalized;
+        
+        _isRunning = Input.GetKey(KeyCode.LeftShift);
+        float targetSpeed = inputDir.magnitude > 0.1f 
+            ? (_isRunning ? runSpeed : walkSpeed) 
+            : 0f;
+        
+        // Smooth speed transition
+        _currentSpeed = Mathf.MoveTowards(_currentSpeed, targetSpeed, acceleration * Time.deltaTime);
+        
+        if (inputDir.magnitude > 0.1f)
+        {
+            // Calculate move direction relative to camera
+            float targetAngle = Mathf.Atan2(inputDir.x, inputDir.z) * Mathf.Rad2Deg 
+                               + cameraTransform.eulerAngles.y;
+            
+            // Smooth rotation
+            float angle = Mathf.SmoothDampAngle(
+                transform.eulerAngles.y, 
+                targetAngle, 
+                ref _rotationVelocity, 
+                0.1f
+            );
+            transform.rotation = Quaternion.Euler(0, angle, 0);
+            
+            _moveDirection = Quaternion.Euler(0, targetAngle, 0) * Vector3.forward;
+        }
+        
+        // Apply horizontal movement
+        Vector3 move = _moveDirection * _currentSpeed;
+        _velocity.x = move.x;
+        _velocity.z = move.z;
+    }
+    
+    private float _rotationVelocity;
+    
+    #endregion
+    
+    #region Jump
+    
+    private void HandleJump()
+    {
+        // Buffer jump input
+        if (Input.GetButtonDown("Jump"))
+        {
+            _jumpBufferedTime = Time.time;
+        }
+        
+        bool jumpBuffered = Time.time - _jumpBufferedTime <= jumpBufferTime;
+        bool canJump = (_isGrounded || CanCoyoteJump()) && jumpBuffered;
+        
+        if (canJump && _velocity.y <= 0)
+        {
+            // Calculate jump velocity from height
+            _velocity.y = Mathf.Sqrt(jumpHeight * -2f * gravity);
+            _jumpBufferedTime = 0;
+            
+            _animator?.SetTrigger(JumpHash);
+        }
+        
+        // Variable jump height (release early = lower jump)
+        if (Input.GetButtonUp("Jump") && _velocity.y > 0)
+        {
+            _velocity.y *= 0.5f;
+        }
+    }
+    
+    private void OnLand()
+    {
+        // Landing effects
+        // Play sound, particles, etc.
+    }
+    
+    #endregion
+    
+    #region Gravity & Slope
+    
+    private void ApplyGravity()
+    {
+        if (_isGrounded && _velocity.y < 0)
+        {
+            _velocity.y = -2f; // Small downward force to stay grounded
+        }
+        else
+        {
+            _velocity.y += gravity * Time.deltaTime;
+        }
+    }
+    
+    private void HandleSlope()
+    {
+        if (!_isGrounded) return;
+        
+        if (Physics.Raycast(transform.position, Vector3.down, out RaycastHit hit, 2f, groundMask))
+        {
+            float angle = Vector3.Angle(hit.normal, Vector3.up);
+            
+            if (angle > maxSlopeAngle)
+            {
+                // Slide down steep slopes
+                Vector3 slideDirection = Vector3.ProjectOnPlane(Vector3.down, hit.normal).normalized;
+                _velocity += slideDirection * slopeSlideSpeed * Time.deltaTime;
+            }
+        }
+    }
+    
+    #endregion
+    
+    #region Animation
+    
+    private void UpdateAnimator()
+    {
+        if (_animator == null) return;
+        
+        _animator.SetFloat(SpeedHash, _currentSpeed / runSpeed);
+        _animator.SetBool(GroundedHash, _isGrounded);
+        
+        if (!_isGrounded && _velocity.y < -1f)
+        {
+            _animator.SetBool(FallHash, true);
+        }
+        else
+        {
+            _animator.SetBool(FallHash, false);
+        }
+    }
+    
+    #endregion
+    
+    void OnDrawGizmosSelected()
+    {
+        if (groundCheck != null)
+        {
+            Gizmos.color = _isGrounded ? Color.green : Color.red;
+            Gizmos.DrawWireSphere(groundCheck.position, groundCheckRadius);
+        }
+    }
+}
+```
+
+---
+
+## First-Person Controller
+
+```csharp
+[RequireComponent(typeof(CharacterController))]
+public class FirstPersonController : MonoBehaviour
+{
+    [Header("Movement")]
+    [SerializeField] private float walkSpeed = 5f;
+    [SerializeField] private float sprintSpeed = 8f;
+    [SerializeField] private float crouchSpeed = 2.5f;
+    
+    [Header("Jump")]
+    [SerializeField] private float jumpForce = 8f;
+    [SerializeField] private float gravity = -20f;
+    
+    [Header("Look")]
+    [SerializeField] private float mouseSensitivity = 2f;
+    [SerializeField] private float maxLookAngle = 85f;
+    [SerializeField] private Transform cameraHolder;
+    
+    [Header("Crouch")]
+    [SerializeField] private float standHeight = 2f;
+    [SerializeField] private float crouchHeight = 1f;
+    [SerializeField] private float crouchTransitionSpeed = 10f;
+    
+    [Header("Head Bob")]
+    [SerializeField] private bool enableHeadBob = true;
+    [SerializeField] private float bobFrequency = 1.5f;
+    [SerializeField] private float bobAmplitude = 0.05f;
+    
+    private CharacterController _controller;
+    private Vector3 _velocity;
+    private float _xRotation;
+    private bool _isCrouching;
+    private float _currentHeight;
+    private float _bobTimer;
+    private Vector3 _cameraDefaultPos;
+    
+    void Start()
+    {
+        _controller = GetComponent<CharacterController>();
+        _currentHeight = standHeight;
+        _cameraDefaultPos = cameraHolder.localPosition;
+        
+        Cursor.lockState = CursorLockMode.Locked;
+        Cursor.visible = false;
+    }
+    
+    void Update()
+    {
+        HandleLook();
+        HandleMovement();
+        HandleCrouch();
+        HandleHeadBob();
+    }
+    
+    private void HandleLook()
+    {
+        float mouseX = Input.GetAxis("Mouse X") * mouseSensitivity;
+        float mouseY = Input.GetAxis("Mouse Y") * mouseSensitivity;
+        
+        // Apply sensitivity from settings
+        mouseX *= SettingsManager.Instance?.Settings.MouseSensitivity ?? 1f;
+        mouseY *= SettingsManager.Instance?.Settings.MouseSensitivity ?? 1f;
+        
+        // Invert Y if setting enabled
+        if (SettingsManager.Instance?.Settings.InvertY ?? false)
+        {
+            mouseY = -mouseY;
+        }
+        
+        // Vertical rotation (camera)
+        _xRotation -= mouseY;
+        _xRotation = Mathf.Clamp(_xRotation, -maxLookAngle, maxLookAngle);
+        cameraHolder.localRotation = Quaternion.Euler(_xRotation, 0, 0);
+        
+        // Horizontal rotation (body)
+        transform.Rotate(Vector3.up * mouseX);
+    }
+    
+    private void HandleMovement()
+    {
+        bool isGrounded = _controller.isGrounded;
+        
+        if (isGrounded && _velocity.y < 0)
+        {
+            _velocity.y = -2f;
+        }
+        
+        // Input
+        float h = Input.GetAxisRaw("Horizontal");
+        float v = Input.GetAxisRaw("Vertical");
+        
+        Vector3 move = transform.right * h + transform.forward * v;
+        move = move.normalized;
+        
+        // Speed selection
+        float speed = walkSpeed;
+        if (_isCrouching)
+            speed = crouchSpeed;
+        else if (Input.GetKey(KeyCode.LeftShift) && v > 0)
+            speed = sprintSpeed;
+        
+        _controller.Move(move * speed * Time.deltaTime);
+        
+        // Jump
+        if (Input.GetButtonDown("Jump") && isGrounded && !_isCrouching)
+        {
+            _velocity.y = Mathf.Sqrt(jumpForce * -2f * gravity);
+        }
+        
+        // Gravity
+        _velocity.y += gravity * Time.deltaTime;
+        _controller.Move(_velocity * Time.deltaTime);
+    }
+    
+    private void HandleCrouch()
+    {
+        if (Input.GetKeyDown(KeyCode.C) || Input.GetKeyDown(KeyCode.LeftControl))
+        {
+            _isCrouching = !_isCrouching;
+        }
+        
+        float targetHeight = _isCrouching ? crouchHeight : standHeight;
+        
+        // Check ceiling before standing
+        if (!_isCrouching && _currentHeight < standHeight)
+        {
+            if (Physics.Raycast(transform.position, Vector3.up, standHeight - crouchHeight + 0.1f))
+            {
+                _isCrouching = true;
+                targetHeight = crouchHeight;
+            }
+        }
+        
+        _currentHeight = Mathf.Lerp(_currentHeight, targetHeight, crouchTransitionSpeed * Time.deltaTime);
+        _controller.height = _currentHeight;
+        _controller.center = new Vector3(0, _currentHeight / 2f, 0);
+        
+        // Adjust camera
+        cameraHolder.localPosition = new Vector3(
+            _cameraDefaultPos.x,
+            _currentHeight - 0.2f,
+            _cameraDefaultPos.z
+        );
+    }
+    
+    private void HandleHeadBob()
+    {
+        if (!enableHeadBob) return;
+        
+        bool isMoving = _controller.velocity.magnitude > 0.1f && _controller.isGrounded;
+        
+        if (isMoving)
+        {
+            _bobTimer += Time.deltaTime * bobFrequency * (_isCrouching ? 0.5f : 1f);
+            
+            float bobOffsetY = Mathf.Sin(_bobTimer * Mathf.PI * 2) * bobAmplitude;
+            float bobOffsetX = Mathf.Cos(_bobTimer * Mathf.PI) * bobAmplitude * 0.5f;
+            
+            cameraHolder.localPosition += new Vector3(bobOffsetX, bobOffsetY, 0);
+        }
+        else
+        {
+            _bobTimer = 0;
+        }
+    }
+}
+```
+
+---
+
+## Advanced Mechanics
+
+### Dash/Dodge
+
+```csharp
+public class DashController : MonoBehaviour
+{
+    [SerializeField] private float dashSpeed = 20f;
+    [SerializeField] private float dashDuration = 0.2f;
+    [SerializeField] private float dashCooldown = 1f;
+    [SerializeField] private int maxDashCharges = 2;
+    [SerializeField] private float chargeRegenTime = 2f;
+    
+    [SerializeField] private AnimationCurve dashCurve = AnimationCurve.EaseInOut(0, 1, 1, 0);
+    
+    private CharacterController _controller;
+    private int _dashCharges;
+    private float _lastDashTime;
+    private float _chargeRegenTimer;
+    private bool _isDashing;
+    
+    void Start()
+    {
+        _controller = GetComponent<CharacterController>();
+        _dashCharges = maxDashCharges;
+    }
+    
+    void Update()
+    {
+        RegenerateDashCharges();
+        
+        if (Input.GetKeyDown(KeyCode.Space) && CanDash())
+        {
+            StartCoroutine(Dash());
+        }
+    }
+    
+    private bool CanDash()
+    {
+        return !_isDashing 
+            && _dashCharges > 0 
+            && Time.time - _lastDashTime >= dashCooldown;
+    }
+    
+    private IEnumerator Dash()
+    {
+        _isDashing = true;
+        _dashCharges--;
+        _lastDashTime = Time.time;
+        
+        // Determine dash direction
+        Vector3 dashDir = GetDashDirection();
+        
+        // Invincibility during dash (optional)
+        // GetComponent<Health>().SetInvincible(true);
+        
+        float elapsed = 0f;
+        
+        while (elapsed < dashDuration)
+        {
+            float curveValue = dashCurve.Evaluate(elapsed / dashDuration);
+            Vector3 move = dashDir * dashSpeed * curveValue * Time.deltaTime;
+            
+            _controller.Move(move);
+            
+            elapsed += Time.deltaTime;
+            yield return null;
+        }
+        
+        // GetComponent<Health>().SetInvincible(false);
+        _isDashing = false;
+    }
+    
+    private Vector3 GetDashDirection()
+    {
+        float h = Input.GetAxisRaw("Horizontal");
+        float v = Input.GetAxisRaw("Vertical");
+        
+        Vector3 inputDir = new Vector3(h, 0, v).normalized;
+        
+        if (inputDir.magnitude < 0.1f)
+        {
+            // Dash forward if no input
+            return transform.forward;
+        }
+        
+        // Dash in input direction relative to camera
+        return Camera.main.transform.TransformDirection(inputDir);
+    }
+    
+    private void RegenerateDashCharges()
+    {
+        if (_dashCharges < maxDashCharges)
+        {
+            _chargeRegenTimer += Time.deltaTime;
+            
+            if (_chargeRegenTimer >= chargeRegenTime)
+            {
+                _dashCharges++;
+                _chargeRegenTimer = 0f;
+            }
+        }
+    }
+}
+```
+
+### Wall Running
+
+```csharp
+public class WallRunController : MonoBehaviour
+{
+    [Header("Wall Detection")]
+    [SerializeField] private float wallCheckDistance = 0.7f;
+    [SerializeField] private LayerMask wallMask;
+    [SerializeField] private float minWallRunHeight = 1f;
+    
+    [Header("Wall Run")]
+    [SerializeField] private float wallRunSpeed = 10f;
+    [SerializeField] private float wallRunGravity = -2f;
+    [SerializeField] private float maxWallRunTime = 2f;
+    [SerializeField] private float wallJumpForce = 12f;
+    [SerializeField] private float wallJumpSideForce = 8f;
+    
+    [Header("Camera")]
+    [SerializeField] private float cameraTiltAngle = 15f;
+    [SerializeField] private float tiltSpeed = 10f;
+    
+    private CharacterController _controller;
+    private bool _isWallRunning;
+    private bool _isWallLeft;
+    private bool _isWallRight;
+    private float _wallRunTimer;
+    private RaycastHit _wallHit;
+    
+    void Update()
+    {
+        CheckWalls();
+        HandleWallRun();
+        UpdateCameraTilt();
+    }
+    
+    private void CheckWalls()
+    {
+        _isWallLeft = Physics.Raycast(
+            transform.position, 
+            -transform.right, 
+            out _wallHit, 
+            wallCheckDistance, 
+            wallMask
+        );
+        
+        if (!_isWallLeft)
+        {
+            _isWallRight = Physics.Raycast(
+                transform.position, 
+                transform.right, 
+                out _wallHit, 
+                wallCheckDistance, 
+                wallMask
+            );
+        }
+        else
+        {
+            _isWallRight = false;
+        }
+    }
+    
+    private void HandleWallRun()
+    {
+        bool canWallRun = (_isWallLeft || _isWallRight) 
+            && !_controller.isGrounded 
+            && transform.position.y > minWallRunHeight
+            && Input.GetAxisRaw("Vertical") > 0;
+        
+        if (canWallRun && !_isWallRunning)
+        {
+            StartWallRun();
+        }
+        else if (!canWallRun && _isWallRunning)
+        {
+            StopWallRun();
+        }
+        
+        if (_isWallRunning)
+        {
+            _wallRunTimer += Time.deltaTime;
+            
+            if (_wallRunTimer >= maxWallRunTime)
+            {
+                StopWallRun();
+                return;
+            }
+            
+            // Wall run movement
+            Vector3 wallForward = Vector3.Cross(_wallHit.normal, Vector3.up);
+            
+            // Ensure we're running in the right direction
+            if (Vector3.Dot(wallForward, transform.forward) < 0)
+            {
+                wallForward = -wallForward;
+            }
+            
+            _controller.Move(wallForward * wallRunSpeed * Time.deltaTime);
+            
+            // Reduced gravity
+            _controller.Move(Vector3.up * wallRunGravity * Time.deltaTime);
+            
+            // Wall jump
+            if (Input.GetButtonDown("Jump"))
+            {
+                WallJump();
+            }
+        }
+    }
+    
+    private void StartWallRun()
+    {
+        _isWallRunning = true;
+        _wallRunTimer = 0f;
+    }
+    
+    private void StopWallRun()
+    {
+        _isWallRunning = false;
+    }
+    
+    private void WallJump()
+    {
+        Vector3 jumpDirection = _wallHit.normal * wallJumpSideForce + Vector3.up * wallJumpForce;
+        
+        // Apply force through velocity (you'll need to integrate this with your main controller)
+        GetComponent<ThirdPersonController>().SetVelocity(jumpDirection);
+        
+        StopWallRun();
+    }
+    
+    private void UpdateCameraTilt()
+    {
+        float targetTilt = 0f;
+        
+        if (_isWallRunning)
+        {
+            targetTilt = _isWallLeft ? cameraTiltAngle : -cameraTiltAngle;
+        }
+        
+        // Smooth camera tilt
+        // camera.transform.localRotation = ...
+    }
+}
+```
+
+### Ledge Climbing
+
+```csharp
+public class LedgeClimbController : MonoBehaviour
+{
+    [Header("Detection")]
+    [SerializeField] private float ledgeCheckDistance = 1f;
+    [SerializeField] private float ledgeCheckHeight = 2f;
+    [SerializeField] private LayerMask climbMask;
+    
+    [Header("Climb")]
+    [SerializeField] private float climbDuration = 0.5f;
+    [SerializeField] private AnimationCurve climbCurve;
+    
+    private CharacterController _controller;
+    private bool _isClimbing;
+    
+    void Update()
+    {
+        if (!_isClimbing && CanClimb())
+        {
+            if (Input.GetKeyDown(KeyCode.E) || (Input.GetAxisRaw("Vertical") > 0 && Input.GetButtonDown("Jump")))
+            {
+                StartCoroutine(ClimbLedge());
+            }
+        }
+    }
+    
+    private bool CanClimb()
+    {
+        if (_controller.isGrounded) return false;
+        
+        // Check for wall in front
+        if (!Physics.Raycast(transform.position + Vector3.up * 0.5f, transform.forward, ledgeCheckDistance, climbMask))
+        {
+            return false;
+        }
+        
+        // Check for ledge above
+        Vector3 ledgeCheckStart = transform.position + Vector3.up * ledgeCheckHeight + transform.forward * ledgeCheckDistance;
+        if (!Physics.Raycast(ledgeCheckStart, Vector3.down, out RaycastHit hit, ledgeCheckHeight - 0.5f, climbMask))
+        {
+            return false;
+        }
+        
+        // Check if there's space on top
+        Vector3 targetPos = hit.point + Vector3.up * 0.1f;
+        return !Physics.CheckSphere(targetPos, 0.3f, climbMask);
+    }
+    
+    private IEnumerator ClimbLedge()
+    {
+        _isClimbing = true;
+        _controller.enabled = false;
+        
+        // Find target position
+        Vector3 ledgeCheckStart = transform.position + Vector3.up * ledgeCheckHeight + transform.forward * ledgeCheckDistance;
+        Physics.Raycast(ledgeCheckStart, Vector3.down, out RaycastHit hit, ledgeCheckHeight - 0.5f, climbMask);
+        
+        Vector3 startPos = transform.position;
+        Vector3 targetPos = hit.point + Vector3.up * 0.1f + transform.forward * 0.5f;
+        
+        // Intermediate position (hands on ledge)
+        Vector3 hangPos = new Vector3(
+            targetPos.x - transform.forward.x * 0.3f,
+            targetPos.y - 0.5f,
+            targetPos.z - transform.forward.z * 0.3f
+        );
+        
+        float elapsed = 0f;
+        float halfDuration = climbDuration * 0.5f;
+        
+        // Rise to hang position
+        while (elapsed < halfDuration)
+        {
+            float t = elapsed / halfDuration;
+            transform.position = Vector3.Lerp(startPos, hangPos, climbCurve.Evaluate(t));
+            elapsed += Time.deltaTime;
+            yield return null;
+        }
+        
+        // Climb up
+        elapsed = 0f;
+        while (elapsed < halfDuration)
+        {
+            float t = elapsed / halfDuration;
+            transform.position = Vector3.Lerp(hangPos, targetPos, climbCurve.Evaluate(t));
+            elapsed += Time.deltaTime;
+            yield return null;
+        }
+        
+        transform.position = targetPos;
+        _controller.enabled = true;
+        _isClimbing = false;
+    }
+}
+```
+
+---
+
+## Input Buffering
+
+```csharp
+public class InputBuffer
+{
+    private struct BufferedInput
+    {
+        public string Action;
+        public float Timestamp;
+    }
+    
+    private Queue<BufferedInput> _buffer = new();
+    private float _bufferWindow = 0.15f;
+    
+    public void BufferInput(string action)
+    {
+        _buffer.Enqueue(new BufferedInput
+        {
+            Action = action,
+            Timestamp = Time.time
+        });
+    }
+    
+    public bool ConsumeInput(string action)
+    {
+        // Clean expired inputs
+        while (_buffer.Count > 0 && Time.time - _buffer.Peek().Timestamp > _bufferWindow)
+        {
+            _buffer.Dequeue();
+        }
+        
+        // Check for action
+        foreach (var input in _buffer)
+        {
+            if (input.Action == action)
+            {
+                // Remove consumed input
+                var temp = new Queue<BufferedInput>();
+                while (_buffer.Count > 0)
+                {
+                    var item = _buffer.Dequeue();
+                    if (item.Action != action || temp.Count > 0)
+                    {
+                        temp.Enqueue(item);
+                    }
+                }
+                _buffer = temp;
+                return true;
+            }
+        }
+        
+        return false;
+    }
+}
+
+// Usage in controller
+private InputBuffer _inputBuffer = new();
+
+void Update()
+{
+    if (Input.GetButtonDown("Jump"))
+    {
+        _inputBuffer.BufferInput("Jump");
+    }
+    
+    // Later, when checking if we can jump:
+    if (_isGrounded && _inputBuffer.ConsumeInput("Jump"))
+    {
+        DoJump();
+    }
+}
+```
+
+---
+
+## Quick Reference
+
+| Mechanic | Key Values |
+|----------|------------|
+| **Walk Speed** | 4-5 m/s |
+| **Run Speed** | 8-10 m/s |
+| **Jump Height** | 1-2 m |
+| **Gravity** | -20 to -30 |
+| **Coyote Time** | 0.1-0.2 s |
+| **Jump Buffer** | 0.1-0.15 s |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Check `Input.GetKey` directly | Use input buffering |
+| Hard-coded values | SerializeField everything |
+| No coyote time | Always add tolerance |
+| Physics in Update | Use FixedUpdate for physics |
+| Instant state changes | Smooth transitions |
+
+---
+
+> **Remember:** Good movement feels responsive but forgiving. Add tiny cheats for the player.