enne2/mice
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

v1.1: Performance optimizations and bug fixes

Browse Source 
Major improvements:
- NumPy-based collision system supporting 200+ units (~3ms/frame)
- Spatial hashing with vectorized distance calculations
- 4-pass game loop ensuring correct collision timing
- Blood overlay system with pre-generated stain pool
- Cached render positions and viewport bounds
- Spawn protection preventing rats spawning on weapons

Bug fixes:
- Fixed bombs not killing rats (collision system timing)
- Fixed gas not affecting rats (collision system timing)
- Fixed rats spawning on weapons (added has_weapon_at check)
- Fixed AttributeError with Gas collisions (added isinstance check)
- Fixed blood stain transparency (RGBA + SDL_BLENDMODE_BLEND)
- Reduced point lifetime from 200 to 90 frames (~1.5s)
- Blood layer now clears on game restart

Technical changes:
- Added engine/collision_system.py with CollisionLayer enum
- Updated all units to use collision layers
- Pre-allocate NumPy arrays with capacity management
- Hybrid collision approach (<10 simple, ≥10 vectorized)
- Python 3.13 compatibility
This commit is contained in:
Matteo Benedetto
2025-10-24 20:04:26 +02:00
parent 12836dd2d2
commit b4224ed3a1
12 changed files with 619 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+129 -50
View File
@@ -3,7 +3,7 @@
Mice! is a strategic game where players must kill rats with bombs before they reproduce and become too numerous. The game is a clone of the classic game Rats! for Windows 95.
## Compatibility
*It's developed in Python 3.11, please use it*
*It's developed in Python 3.13, please use it*
## Features
@@ -12,6 +12,7 @@ Mice! is a strategic game where players must kill rats with bombs before they re
- **Graphics**: Custom graphics for maze tiles, units, and effects.
- **Sound Effects**: Audio feedback for various game events.
- **Scoring**: Points system to track player progress.
- **Performance**: Optimized collision detection system supporting 200+ simultaneous units using NumPy vectorization.
## Engine Architecture
@@ -19,22 +20,42 @@ The Mice! game engine is built on a modular architecture designed for flexibilit
### Core Engine Components
#### 1. **Rendering System** (`engine/sdl2.py`)
#### 1. **Collision System** (`engine/collision_system.py`)
- **CollisionSystem Class**: High-performance collision detection using NumPy vectorization
- **Features**:
- Spatial hashing with grid-based lookups (O(1) average case)
- Support for 6 collision layers (RAT, BOMB, GAS, MINE, POINT, EXPLOSION)
- Hybrid approach: simple iteration for <10 candidates, NumPy vectorization for ≥10
- Pre-allocated arrays with capacity management to minimize overhead
- Area queries for explosion damage (get_units_in_area)
- Cell-based queries for gas/mine detection (get_units_in_cell)
- **Performance**:
- Handles 200+ units at ~3ms per frame
- Reduces collision checks from O(n²) to O(n) using spatial partitioning
- Vectorized distance calculations for massive parallel processing
#### 2. **Rendering System** (`engine/sdl2.py`)
- **GameWindow Class**: Central rendering manager using SDL2
- **Features**:
- Hardware-accelerated rendering via SDL2
- Texture management and caching
- Sprite rendering with transparency support
- Sprite rendering with transparency support (SDL_BLENDMODE_BLEND for alpha blending)
- Text rendering with custom fonts
- Resolution-independent scaling
- Fullscreen/windowed mode switching
- Blood stain rendering with RGBA format and proper alpha channel
- **Optimizations**:
- Cached viewport bounds to avoid repeated calculations
- Pre-cached image sizes for all assets at startup
- Blood overlay layer system (no background regeneration needed)
- Pre-generated blood stain pool (10 variants) for instant spawning
- **Implementation**:
- Uses SDL2 renderer for efficient GPU-accelerated drawing
- Implements double buffering for smooth animation
- Manages texture atlas for optimized memory usage
- Handles viewport transformations for different screen resolutions
#### 2. **Input System** (`engine/controls.py`)
#### 3. **Input System** (`engine/controls.py`)
- **KeyBindings Class**: Handles all user input
- **Features**:
- Keyboard input mapping and handling
@@ -74,16 +95,18 @@ The Mice! game engine is built on a modular architecture designed for flexibilit
### Game Loop Architecture
The main game loop follows the standard pattern:
1. **Input Processing**: Capture and process user input
2. **Update Phase**: Update game state, unit logic, and physics
3. **Render Phase**: Draw all game objects to the screen
4. **Timing Control**: Maintain consistent frame rate
The main game loop follows an optimized 4-pass pattern:
1. **Pre-Registration Phase**: Populate collision system with unit positions before movement
2. **Update Phase**: Execute unit logic and movement (bombs/gas can now query collision system)
3. **Re-Registration Phase**: Update collision system with new positions after movement
4. **Collision & Render Phase**: Check collisions and draw all game objects
```
Input → Update → Render → Present → Repeat
Pre-Register → Move → Re-Register → Collisions → Render → Present → Repeat
```
This architecture ensures weapons (bombs, gas) can detect victims during their execution phase while maintaining accurate collision data.
## Units Implementation
The game uses an object-oriented approach for all game entities. Each unit type inherits from a base unit class and implements specific behaviors.
@@ -118,13 +141,29 @@ All units share common properties and methods:
**Implementation Details**:
```python
# Simplified rat behavior structure
# Optimized rat behavior with pre-calculated render positions
class Rat:
def update(self):
self.process_ai() # Decision making
self.handle_movement() # Position updates
self.check_collisions() # Collision detection
self.update_state() # State transitions
def move(self):
self.process_ai() # Decision making
self.handle_movement() # Position updates
self._update_render_position() # Cache render coordinates
def collisions(self):
# Use optimized collision system with vectorization
collisions = self.game.collision_system.get_collisions_for_unit(
self.id, self.bbox, self.collision_layer
)
# Process only Rat-to-Rat collisions
for _, other_id in collisions:
other_unit = self.game.get_unit_by_id(other_id)
if isinstance(other_unit, Rat):
self.handle_rat_collision(other_unit)
def draw(self):
# Use cached render positions (no recalculation)
self.game.render_engine.draw_image(
self.render_x, self.render_y, self.sprite, tag="unit"
)
```
#### 2. **Bomb Units** (`units/bomb.py`)
@@ -141,8 +180,23 @@ class Rat:
**Implementation Details**:
- **State Machine**: Armed → Countdown → Exploding → Cleanup
- **Collision System**: Different collision behaviors per state
- **Optimized Damage System**: Uses collision_system.get_units_in_area() with vectorized distance calculations
- **Effect Propagation**: Chain reaction support for multiple bombs
- **Area Query Example**:
```python
def die(self):
# Collect explosion positions
explosion_positions = self.calculate_blast_radius()
# Query all rats in blast area using vectorized collision system
victims = self.game.collision_system.get_units_in_area(
explosion_positions,
layer_filter=CollisionLayer.RAT
)
for unit_id in victims:
rat = self.game.get_unit_by_id(unit_id)
if rat:
rat.die()
```
#### 3. **Point Units** (`units/points.py`)
@@ -156,39 +210,52 @@ class Rat:
Units interact through a centralized collision and event system:
1. **Collision Detection**:
- Grid-based broad phase for efficiency
- Precise bounding box narrow phase
- Custom collision responses per unit type pair
- **Spatial hashing**: Grid-based broad phase with O(1) lookups
- **NumPy vectorization**: Parallel distance calculations for large candidate sets
- **Hybrid approach**: Direct iteration for <10 candidates, vectorization for ≥10
- **Layer filtering**: Efficient collision filtering by unit type (RAT, BOMB, GAS, etc.)
- **Area queries**: Optimized explosion and gas effect calculations
2. **Event System**:
- Unit death events
- Reproduction events
- Explosion events
- Point collection events
- Explosion events (with area damage)
- Point collection events (90 frames lifetime ~1.5s at 60 FPS)
3. **AI Communication**:
- Shared pathfinding data
- Pheromone trail system for rat behavior
- Danger awareness (bombs, explosions)
4. **Spawn Protection**:
- Rats won't spawn on cells occupied by weapons (mines, bombs, gas)
- Automatic fallback to adjacent cells if primary position blocked
- Prevents unfair early-game deaths
## Technical Details
- **Language**: Python 3.11
- **Language**: Python 3.13
- **Libraries**:
- `numpy` 2.3.4 for vectorized collision detection
- `sdl2` for graphics and window management
- `Pillow` for image processing
- `uuid` for unique unit identification
- `subprocess` for playing sound effects
- `tkinter` for maze generation visualization
- **Performance Optimizations**:
- Spatial partitioning for collision detection
- Texture atlasing for reduced memory usage
- Object pooling for frequently created/destroyed units
- Delta time-based updates for frame rate independence
- **Collision System**: NumPy-based spatial hashing reducing O(n²) to O(n)
- **Rendering Cache**: Pre-calculated render positions, viewport bounds, and image sizes
- **Blood Overlay**: Separate sprite layer eliminates background regeneration
- **Hybrid Processing**: Automatic switching between direct iteration and vectorization
- **Pre-allocated Arrays**: Capacity-based resizing minimizes NumPy vstack overhead
- **Texture Atlasing**: Reduced memory usage and GPU calls
- **Object Pooling**: Blood stain pool (10 pre-generated variants)
- **Delta Time Updates**: Frame rate independence
- **Memory Management**:
- Automatic cleanup of dead units
- Texture caching and reuse
- Efficient data structures for large numbers of units
- Efficient data structures for 200+ simultaneous units
- Blood stain sprite pool to avoid runtime generation
## Environment Variables
@@ -222,35 +289,47 @@ Units interact through a centralized collision and event system:
```
mice/
├── engine/ # Core engine components
│ ├── controls.py # Input handling system
│ ├── maze.py # Map and collision system
│ └── sdl2.py # Rendering and window management
├── units/ # Game entity implementations
│ ├── bomb.py # Bomb and explosion logic
│ ├── rat.py # Rat AI and behavior
│ └── points.py # Collectible points
├── assets/ # Game resources
│ ├── images/ # Sprites and textures
│ └── fonts/ # Text rendering fonts
├── sound/ # Audio files
├── maze.py # Maze generation algorithms
├── rats.py # Main game entry point
├── requirements.txt # Python dependencies
├── .env # Environment configuration
└── README.md # This documentation
├── engine/ # Core engine components
│ ├── collision_system.py # NumPy-based vectorized collision detection
│ ├── controls.py # Input handling system
│ ├── graphics.py # Blood overlay and rendering optimizations
│ ├── maze.py # Map and collision system
│ ├── sdl2.py # Rendering and window management
│ └── unit_manager.py # Unit spawning and lifecycle management
├── units/ # Game entity implementations
│ ├── unit.py # Base unit class with collision layers
│ ├── bomb.py # Bomb and explosion logic with area damage
│ ├── gas.py # Gas weapon with cell-based detection
│ ├── mine.py # Proximity mine with trigger system
│ ├── rat.py # Rat AI with optimized rendering cache
│ └── points.py # Collectible points (90 frames lifetime)
├── assets/ # Game resources
│ ├── images/ # Sprites and textures
│ └── fonts/ # Text rendering fonts
├── sound/ # Audio files
├── maze.py # Maze generation algorithms
├── rats.py # Main game entry point with 4-pass game loop
├── requirements.txt # Python dependencies (including numpy)
├── .env # Environment configuration
└── README.md # This documentation
```
## Game Files Details
- `maze.py`: Contains the `MazeGenerator` class implementing DFS algorithm for procedural maze generation
- `rats.py`: Main game controller, initializes engine systems and manages game state
- `rats.py`: Main game controller with 4-pass optimized game loop, manages collision system and unit lifecycle
- `engine/collision_system.py`: NumPy-based spatial hashing system supporting 200+ units at 3ms/frame
- `engine/graphics.py`: Blood overlay system with pre-generated stain pool and rendering optimizations
- `engine/controls.py`: Input abstraction layer with configurable key bindings
- `engine/maze.py`: World representation with collision detection and pathfinding support
- `engine/sdl2.py`: Low-level graphics interface wrapping SDL2 functionality
- `units/bomb.py`: Explosive units with timer mechanics and blast radius calculations
- `units/rat.py`: AI-driven entities with reproduction, pathfinding, and survival behaviors
- `units/points.py`: Collectible scoring items with visual feedback systems
- `engine/sdl2.py`: Low-level graphics interface wrapping SDL2 with alpha blending and texture caching
- `engine/unit_manager.py`: Centralized unit spawning with weapon collision avoidance
- `units/unit.py`: Base unit class with collision layer support
- `units/bomb.py`: Explosive units with vectorized area damage calculations
- `units/gas.py`: Area denial weapon using cell-based victim detection
- `units/mine.py`: Proximity-triggered explosives
- `units/rat.py`: AI-driven entities with cached render positions and collision filtering
- `units/points.py`: Collectible scoring items (90 frame lifetime, ~1.5s at 60 FPS)
- `assets/`: Game resources including sprites, textures, and fonts
- `sound/`: Audio assets for game events and feedback
- `scores.txt`: Persistent high score storage