A terminal-based racing game showcasing modern JavaScript and Python features through identical implementations

Vertical Lane Racer is an educational project that implements the same racing game in both JavaScript and Python, demonstrating how modern language features can be applied to solve real-world problems. Watch 4 AI-controlled cars race down vertical lanes, dodging obstacles in your terminal!

cd javascript
npm install
npm start

cd python
python3 src/main.py

• 🏎️ 4 Vertical Lanes - Cars can switch between lanes dynamically
• 🎮 AI-Controlled - Random decision making via pluggable controllers
• 💥 Dynamic Obstacles - Randomly spawned hazards to avoid
• 🏁 Win Condition - First car to the finish line wins
• 🎨 Terminal UI - Smooth animated rendering with emojis
• ⚡ Real-time - 10 FPS with async concurrent updates

Cars delegate decision-making to controller objects, making the game AI-ready with zero refactoring:

• Current: RandomController (random lane changes)
• Future: AIController (LLM-based decisions)
• Future: UserController (keyboard input)

Even though random decisions are instant, the entire system uses async/await to support future controllers that require network requests (AI models) or user input.

Complete game state can be exported to JSON, enabling:

• AI model integration (text or vision-based)
• Network multiplayer
• Replay systems
• Debugging and analysis

race_sim/
├── README.md                  # This file
├── game.md                    # Complete game design document
├── phase_1.md                 # Phase 1 completion report
├── phase_2.md                 # Phase 2 completion report
│
├── javascript/                # JavaScript implementation
│   ├── README.md
│   ├── package.json
│   └── src/
│       ├── main.js           # Entry point
│       ├── game.js           # Game controller
│       ├── renderer.js       # Terminal rendering
│       ├── config.js         # Constants
│       ├── entities/         # Car, Obstacle
│       ├── controllers/      # RandomController
│       └── utils/            # Sleep, generators
│
└── python/                    # Python implementation
    ├── README.md
    └── src/
        ├── main.py           # Entry point
        ├── game.py           # Game controller
        ├── renderer.py       # Terminal rendering
        ├── config.py         # Constants
        ├── entities/         # Car, Obstacle
        ├── controllers/      # RandomController
        └── utils/            # Generators

• Implemented Car, Obstacle, and RandomController classes
• Established strategy pattern architecture
• Full feature parity between JS and Python

• Game class with collision detection
• Win condition checking
• Obstacle spawning and management
• State serialization

• Generator functions for obstacles
• Async generators with delays
• Iterator helpers and utilities

• Full terminal renderer with ANSI codes
• Track visualization with cars and obstacles
• Stats display and results screen
• Smooth frame updates

• Complete game loop with rendering
• Graceful shutdown (Ctrl+C handling)
• Error handling and cleanup
• Production-ready entry points

• Comprehensive README files
• Code comments highlighting features
• Architecture documentation
• Usage examples

• ✨ ES Modules (import/export)
• 🔒 Private Fields (#speed)
• 🎭 Async/Await & Promise.all
• 🧬 Generators (function*)
• 🎯 Optional Chaining (?.)
• 🔢 Nullish Coalescing (??)
• 📦 Set.difference() (ES2024)
• 🏷️ Template Literals
• 📋 Destructuring
• 🌊 Spread Operator

• 📝 Type Hints (list[Car], dict[str, Any])
• 🎭 Pattern Matching (match/case)
• 📊 Dataclasses (@dataclass)
• 🔌 Protocols (structural typing)
• 📜 Enhanced F-Strings
• 🔄 Context Managers (with)
• ⚡ Async/Await & asyncio.gather
• 🧬 Generators & Comprehensions
• 🎨 Decorators (@property)
• 🎯 Literal Types

This project demonstrates:

1. Identical Logic, Different Syntax - Same game, different language features
2. Modern Patterns - Strategy pattern, async/await, generators
3. Production Practices - Error handling, cleanup, documentation
4. Type Safety - JSDoc (JS) vs Type Hints (Python)
5. Terminal UI - ANSI codes, rendering, animation
6. Async Architecture - Concurrent updates, promise handling

1. AI Controller - Integrate Claude/GPT for decision making
2. User Controller - Add keyboard controls
3. Vision Models - Send rendered frame to vision models

4. Power-ups - Speed boost, shield, invincibility
5. Difficulty Levels - More obstacles, faster speeds
6. Leaderboard - Track best times and records

7. Multiplayer - Network-based racing
8. Replay System - Save and replay races
9. Custom Tracks - Load track layouts from files
10. Sound Effects - Terminal bell for events

# JavaScript version
cd javascript && npm start

# Python version
cd python && python3 src/main.py

Press Ctrl+C at any time to exit cleanly.

• 📖 JavaScript README - Detailed JS implementation guide
• 📖 Python README - Detailed Python implementation guide
• 📋 Game Design Document - Complete architectural specification
• ✅ Phase 1 Report - Core entities completion
• ✅ Phase 2 Report - Game logic completion

• Node.js v18.0.0+
• Terminal with emoji support

• Python 3.10+
• Terminal with emoji support

1. Compare async/await patterns between languages
2. Study private fields (#) vs Python's _ convention
3. Compare generators and iterators
4. Learn about Python's type hints and protocols

1. Explore JavaScript's private fields and closures
2. Compare comprehensions with array methods
3. Study Promise.all vs asyncio.gather
4. Learn about optional chaining and nullish coalescing

1. Understand the strategy pattern implementation
2. Learn terminal rendering techniques
3. Study async architecture for I/O-bound operations
4. Explore state serialization patterns

MIT - Educational project for learning modern programming language features

This is an educational project. Feel free to:

• Fork and experiment
• Add new controller types
• Implement additional features
• Create tutorials or guides

Built as a practical demonstration of modern JavaScript and Python features, showcasing how the same problem can be solved idiomatically in different languages.

Happy Racing! 🏁