A turn-based vector racing game for iOS
GridRacer is a strategic racing game inspired by classic pen-and-paper racing games. Navigate a grid-based track using velocity and acceleration vectors. High speed means fast progress but less control—crash into walls and lose one of your three lives!
- 🏎️ Turn-based vector racing - Position + velocity + acceleration physics
- 🎮 2-player local multiplayer - Take turns, see opponent moves
- 💥 Collision detection - Bresenham algorithm checks entire movement path
- ❤️ Lives system - 3 lives per player with respawn
- 🏁 Lap counting - First to complete a lap wins
- ✨ Visual polish - Grid lines, checkerboard finish, animated indicators
- 🎯 60 FPS - Smooth SceneKit rendering
- ✅ 92+ tests - Comprehensive unit test coverage
 |
 |
Each turn, choose one of 9 acceleration vectors:
(-1,+1) (0,+1) (+1,+1)
↖ ↑ ↗
(-1, 0) (0, 0) (+1, 0)
← ● →
(-1,-1) (0,-1) (+1,-1)
↙ ↓ ↘
Movement Formula:
NewPosition = CurrentPosition + CurrentVelocity + Acceleration
NewVelocity = CurrentVelocity + Acceleration
- Navigate the track without crashing
- Build up speed on straightaways
- Slow down for corners (or risk crashing!)
- Cross the finish line first
- Tap green markers - Valid moves (stay on track)
- Red markers - Would crash into walls
- Reset button - Start a new race
- Autoplay button - Watch AI race
- Xcode 15.0+
- iOS 18.5+ (or iOS Simulator)
- macOS 14.0+ (for development)
# Clone the repository
git clone https://github.com/Pjpj42/GridRacer.git
cd GridRacer
# Open in Xcode
open GridRacer.xcodeproj
# Select your simulator/device and press Cmd+R to run# Build
xcodebuild -scheme GridRacer -configuration Debug \
-destination 'generic/platform=iOS Simulator' build
# Run tests
xcodebuild test -scheme GridRacer \
-destination 'platform=iOS Simulator,name=iPhone 16'
# Launch in simulator
xcrun simctl launch booted trouarat.GridRacer- Language: Swift 5.0
- Graphics: SceneKit (3D rendering of 2D grid)
- UI: UIKit
- Testing: Swift Testing + XCTest
- Platform: iOS 18.5+
GridRacer/
├── GridRacer/ # Main app source
│ ├── Model/ # Game state (immutable structs)
│ ├── Logic/ # Game engine, collision, movement
│ ├── Rendering/ # SceneKit renderers
│ └── UI/ # UIKit views and controls
├── GridRacerTests/ # Unit tests (Swift Testing)
├── GridRacerUITests/ # UI tests (XCTest)
├── docs/ # Design documents
└── .claude/ # AI-assisted development config
- Immutable state - All game state uses value types (structs)
- Functional updates - State transitions return new state
- Separation of concerns - Model, logic, rendering, UI layers
- Test-driven - 80%+ coverage on game logic
This project includes Claude Code configuration for AI-assisted development:
# See available commands
/help
# Run full development cycle
/iterate
# Create new feature from design doc
/feature "feature-name"
# Analyze and fix bugs
/debug "issue description"See CLAUDE.md for complete development guide.
# Run all tests
xcodebuild test -scheme GridRacer
# Run specific test suite
xcodebuild test -scheme GridRacer \
-only-testing:GridRacerTests/GameEngineTests
# With coverage
xcodebuild test -scheme GridRacer -enableCodeCoverage YES- CLAUDE.md - Developer guide and AI assistant context
- docs/GridRacer Concept.md - Game design document
- [.claude/rules/](. claude/rules/) - Architecture and coding conventions
- Additional tracks (5+ layouts)
- Track difficulty ratings
- Sound effects and music
- 3D racer models
- Single-player mode
- Multiple AI difficulty levels
- AI racing line optimization
- 3-4 player support
- Online multiplayer
- Leaderboards
- Track editor
- Particle effects
- Camera controls
- Achievements
Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
See .github/CONTRIBUTING.md for detailed guidelines.
This project is licensed under the MIT License - see the LICENSE file for details.
- Inspired by classic pen-and-paper racing games
- Built with Claude Code AI assistant
- Uses Bresenham's line algorithm for collision detection
PJ - @Pjpj42
Project Link: https://github.com/Pjpj42/GridRacer
Made with ❤️ and vector physics