🎮 Play the Egg Drop game

Egg Drop is a fun web-based game where you control Chef Rafi who tries to catch eggs dropped by hens to make his egg drop soup. It was inspired by the old Atari 2600 game, Kaboom. Additionally, this version of game features a genetic algorithm that evolves the characteristics of the hens over time, making each playthrough unique and progressively challenging.

This project was originally created as a demo for my talk, "Evolving Game Development with Genetic Algorithms" that was delivered at:

• What The Stack - Skopje, North Macedonia, September 14, 2024 | Slides
• React Alicante - Alicante, Spain, September 21, 2024 | Slides | Video
• CityJS Athens - Athens, Greece, November 29, 2024

• Node.js (v18 or higher recommended)
• pnpm package manager

1. Clone the repository:

   git clone https://github.com/kevinmaes/eggdrop.git
   cd eggdrop

2. Install dependencies:

   pnpm install

3. Start the development server:

   pnpm dev

4. Open your browser and navigate to:

   http://localhost:5173
   

For more testing commands and details, see TESTING.md.

See TESTING.md for a complete guide to running tests.

Canvas games are notoriously hard to test. Traditional approaches have significant limitations:

• Visual/screenshot testing - Brittle, slow, breaks on any UI change
• Fake DOM elements - Extra maintenance, test drift, doesn't guarantee canvas output matches tested state
• No DOM representation - Can't query or assert on canvas state directly

Our solution: Test the state machines directly instead of the canvas rendering.

Using XState, we expose a test API (window.__TEST_API__) that provides:

• Direct access to state machine contexts (positions, velocities, game state)
• Event sending to trigger state transitions
• Snapshot queries for assertions

Benefits:

• Tests are deterministic and fast
• Only break when game logic changes, not UI
• Can test internal state that isn't visible
• Enable complex scenarios like the ChefBot AI playing full games

Further reading: XState Testing Docs • MDN Canvas Testing

This project uses GitHub Actions for Continuous Integration. The CI workflow:

1. Runs on all Pull Requests to the main branch
2. Verifies code quality with TypeScript and ESLint checks
3. Ensures all tests pass before merging
4. Confirms the build process works correctly

You can run these checks locally before pushing with:

pnpm ci

• React - UI library for building the game interface
• TypeScript - Type-safe JavaScript for robust code
• Vite - Fast build tool and development server

• Konva - Canvas library for 2D graphics and animations
• React Konva - React integration for Konva
• XState - State management using state machines and the actor model
• Howler - Audio library for game sounds

Several XState state machines are used throughout the game:

• Application (loading and overall coordination)
• Game Play (levels)
• Chef - Player character controlled by the user
• Hen
• Egg (hatching into chicks)
• Egg Points - Points won when catching an egg
• Sounds

The game features a genetic algorithm that evolves the characteristics of the hens who drop eggs. Each hen (referred to as a "Hendividual") has DNA composed of traits related to:

• Movement patterns and speed
• Egg-laying frequency and timing
• Other behavioral characteristics

As the game progresses, hens evolve based on their performance, creating a dynamic and increasingly challenging gameplay experience.

The game includes a developer panel to track statistics related to the genetic algorithm:

• Press cmd-d (Mac) or ctrl-d (Windows/Linux) to toggle the Dev Panel visibility
• Monitor hen population statistics and evolution metrics
• Track game performance and state

eggdrop/
├── public/               # Static assets (images, sounds, fonts)
├── src/                  # Source code
│   ├── App.tsx           # Main application component
│   ├── app.machine.ts    # Main state machine
│   ├── Hen/              # Hen components and logic
│   ├── Egg/              # Egg components and logic
│   ├── Chef/             # Chef (player) components
│   ├── GameLevel/        # Level management
│   ├── geneticAlgorithm/ # Genetic algorithm implementation
│   ├── DevPanel/         # Developer panel components
│   └── ...               # Other components and utilities
├── package.json          # Dependencies and scripts
└── vite.config.ts        # Vite configuration

The following tools were used to create game assets:

• ChatGPT - Character image generation
• Logoist 5 - Vector graphics and animation alignment
• Texture Packer - Sprite sheet creation
• Audacity - Audio recording and editing

THIS GAME IS STILL IN ACTIVE DEVELOPMENT

See the Issues for a list of upcoming features, fixes, and enhancements.

Current limitations:

• No instructions screen
• No defined end-game condition
• Genetic algorithm still being refined

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

Kevin Maes - @kvmaes