Asteroids Demo Game for SolarSail

A classic Asteroids arcade game demonstrating physics, collision detection, AI systems, and robust entity management in the SolarSail engine.

Features

• Ship movement with rotation and thrust
• Shooting mechanics with accurate collision detection
• Asteroid spawning and splitting (large → medium → small)
• Score tracking (20/50/100 points by size)
• Lives system (3 lives)
• Wave progression
• Ghost ship visual for edge wrapping
• AI Demo mode - intelligent autopilot
• AI Monkey mode - chaotic stress testing

Game Features

• Classic vector-style graphics
• Momentum-based physics
• Screen wrapping for ship and asteroids
• Progressive difficulty with wave system
• Hyperjump emergency escape
• Audio feedback for all actions

Technical Implementation

Key Design Patterns

1. Robust Entity Management: Comprehensive system preventing double-release and race conditions

   • Entity lifecycle tracking
   • Collision coordination
   • Resource cleanup management

2. AI Systems: Two distinct AI personalities

   • Demo AI: Intelligent targeting, threat avoidance, strategic decisions
   • Monkey AI: Stress testing with chaotic random behaviors

3. Single Responsibility Architecture: Clean separation of concerns

   • Bullets handle movement/lifetime only
   • GameController manages all collision detection
   • Each system has a focused responsibility

4. Frame-Independent Physics: Uses Time.deltaTime for consistent gameplay

5. Component Pattern: Each game object has dedicated script modules

File Structure

• game.json - Scene definition with entities and templates
• program.lua - Main engine callbacks
• gamecontroller.lua - Core game logic and collision detection
• ship.lua - Ship movement and controls
• bullet.lua - Bullet movement and lifecycle
• asteroid.lua - Asteroid behavior and splitting
• explosion.lua - Visual effects
• ai_demo.lua - Intelligent AI player
• ai_monkey.lua - Chaos testing AI
• constants.lua - Centralized game constants
• math_utils.lua - Mathematical utilities

Building and Running

make

Controls

Ship Controls

• Arrow Keys or WASD: LEFT/A rotate left, RIGHT/D rotate right, UP/W thrust forward
• SPACE or ENTER: Shoot bullets
• H, J or SHIFT: Hyperjump (teleport to random location with 25% self-destruct risk)

Game Controls

• ESC or P: Pause/Resume game
• R: Reset game
• 1: Human control mode
• 2: AI Demo mode (intelligent autopilot)
• 3: AI Monkey mode (chaotic stress testing)

Implementation Notes

• Uses SolarSail's Entity Component System
• All coordinates in world space (-1.78 to 1.78 for X, -1 to 1 for Y)
• Collision detection uses distance-based checks
• Ghost ship visualization for seamless edge wrapping
• AI performance metrics tracked for game balance tuning

AI Performance Metrics

The AI Demo mode tracks:

• Shot accuracy percentage
• Survival time and death count
• Score gained per life
• Decision-making frequency
• Threat avoidance success rate

Recent Improvements

• Fixed asteroid movement to use proper straight-line trajectories
• Refactored collision detection for single responsibility
• Added comprehensive entity lifecycle management
• Implemented ghost ship edge wrapping visualization
• Created two distinct AI personalities for different purposes

Potential Enhancements

• UFO enemies (large and small variants)
• Power-ups (shield, rapid fire, multi-shot)
• Particle effects for explosions and thrust
• Persistent high score tracking
• Start menu and settings
• Mobile touch controls