@jarrodmedrano/claude-skills 1.0.2 → 1.0.3

package/.claude/skills/game-feel/references/adsr-tuning.md

@@ -0,0 +1,271 @@
+# ADSR Tuning for Game Feel
+
+The ADSR envelope, borrowed from audio synthesis, provides a powerful framework for understanding and tuning game response curves.
+
+## The ADSR Model
+
+```
+Level
+  ^
+  |     Decay
+  |    /‾‾‾‾\
+  |   /      \___________Sustain___________
+  |  /Attack                               \
+  | /                                       \Release
+  |/                                         \
+  +---------------------------------------------> Time
+  Input Starts                            Input Ends
+```
+
+| Phase | Definition | Game Example |
+|-------|------------|--------------|
+| **Attack** | Time from input start to peak response | Acceleration from standstill |
+| **Decay** | Time from peak to sustained level | Initial burst settling |
+| **Sustain** | Level maintained while input held | Running at max speed |
+| **Release** | Time from input end to neutral | Deceleration to stop |
+
+## Why ADSR Matters for Feel
+
+Most "feel" descriptions map directly to ADSR characteristics:
+
+| Feel Term | Primary ADSR Factor |
+|-----------|---------------------|
+| Tight | Short Attack + Short Release |
+| Floaty | Long Attack + Long Release |
+| Responsive | Short Attack |
+| Sluggish | Long Attack |
+| Slippery | Long Release |
+| Snappy | Short Attack + Short Release |
+| Weighty | Medium Attack + Medium Release |
+
+## Measuring ADSR in Games
+
+### Attack Time
+1. Start from neutral (stationary)
+2. Press input
+3. Measure time until maximum response reached
+
+**Mario walk attack**: ~0.2 seconds
+**Asteroids thrust attack**: ~0.3 seconds
+**Donkey Kong walk attack**: ~0.03 seconds (nearly instant)
+
+### Release Time
+1. From sustained state (full speed)
+2. Release input
+3. Measure time until neutral (stopped)
+
+**Mario release**: ~0.3 seconds
+**Asteroids release**: ~4+ seconds
+**Donkey Kong release**: ~0.03 seconds (nearly instant)
+
+### Sustain Level
+The maintained response value during continuous input.
+
+**Mario walk sustain**: Walk max speed
+**Mario run sustain**: Run max speed (higher)
+**Asteroids sustain**: Max velocity (capped)
+
+## Tuning Guidelines
+
+### For Platformers (Mario-like)
+
+```
+Attack:  0.1 - 0.3 seconds
+Decay:   Minimal (go straight to sustain)
+Sustain: Max speed (walk or run)
+Release: 0.2 - 0.4 seconds
+
+Jump Attack: Instant (frame 1 response)
+Jump Release: Variable based on button hold
+```
+
+### For Space Games (Asteroids-like)
+
+```
+Attack:  0.2 - 0.5 seconds
+Decay:   Minimal
+Sustain: Max thrust speed
+Release: 2 - 5+ seconds (low friction)
+
+Rotation Attack: Very short (0.05-0.1s)
+Rotation Release: Instant (no inertia)
+```
+
+### For Racing Games
+
+```
+Acceleration Attack: 1-3 seconds (car builds speed)
+Acceleration Sustain: Top speed
+Braking Release: 0.5-1 second
+
+Steering Attack: 0.1-0.2 seconds (turn-in)
+Steering Release: 0.1-0.2 seconds (self-centering)
+```
+
+### For Fighting Games
+
+```
+Normal Attack: 2-5 frames attack (~0.03-0.08s)
+Heavy Attack: 8-15 frames attack (~0.13-0.25s)
+Recovery (Release): 5-20 frames depending on move
+
+Movement Attack: Very short (instant response)
+Movement Release: Very short (precise positioning)
+```
+
+## Attack Curves
+
+Not all attacks are linear. Common curve shapes:
+
+### Linear
+```
+Response
+    |    /
+    |   /
+    |  /
+    | /
+    |/_____ Time
+```
+Steady increase. Feels mechanical.
+
+### Ease-In (Slow Start)
+```
+Response
+    |      _/
+    |    _/
+    |  _/
+    | /
+    |/_____ Time
+```
+Sluggish start, fast finish. Feels heavy.
+
+### Ease-Out (Fast Start)
+```
+Response
+    |  /‾‾‾
+    | /
+    |/
+    |/
+    |/_____ Time
+```
+Quick start, gradual finish. Feels responsive.
+
+### Ease-In-Out
+```
+Response
+    |    _--‾
+    |  _/
+    | /
+    |/
+    |/_____ Time
+```
+Smooth acceleration. Feels natural.
+
+## Release Curves
+
+### Linear Deceleration
+Constant friction. Feels artificial but predictable.
+
+### Exponential Decay
+Fast initial slowdown, gradual final approach to zero.
+Feels more natural, like real friction.
+
+### Instant Stop
+No release phase. Feels robotic, but precise.
+
+## The Mario Jump ADSR
+
+The Mario jump is a special case with modified ADSR:
+
+```
+        Variable Attack (button held)
+             |
+             v
+Force   ____/‾‾‾\
+            |    \
+            |     \_ Apex
+            |       \
+            |        \ Accelerated Release (3× gravity)
+            |         \
+        ____+__________\____
+            ^           ^
+        Button       Button
+        Pressed      Released
+```
+
+### Key Features:
+1. **Attack is instant** (large force applied frame 1)
+2. **Attack extends** while button held (up to max time)
+3. **Early release** artificially caps upward velocity
+4. **Release accelerates** (fall gravity > rise gravity)
+
+## Practical Tuning Process
+
+### Step 1: Identify Desired Feel
+"I want movement to feel tight but not robotic"
+
+### Step 2: Set Target ADSR Values
+- Attack: 0.1s (responsive)
+- Release: 0.15s (not instant, slight slide)
+- Sustain: Based on desired max speed
+
+### Step 3: Implement and Test
+Build the basic response, measure actual values
+
+### Step 4: Iterate
+- Too floaty? Shorten attack and release
+- Too stiff? Lengthen attack and release
+- Too slippery? Shorten release specifically
+- Too sticky? Shorten attack specifically
+
+### Step 5: Test Edge Cases
+- Direction reversal
+- Stop from max speed
+- Start from standstill
+- Interrupting actions
+
+## Common ADSR Mistakes
+
+### All Values Same
+Everything feels samey. Vary ADSR between actions.
+
+### No Attack Phase
+Movement feels robotic, digital, unnatural.
+
+### No Release Phase
+Stopping feels abrupt, jarring.
+
+### Too Long Attack
+Players feel input is being ignored.
+
+### Too Long Release  
+Players feel out of control.
+
+### Inconsistent Curves
+Different actions feel like different games.
+
+## ADSR for Different Actions
+
+| Action | Attack | Release | Notes |
+|--------|--------|---------|-------|
+| Walk | 0.1-0.2s | 0.2-0.3s | Moderate both |
+| Run | 0.2-0.4s | 0.3-0.5s | Longer for weight |
+| Jump | Instant | Gravity-driven | Special handling |
+| Turn | 0.05-0.1s | 0.05-0.1s | Needs precision |
+| Shoot | 0-0.03s | 0-0.03s | Near instant |
+| Charge | 0.5-3s | Variable | Long attack is the point |
+| Drift | N/A | 1-3s | Release IS the mechanic |
+
+## Testing Tools
+
+### Frame-by-Frame Analysis
+Record gameplay at 60fps, step through frames
+Count frames from input to response
+
+### Value Visualization
+Graph position/velocity over time
+Look for smooth curves vs jagged transitions
+
+### Comparison Recording
+Record same action in reference game
+Match curves to match feel

package/.claude/skills/game-feel/references/classic-profiles.md

@@ -0,0 +1,279 @@
+# Classic Game Feel Profiles
+
+Detailed breakdowns of iconic game feel implementations for reference and study.
+
+---
+
+## Asteroids (1979)
+
+**Feel Summary**: Floaty, on-the-edge-of-control, expressive space simulation
+
+### Why It Worked
+Asteroids redefined what games could feel like. By separating thrust from rotation, it created a sensation of piloting a craft that was always *almost* out of control—but never actually was.
+
+### Input
+- 5 two-state buttons (Rotate L/R, Thrust, Fire, Hyperspace)
+- Two-handed operation required
+- No chorded moves
+- Big, springy, satisfying buttons
+
+### Core Mechanic: Separated Thrust/Rotation
+
+**Rotation**: Direct, instant
+```
+if (rotateLeft) shipAngle -= rotateSpeed
+if (rotateRight) shipAngle += rotateSpeed
+```
+- Very slight attack (~0.1s ramp)
+- No simulation, no inertia
+- Crisp, precise
+
+**Thrust**: Simulated, accumulative
+```
+thrustVector = directionFromAngle(shipAngle) × thrustSpeed
+shipVelocity = shipVelocity + thrustVector  // ADD, not overwrite!
+```
+- Floaty 3+ second attack to max speed
+- 4+ second release (very low dampening ~0.99)
+- Creates "spacey" frictionless feel
+
+### Critical Insight
+The thrust vector is **added** to ship velocity, not overwriting it. This decouples where you're facing from where you're going—the fundamental Asteroids feel.
+
+### Context
+- Screen wrap containment (no escape)
+- Asteroid density provides constant danger
+- Ship moves faster than asteroids but less predictably
+- "Like being an experienced ice skater at a crowded public rink"
+
+### Polish
+- Size-pitch correlation: Large asteroid = deep boom, small = high ping
+- Ship disintegrates into component lines on death
+- Thruster visual: flickering vector line
+- Cohesive despite limited hardware
+
+### Rules
+- One-hit death (ship feels fragile)
+- Points scale with difficulty (small asteroid = 100, large = 20)
+- Flying saucers: High risk/reward (1000 points for small)
+- Extra life at 10,000 points
+
+---
+
+## Super Mario Bros (1985)
+
+**Feel Summary**: Fluid, expressive, intuitive—the gold standard for platformers
+
+### Why It Worked
+Miyamoto understood feel as artistic experience, not simulation accuracy. The result: controls that feel natural despite being highly artificial.
+
+### Input
+- NES Controller: D-pad + A (jump) + B (run)
+- Simple Boolean signals
+- B modifies movement parameters, not separate action
+
+### Horizontal Movement
+
+**Walk**:
+- Acceleration: Moderate
+- Max speed: Capped
+- Deceleration: Moderate slide to stop
+
+**Run (B held)**:
+- Acceleration: Higher
+- Max speed: Higher cap
+- Deceleration: Same as walk
+
+**Air**:
+- Acceleration: Reduced
+- Same max speed limits apply
+
+### Vertical Movement (The Jump)
+
+**The Recipe**:
+1. Button press → Instant large upward force
+2. While held → Force continues (up to max time)
+3. Early release → Velocity artificially set to low preset value
+4. Apex detected → Gravity TRIPLES for descent
+5. Terminal velocity caps fall speed
+
+**The Critical Hack**:
+When player releases jump early:
+```
+if (velocity.y > reducedJumpVelocity) {
+    velocity.y = reducedJumpVelocity  // Artificial cap
+}
+```
+This creates consistent arc shapes regardless of release timing.
+
+**Running Jump Boost**:
+If speed > walk max when jumping, slight extra jump force.
+
+### Key Parameters
+| Parameter | Approximate Value |
+|-----------|------------------|
+| Walk acceleration | Moderate |
+| Walk max speed | ~3 units/frame |
+| Run acceleration | Higher |
+| Run max speed | ~5 units/frame |
+| Air acceleration | ~30% of ground |
+| Jump force | Large instant burst |
+| Gravity | Moderate |
+| Fall gravity | 3× normal gravity |
+| Max jump time | ~0.4 seconds |
+
+### Context
+- Blocks at exact jump heights
+- Gaps at exact run-jump distances  
+- Enemies as timing challenges
+- Pipes and hidden areas reward exploration
+
+### Polish
+- Slide whistle jump sound (rising pitch)
+- Dust on direction change
+- Squash on landing
+- Simple but coherent
+
+### Rules
+- Size changes with powerups (feel different)
+- One-hit death (small) or shrink (big)
+- Coins everywhere (constant small rewards)
+- Time pressure (never truly relaxed)
+
+---
+
+## Super Mario 64 (1996)
+
+**Feel Summary**: Expressive 3D translation with precision special moves
+
+### Why It Worked
+Successfully translated 2D Mario feel to 3D through camera-relative controls, multiple jump types, and incline-based physics.
+
+### Input
+- N64 controller: Analog stick + A (jump) + B (attack) + Z (crouch)
+- Stick provides continuous direction AND speed
+- Camera controls on C-buttons
+
+### Movement System
+
+**Thumbstick → World Direction**:
+```
+worldDirection = cameraForward × stick.y + cameraRight × stick.x
+```
+
+**Turn Interpolation**:
+```
+if (speed > 0) {
+    currentDirection = lerp(currentDirection, desiredDirection, turnSpeed)
+} else {
+    currentDirection = desiredDirection  // Instant at standstill
+}
+```
+Creates carving motion when moving, instant turns when stopped.
+
+**Incline Physics**:
+- Steep slopes (>45°) resist climbing
+- Very steep slopes (~75°) trigger slide state
+- Creates soft boundaries without invisible walls
+
+### Jump Types
+
+| Jump | Trigger | Height | Control |
+|------|---------|--------|---------|
+| Basic | A | Variable (hold) | Full air steering |
+| Continuous | A after landing | Higher, variable | Full air steering |
+| Triple | A after Continuous + speed | Highest, fixed | Air steering |
+| Long | Z+A moving | Low, far, fixed | Air steering |
+| Back Somersault | A while crouching | Very high, fixed | Air steering |
+| Side Somersault | A during direction change | High, fixed | Air steering |
+| Wall Kick | A near wall + away | Fixed | Limited steering |
+
+**Variable vs Fixed**:
+- Variable jumps: Expressive, moment-to-moment control
+- Fixed jumps: Predictable, precision platforming
+
+### Ground Pound
+```
+if (inAir && Z) {
+    velocity.x = 0; velocity.z = 0  // Kill horizontal momentum
+    wait(0.1)
+    velocity.y = -groundPoundSpeed
+}
+```
+Provides precision landing by removing horizontal momentum.
+
+### Context
+- Levels designed around jump trajectories
+- Landmarks visible from anywhere (aids navigation)
+- Inclines create soft boundaries
+- Open spaces for running, tight spaces for precision
+
+### Polish
+- Three-tier impact system (light/medium/heavy)
+- Surface-specific footsteps
+- Mario's vocalizations sync with motion
+- Exaggerated limb scaling on attacks
+
+### Control Ambiguity (Flaw)
+Z+A can produce ground pound, backflip, or long jump depending on subtle timing differences. This is acknowledged as a design flaw.
+
+---
+
+## Comparative Analysis
+
+### Response Time
+| Game | Attack | Release |
+|------|--------|---------|
+| Asteroids rotation | ~0.1s | Instant |
+| Asteroids thrust | ~3s | ~4s |
+| Mario Bros walk | ~0.2s | ~0.3s |
+| Mario Bros run | ~0.3s | ~0.3s |
+| Mario 64 run | ~0.15s | ~0.1s |
+
+### Expressivity
+| Game | Movement States | Jump Variety |
+|------|-----------------|--------------|
+| Asteroids | Continuous velocity | N/A |
+| Mario Bros | Walk/Run | Variable height |
+| Mario 64 | Walk/Run/Slide/Crawl | 7+ jump types |
+
+### What They Share
+1. **Separated systems**: Thrust/rotation, horizontal/vertical
+2. **Artificial interventions**: Hacks that feel natural
+3. **Context-mechanic fit**: Levels designed for the controls
+4. **Coherent polish**: Effects reinforce physics
+5. **Responsive input**: <100ms response times
+
+---
+
+## Modern Applications
+
+### When to Use Asteroids-Style Feel
+- Space games
+- Physics toys
+- "Barely in control" experiences
+- Games about mastering momentum
+
+### When to Use Mario-Style Feel
+- Platformers
+- Action games
+- Games requiring precise positioning
+- Accessible but deep controls
+
+### When to Use Mario 64-Style Feel
+- 3D platformers
+- Exploration games
+- Games with diverse movement options
+- Precision 3D navigation
+
+---
+
+## Study Recommendations
+
+To deeply understand these profiles:
+
+1. **Play** the original games extensively
+2. **Analyze** by recording and frame-stepping
+3. **Recreate** the feel in a simple prototype
+4. **Modify** parameters to understand their impact
+5. **Compare** to modern games in the same genre

package/.claude/skills/game-feel/references/perception-thresholds.md

@@ -0,0 +1,160 @@
+# Perception Thresholds for Game Feel
+
+Understanding human perception limits is essential for creating responsive controls.
+
+## The Model Human Processor
+
+Card, Moran, and Newell's research established three processors working in sequence:
+
+### Processor Cycle Times
+
+| Processor | Average | Range | Function |
+|-----------|---------|-------|----------|
+| **Perceptual** | ~100ms | 50-200ms | Takes sensory input, finds patterns |
+| **Cognitive** | ~70ms | 30-100ms | Compares state to intent, decides action |
+| **Motor** | ~70ms | 25-170ms | Translates decision to muscle movement |
+
+**Total correction cycle: ~240ms**
+
+This is the minimum time for a human to:
+1. See the current state
+2. Think about what to do
+3. Act on that decision
+
+## The Correction Cycle in Games
+
+When controlling a game, players run continuous correction cycles:
+
+```
+Intent (grab coin) 
+    → Perceive (see Mario's position)
+    → Think (too far right)
+    → Act (press left)
+    → Perceive (see Mario move)
+    → Think (almost there)
+    → Act (release, press jump)
+    → ...repeat at ~240ms intervals
+```
+
+This is identical to reaching for a muffin on your desk—constant micro-adjustments until the goal is achieved.
+
+## Critical Thresholds for Game Response
+
+### Frame Rate (Impression of Motion)
+
+| FPS | Milliseconds | Perception |
+|-----|--------------|------------|
+| 10 | 100ms | Minimum for motion illusion |
+| 20 | 50ms | Acceptable motion |
+| 30 | 33ms | Smooth motion |
+| 60 | 16ms | Very smooth |
+| 120+ | <8ms | Diminishing returns for most |
+
+**Why it matters**: Below 10fps, the brain sees discrete images, not motion. The illusion breaks.
+
+### Response Time (Input to Visual Feedback)
+
+| Response | Feel | Notes |
+|----------|------|-------|
+| <50ms | Instantaneous | "Extension of your body" |
+| 50-100ms | Tight, responsive | Ideal for action games |
+| 100-150ms | Noticeable but acceptable | Strategy games tolerate this |
+| 150-200ms | Sluggish | Players complain |
+| >240ms | Broken | Exceeds correction cycle |
+
+**The 50ms rule**: At 50ms or less, cause and effect feel simultaneous due to perceptual fusion.
+
+### Continuity (Consistent Response Rate)
+
+The game must accept input and provide feedback at **consistent 100ms intervals or less**.
+
+Sporadic response is worse than slow response:
+- Consistent 80ms = acceptable
+- Varying 40-200ms = feels broken
+
+## Perceptual Fusion
+
+When two events occur within the same perceptual cycle (~100ms), they appear fused:
+
+- Mario in position A, then position B within 100ms = perceived as motion
+- Button press and character response within 100ms = perceived as cause-and-effect
+
+**This is how games create the illusion of direct control.**
+
+## Fitt's Law Application
+
+The time to reach a target depends on distance and target size:
+
+```
+MT = a + b × log₂(2D/W)
+
+MT = movement time
+a = start/stop time
+b = device speed
+D = distance to target
+W = target width
+```
+
+**Game design implications**:
+- Larger targets = faster to hit
+- Closer targets = faster to hit
+- Menu items at screen edges = effectively infinite width
+- Tiny checkboxes = frustrating
+
+## Factors That Affect Perception Speed
+
+### Faster Processing
+- High alertness/stress
+- Familiar tasks
+- Clear visual feedback
+- Predictable patterns
+
+### Slower Processing
+- Fatigue
+- Distraction
+- Poor visibility
+- Novel situations
+
+## Measuring Your Own Response Time
+
+Test at humanbenchmark.com/tests/reactiontime
+
+Typical results:
+- Average person: 200-250ms
+- Trained gamer: 150-180ms
+- Theoretical minimum: ~150ms
+
+This represents perception + cognition + motor response combined.
+
+## Practical Guidelines
+
+### For Responsive Feel
+1. Target <100ms input-to-display
+2. Maintain consistent frame rate (30+ fps)
+3. Never exceed 240ms response time
+4. Use animation to mask unavoidable delays
+
+### Acceptable Delay Contexts
+Delays can be acceptable when:
+- Player chose to trigger a long animation
+- Metaphor supports it (heavy character)
+- Risk/reward tradeoff is clear
+- Delay is consistent and predictable
+
+### Breaking Feel Intentionally
+Sometimes you want temporary loss of control:
+- Recovery frames after attacks (fighting games)
+- Stumble animations after hits
+- Charge-up mechanics
+
+**Key**: Player must have chosen to enter the vulnerable state.
+
+## The Computer's Responsibility
+
+Real-time control requires the computer to maintain:
+
+1. **Motion threshold**: Display updates at 10+ fps (ideally 30+)
+2. **Response threshold**: Input-to-display in <240ms (ideally <100ms)
+3. **Continuity threshold**: Consistent update rate at 100ms or less
+
+If any threshold is violated, the player will notice. If response exceeds 240ms, real-time control is broken entirely.