feat(crash): Cosmic Encounters system

[evanmcfarland]

Summary

• Adds "Cosmic Encounters" system to Crash game - space objects (satellites, planets, aliens, galaxies) that appear during flight based on altitude
• Encounters drift down and left, simulating the rocket flying past them through space
• Higher multiplier = more frequent and exotic encounters (formula: 10% + 3% per multiplier, capped at 70%)

Features

• 5 altitude zones with appropriate encounter types:

  • Low orbit (5x-20x): satellites, astronauts, space stations
  • Deep space (20x-60x): asteroids, comets, moons
  • Outer system (60x-120x): ringed planets, gas giants, alien probes
  • Interstellar (120x-250x): alien ships, wormholes, Dyson spheres
  • Cosmic (250x+): galaxies, black holes, cosmic entities

• Dynamic movement: Objects drift based on current altitude (faster at higher multipliers)

• Type-specific animations: Wormholes/galaxies spin, aliens wobble, rare objects glow

• Visual effects: Fade in/out, drop shadows, text glow

Notes

• Currently uses emoji placeholders - PNG sprites can be added later
• Deployed and tested at https://pezw3-laaaa-aaaal-qssoa-cai.icp0.io/crash

Test plan

• Play game, watch for encounters appearing at various multipliers
• Verify encounters drift smoothly down-left
• Check that encounter types match altitude zones
• Confirm encounters clear when game resets

🤖 Generated with Claude Code

[claude]

Code Review: Cosmic Encounters System

🎯 Overall Assessment

This is a well-implemented feature that adds visual polish to the Crash game. The code is clean, well-structured, and follows good React patterns. However, there are several concerns around performance, user experience, and code maintainability.

---

✅ Strengths

1. Code Organization & Structure

• Clean separation of concerns with CosmicEncounter interface and EncounterType
• Good use of React patterns: useCallback, useRef, proper cleanup in useEffect
• Well-documented altitude zones and encounter types
• CSS animations properly separated into CrashRocket.css

2. Visual Design

• Progressive encounter system (5 altitude zones) is creative
• Probability formula (10% + 3% per multiplier, capped at 70%) is balanced
• Emoji placeholders are practical for MVP - easy to swap for real sprites later
• Multiple animation styles (pulse, spin, wobble, glow) add variety

3. Performance Considerations

• Throttling encounter checks (1.5s intervals) prevents spam
• Cleanup of expired encounters every 1s
• Proper animation frame cleanup

---

⚠️ Issues & Concerns

🔴 Critical: Performance Impact

Issue 1: Render Performance

// Lines 1021-1087: Encounters are rendered on EVERY frame
{encounters.map(encounter => {
  const now = Date.now();
  const elapsed = now - encounter.startTime;
  // ... calculations on every render

Impact: With 10+ encounters on screen, this creates unnecessary recalculations every render (60fps).

Recommendation:

// Use useMemo to cache encounter rendering
const renderedEncounters = useMemo(() => {
  const now = Date.now();
  return encounters.map(encounter => {
    // ... calculations
  }).filter(Boolean);
}, [encounters, size]); // Only recalculate when encounters or size changes

---

Issue 2: Z-Index Layer Confusion

// Line 1019: Encounters at z-index 25
style={{ zIndex: 25 }}

// Lines 885, 953: Rockets at z-index 20-30
zIndex: rocket.isCrashed ? 25 : 20
zIndex: 20 + i

Problem: Crashed rockets and encounters share z-index 25, causing overlapping issues.

Recommendation:

// Define clear z-index hierarchy
const Z_INDEX = {
  STARS: 5,
  CANVAS: 10,
  ENCOUNTERS: 15,
  ROCKETS_FLYING: 20,
  ROCKETS_CRASHED: 25,
  UI: 30
} as const;

---

🟡 User Experience Issues

Issue 3: Visual Clutter at High Multipliers

At 200x+, encounters spawn at 70% probability every 1.5s = ~0.5 encounters per second. Over 10 seconds, that's 5+ simultaneous encounters, which could obscure rockets.

// Line 321: High probability at high multipliers
const chance = Math.min(0.10 + 0.03 * multiplier, 0.70);

Recommendations:

1. Add encounter limit: if (encounters.length >= 8) return;
2. Reduce max probability to 50%
3. Increase check interval at high multipliers

---

Issue 4: Drift Direction Confusing

// Lines 330-342: Objects drift down-left
const driftAngle = -0.6 + Math.random() * 0.4; // -0.6 to -0.2 radians

Problem: In space, the rocket flying up-right should see objects drift down-left (parallax effect). But random drift angles add inconsistency.

Recommendation: Consider physics - all objects should drift consistently based on rocket velocity, not random angles.

---

🟢 Code Quality Issues

Issue 5: Magic Numbers

// Lines 336-340: Unexplained magic numbers
x: 20 + Math.random() * 60, // Why 20-80?
y: 5 + Math.random() * 50,  // Why 5-55?
duration: 5000 + Math.random() * 3000, // Why 5-8 seconds?

Recommendation: Extract to constants with comments:

const ENCOUNTER_CONFIG = {
  X_SPAWN_MIN: 20, // Avoid left edge
  X_SPAWN_RANGE: 60, // Center spawn zone
  Y_SPAWN_MIN: 5, // Start higher for drift
  Y_SPAWN_RANGE: 50,
  DURATION_MIN: 5000,
  DURATION_VARIANCE: 3000
} as const;

---

Issue 6: Duplicate Animation Classes

/* Lines 230-241: encounterPulse */
.cosmic-encounter {
  animation: encounterPulse 2s ease-in-out infinite;
}

/* Lines 264-275: encounterGlow */
.cosmic-encounter-rare {
  animation: encounterGlow 1.5s ease-in-out infinite;
}

Both do similar brightness pulsing. Consider consolidating or clarifying their distinct purposes.

---

Issue 7: Memory Leak Risk

// Lines 376-394: Interval creates closure over checkForEncounter
useEffect(() => {
  const encounterInterval = setInterval(() => {
    // Uses checkForEncounter from outer scope
    checkForEncounter(currentMax, Date.now());
  }, 500);
  return () => clearInterval(encounterInterval);
}, [checkForEncounter]); // ⚠️ checkForEncounter recreated on every render

Problem: If checkForEncounter changes frequently (due to deps), interval is destroyed/recreated rapidly.

Recommendation: Add useCallback dependencies analysis or use ref pattern.

---

🟣 Testing & Maintainability

Issue 8: No Tests

This feature has zero test coverage. Consider adding:

• Unit tests for getEncounterTypeForAltitude (altitude zone logic)
• Unit tests for probability calculation
• Visual regression tests for encounter animations

---

Issue 9: Accessibility

// Line 1082: Emoji without proper semantics
<span role="img" aria-label={encounter.type}>
  {visual.emoji}
</span>

Problem: aria-label="satellite" is better than aria-label="satellite" but emojis aren't meaningful to screen readers in this context.

Recommendation: Since encounters are decorative, use aria-hidden="true" or role="presentation".

---

🔵 Documentation

Issue 10: Missing Inline Comments

Complex logic like drift calculation (lines 326-342) needs inline comments:

// Calculate drift speed based on altitude (faster at high multipliers)
// Objects appear to move faster as rocket accelerates
const baseDriftSpeed = 3 + Math.min(multiplier / 10, 8);

---

🎯 Recommended Changes Before Merge

Priority 1 (Must Fix):

1. ✅ Fix z-index conflicts between encounters and rockets
2. ✅ Add encounter limit (max 8 on screen)
3. ✅ Optimize render performance with useMemo

Priority 2 (Should Fix):

4. Extract magic numbers to constants
5. Reduce max encounter probability to 50%
6. Add comments to drift calculation logic

Priority 3 (Nice to Have):

7. Add unit tests for altitude zones
8. Fix accessibility (aria-hidden on decorative emojis)
9. Consolidate duplicate CSS animations

---

🚀 Deployment Checklist

Before deploying to mainnet:

• Test at 10x, 50x, 100x, 200x multipliers
• Verify no performance degradation (check Chrome DevTools Performance tab)
• Test on mobile (portrait + landscape)
• Verify encounters don't obscure critical UI elements
• Test with reduced motion preferences (prefers-reduced-motion)

---

💡 Future Enhancements

Once real pixel art sprites are added:

1. Replace emoji with PNG sprites in /public/cosmic/ folder
2. Add sprite sheet for better performance
3. Consider WebGL/Canvas rendering for 20+ simultaneous encounters
4. Add sound effects for rare encounters (wormholes, black holes)

---

🎨 Final Thoughts

This is a solid feature that adds personality to the game. The code is mostly well-written, but needs performance optimization before mainnet deployment. The 70% encounter rate at high multipliers may overwhelm players visually.

Recommendation: Merge after addressing Priority 1 issues.

[claude]

Code Review - PR #186: Cosmic Encounters System

Summary

This PR adds a "Cosmic Encounters" system to the Crash game, where space objects (satellites, planets, aliens, galaxies) appear during flight based on altitude. The implementation is feature-complete with 15 encounter types across 5 altitude zones, dynamic probability-based spawning, smooth fade animations, and drift movement effects.

---

Strengths

1. Well-Structured Implementation

• Clean separation of concerns with dedicated types, configs, and helper functions
• Good use of TypeScript with proper type definitions
• Constants are well-organized (ENCOUNTER_CONFIG, Z_INDEX) making the system configurable
• Clear code comments explaining the purpose of each section

2. Game Design & UX

• Altitude-based progression creates a sense of journey (satellites to planets to galaxies)
• Probability scaling (10% base + 2% per multiplier) rewards higher flights with more encounters
• Visual feedback through emoji placeholders makes encounters immediately visible
• Smooth animations with fade in/out, drift movement, and type-specific effects
• Proper layering with Z_INDEX ensures encounters don't obscure gameplay elements

3. Performance Considerations

• MAX_ON_SCREEN: 6 limit prevents visual clutter and performance degradation
• Throttled encounter checks (CHECK_INTERVAL_MS: 1500) avoid excessive state updates
• Cleanup effect removes expired encounters efficiently
• Uses useCallback and useMemo appropriately to prevent unnecessary re-renders

4. CSS Animations

• Nice variety of keyframe animations (encounterPulse, encounterSpin, encounterWobble, encounterGlow)
• Different animation classes for different encounter types adds personality
• Animations are subtle enough not to distract from core gameplay

---

Issues & Concerns

1. Critical: Emoji Rendering Issues

Problem: Emojis may not render consistently across browsers/platforms. Some emojis might display as empty boxes or fall back to system defaults.

Impact: Users on older browsers/devices won't see encounters properly, defeating the purpose of the feature.

Recommendation: Create a fallback system with SVG icons or CSS-based visuals for consistent rendering across all platforms.

2. Performance: Animation Loop Concerns

Location: Lines 410-450 in CrashCanvas.tsx

Problem: The encounter drift calculation happens inside the render loop with Date.now() calls for every encounter on every render. With 6 encounters on screen at 60fps, this means 360+ calculations per second.

Recommendation: Move position updates to CSS animations or use a dedicated interval at 30fps instead of recalculating on every render.

3. Logic Issue: Encounter Spawning During Multiple Rockets

Location: Line 348 - checkForEncounter function

Problem: The probability formula uses the MAX multiplier across all rockets. If ONE rocket reaches 100x, encounters spawn as if ALL rockets are at 100x, which might feel disconnected from actual rocket positions.

Recommendation: Consider using average multiplier for more balanced spawning, or document this behavior explicitly.

4. Code Quality: Magic Numbers

Examples:

• Line 373: if (progress < 0.15) - fade-in threshold
• Line 375: if (progress > 0.8) - fade-out threshold
• Line 356: probability formula constants

Recommendation: Extract to named constants for better maintainability.

5. Missing Edge Case Handling

Location: Lines 410-450 - Encounter rendering JSX

Issues:

• No error boundary: If getEncounterVisual throws, entire render fails
• Potential race condition between render filter and cleanup interval
• Missing null checks

---

Security Review

No Critical Security Issues Found

The code handles:

• No user input processed in encounter system
• No external data fetched
• No eval() or dangerous operations
• Proper React key usage

---

Performance Analysis

Estimated Impact:

• CPU: +5-10% during active flight
• Memory: +~100KB
• Render time: +2-5ms per frame

Recommendations:

1. Profile on low-end mobile devices
2. Consider will-change: transform CSS hint for encounter elements
3. Use transform instead of left/top for drift (GPU acceleration)

---

Test Coverage

Major Gap: No Tests Added

Missing test cases:

1. Unit tests for getEncounterTypeForAltitude() - verify correct types per zone
2. Unit tests for checkForEncounter() - probability calculations
3. Integration tests for MAX_ON_SCREEN limit enforcement
4. Tests for cleanup logic when game resets

Recommendation: Add basic unit tests for the core encounter logic functions.

---

Code Style & Best Practices

Issues:

1. Inconsistent naming: Mix of SCREAMING_SNAKE_CASE and camelCase
2. Long function: checkForEncounter (54 lines) - consider splitting
3. Deep nesting: Encounter render JSX (5+ levels) - extract to component
4. Missing JSDoc: No documentation for public functions

---

Documentation

Issues:

1. No inline JSDoc for public functions
2. No README update explaining the feature
3. .ralph/ directory changes should be removed before merge

---

Deployment Considerations

Pre-Deploy Checklist:

• Test on Safari (emoji support varies)
• Test on mobile devices (performance + emoji rendering)
• Verify encounters don't interfere with touch controls
• Check memory usage over extended play sessions
• Confirm Z-index layering works correctly

---

Final Verdict: APPROVE WITH CHANGES

This is a solid feature implementation that adds meaningful visual interest to the game. The code is well-structured, performance-conscious, and the game design is sound.

Required Changes (Block Merge):

1. Fix emoji rendering - Add fallback for unsupported emojis or use simpler Unicode symbols
2. Add basic tests - At minimum, test encounter logic functions
3. Remove Ralph artifacts - Clean up .ralph/ directory changes

Recommended Changes (Don't Block):

4. Optimize animation performance (CSS transforms vs JS calculations)
5. Add JSDoc comments for public functions
6. Extract encounter rendering to separate component
7. Consider using average multiplier instead of max for spawning

---

Suggestions for Follow-Up PRs

1. Replace emojis with pixel art sprites (as mentioned in PR description)
2. A/B test spawn rates - Current formula might need tuning
3. Add encounter events - Rare encounters could trigger special effects
4. Analytics tracking - Log encounter types seen, correlate with engagement
5. Accessibility - Add aria-label descriptions for screen readers

---

Great Work!

This feature adds personality and progression to the Crash game. The altitude-based system creates a sense of exploration, and the implementation is clean and maintainable. With the suggested fixes (especially emoji fallbacks and tests), this will be a great addition to OpenHouse.

Reviewer: Claude Code
Review Date: 2026-01-13