@jarrodmedrano/claude-skills 1.0.2 → 1.0.4

package/.claude/skills/game-feel/references/polish-effects.md

@@ -0,0 +1,246 @@
+# Polish Effects for Game Feel
+
+Polish transforms mechanical interactions into visceral experiences. Without polish, even perfect mechanics feel flat and lifeless.
+
+## Why Polish Matters
+
+> "Because of the limited processing power, each individual effect is drop-dead simple. They harmonize so well, though, that the net effect is a powerful sense of physical properties."
+> — On Asteroids
+
+Polish accomplishes three things:
+1. **Sells the interaction** — Makes virtual contact feel real
+2. **Provides feedback** — Confirms player actions
+3. **Creates consistency** — Builds coherent physical world
+
+## The Polish Toolkit
+
+### Visual Effects
+
+| Effect | Use For | Example |
+|--------|---------|---------|
+| **Particles** | Impacts, movement, environment | Dust on landing, sparks on collision |
+| **Screen shake** | Heavy impacts, explosions | Camera shake on ground pound |
+| **Screen flash** | Damage, power-ups, transitions | White flash on hit |
+| **Motion blur** | High speed, impacts | Blur during dash |
+| **Distortion** | Energy, impacts, power | Shockwave ripple |
+| **Squash/stretch** | Weight, anticipation | Character squashes on landing |
+| **Trailing** | Fast movement, special moves | Afterimages during jump |
+
+### Audio Effects
+
+| Effect | Use For | Example |
+|--------|---------|---------|
+| **Impact sounds** | Collisions, attacks | Thud on landing |
+| **Footsteps** | Movement grounding | Steps sync with animation |
+| **Whooshes** | Fast movement | Swoosh during jump/swing |
+| **UI sounds** | Feedback, confirmation | Click on menu selection |
+| **Ambient** | Environmental presence | Wind, machinery |
+| **Music stingers** | State changes, achievements | Jingle on item pickup |
+
+### Haptic Effects
+
+| Effect | Use For | Example |
+|--------|---------|---------|
+| **Rumble pulse** | Impacts, damage | Vibration on hit |
+| **Sustained rumble** | Ongoing effects | Engine running |
+| **Pattern rumble** | Footsteps, rhythm | Step-step-step pattern |
+
+### Animation Polish
+
+| Technique | Purpose | Example |
+|-----------|---------|---------|
+| **Anticipation** | Prepares viewer for action | Wind-up before jump |
+| **Follow-through** | Completes action believably | Hair settling after landing |
+| **Secondary motion** | Adds life and weight | Cape flowing behind |
+| **Exaggeration** | Emphasizes key moments | Fist enlarges during punch |
+| **Ease in/out** | Natural acceleration | Smooth start/stop |
+
+## The Three-Tier Impact System
+
+Many polished games use three impact levels:
+
+### Light Impact
+- Small particle burst
+- High-pitched click sound
+- Subtle/no screen shake
+- Brief rumble pulse
+
+### Medium Impact
+- Moderate particle spray
+- Mid-tone thud sound
+- Slight screen shake
+- Medium rumble
+
+### Heavy Impact
+- Large particle explosion
+- Deep boom sound
+- Strong screen shake
+- Long rumble
+
+**Application**: Map game interactions to appropriate tier:
+- Walking into wall → Light
+- Landing from jump → Medium
+- Ground pound → Heavy
+
+## Sound-Motion Harmony
+
+### Pitch-Position Correlation
+Mario's jump: Rising tone as he rises, falling tone as he falls.
+Creates subconscious reinforcement of motion.
+
+### Size-Pitch Correlation
+- Large objects → Low sounds
+- Small objects → High sounds
+- Asteroids: Large asteroid explosion = deep boom, small = high ping
+
+### Speed-Intensity Correlation
+- Fast motion → Louder, more intense
+- Slow motion → Quieter, more subtle
+
+### Material-Sound Correlation
+Footstep sounds change based on surface:
+- Stone → Hard click
+- Grass → Soft thud
+- Metal → Metallic clang
+- Water → Splash
+
+## Animation Timing
+
+### Sync Points
+Critical moments when animation, sound, and effect must align:
+- **Foot contact** — Footstep sound, dust particle
+- **Impact moment** — Hit sound, screen shake, particle burst
+- **Jump apex** — Can trigger state changes, sound shifts
+
+### Frame-Perfect Events
+Some events must happen on exact frames:
+- Jump sound on frame 1 of jump
+- Landing effect on exact frame of ground contact
+- Attack hit on specific animation frame
+
+## Screen Shake Best Practices
+
+### Parameters to Control
+- **Intensity** — How far camera moves
+- **Duration** — How long shake lasts
+- **Frequency** — How fast it oscillates
+- **Decay** — How it diminishes over time
+- **Direction** — Random, directional, or circular
+
+### Guidelines
+- Heavy impacts: High intensity, medium duration, fast decay
+- Rumble effects: Low intensity, long duration, no decay
+- Avoid constant shaking — loses impact
+- Direction can indicate impact direction
+
+### Common Mistake
+Shake intensity too high → Nauseating, obscures action
+Shake duration too long → Annoying, feels broken
+
+## Crossover Sensation
+
+When multiple mechanics exist, polish should reinforce their shared physics:
+
+**Swimming feels floaty BECAUSE walking feels grounded**
+- Same gravity system, different friction values
+- Polish effects reflect this (bubbles vs dust)
+
+**Flying defies THE SAME gravity that affects jumping**
+- Player recognizes the relationship
+- Polish should reference the shared system
+
+## Asteroids Polish Case Study
+
+Despite limited hardware, Asteroids achieves excellent polish through coherence:
+
+### Visual-Audio Consistency
+- Large asteroid → Deep boom, large debris
+- Medium asteroid → Mid-pitch, medium debris
+- Small asteroid → High ping, small debris
+- Ship thruster → Lowest rumble (powerful device)
+
+### Effect Cohesion
+- Ship destruction → Breaks into component lines
+- Asteroid destruction → Particle spray
+- Consistent visual language
+
+## Mario 64 Polish Case Study
+
+### Three-Tier System
+All interactions categorized as light/medium/heavy with corresponding:
+- Animation intensity
+- Sound pitch and volume
+- Particle quantity
+- Screen shake intensity
+
+### Footstep Sophistication
+- Sound varies by surface material
+- Timing syncs with animation
+- Volume scales with movement speed
+
+### Mario's Vocalizations
+- Rising yell during jump ascent
+- Grunt on heavy landing
+- "Wahoo!" on special jumps
+- Reinforces motion with voice
+
+### Impact Exaggeration
+- Mario's fist enlarges during punch
+- Foot enlarges during kick
+- Sells the power of the impact
+
+## Polish Implementation Checklist
+
+For each player action, ensure:
+
+- [ ] Immediate visual feedback (frame 1)
+- [ ] Appropriate sound effect
+- [ ] Animation supports the action
+- [ ] Effect intensity matches action intensity
+- [ ] Effects harmonize (don't contradict)
+- [ ] Haptic feedback (if applicable)
+
+## Common Polish Mistakes
+
+### Over-Polish
+Too many effects obscure the action. Know when to restrain.
+
+### Inconsistent Polish
+One action heavily polished, another bare. Feels uneven.
+
+### Wrong Intensity
+Light action with heavy polish (or vice versa). Creates confusion.
+
+### Out of Sync
+Sound slightly before or after visual. Breaks believability.
+
+### Polish Without Purpose
+Effects that don't reinforce an interaction. Just noise.
+
+## The Minimum Viable Polish
+
+If resources are limited, prioritize:
+
+1. **Jump landing** — Players do this constantly
+2. **Attack/hit confirmation** — Core gameplay feedback  
+3. **Damage received** — Critical player information
+4. **Movement sounds** — Grounds player in world
+5. **UI feedback** — Confirms player inputs
+
+## Testing Polish
+
+### The Mute Test
+Play with sound off. Can you still feel the impacts?
+If not, visual polish is insufficient.
+
+### The Blind Test  
+Listen without watching. Can you tell what's happening?
+If not, audio polish is insufficient.
+
+### The Slow-Mo Test
+Watch at reduced speed. Do effects align with actions?
+Reveals timing issues.
+
+### The Comparison Test
+Compare to a polished reference game.
+Note where your game feels "flat" by comparison.

package/.claude/skills/game-feel/references/simulation-recipes.md

@@ -0,0 +1,306 @@
+# Simulation Recipes for Game Feel
+
+Practical patterns for implementing specific feel profiles.
+
+## Fundamental Simulation Approaches
+
+### Level 1: Set Position Directly
+```
+position = position + (direction × speed)
+```
+- Input directly moves object
+- Feel: Stiff, robotic, no momentum
+- Example: Donkey Kong, early arcade games
+
+### Level 2: Set Velocity
+```
+if (input) velocity = targetVelocity
+position = position + velocity
+```
+- Input sets speed directly
+- Feel: More responsive than position, but still abrupt
+- Example: Some puzzle games
+
+### Level 3: Apply Force (Acceleration)
+```
+if (input) acceleration = force
+velocity = velocity + acceleration
+velocity = velocity × friction
+position = position + velocity
+```
+- Input adds force, velocity accumulates
+- Feel: Fluid, physical, expressive
+- Example: Mario, Asteroids, most modern games
+
+---
+
+## The Asteroids Recipe
+
+The classic "spaceship" feel.
+
+### Core Principle
+**Separate thrust from rotation.**
+
+### Variables
+```
+shipRotation          // Current facing angle
+shipPosition          // X, Y coordinates
+shipVelocity          // Current movement vector
+thrustSpeed           // Current thrust magnitude
+thrustAcceleration    // How fast thrust builds
+thrustVelocity        // Force vector to add
+maxThrustSpeed        // Speed cap
+dampening             // Very low (0.99+)
+```
+
+### The Algorithm
+```
+// Rotation: Direct, instant
+if (rotateLeft) shipRotation -= rotateSpeed
+if (rotateRight) shipRotation += rotateSpeed
+
+// Thrust: Simulated, accumulates
+if (thrustButton) {
+    thrustSpeed = min(thrustSpeed + thrustAcceleration, maxThrustSpeed)
+    thrustVelocity = directionFromAngle(shipRotation) × thrustSpeed
+    shipVelocity = shipVelocity + thrustVelocity
+}
+
+// Very low friction (space feel)
+shipVelocity = shipVelocity × dampening
+
+// Cap maximum speed
+shipVelocity = clampMagnitude(shipVelocity, maxVelocity)
+
+// Update position
+shipPosition = shipPosition + shipVelocity
+
+// Screen wrap
+shipPosition = wrapToScreen(shipPosition)
+```
+
+### Key Insight
+Thrust vector is ADDED to velocity, not overwriting it. This decouples rotation from movement direction, creating the "always on the edge of control" feel.
+
+### Tuning Notes
+- Rotation should be instant with very slight attack (~0.1s)
+- Dampening very low: 4+ seconds to stop from full speed
+- Screen wrap prevents escape, creates constant danger
+
+---
+
+## The Super Mario Bros Recipe
+
+The gold standard for platformer feel.
+
+### Core Principle
+**Separate horizontal and vertical systems.**
+
+### Horizontal Variables
+```
+walkAcceleration      // Force applied when walking
+walkMaxSpeed          // Walking speed cap
+runAcceleration       // Force when B held (higher)
+runMaxSpeed           // Running speed cap (higher)
+airAcceleration       // Reduced control in air
+deceleration          // Friction when not pressing direction
+```
+
+### Vertical Variables
+```
+gravity               // Constant downward force
+initialJumpForce      // Upward velocity on button press
+minJumpTime           // Minimum button hold for jump
+maxJumpTime           // Maximum button hold for jump
+reducedJumpVelocity   // Velocity set on early release
+fallGravity           // Gravity after apex (3× normal!)
+terminalVelocity      // Maximum fall speed
+```
+
+### Horizontal Movement
+```
+if (leftOrRight) {
+    if (onGround) {
+        if (runButton) {
+            velocity.x += runAcceleration × direction
+            velocity.x = clamp(velocity.x, -runMaxSpeed, runMaxSpeed)
+        } else {
+            velocity.x += walkAcceleration × direction
+            velocity.x = clamp(velocity.x, -walkMaxSpeed, walkMaxSpeed)
+        }
+    } else {
+        // Reduced air control
+        velocity.x += airAcceleration × direction
+    }
+} else {
+    // Apply deceleration toward zero
+    velocity.x = moveToward(velocity.x, 0, deceleration)
+}
+```
+
+### Vertical Movement (The Jump)
+```
+// Gravity always applied
+velocity.y -= gravity
+
+// Jump initiation
+if (jumpButtonPressed && onGround) {
+    velocity.y = initialJumpForce
+    jumpHoldTime = 0
+    isJumping = true
+}
+
+// Jump extension while held
+if (isJumping && jumpButtonHeld) {
+    jumpHoldTime += deltaTime
+    if (jumpHoldTime < maxJumpTime) {
+        // Continue applying upward force
+        velocity.y = initialJumpForce
+    }
+}
+
+// THE CRITICAL HACK: Early release handling
+if (isJumping && jumpButtonReleased) {
+    if (velocity.y > reducedJumpVelocity) {
+        velocity.y = reducedJumpVelocity  // Artificial cap!
+    }
+    isJumping = false
+}
+
+// Increased fall gravity after apex
+if (velocity.y < 0) {
+    velocity.y -= fallGravity  // 3× normal gravity!
+}
+
+// Terminal velocity
+velocity.y = max(velocity.y, -terminalVelocity)
+```
+
+### Why the "Hack" Works
+Setting velocity to a fixed low value on early release:
+1. Creates consistent arc shapes
+2. Maintains graceful motion
+3. Provides clear minimum jump height
+4. Feels natural despite being artificial
+
+### Running Jump Boost
+```
+if (jumpButtonPressed && speed > walkMaxSpeed) {
+    initialJumpForce *= 1.1  // Slight boost
+}
+```
+
+---
+
+## The Mario 64 Recipe
+
+Translating platformer feel to 3D.
+
+### Core Additions for 3D
+
+**Camera-Relative Input**
+```
+// Thumbstick direction relative to camera, not character
+worldDirection = cameraForward × stick.y + cameraRight × stick.x
+```
+
+**Turn Interpolation**
+```
+// Blend toward desired direction for carving motion
+if (speed > 0) {
+    currentDirection = lerp(currentDirection, desiredDirection, turnSpeed)
+} else {
+    currentDirection = desiredDirection  // Instant at standstill
+}
+```
+
+**Incline Physics**
+```
+groundAngle = getGroundAngle()
+if (groundAngle > slideThreshold) {
+    // Enter slide state
+    state = SLIDING
+    velocity += getDownhillVector() × slideAcceleration
+}
+```
+
+### Multiple Jump Types
+
+| Jump | Trigger | Properties |
+|------|---------|------------|
+| **Basic** | A button | Variable height (hold-sensitive) |
+| **Continuous** | A after landing | Higher, still variable |
+| **Triple** | A after Continuous + speed | Fixed trajectory, highest |
+| **Long** | Z+A while moving | Fixed, horizontal emphasis |
+| **Back Somersault** | A while ducking | Fixed, highest vertical |
+| **Side Somersault** | A during direction change | Fixed, high |
+| **Wall Kick** | A near wall + away input | Fixed |
+
+### Fixed vs Variable Trajectories
+- **Variable** (basic): Expressive, moment-to-moment control
+- **Fixed** (special): Predictable, precision platforming
+
+### The Ground Pound
+```
+if (inAir && zButtonPressed) {
+    velocity.x = 0
+    velocity.z = 0
+    // Pause briefly
+    wait(0.1)
+    // Slam down with high gravity
+    velocity.y = -groundPoundSpeed
+}
+```
+Provides precision landing by removing horizontal momentum.
+
+---
+
+## Tuning Guidelines
+
+### For "Tight" Feel
+- High acceleration values
+- Short attack times (<0.1s)
+- Moderate deceleration
+- Quick release phase
+
+### For "Floaty" Feel
+- Low acceleration values
+- Long attack times (0.3-0.5s)
+- Low deceleration (high inertia)
+- Long release phase
+
+### For "Weighty" Feel
+- Strong gravity
+- Even stronger fall gravity
+- Moderate acceleration
+- Pronounced squash/stretch animation
+
+### For "Responsive" Feel
+- <100ms input-to-response
+- Direct mapping where possible
+- Visual feedback on frame 1
+- Sound on input, not on action completion
+
+---
+
+## Common Pitfalls
+
+### Problem: Character won't stop
+**Cause**: No deceleration when input stops
+**Fix**: Apply friction force toward zero velocity
+
+### Problem: Jump feels "swimmy"
+**Cause**: Same gravity up and down
+**Fix**: Increase fall gravity (2-3× normal)
+
+### Problem: Controls feel random
+**Cause**: Variable attack/release based on frame timing
+**Fix**: Use fixed-timestep physics, frame-independent values
+
+### Problem: Can't make precise movements
+**Cause**: Only high-speed movement available
+**Fix**: Add acceleration curve, lower minimum speed threshold
+
+### Problem: Character slides off platforms
+**Cause**: Deceleration too slow, momentum carries past edge
+**Fix**: Increase deceleration, or snap to platform edges