Browse Source
- Introduced `test_final_level_flow.py` to validate final level transitions and game end scenarios. - Created `test_game_over_flow.py` to ensure game over conditions trigger correctly based on rat counts. - Implemented `test_keybindings.py` to verify keybinding configurations and their context-specific actions. - Developed `test_level_editor.py` to assess level editor functionalities and layout computations. - Added `test_level_io.py` for testing level data serialization and deserialization. - Established `test_loop_logic_parity.py` to ensure consistent game state across multiple simulation runs. - Created `test_non_regression.py` to simulate game behavior and capture states for future verification. - Implemented `test_verify.py` to compare current game states against a golden master for regression detection.master
53 changed files with 10110 additions and 3827 deletions
@ -1,76 +0,0 @@
|
||||
# Piano di distribuzione ARM con AppImage |
||||
|
||||
Questo repository ora e pronto per essere portato dentro un bundle AppImage senza dipendere dalla directory corrente e senza scrivere nel filesystem montato in sola lettura dell'AppImage. |
||||
|
||||
## Stato attuale |
||||
|
||||
- Le risorse di runtime vengono risolte a partire dal root del progetto tramite `MICE_PROJECT_ROOT`. |
||||
- I dati persistenti (`scores.txt`, `user_profiles.json`) vengono scritti in una directory utente persistente: |
||||
- `MICE_DATA_DIR`, se impostata. |
||||
- altrimenti `${XDG_DATA_HOME}/mice`. |
||||
- fallback: `~/.local/share/mice`. |
||||
- E presente uno scaffold di packaging in `packaging/`. |
||||
|
||||
## Strategia consigliata |
||||
|
||||
1. Costruire l'AppImage su una macchina `aarch64` reale o in una chroot/container ARM. |
||||
2. Creare dentro `AppDir` un ambiente Python copiato localmente con `python -m venv --copies`. |
||||
3. Installare le dipendenze Python da `requirements.txt` dentro quel Python locale. |
||||
4. Copiare il gioco e gli asset in `AppDir/usr/share/mice`. |
||||
5. Bundlare le librerie native richieste da SDL2 e dai wheel Python dentro `AppDir/usr/lib`. |
||||
6. Usare `AppRun` per esportare `LD_LIBRARY_PATH`, `MICE_PROJECT_ROOT` e `MICE_DATA_DIR` prima del lancio di `rats.py`. |
||||
7. Generare il file finale con `appimagetool`. |
||||
|
||||
## Perche costruire nativamente su ARM |
||||
|
||||
- Un AppImage deve contenere binari della stessa architettura del target. |
||||
- `PySDL2`, `numpy` e `Pillow` portano con se librerie native o dipendenze native. |
||||
- Il cross-build da `x86_64` a `aarch64` e possibile, ma aumenta molto il rischio di incompatibilita su `glibc`, `libSDL2` e wheel Python. |
||||
|
||||
## Comando di build |
||||
|
||||
Da una macchina Linux `aarch64` con `python3`, `rsync`, `ldd`, `ldconfig` e `appimagetool` disponibili: |
||||
|
||||
```bash |
||||
./packaging/build_appimage_aarch64.sh |
||||
``` |
||||
|
||||
Output previsto: |
||||
|
||||
- `dist/AppDir` |
||||
- `dist/Mice-aarch64.AppImage` |
||||
|
||||
## Dipendenze host richieste al builder ARM |
||||
|
||||
Serve un sistema di build ARM con almeno: |
||||
|
||||
- `python3` |
||||
- `python3-venv` |
||||
- `rsync` |
||||
- `glibc` userland standard |
||||
- `appimagetool` |
||||
- librerie di sviluppo/runtime installate sul builder, in particolare: |
||||
- `libSDL2` |
||||
- `libSDL2_ttf` |
||||
|
||||
## Test minimi da fare sul target ARM |
||||
|
||||
1. Avvio del gioco da shell. |
||||
2. Caricamento font e immagini. |
||||
3. Riproduzione audio WAV. |
||||
4. Salvataggio punteggi in `~/.local/share/mice/scores.txt`. |
||||
5. Creazione e lettura profili in `~/.local/share/mice/user_profiles.json`. |
||||
6. Cambio livello da `assets/Rat/level.dat`. |
||||
|
||||
## Rischi residui |
||||
|
||||
- La relocazione di un venv copiato dentro AppImage e pratica, ma va verificata sul target reale. |
||||
- Se il target ARM ha un userland molto vecchio, conviene costruire l'AppImage su una distro ARM con `glibc` piu vecchia del target. |
||||
- Se emergono problemi di relocazione del Python del venv, il passo successivo corretto e passare a un Python relocatable tipo `python-build-standalone` mantenendo invariato il launcher. |
||||
|
||||
## File introdotti |
||||
|
||||
- `runtime_paths.py` |
||||
- `packaging/appimage/AppRun` |
||||
- `packaging/appimage/mice.desktop` |
||||
- `packaging/build_appimage_aarch64.sh` |
||||
@ -1,221 +0,0 @@
|
||||
# Ottimizzazione Sistema di Collisioni con NumPy |
||||
|
||||
## Sommario |
||||
|
||||
Il sistema di collisioni del gioco è stato ottimizzato per gestire **oltre 200 unità simultanee** mantenendo performance elevate (50+ FPS). |
||||
|
||||
## Problema Originale |
||||
|
||||
### Analisi del Vecchio Sistema |
||||
|
||||
1. **Metodo Rat.collisions()**: O(n²) nel caso peggiore |
||||
- Ogni ratto controllava tutte le unità nelle sue celle |
||||
- Controllo AABB manuale per ogni coppia |
||||
- Con molti ratti nella stessa cella, diventava O(n²) |
||||
|
||||
2. **Calcoli bbox ridondanti** |
||||
- bbox calcolata in `draw()` ma usata anche in `collisions()` |
||||
- Nessun caching |
||||
|
||||
3. **Esplosioni bombe**: Iterazioni multiple sulle stesse posizioni |
||||
- Loop annidati per ogni direzione dell'esplosione |
||||
- Controllo manuale di `unit_positions` e `unit_positions_before` |
||||
|
||||
4. **Gas**: Controllo vittime a ogni frame anche quando non necessario |
||||
|
||||
## Soluzione Implementata |
||||
|
||||
### Nuovo Sistema: CollisionSystem (engine/collision_system.py) |
||||
|
||||
#### Caratteristiche Principali |
||||
|
||||
1. **Approccio Ibrido** |
||||
- < 10 candidati: Metodo semplice senza overhead NumPy |
||||
- ≥ 10 candidati: Operazioni vettorizzate con NumPy |
||||
- Ottimale per tutti gli scenari |
||||
|
||||
2. **Spatial Hashing** |
||||
- Dizionari `spatial_grid` e `spatial_grid_before` |
||||
- Lookup O(1) per posizioni |
||||
- Solo candidati nella stessa cella vengono controllati |
||||
|
||||
3. **Pre-allocazione Array NumPy** |
||||
- Arrays pre-allocati con capacità iniziale di 100 |
||||
- Raddoppio dinamico quando necessario |
||||
- Riduce overhead di `vstack`/`append` |
||||
|
||||
4. **Collision Layers** |
||||
- Matrice di collisione 6x6 per filtrare interazioni non necessarie |
||||
- Layers: RAT, BOMB, GAS, MINE, POINT, EXPLOSION |
||||
- Controllo O(1) se due layer possono collidere |
||||
|
||||
5. **AABB Vettorizzato** |
||||
- Controllo collisioni bbox per N unità in una sola operazione |
||||
- Broadcasting NumPy per calcoli paralleli |
||||
|
||||
### Struttura del Sistema |
||||
|
||||
```python |
||||
class CollisionSystem: |
||||
- register_unit() # Registra unità nel frame corrente |
||||
- get_collisions_for_unit() # Trova tutte le collisioni per un'unità |
||||
- get_units_in_area() # Ottiene unità in più celle (esplosioni) |
||||
- check_aabb_collision_vectorized() # AABB vettorizzato |
||||
- _simple_collision_check() # Metodo semplice per pochi candidati |
||||
``` |
||||
|
||||
### Modifiche alle Unità |
||||
|
||||
#### 1. Unit (units/unit.py) |
||||
- Aggiunto attributo `collision_layer` |
||||
- Inizializzazione con layer specifico |
||||
|
||||
#### 2. Rat (units/rat.py) |
||||
- Usa `CollisionSystem.get_collisions_for_unit()` |
||||
- Eliminati loop manuali |
||||
- Tolleranza AABB gestita dal sistema |
||||
|
||||
#### 3. Bomb (units/bomb.py) |
||||
- Esplosioni usano `get_units_in_area()` |
||||
- Raccolta posizioni esplosione → query batch |
||||
- Singola operazione per trovare tutte le vittime |
||||
|
||||
#### 4. Gas (units/gas.py) |
||||
- Usa `get_units_in_cell()` per trovare vittime |
||||
- Separazione tra position e position_before |
||||
|
||||
#### 5. Mine (units/mine.py) |
||||
- Controllo trigger con `get_units_in_cell()` |
||||
- Layer-based detection |
||||
|
||||
### Integrazione nel Game Loop (rats.py) |
||||
|
||||
```python |
||||
# Inizializzazione |
||||
self.collision_system = CollisionSystem( |
||||
self.cell_size, self.map.width, self.map.height |
||||
) |
||||
|
||||
# Update loop (3 passaggi) |
||||
1. Move: Tutte le unità si muovono |
||||
2. Register: Registrazione nel collision system + backward compatibility |
||||
3. Collisions + Draw: Controllo collisioni e rendering |
||||
``` |
||||
|
||||
## Performance |
||||
|
||||
### Test Results (250 unità su griglia 30x30) |
||||
|
||||
**Stress Test - 100 frames:** |
||||
``` |
||||
Total time: 332.41ms |
||||
Average per frame: 3.32ms |
||||
FPS capacity: 300.8 FPS |
||||
Target (50 FPS): ✓ PASS |
||||
``` |
||||
|
||||
### Confronto Scenari Reali |
||||
|
||||
| Numero Unità | Frame Time | FPS Capacity | |
||||
|--------------|------------|--------------| |
||||
| 50 | ~0.5ms | 2000 FPS | |
||||
| 100 | ~1.3ms | 769 FPS | |
||||
| 200 | ~2.5ms | 400 FPS | |
||||
| 250 | ~3.3ms | 300 FPS | |
||||
| 300 | ~4.0ms | 250 FPS | |
||||
|
||||
**Conclusione**: Il sistema mantiene **performance eccellenti** anche con 300+ unità, ben oltre il target di 50 FPS. |
||||
|
||||
### Vantaggi per Scenari Specifici |
||||
|
||||
1. **Molti ratti in poche celle**: |
||||
- Vecchio: O(n²) per celle dense |
||||
- Nuovo: O(n) con spatial hashing |
||||
|
||||
2. **Esplosioni bombe**: |
||||
- Vecchio: Loop annidati per ogni direzione |
||||
- Nuovo: Singola query batch per tutte le posizioni |
||||
|
||||
3. **Scalabilità**: |
||||
- Vecchio: Degrada linearmente con numero unità |
||||
- Nuovo: Performance costante grazie a spatial hashing |
||||
|
||||
## Compatibilità |
||||
|
||||
- **Backward compatible**: Mantiene `unit_positions` e `unit_positions_before` |
||||
- **Rimozione futura**: Questi dizionari possono essere rimossi dopo test estesi |
||||
- **Nessuna breaking change**: API delle unità invariata |
||||
|
||||
## File Modificati |
||||
|
||||
1. ✅ `requirements.txt` - Aggiunto numpy |
||||
2. ✅ `engine/collision_system.py` - Nuovo sistema (370 righe) |
||||
3. ✅ `units/unit.py` - Aggiunto collision_layer |
||||
4. ✅ `units/rat.py` - Ottimizzato collisions() |
||||
5. ✅ `units/bomb.py` - Esplosioni vettorizzate |
||||
6. ✅ `units/gas.py` - Query ottimizzate |
||||
7. ✅ `units/mine.py` - Detection ottimizzata |
||||
8. ✅ `units/points.py` - Aggiunto collision_layer |
||||
9. ✅ `rats.py` - Integrato CollisionSystem nel game loop |
||||
10. ✅ `test_collision_performance.py` - Benchmark suite |
||||
|
||||
## Prossimi Passi (Opzionali) |
||||
|
||||
1. **Rimozione backward compatibility**: Eliminare `unit_positions`/`unit_positions_before` |
||||
2. **Profiling avanzato**: Identificare ulteriori bottleneck |
||||
3. **Spatial grid gerarchico**: Per mappe molto grandi (>100x100) |
||||
4. **Caching bbox**: Se le unità non si muovono ogni frame |
||||
|
||||
## Installazione |
||||
|
||||
```bash |
||||
cd /home/enne2/Sviluppo/mice |
||||
source .venv/bin/activate |
||||
pip install numpy |
||||
``` |
||||
|
||||
## Testing |
||||
|
||||
```bash |
||||
# Benchmark completo |
||||
python test_collision_performance.py |
||||
|
||||
# Gioco normale |
||||
./mice.sh |
||||
``` |
||||
|
||||
## Note Tecniche |
||||
|
||||
### Approccio Ibrido Spiegato |
||||
|
||||
Il sistema usa un **threshold di 10 candidati** per decidere quando usare NumPy: |
||||
|
||||
- **< 10 candidati**: Loop Python semplice (no overhead numpy) |
||||
- **≥ 10 candidati**: Operazioni vettorizzate NumPy |
||||
|
||||
Questo è ottimale perché: |
||||
- Con pochi candidati, l'overhead di creare array NumPy supera i benefici |
||||
- Con molti candidati, la vettorizzazione compensa l'overhead iniziale |
||||
|
||||
### Memory Layout |
||||
|
||||
``` |
||||
Arrays NumPy (pre-allocati): |
||||
- bboxes: (capacity, 4) float32 → ~1.6KB per 100 unità |
||||
- positions: (capacity, 2) int32 → ~800B per 100 unità |
||||
- layers: (capacity,) int8 → ~100B per 100 unità |
||||
|
||||
Total: ~2.5KB per 100 unità (trascurabile) |
||||
``` |
||||
|
||||
## Conclusioni |
||||
|
||||
L'ottimizzazione con NumPy è **altamente efficace** per il caso d'uso di Mice! con 200+ unità: |
||||
|
||||
✅ Performance eccellenti (300+ FPS con 250 unità) |
||||
✅ Scalabilità lineare grazie a spatial hashing |
||||
✅ Backward compatible |
||||
✅ Approccio ibrido ottimale per tutti gli scenari |
||||
✅ Memory footprint minimo |
||||
|
||||
Il sistema è **pronto per la produzione**. |
||||
@ -1,308 +0,0 @@
|
||||
# Game Profile Manager |
||||
|
||||
A PySDL2-based user profile management system designed for gamepad-only control with virtual keyboard input. This system allows players to create, edit, delete, and select user profiles for games using only gamepad inputs or directional keys, with no need for physical keyboard text input. |
||||
|
||||
## Features |
||||
|
||||
- **640x480 Resolution**: Optimized for retro gaming systems and handheld devices |
||||
- **Create New Profiles**: Add new user profiles with custom names using virtual keyboard |
||||
- **Profile Selection**: Browse and select active profiles |
||||
- **Edit Settings**: Modify profile settings including difficulty, volume levels, and preferences |
||||
- **Delete Profiles**: Remove unwanted profiles |
||||
- **Gamepad/Directional Navigation**: Full control using only gamepad/joystick inputs or arrow keys |
||||
- **Virtual Keyboard**: Text input using directional controls - no physical keyboard typing required |
||||
- **JSON Storage**: Profiles stored in human-readable JSON format |
||||
- **Persistent Settings**: All changes automatically saved |
||||
|
||||
## Installation |
||||
|
||||
### Requirements |
||||
- Python 3.6+ |
||||
- PySDL2 |
||||
- SDL2 library |
||||
|
||||
### Setup |
||||
```bash |
||||
# Install required Python packages |
||||
pip install pysdl2 |
||||
|
||||
# For Ubuntu/Debian users, you may also need: |
||||
sudo apt-get install libsdl2-dev libsdl2-ttf-dev |
||||
|
||||
# Make launcher executable |
||||
chmod +x launch_profile_manager.sh |
||||
``` |
||||
|
||||
## Usage |
||||
|
||||
### Running the Profile Manager |
||||
```bash |
||||
# Method 1: Use the launcher script |
||||
./launch_profile_manager.sh |
||||
|
||||
# Method 2: Run directly with Python |
||||
python3 profile_manager.py |
||||
``` |
||||
|
||||
### Gamepad Controls |
||||
|
||||
#### Standard Gamepad Layout (Xbox/PlayStation compatible) |
||||
- **D-Pad/Hat**: Navigate menus up/down/left/right, control virtual keyboard cursor |
||||
- **Button 0 (A/X)**: Confirm selection, enter menus, select virtual keyboard characters |
||||
- **Button 1 (B/Circle)**: Go back, cancel action |
||||
- **Button 2 (X/Square)**: Delete profile, backspace in virtual keyboard |
||||
- **Button 3 (Y/Triangle)**: Reserved for future features |
||||
|
||||
#### Keyboard Controls (Alternative) |
||||
- **Arrow Keys**: Navigate menus and virtual keyboard cursor |
||||
- **Enter/Space**: Confirm selection, select virtual keyboard characters |
||||
- **Escape**: Go back, cancel action |
||||
- **Delete/Backspace**: Delete profile, backspace in virtual keyboard |
||||
- **Tab**: Reserved for future features |
||||
|
||||
#### Virtual Keyboard Text Input |
||||
When creating or editing profile names: |
||||
1. **Navigate**: Use D-Pad/Arrow Keys to move cursor over virtual keyboard |
||||
2. **Select Character**: Press A/Enter to add character to profile name |
||||
3. **Backspace**: Press X/Delete to remove last character |
||||
4. **Complete**: Navigate to "DONE" and press A/Enter to finish input |
||||
5. **Cancel**: Navigate to "CANCEL" and press A/Enter to abort |
||||
|
||||
#### Navigation Flow |
||||
1. **Main Menu**: Create Profile → Select Profile → Edit Settings → Exit |
||||
2. **Profile List**: Choose from existing profiles, or go back |
||||
3. **Create Profile**: Use virtual keyboard to enter name, confirm with directional controls |
||||
4. **Edit Profile**: Adjust settings using left/right navigation |
||||
|
||||
### Display Specifications |
||||
- **Resolution**: 640x480 pixels (4:3 aspect ratio) |
||||
- **Optimized for**: Retro gaming systems, handheld devices, embedded systems |
||||
- **Font Scaling**: Adaptive font sizes for optimal readability at low resolution |
||||
|
||||
### Profile Structure |
||||
|
||||
Profiles are stored in `user_profiles.json` with the following structure: |
||||
|
||||
```json |
||||
{ |
||||
"profiles": { |
||||
"PlayerName": { |
||||
"name": "PlayerName", |
||||
"created_date": "2024-01-15T10:30:00", |
||||
"last_played": "2024-01-20T14:45:00", |
||||
"games_played": 25, |
||||
"total_score": 15420, |
||||
"best_score": 980, |
||||
"settings": { |
||||
"difficulty": "normal", |
||||
"sound_volume": 75, |
||||
"music_volume": 60, |
||||
"screen_shake": true, |
||||
"auto_save": true |
||||
}, |
||||
"achievements": [ |
||||
"first_win", |
||||
"score_500" |
||||
] |
||||
} |
||||
}, |
||||
"active_profile": "PlayerName" |
||||
} |
||||
``` |
||||
|
||||
## Integration with Games |
||||
|
||||
### Loading Active Profile |
||||
```python |
||||
import json |
||||
|
||||
def load_active_profile(): |
||||
try: |
||||
with open('user_profiles.json', 'r') as f: |
||||
data = json.load(f) |
||||
active_name = data.get('active_profile') |
||||
if active_name and active_name in data['profiles']: |
||||
return data['profiles'][active_name] |
||||
except (FileNotFoundError, json.JSONDecodeError): |
||||
pass |
||||
return None |
||||
|
||||
# Usage in your game |
||||
profile = load_active_profile() |
||||
if profile: |
||||
difficulty = profile['settings']['difficulty'] |
||||
sound_volume = profile['settings']['sound_volume'] |
||||
``` |
||||
|
||||
### Updating Profile Stats |
||||
```python |
||||
def update_profile_stats(score, game_completed=True): |
||||
try: |
||||
with open('user_profiles.json', 'r') as f: |
||||
data = json.load(f) |
||||
|
||||
active_name = data.get('active_profile') |
||||
if active_name and active_name in data['profiles']: |
||||
profile = data['profiles'][active_name] |
||||
|
||||
if game_completed: |
||||
profile['games_played'] += 1 |
||||
profile['total_score'] += score |
||||
profile['best_score'] = max(profile['best_score'], score) |
||||
profile['last_played'] = datetime.now().isoformat() |
||||
|
||||
with open('user_profiles.json', 'w') as f: |
||||
json.dump(data, f, indent=2) |
||||
except Exception as e: |
||||
print(f"Error updating profile: {e}") |
||||
``` |
||||
|
||||
## Customization |
||||
|
||||
### Adding New Settings |
||||
Edit the `UserProfile` dataclass and the settings adjustment methods: |
||||
|
||||
```python |
||||
# In profile_manager.py, modify the UserProfile.__post_init__ method |
||||
def __post_init__(self): |
||||
if self.settings is None: |
||||
self.settings = { |
||||
"difficulty": "normal", |
||||
"sound_volume": 50, |
||||
"music_volume": 50, |
||||
"screen_shake": True, |
||||
"auto_save": True, |
||||
"your_new_setting": "default_value" # Add here |
||||
} |
||||
``` |
||||
|
||||
### Custom Font |
||||
Place your font file in the `assets/` directory and update the font path: |
||||
```python |
||||
font_path = "assets/your_font.ttf" |
||||
``` |
||||
|
||||
### Screen Resolution |
||||
The application is optimized for 640x480 resolution. To change resolution, modify the window size in the init_sdl method: |
||||
```python |
||||
self.window = sdl2.ext.Window( |
||||
title="Profile Manager", |
||||
size=(your_width, your_height) # Change from (640, 480) |
||||
) |
||||
``` |
||||
|
||||
### Virtual Keyboard Layout |
||||
Customize the virtual keyboard characters by modifying the keyboard_chars list: |
||||
```python |
||||
self.keyboard_chars = [ |
||||
['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J'], |
||||
['K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T'], |
||||
['U', 'V', 'W', 'X', 'Y', 'Z', '1', '2', '3', '4'], |
||||
['5', '6', '7', '8', '9', '0', '_', '-', ' ', '<'], |
||||
['DONE', 'CANCEL', '', '', '', '', '', '', '', ''] |
||||
] |
||||
``` |
||||
|
||||
## Troubleshooting |
||||
|
||||
### No Gamepad Detected |
||||
- Ensure your gamepad is connected before starting the application |
||||
- Try different USB ports |
||||
- Check if your gamepad is recognized by your system |
||||
- The application will show "No gamepad detected - using keyboard fallback" |
||||
- Virtual keyboard works with both gamepad and keyboard controls |
||||
|
||||
### Font Issues |
||||
- Ensure the font file exists in the assets directory |
||||
- The system will fall back to default font if custom font is not found |
||||
- Supported font formats: TTF, OTF |
||||
- Font sizes are automatically scaled for 640x480 resolution |
||||
|
||||
### Virtual Keyboard Not Responding |
||||
- Ensure you're in text input mode (creating/editing profile names) |
||||
- Use arrow keys or D-Pad to navigate the virtual keyboard cursor |
||||
- Press Enter/A button to select characters |
||||
- The virtual keyboard cursor should be visible as a highlighted character |
||||
|
||||
### Profile Not Saving |
||||
- Check file permissions in the application directory |
||||
- Ensure sufficient disk space |
||||
- Verify JSON format is not corrupted |
||||
|
||||
### Resolution Issues |
||||
- The application is designed for 640x480 resolution |
||||
- On higher resolution displays, the window may appear small |
||||
- This is intentional for compatibility with retro gaming systems |
||||
- Content is optimized and readable at this resolution |
||||
|
||||
## File Structure |
||||
``` |
||||
project_directory/ |
||||
├── profile_manager.py # Main application (640x480, virtual keyboard) |
||||
├── launch_profile_manager.sh # Launcher script |
||||
├── user_profiles.json # Profile data storage |
||||
├── test_profile_manager.py # Test suite for core functions |
||||
├── game_profile_integration.py # Example game integration |
||||
├── assets/ |
||||
│ └── decterm.ttf # Font file (optional) |
||||
└── README_PROFILE_MANAGER.md # This documentation |
||||
``` |
||||
|
||||
## Development Notes |
||||
|
||||
### Virtual Keyboard Implementation |
||||
The virtual keyboard is implemented as a 2D grid of characters: |
||||
- Cursor position tracked with (keyboard_cursor_x, keyboard_cursor_y) |
||||
- Character selection adds to input_text string |
||||
- Special functions: DONE (confirm), CANCEL (abort), < (backspace) |
||||
- Fully navigable with directional controls only |
||||
|
||||
### Screen Layout for 640x480 |
||||
- Header area: 0-80px (titles, status) |
||||
- Content area: 80-400px (main UI elements) |
||||
- Controls area: 400-480px (help text, instructions) |
||||
- All elements scaled and positioned for optimal readability |
||||
|
||||
### Adding New Screens |
||||
1. Add screen name to `current_screen` handling |
||||
2. Create render method (e.g., `render_new_screen()`) |
||||
3. Add navigation logic in input handlers |
||||
4. Update screen transitions in confirm/back handlers |
||||
|
||||
### Gamepad Button Mapping |
||||
The application uses SDL2's joystick interface. Button numbers may vary by controller: |
||||
- Most modern controllers follow the Xbox layout |
||||
- PlayStation controllers map similarly but may have different button numbers |
||||
- Test with your specific controller and adjust mappings if needed |
||||
|
||||
### Performance Considerations |
||||
- Rendering is capped at 60 FPS for smooth operation |
||||
- Input debouncing prevents accidental rapid inputs |
||||
- JSON operations are minimized and occur only when necessary |
||||
- Virtual keyboard rendering optimized for 640x480 resolution |
||||
- Font scaling automatically adjusted for readability |
||||
|
||||
### Adding Support for Different Resolutions |
||||
To support different screen resolutions, modify these key areas: |
||||
1. Window initialization in `init_sdl()` |
||||
2. Panel and button positioning in render methods |
||||
3. Font size scaling factors |
||||
4. Virtual keyboard grid positioning |
||||
|
||||
### Gamepad Integration Notes |
||||
- Uses SDL2's joystick interface for maximum compatibility |
||||
- Button mapping follows standard Xbox controller layout |
||||
- Hat/D-Pad input prioritized over analog sticks for precision |
||||
- Input timing designed for responsive but not accidental activation |
||||
|
||||
## Target Platforms |
||||
|
||||
This profile manager is specifically designed for: |
||||
- **Handheld Gaming Devices**: Steam Deck, ROG Ally, etc. |
||||
- **Retro Gaming Systems**: RetroPie, Batocera, etc. |
||||
- **Embedded Gaming Systems**: Custom arcade cabinets, portable devices |
||||
- **Low-Resolution Displays**: 640x480, 800x600, and similar resolutions |
||||
- **Gamepad-Only Environments**: Systems without keyboard access |
||||
|
||||
## License |
||||
This profile manager is provided as-is for educational and personal use. Designed for integration with retro and handheld gaming systems. |
||||
@ -1,419 +0,0 @@
|
||||
# regenerate_background() Analysis And Refactor Plan |
||||
|
||||
## Scope |
||||
|
||||
This document analyzes `Graphics.regenerate_background()` and proposes a staged refactor plan. |
||||
|
||||
Relevant code paths: |
||||
|
||||
- `engine/graphics.py#L146` `draw_maze()` lazily triggers background generation. |
||||
- `engine/graphics.py#L155` `draw_cave_foreground()` consumes cave overlay metadata produced during regeneration. |
||||
- `engine/graphics.py#L175` `regenerate_background()` builds the static background texture and cave overlay placements. |
||||
- `engine/graphics.py#L311` `add_blood_stain()` confirms that blood is intentionally excluded from the background texture and rendered as a separate overlay. |
||||
- `engine/sdl2.py#L98` `create_texture()` composites surface tiles into one SDL texture. |
||||
- `engine/sdl2.py#L118` `load_image()` explains why the code keeps both surfaces and textures for the same themed assets. |
||||
- `engine/maze.py#L13-L15` define `MAP_EMPTY`, `MAP_WALL`, and `MAP_TUNNEL`. |
||||
- `rats.py#L79`, `rats.py#L117-L121`, and `rats.py#L163-L165` show where background state is invalidated. |
||||
- `rats.py#L335` shows cave foreground rendering happens after the background draw and before units are drawn. |
||||
|
||||
## What The Method Actually Does |
||||
|
||||
`regenerate_background()` is doing more than the name suggests. It is not only “regenerating a background”; it is handling five separate concerns in one place: |
||||
|
||||
1. It walks the logical map cell by cell. |
||||
2. It analyzes neighborhood topology around each wall or tunnel cell. |
||||
3. It chooses visual variants, including random grass and flower decoration. |
||||
4. It builds cave foreground overlay metadata for later explosion-aware rendering. |
||||
5. It commits the accumulated surfaces into a single SDL background texture. |
||||
|
||||
That makes it both a planner and a renderer. |
||||
|
||||
## Current Inputs, Outputs, And Side Effects |
||||
|
||||
### Inputs read from `self` |
||||
|
||||
- `self.map.tiles`, `self.map.width`, `self.map.height` |
||||
- `self.cell_size` |
||||
- `self.grasses`, `self.grass_textures` |
||||
- `self.flowers`, `self.flower_textures` |
||||
- `self.edges`, `self.corners`, `self.inner_corners` |
||||
- `self.caves` |
||||
- `self.render_engine` |
||||
|
||||
### Derived helpers inside the method |
||||
|
||||
- `occupied(x, y)` treats every non-empty cell as occupied, so both walls and tunnels count as solid neighbors for topology decisions. |
||||
- `is_tunnel(x, y)` is used only for the flower suppression logic in the bottom-right quadrant. |
||||
- `draw(...)` appends background surface tiles. |
||||
- `draw_cave(...)` appends cave overlay tuples in the format consumed later by `draw_cave_foreground()`. |
||||
- `random_wall()`, `random_wall_texture()`, `random_flower()`, `random_flower_texture()` embed random selection directly in the traversal logic. |
||||
|
||||
### Outputs and side effects |
||||
|
||||
- Resets `self.cave_foreground_tiles` |
||||
- Builds a local `texture_tiles` list |
||||
- Sets `self.background_texture` |
||||
- Does not return a value |
||||
|
||||
This means the method is hard to test in isolation because the real output is split across mutable instance state and SDL object creation. |
||||
|
||||
## Functional Walkthrough |
||||
|
||||
### 1. Initialization |
||||
|
||||
The method creates: |
||||
|
||||
- `texture_tiles`: a list of `(surface, x, y)` tuples for the static background |
||||
- `self.cave_foreground_tiles`: a list of `(cell_x, cell_y, direction, surface, x, y)` tuples for overlay rendering |
||||
- `half_cell`: used to place quarter-cell tiles at 20 px offsets when `cell_size` is 40 |
||||
|
||||
This immediately shows a hidden design choice: one map cell can emit up to four quarter tiles rather than a single full-tile sprite. |
||||
|
||||
### 2. Cell iteration |
||||
|
||||
The outer loop traverses every cell of `self.map.tiles`. |
||||
|
||||
- `MAP_EMPTY`: skipped completely |
||||
- `MAP_WALL`: potentially emits several quarter tiles |
||||
- `MAP_TUNNEL`: emits cave overlays and sometimes grass filler tiles |
||||
|
||||
### 3. Wall rendering logic |
||||
|
||||
For `MAP_WALL`, the method evaluates the four quadrants independently. |
||||
|
||||
#### Top-left quadrant |
||||
|
||||
If the north-west corner is exposed, it chooses among: |
||||
|
||||
- `inner_corners["WN"]` |
||||
- `edges["W"]` |
||||
- `edges["N"]` |
||||
- `corners["NW"]` |
||||
|
||||
based on whether the north and west neighbors are occupied. |
||||
|
||||
#### Bottom-right quadrant |
||||
|
||||
This is the densest branch. It checks south, east, and south-east occupancy. |
||||
|
||||
- If all three are occupied, it usually draws a random grass tile. |
||||
- With a 10% chance, it draws a flower instead, but only if the cell is not near the border and none of the neighboring cells involved are tunnels. |
||||
- If only south or east are occupied, it chooses `inner_corners["ES"]`, `edges["E"]`, or `edges["S"]`. |
||||
- Otherwise it uses `corners["SE"]`. |
||||
|
||||
This branch mixes topology, decoration policy, border constraints, and tunnel suppression all in one nested block. |
||||
|
||||
#### Top-right quadrant |
||||
|
||||
Mirrors the top-left logic using north and east occupancy: |
||||
|
||||
- `inner_corners["EN"]` |
||||
- `edges["E"]` |
||||
- `edges["N"]` |
||||
- `corners["NE"]` |
||||
|
||||
#### Bottom-left quadrant |
||||
|
||||
Mirrors the same pattern using south and west occupancy: |
||||
|
||||
- `inner_corners["WS"]` |
||||
- `edges["W"]` |
||||
- `edges["S"]` |
||||
- `corners["SW"]` |
||||
|
||||
### 4. Tunnel rendering logic |
||||
|
||||
For `MAP_TUNNEL`, the method checks `above`, `below`, `left`, and `right` occupancy and chooses cave overlay sprites. |
||||
|
||||
Observed behavior: |
||||
|
||||
- If there is no occupied tile above, it always draws a grass filler in the bottom-right quarter and uses the `UP` cave sprite. |
||||
- If there is an occupied tile above but not below, it uses the `DOWN` cave sprite. |
||||
- If both above and below are occupied and the left side is blocked, it may use a full-quarter wall/flower texture in the cave list. |
||||
- If both above and below are occupied and the left side is open, it draws a grass filler plus the `LEFT` cave sprite. |
||||
- If above and below are occupied, left is blocked, and right is open, it uses the `RIGHT` cave sprite. |
||||
|
||||
This logic appears tuned to the current level topology and asset set rather than representing a complete, explicit rule system for all tunnel neighbor combinations. |
||||
|
||||
### 5. Commit phase |
||||
|
||||
After traversal, the method calls `render_engine.create_texture(texture_tiles, fill_color=(128, 128, 128))` to compose one static SDL texture for the entire maze background. |
||||
|
||||
This is the correct optimization boundary for the current architecture, but it also means SDL concerns leak directly into the generation logic. |
||||
|
||||
## Why The Method Feels Complex |
||||
|
||||
The complexity is not only “too many lines”. It comes from multiple kinds of coupling. |
||||
|
||||
### 1. Mixed responsibilities |
||||
|
||||
The method mixes: |
||||
|
||||
- map analysis |
||||
- rule selection |
||||
- random decoration |
||||
- cave overlay planning |
||||
- final rendering commit |
||||
|
||||
Each of these changes for different reasons, so they should not live in the same function. |
||||
|
||||
### 2. Repeated neighborhood queries |
||||
|
||||
Neighbor checks like `occupied(x, y - 1)` and `occupied(x + 1, y)` are recomputed many times, often inside overlapping branches. That makes the code noisy and increases the chance of introducing asymmetric bugs during edits. |
||||
|
||||
### 3. Hidden representation mismatch |
||||
|
||||
Background composition uses SDL surfaces, while cave overlays use textures. That is why the code has parallel helpers like `random_wall()` and `random_wall_texture()`. The behavior is valid, but the representation split is leaking into every branch. |
||||
|
||||
### 4. Randomness is embedded in rule logic |
||||
|
||||
The function directly calls global `random` during traversal. That makes visual behavior hard to snapshot-test or compare before and after a refactor. |
||||
|
||||
### 5. Side effects are scattered across the class lifecycle |
||||
|
||||
Invalidation is controlled elsewhere in `rats.py`, where the code manually clears: |
||||
|
||||
- `self.background_texture` |
||||
- `self.blood_layer_sprites` |
||||
- `self.cave_foreground_tiles` |
||||
|
||||
This is correct today, but it creates a fragile contract between game flow code and rendering code. |
||||
|
||||
### 6. Tunnel rules are implicit |
||||
|
||||
The tunnel branch contains nested assumptions that are hard to verify by inspection. It is not obvious whether the logic is exhaustive, map-specific, or intentionally asymmetric. |
||||
|
||||
## Important Invariants To Preserve |
||||
|
||||
Any refactor must keep these behaviors unless you explicitly choose to change them: |
||||
|
||||
1. Blood stains remain outside the static background texture. |
||||
2. `draw_cave_foreground()` must still be able to swap cave sprites for explosion sprites at runtime. |
||||
3. Quarter-tile placement and offsets must remain visually identical. |
||||
4. Random flower placement must preserve the current frequency and tunnel/border exclusions, or the change must be documented as a visual redesign. |
||||
5. Theme asset selection must keep using surfaces for background composition and textures for runtime overlays unless the render-engine API changes. |
||||
|
||||
## Refactor Goals |
||||
|
||||
The target should be: |
||||
|
||||
- easier to read |
||||
- behaviorally stable |
||||
- testable without SDL |
||||
- explicit about map-topology rules |
||||
- easy to extend with new wall or tunnel tile rules |
||||
|
||||
## Recommended Refactor Direction |
||||
|
||||
The safest path is not a full rewrite. It is a staged extraction toward a pure planning layer. |
||||
|
||||
### Stage 1: Name The Concepts |
||||
|
||||
Extract small private helpers without changing data structures yet. |
||||
|
||||
Suggested helpers: |
||||
|
||||
- `_is_occupied(x, y)` |
||||
- `_is_tunnel(x, y)` |
||||
- `_make_cell_context(x, y)` |
||||
- `_append_background_tile(surface, x, y, texture_tiles)` |
||||
- `_append_cave_tile(surface, x, y, direction)` |
||||
- `_choose_wall_fill(x, y, allow_flower)` |
||||
|
||||
This alone will remove repeated neighbor reads and make the current logic easier to reason about. |
||||
|
||||
### Stage 2: Introduce A Pure Planning Model |
||||
|
||||
Create lightweight data containers, for example: |
||||
|
||||
```python |
||||
from dataclasses import dataclass |
||||
|
||||
@dataclass(frozen=True) |
||||
class TilePlacement: |
||||
surface: object |
||||
x: int |
||||
y: int |
||||
|
||||
@dataclass(frozen=True) |
||||
class CavePlacement: |
||||
cell_x: int |
||||
cell_y: int |
||||
direction: str | None |
||||
sprite: object |
||||
x: int |
||||
y: int |
||||
|
||||
@dataclass(frozen=True) |
||||
class CellContext: |
||||
x: int |
||||
y: int |
||||
cell: int |
||||
north: bool |
||||
south: bool |
||||
east: bool |
||||
west: bool |
||||
north_west: bool |
||||
north_east: bool |
||||
south_west: bool |
||||
south_east: bool |
||||
``` |
||||
|
||||
Then split the method into: |
||||
|
||||
- `_build_background_plan()` |
||||
- `_plan_wall_cell(context, plan)` |
||||
- `_plan_tunnel_cell(context, plan)` |
||||
- `_commit_background_plan(plan)` |
||||
|
||||
The important shift is this: planning should produce plain Python data first, and SDL texture creation should happen only in the commit step. |
||||
|
||||
### Stage 3: Replace Nested Branches With Rule Helpers |
||||
|
||||
The wall logic is currently “four quadrants, each with a small rule tree”. Keep that structure, but make it explicit. |
||||
|
||||
Suggested helpers: |
||||
|
||||
- `_plan_wall_nw(context, px, py, plan)` |
||||
- `_plan_wall_ne(context, px, py, half_cell, plan)` |
||||
- `_plan_wall_sw(context, px, py, half_cell, plan)` |
||||
- `_plan_wall_se(context, px, py, half_cell, plan)` |
||||
|
||||
This sounds verbose, but it is much easier to review because each helper owns one visual quadrant and one set of rules. |
||||
|
||||
### Stage 4: Isolate Decoration Policy |
||||
|
||||
The flower rule is currently buried inside the `SE` branch. Extract it into a dedicated function such as: |
||||
|
||||
```python |
||||
def _should_place_flower(self, x, y, context) -> bool: |
||||
... |
||||
``` |
||||
|
||||
That function should own: |
||||
|
||||
- the 10% probability |
||||
- border exclusions |
||||
- tunnel exclusions |
||||
|
||||
This makes visual tuning possible without reopening the topology logic. |
||||
|
||||
### Stage 5: Make Tunnel Rules Explicit |
||||
|
||||
Tunnel behavior needs a named rule function with documented cases. |
||||
|
||||
For example: |
||||
|
||||
- `_classify_tunnel(context) -> TunnelPattern` |
||||
- `_plan_tunnel_pattern(pattern, px, py, plan)` |
||||
|
||||
Even if the final logic stays the same, naming the tunnel patterns will expose whether the code is intentionally map-specific or accidentally incomplete. |
||||
|
||||
### Stage 6: Centralize Invalidation |
||||
|
||||
Introduce one method such as: |
||||
|
||||
```python |
||||
def invalidate_background(self): |
||||
self.background_texture = None |
||||
self.cave_foreground_tiles.clear() |
||||
``` |
||||
|
||||
Then use that method from lifecycle points in `rats.py`. |
||||
|
||||
This reduces the chance of future bugs where one part of the cached rendering state is reset and another is forgotten. |
||||
|
||||
## Suggested Final Shape |
||||
|
||||
The long-term shape can stay inside `Graphics` and still be much cleaner: |
||||
|
||||
```python |
||||
def regenerate_background(self): |
||||
plan = self._build_background_plan() |
||||
self._commit_background_plan(plan) |
||||
|
||||
def _build_background_plan(self): |
||||
... |
||||
|
||||
def _plan_wall_cell(self, context, plan): |
||||
... |
||||
|
||||
def _plan_tunnel_cell(self, context, plan): |
||||
... |
||||
|
||||
def _commit_background_plan(self, plan): |
||||
self.cave_foreground_tiles = plan.cave_tiles |
||||
self.background_texture = self.render_engine.create_texture( |
||||
plan.background_tiles, |
||||
fill_color=(128, 128, 128), |
||||
) |
||||
``` |
||||
|
||||
This would preserve the current class boundaries while making the core algorithm testable. |
||||
|
||||
## Test Strategy Before Refactoring |
||||
|
||||
Because the function is visual and randomized, refactoring without a guardrail is risky. |
||||
|
||||
Recommended safety steps: |
||||
|
||||
1. Introduce a seeded RNG path so map generation can be deterministic during tests. |
||||
2. Add a small test map fixture that exercises walls, corners, borders, and tunnels. |
||||
3. Snapshot the produced tile plan, not the SDL texture object. |
||||
4. Verify cave overlay tuples are identical before and after the extraction. |
||||
5. Add a smoke test for `draw_cave_foreground()` with an explosion unit to ensure cave sprite replacement still works. |
||||
|
||||
## Proposed Implementation Order |
||||
|
||||
### Phase 0: Freeze Current Behavior |
||||
|
||||
- Add a deterministic RNG entry point or injectable random source. |
||||
- Capture the current background plan for one or two representative maps. |
||||
|
||||
### Phase 1: Extract Context And Emit Helpers |
||||
|
||||
- Remove repeated `occupied(...)` calls. |
||||
- Keep current tuple outputs and current SDL commit behavior. |
||||
|
||||
### Phase 2: Split Wall And Tunnel Planning |
||||
|
||||
- Move wall rules into quadrant helpers. |
||||
- Move tunnel rules into a dedicated planner. |
||||
|
||||
### Phase 3: Introduce A `BackgroundPlan` |
||||
|
||||
- Return plain data from planning. |
||||
- Keep SDL texture creation in one place. |
||||
|
||||
### Phase 4: Centralize Cache Invalidation |
||||
|
||||
- Replace direct state resets with a single background invalidation method. |
||||
|
||||
### Phase 5: Optional Optimization Pass |
||||
|
||||
- Consider caching immutable plans by `(level_index, theme_index)` if needed. |
||||
- Consider precomputing per-cell contexts if profiling shows the planner is still hot. |
||||
|
||||
## Refactor Risks And Questions |
||||
|
||||
These should be clarified before implementation: |
||||
|
||||
1. Are tunnel patterns guaranteed by the level data, or should the code become exhaustive for arbitrary maps? |
||||
2. Is `occupied()` intentionally treating tunnels as “solid” for wall topology, or is that only a rendering shortcut? |
||||
3. Is the flower placement rule part of the visual identity, or can it be simplified? |
||||
4. Do we want to keep both surfaces and textures in the theme cache, or would a render-engine API change be acceptable later? |
||||
|
||||
## Recommended First Refactor PR |
||||
|
||||
The lowest-risk first PR would do only this: |
||||
|
||||
1. Extract `CellContext` creation. |
||||
2. Extract the four wall-quadrant planners. |
||||
3. Extract tunnel planning into one helper. |
||||
4. Leave the tuple formats and SDL commit step unchanged. |
||||
|
||||
That PR would reduce complexity sharply while keeping the visual output almost certainly identical. |
||||
|
||||
## Summary |
||||
|
||||
`regenerate_background()` is complex because it is simultaneously a topology analyzer, decoration policy engine, cave overlay planner, and SDL background composer. The safest refactor is to separate planning from rendering, then isolate wall rules, tunnel rules, and decoration policy into named helpers with deterministic test coverage. |
||||
@ -1,259 +0,0 @@
|
||||
# Ottimizzazioni Rendering Implementate |
||||
|
||||
## ✅ Completato - 24 Ottobre 2025 |
||||
|
||||
### Modifiche Implementate |
||||
|
||||
#### 1. **Cache Viewport Bounds** ✅ (+15% performance) |
||||
**File:** `engine/sdl2.py` |
||||
|
||||
**Problema:** `is_in_visible_area()` ricalcolava i bounds ogni chiamata (4 confronti × 250 unità = 1000 operazioni/frame) |
||||
|
||||
**Soluzione:** |
||||
```python |
||||
def _update_viewport_bounds(self): |
||||
"""Update cached viewport bounds for fast visibility checks""" |
||||
self.visible_x_min = -self.w_offset - self.cell_size |
||||
self.visible_x_max = self.width - self.w_offset |
||||
self.visible_y_min = -self.h_offset - self.cell_size |
||||
self.visible_y_max = self.height - self.h_offset |
||||
|
||||
def is_in_visible_area(self, x, y): |
||||
"""Ottimizzato con cached bounds""" |
||||
return (self.visible_x_min <= x <= self.visible_x_max and |
||||
self.visible_y_min <= y <= self.visible_y_max) |
||||
``` |
||||
|
||||
I bounds vengono aggiornati solo quando cambia il viewport (scroll), non a ogni check. |
||||
|
||||
--- |
||||
|
||||
#### 2. **Pre-cache Image Sizes** ✅ (+5% performance) |
||||
**File:** `engine/graphics.py` |
||||
|
||||
**Problema:** `get_image_size()` chiamato 250 volte/frame anche se le dimensioni sono statiche |
||||
|
||||
**Soluzione:** |
||||
```python |
||||
# All'avvio, memorizza tutte le dimensioni |
||||
self.rat_image_sizes = {} |
||||
for sex in ["MALE", "FEMALE", "BABY"]: |
||||
self.rat_image_sizes[sex] = {} |
||||
for direction in ["UP", "DOWN", "LEFT", "RIGHT"]: |
||||
texture = self.rat_assets_textures[sex][direction] |
||||
self.rat_image_sizes[sex][direction] = texture.size # Cache! |
||||
``` |
||||
|
||||
Le dimensioni vengono lette una sola volta all'avvio, non ogni frame. |
||||
|
||||
--- |
||||
|
||||
#### 3. **Cache Render Positions in Rat** ✅ (+10% performance) |
||||
**File:** `units/rat.py` |
||||
|
||||
**Problema:** |
||||
- `calculate_rat_direction()` chiamato sia in `move()` che in `draw()` → duplicato |
||||
- Calcoli aritmetici (partial_x, partial_y, x_pos, y_pos) ripetuti ogni frame |
||||
- `get_image_size()` chiamato ogni frame (ora risolto con cache) |
||||
|
||||
**Soluzione:** |
||||
```python |
||||
def move(self): |
||||
# ... movimento ... |
||||
self.direction = self.calculate_rat_direction() |
||||
self._update_render_position() # Pre-calcola per draw() |
||||
|
||||
def _update_render_position(self): |
||||
"""Pre-calcola posizione di rendering durante move()""" |
||||
sex = self.sex if self.age > AGE_THRESHOLD else "BABY" |
||||
image_size = self.game.rat_image_sizes[sex][self.direction] # Cache! |
||||
|
||||
# Calcola una sola volta |
||||
if self.direction in ["UP", "DOWN"]: |
||||
partial_x = 0 |
||||
partial_y = self.partial_move * self.game.cell_size * (1 if self.direction == "DOWN" else -1) |
||||
else: |
||||
partial_x = self.partial_move * self.game.cell_size * (1 if self.direction == "RIGHT" else -1) |
||||
partial_y = 0 |
||||
|
||||
self.render_x = self.position_before[0] * self.game.cell_size + (self.game.cell_size - image_size[0]) // 2 + partial_x |
||||
self.render_y = self.position_before[1] * self.game.cell_size + (self.game.cell_size - image_size[1]) // 2 + partial_y |
||||
self.bbox = (self.render_x, self.render_y, self.render_x + image_size[0], self.render_y + image_size[1]) |
||||
|
||||
def draw(self): |
||||
"""Semplicissimo - usa solo valori pre-calcolati""" |
||||
sex = self.sex if self.age > AGE_THRESHOLD else "BABY" |
||||
image = self.game.rat_assets_textures[sex][self.direction] |
||||
self.game.render_engine.draw_image(self.render_x, self.render_y, image, tag="unit") |
||||
``` |
||||
|
||||
**Benefici:** |
||||
- Nessun calcolo duplicato |
||||
- `draw()` diventa semplicissimo |
||||
- `bbox` aggiornato automaticamente per collision system |
||||
|
||||
--- |
||||
|
||||
#### 4. **Blood Stains come Overlay Layer** ✅ (+30% in scenari con morti) |
||||
**File:** `engine/graphics.py` |
||||
|
||||
**Problema:** |
||||
- Ogni morte di ratto → `generate_blood_surface()` (pixel-by-pixel loop) |
||||
- Poi → `combine_blood_surfaces()` (blending RGBA manuale) |
||||
- Infine → `self.background_texture = None` → **rigenerazione completa background** |
||||
- Con 200 morti = 200 rigenerazioni di texture enorme! |
||||
|
||||
**Soluzione:** |
||||
|
||||
**A) Pre-generazione pool all'avvio:** |
||||
```python |
||||
def load_assets(self): |
||||
# ... |
||||
# Pre-genera 10 varianti di blood stains |
||||
self.blood_stain_textures = [] |
||||
for _ in range(10): |
||||
blood_surface = self.render_engine.generate_blood_surface() |
||||
blood_texture = self.render_engine.draw_blood_surface(blood_surface, (0, 0)) |
||||
if blood_texture: |
||||
self.blood_stain_textures.append(blood_texture) |
||||
|
||||
self.blood_layer_sprites = [] # Lista di blood sprites |
||||
``` |
||||
|
||||
**B) Blood come sprites overlay:** |
||||
```python |
||||
def add_blood_stain(self, position): |
||||
"""Aggiunge blood come sprite - NESSUNA rigenerazione background!""" |
||||
import random |
||||
|
||||
blood_texture = random.choice(self.blood_stain_textures) |
||||
x = position[0] * self.cell_size |
||||
y = position[1] * self.cell_size |
||||
|
||||
# Aggiungi alla lista invece di rigenerare |
||||
self.blood_layer_sprites.append((blood_texture, x, y)) |
||||
|
||||
def draw_blood_layer(self): |
||||
"""Disegna tutti i blood stains come sprites""" |
||||
for blood_texture, x, y in self.blood_layer_sprites: |
||||
self.render_engine.draw_image(x, y, blood_texture, tag="blood") |
||||
``` |
||||
|
||||
**C) Background statico:** |
||||
```python |
||||
def draw_maze(self): |
||||
if self.background_texture is None: |
||||
self.regenerate_background() |
||||
self.render_engine.draw_background(self.background_texture) |
||||
self.draw_blood_layer() # Blood come overlay separato |
||||
``` |
||||
|
||||
**Benefici:** |
||||
- Background generato UNA SOLA VOLTA (all'inizio) |
||||
- Blood stains: pre-generati → nessun costo runtime |
||||
- Nessuna rigenerazione costosa |
||||
- 10 varianti casuali per varietà visiva |
||||
|
||||
--- |
||||
|
||||
### Performance Stimate |
||||
|
||||
#### Prima delle Ottimizzazioni |
||||
Con 250 unità: |
||||
``` |
||||
Frame breakdown: |
||||
- Collision detection: 3.3ms (già ottimizzato con NumPy) |
||||
- Rendering: 10-15ms |
||||
- draw_image checks: ~2ms (visibility checks) |
||||
- get_image_size calls: ~1ms |
||||
- Render calculations: ~2ms |
||||
- Blood regenerations: ~3-5ms (picchi) |
||||
- SDL copy calls: ~4ms |
||||
- Game logic: 2ms |
||||
TOTALE: ~15-20ms → 50-65 FPS |
||||
``` |
||||
|
||||
#### Dopo le Ottimizzazioni |
||||
Con 250 unità: |
||||
``` |
||||
Frame breakdown: |
||||
- Collision detection: 3.3ms (invariato) |
||||
- Rendering: 5-7ms ✅ |
||||
- draw_image checks: ~0.5ms (cached bounds) |
||||
- get_image_size calls: 0ms (pre-cached) |
||||
- Render calculations: ~0.5ms (pre-calcolati in move) |
||||
- Blood regenerations: 0ms (overlay sprites) |
||||
- SDL copy calls: ~4ms (invariato) |
||||
- Game logic: 2ms |
||||
TOTALE: ~10-12ms → 80-100 FPS |
||||
``` |
||||
|
||||
**Miglioramento: ~2x più veloce nel rendering** |
||||
|
||||
--- |
||||
|
||||
### Metriche di Successo |
||||
|
||||
| Unità | FPS Prima | FPS Dopo | Miglioramento | |
||||
|-------|-----------|----------|---------------| |
||||
| 50 | ~60 | 60+ | Stabile | |
||||
| 100 | ~55 | 60+ | +9% | |
||||
| 200 | ~45 | 75-85 | +67-89% | |
||||
| 250 | ~35-40 | 60-70 | +71-100% | |
||||
| 300 | ~30 | 55-65 | +83-117% | |
||||
|
||||
--- |
||||
|
||||
### File Modificati |
||||
|
||||
1. ✅ `engine/sdl2.py` - Cache viewport bounds |
||||
2. ✅ `engine/graphics.py` - Pre-cache sizes + blood overlay |
||||
3. ✅ `units/rat.py` - Cache render positions |
||||
|
||||
**Linee di codice modificate:** ~120 linee |
||||
**Tempo implementazione:** ~2 ore |
||||
**Performance gain:** 2x rendering, 1.5-2x FPS totale con 200+ unità |
||||
|
||||
--- |
||||
|
||||
### Ottimizzazioni Future (Opzionali) |
||||
|
||||
#### Non Implementate (basso impatto): |
||||
- ❌ Rimozione tag parameter (1-2% gain) |
||||
- ❌ Sprite batching (complesso, 15-25% gain ma richiede refactor) |
||||
- ❌ Texture atlas (10-20% gain ma richiede asset rebuild) |
||||
|
||||
#### Motivo: |
||||
Le ottimizzazioni implementate hanno già raggiunto l'obiettivo di 60+ FPS con 250 unità. Le ulteriori ottimizzazioni avrebbero costo/beneficio sfavorevole. |
||||
|
||||
--- |
||||
|
||||
### Testing |
||||
|
||||
**Come testare i miglioramenti:** |
||||
|
||||
1. Avvia il gioco: `./mice.sh` |
||||
2. Spawna molti ratti (usa keybinding per spawn) |
||||
3. Osserva FPS counter in alto a sinistra |
||||
4. Usa bombe per uccidere ratti → osserva che NON ci sono lag durante morti multiple |
||||
|
||||
**Risultati attesi:** |
||||
- Con 200+ ratti: FPS stabile 70-85 |
||||
- Durante esplosioni multiple: nessun lag |
||||
- Blood stains appaiono istantaneamente |
||||
|
||||
--- |
||||
|
||||
### Conclusioni |
||||
|
||||
✅ **Obiettivo raggiunto**: Da ~40 FPS a ~70-80 FPS con 250 unità |
||||
|
||||
Le ottimizzazioni si concentrano sui bottleneck reali: |
||||
1. **Viewport checks** erano costosi → ora cached |
||||
2. **Image sizes** venivano riletti → ora cached |
||||
3. **Render calculations** erano duplicati → ora pre-calcolati |
||||
4. **Blood stains** rigeneravano tutto → ora overlay |
||||
|
||||
Il sistema ora scala bene fino a 300+ unità mantenendo 50+ FPS. |
||||
|
||||
Il rendering SDL2 è ora **2x più veloce** e combinato con il collision system NumPy già ottimizzato, il gioco può gestire scenari con centinaia di unità senza problemi di performance. |
||||
@ -1,82 +0,0 @@
|
||||
#!/usr/bin/env python3 |
||||
|
||||
import sys |
||||
import os |
||||
import sdl2 |
||||
import sdl2.ext |
||||
|
||||
class KeyLogger: |
||||
def __init__(self): |
||||
# Initialize SDL2 |
||||
sdl2.ext.init(joystick=True, video=True, audio=False) |
||||
# Initialize joystick support |
||||
sdl2.SDL_Init(sdl2.SDL_INIT_JOYSTICK) |
||||
sdl2.SDL_JoystickOpen(0) |
||||
sdl2.SDL_JoystickOpen(1) # Open the first joystick |
||||
sdl2.SDL_JoystickEventState(sdl2.SDL_ENABLE) |
||||
self.window = sdl2.ext.Window("Key Logger", size=(640, 480)) |
||||
self.window.show() |
||||
self.running = True |
||||
self.key_down = True |
||||
self.font = sdl2.ext.FontManager("assets/decterm.ttf", size=24) |
||||
|
||||
def run(self): |
||||
# Main loop |
||||
|
||||
while self.running: |
||||
# Handle SDL events |
||||
events = sdl2.ext.get_events() |
||||
for event in events: |
||||
self.event = event.type |
||||
if event.type == sdl2.SDL_KEYDOWN: |
||||
keycode = event.key.keysym.sym |
||||
# Log keycode to file |
||||
self.message = f"Key pressed: {sdl2.SDL_GetKeyName(keycode).decode('utf-8')}" |
||||
elif event.type == sdl2.SDL_KEYUP: |
||||
keycode = event.key.keysym.sym |
||||
# Log keycode to file |
||||
self.message = f"Key released: {sdl2.SDL_GetKeyName(keycode).decode('utf-8')}" |
||||
elif event.type == sdl2.SDL_JOYBUTTONDOWN: |
||||
button = event.jbutton.button |
||||
self.message = f"Joystick button {button} pressed" |
||||
if button == 9: # Assuming button 0 is the right trigger |
||||
self.running = False |
||||
elif event.type == sdl2.SDL_JOYBUTTONUP: |
||||
button = event.jbutton.button |
||||
self.message = f"Joystick button {button} released" |
||||
elif event.type == sdl2.SDL_JOYAXISMOTION: |
||||
axis = event.jaxis.axis |
||||
value = event.jaxis.value |
||||
self.message = f"Joystick axis {axis} moved to {value}" |
||||
elif event.type == sdl2.SDL_JOYHATMOTION: |
||||
hat = event.jhat.hat |
||||
value = event.jhat.value |
||||
self.message = f"Joystick hat {hat} moved to {value}" |
||||
elif event.type == sdl2.SDL_QUIT: |
||||
self.running = False |
||||
|
||||
# Update the window |
||||
sdl2.ext.fill(self.window.get_surface(), sdl2.ext.Color(34, 0, 33)) |
||||
greeting = self.font.render("Press any key...", color=sdl2.ext.Color(255, 255, 255)) |
||||
sdl2.SDL_BlitSurface(greeting, None, self.window.get_surface(), None) |
||||
if hasattr(self, 'message'): |
||||
text_surface = self.font.render(self.message, color=sdl2.ext.Color(255, 255, 255)) |
||||
sdl2.SDL_BlitSurface(text_surface, None, self.window.get_surface(), sdl2.SDL_Rect(0, 30, 640, 480)) |
||||
if hasattr(self, 'event'): |
||||
event_surface = self.font.render(f"Event: {self.event}", color=sdl2.ext.Color(255, 255, 255)) |
||||
sdl2.SDL_BlitSurface(event_surface, None, self.window.get_surface(), sdl2.SDL_Rect(0, 60, 640, 480)) |
||||
sdl2.SDL_UpdateWindowSurface(self.window.window) |
||||
# Refresh the window |
||||
|
||||
self.window.refresh() |
||||
sdl2.SDL_Delay(10) |
||||
# Check for quit event |
||||
if not self.running: |
||||
break |
||||
# Cleanup |
||||
sdl2.ext.quit() |
||||
|
||||
if __name__ == "__main__": |
||||
logger = KeyLogger() |
||||
logger.run() |
||||
|
||||
@ -1,76 +0,0 @@
|
||||
#!/bin/sh |
||||
|
||||
set -eu |
||||
|
||||
SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) |
||||
|
||||
log() { |
||||
printf '[mice-mic] %s\n' "$*" |
||||
} |
||||
|
||||
find_game_dir() { |
||||
for candidate in \ |
||||
"$SCRIPT_DIR/mice" \ |
||||
"$SCRIPT_DIR" \ |
||||
/mnt/mmc/ports/mice \ |
||||
/roms/ports/mice \ |
||||
"$HOME/mice-current" \ |
||||
/root/mice \ |
||||
"$HOME/mice"; do |
||||
if [ -f "$candidate/rats.py" ]; then |
||||
printf '%s\n' "$candidate" |
||||
return 0 |
||||
fi |
||||
done |
||||
return 1 |
||||
} |
||||
|
||||
find_python() { |
||||
for candidate in \ |
||||
"$GAMEDIR/.venv/bin/python" \ |
||||
"$HOME/miniconda3/bin/python" \ |
||||
/root/miniconda3/bin/python \ |
||||
/usr/bin/python3 \ |
||||
/usr/bin/python; do |
||||
if [ -x "$candidate" ]; then |
||||
printf '%s\n' "$candidate" |
||||
return 0 |
||||
fi |
||||
done |
||||
return 1 |
||||
} |
||||
|
||||
GAMEDIR=$(find_game_dir) |
||||
PYTHONBIN=$(find_python) |
||||
|
||||
mkdir -p "$GAMEDIR/logs" |
||||
LOGFILE="$GAMEDIR/logs/mic_visualizer.log" |
||||
exec >>"$LOGFILE" 2>&1 |
||||
|
||||
log "script_dir=$SCRIPT_DIR" |
||||
log "game_dir=$GAMEDIR" |
||||
log "python=$PYTHONBIN" |
||||
|
||||
export MICE_PROJECT_ROOT="$GAMEDIR" |
||||
|
||||
set -- --fullscreen --hide-cursor |
||||
|
||||
if [ -n "${MICE_MIC_DEVICE_INDEX:-}" ]; then |
||||
set -- "$@" --device-index "$MICE_MIC_DEVICE_INDEX" |
||||
log "device_index=$MICE_MIC_DEVICE_INDEX" |
||||
fi |
||||
|
||||
if [ "${MICE_MIC_LIST_DEVICES:-0}" = "1" ]; then |
||||
set -- --list-devices |
||||
log "list_devices=1" |
||||
fi |
||||
|
||||
if [ -n "${MICE_MIC_EXTRA_ARGS:-}" ]; then |
||||
# shellcheck disable=SC2086 |
||||
set -- "$@" ${MICE_MIC_EXTRA_ARGS} |
||||
log "extra_args=$MICE_MIC_EXTRA_ARGS" |
||||
fi |
||||
|
||||
cd "$GAMEDIR" |
||||
log "argv=$*" |
||||
exec "$PYTHONBIN" tools/mic_visualizer.py "$@" |
||||
@ -1,25 +0,0 @@
|
||||
#!/bin/sh |
||||
set -eu |
||||
|
||||
APPDIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) |
||||
VENV_DIR="$APPDIR/usr/opt/python" |
||||
GAME_DIR="$APPDIR/usr/share/mice" |
||||
|
||||
if [ -n "${MICE_DATA_DIR:-}" ]; then |
||||
DATA_DIR="$MICE_DATA_DIR" |
||||
elif [ -n "${XDG_DATA_HOME:-}" ]; then |
||||
DATA_DIR="$XDG_DATA_HOME/mice" |
||||
else |
||||
DATA_DIR="$HOME/.local/share/mice" |
||||
fi |
||||
|
||||
mkdir -p "$DATA_DIR" |
||||
|
||||
export PATH="$VENV_DIR/bin:${PATH:-}" |
||||
export LD_LIBRARY_PATH="$APPDIR/usr/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" |
||||
export MICE_PROJECT_ROOT="$GAME_DIR" |
||||
export MICE_DATA_DIR="$DATA_DIR" |
||||
export PYTHONNOUSERSITE=1 |
||||
|
||||
cd "$GAME_DIR" |
||||
exec "$VENV_DIR/bin/python" rats.py "$@" |
||||
@ -1,9 +0,0 @@
|
||||
[Desktop Entry] |
||||
Type=Application |
||||
Name=Mice! |
||||
Comment=Strategic rat extermination game built with Python and SDL2 |
||||
Exec=mice |
||||
Icon=mice |
||||
Categories=Game;StrategyGame; |
||||
Terminal=false |
||||
StartupNotify=false |
||||
@ -1,136 +0,0 @@
|
||||
#!/usr/bin/env bash |
||||
set -euo pipefail |
||||
|
||||
ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) |
||||
DIST_DIR="${DIST_DIR:-$ROOT_DIR/dist}" |
||||
APPDIR="${APPDIR:-$DIST_DIR/AppDir}" |
||||
APP_NAME="Mice" |
||||
APP_ID="mice" |
||||
ARCH_EXPECTED="aarch64" |
||||
APPIMAGETOOL_BIN="${APPIMAGETOOL_BIN:-appimagetool}" |
||||
PYTHON_BIN="${PYTHON_BIN:-python3}" |
||||
OUTPUT_APPIMAGE="${OUTPUT_APPIMAGE:-$DIST_DIR/${APP_NAME}-${ARCH_EXPECTED}.AppImage}" |
||||
|
||||
PYTHON_DIR="$APPDIR/usr/opt/python" |
||||
GAME_DIR="$APPDIR/usr/share/mice" |
||||
LIB_DIR="$APPDIR/usr/lib" |
||||
|
||||
require_command() { |
||||
if ! command -v "$1" >/dev/null 2>&1; then |
||||
printf 'Missing required command: %s\n' "$1" >&2 |
||||
exit 1 |
||||
fi |
||||
} |
||||
|
||||
find_system_library() { |
||||
local soname="$1" |
||||
ldconfig -p | awk -v target="$soname" '$1 == target { print $NF; exit }' |
||||
} |
||||
|
||||
should_bundle_soname() { |
||||
case "$1" in |
||||
linux-vdso.so.*|libc.so.*|libm.so.*|libpthread.so.*|libdl.so.*|librt.so.*|libutil.so.*|libresolv.so.*|ld-linux*.so.*) |
||||
return 1 |
||||
;; |
||||
*) |
||||
return 0 |
||||
;; |
||||
esac |
||||
} |
||||
|
||||
copy_dependency_tree() { |
||||
local binary="$1" |
||||
local dep |
||||
local soname |
||||
|
||||
while IFS= read -r dep; do |
||||
[ -n "$dep" ] || continue |
||||
[ -f "$dep" ] || continue |
||||
soname=$(basename "$dep") |
||||
if ! should_bundle_soname "$soname"; then |
||||
continue |
||||
fi |
||||
if [ ! -e "$LIB_DIR/$soname" ]; then |
||||
cp -a "$dep" "$LIB_DIR/$soname" |
||||
chmod 755 "$LIB_DIR/$soname" || true |
||||
copy_dependency_tree "$dep" |
||||
fi |
||||
done < <( |
||||
ldd "$binary" 2>/dev/null | awk ' |
||||
/=>/ && $3 ~ /^\// { print $3 } |
||||
$1 ~ /^\// { print $1 } |
||||
' | sort -u |
||||
) |
||||
} |
||||
|
||||
copy_system_library() { |
||||
local soname="$1" |
||||
local path |
||||
path=$(find_system_library "$soname") |
||||
if [ -z "$path" ]; then |
||||
printf 'Unable to locate required system library: %s\n' "$soname" >&2 |
||||
exit 1 |
||||
fi |
||||
cp -a "$path" "$LIB_DIR/$(basename "$path")" |
||||
chmod 755 "$LIB_DIR/$(basename "$path")" || true |
||||
copy_dependency_tree "$path" |
||||
} |
||||
|
||||
printf '==> Checking build prerequisites\n' |
||||
require_command rsync |
||||
require_command "$PYTHON_BIN" |
||||
require_command "$APPIMAGETOOL_BIN" |
||||
require_command ldconfig |
||||
require_command ldd |
||||
|
||||
if [ "$(uname -m)" != "$ARCH_EXPECTED" ]; then |
||||
printf 'This builder must run on %s. Current architecture: %s\n' "$ARCH_EXPECTED" "$(uname -m)" >&2 |
||||
exit 1 |
||||
fi |
||||
|
||||
printf '==> Creating AppDir at %s\n' "$APPDIR" |
||||
rm -rf "$APPDIR" |
||||
mkdir -p "$DIST_DIR" "$LIB_DIR" "$GAME_DIR" |
||||
|
||||
printf '==> Building bundled Python environment with %s\n' "$PYTHON_BIN" |
||||
"$PYTHON_BIN" -m venv --copies "$PYTHON_DIR" |
||||
"$PYTHON_DIR/bin/pip" install --upgrade pip setuptools wheel |
||||
"$PYTHON_DIR/bin/pip" install -r "$ROOT_DIR/requirements.txt" |
||||
|
||||
printf '==> Syncing game files\n' |
||||
rsync -a \ |
||||
--delete \ |
||||
--exclude '.git' \ |
||||
--exclude '.github' \ |
||||
--exclude '.venv' \ |
||||
--exclude '__pycache__' \ |
||||
--exclude '*.pyc' \ |
||||
--exclude '.mypy_cache' \ |
||||
--exclude '.pytest_cache' \ |
||||
--exclude 'build' \ |
||||
--exclude 'dist' \ |
||||
--exclude 'packaging' \ |
||||
"$ROOT_DIR/" "$GAME_DIR/" |
||||
|
||||
rm -f "$GAME_DIR/user_profiles.json" "$GAME_DIR/scores.txt" |
||||
|
||||
printf '==> Installing AppImage metadata\n' |
||||
install -Dm755 "$ROOT_DIR/packaging/appimage/AppRun" "$APPDIR/AppRun" |
||||
install -Dm644 "$ROOT_DIR/packaging/appimage/mice.desktop" "$APPDIR/$APP_ID.desktop" |
||||
install -Dm644 "$ROOT_DIR/packaging/appimage/mice.desktop" "$APPDIR/usr/share/applications/$APP_ID.desktop" |
||||
install -Dm644 "$ROOT_DIR/assets/Rat/BMP_WEWIN.png" "$APPDIR/$APP_ID.png" |
||||
install -Dm644 "$ROOT_DIR/assets/Rat/BMP_WEWIN.png" "$APPDIR/usr/share/icons/hicolor/256x256/apps/$APP_ID.png" |
||||
|
||||
printf '==> Bundling native dependencies\n' |
||||
copy_system_library libSDL2-2.0.so.0 |
||||
copy_system_library libSDL2_ttf-2.0.so.0 |
||||
copy_dependency_tree "$PYTHON_DIR/bin/python" |
||||
|
||||
while IFS= read -r -d '' candidate; do |
||||
copy_dependency_tree "$candidate" |
||||
done < <(find "$PYTHON_DIR" -type f \( -name '*.so' -o -name '*.so.*' -o -perm -u+x \) -print0) |
||||
|
||||
printf '==> Building AppImage %s\n' "$OUTPUT_APPIMAGE" |
||||
ARCH="$ARCH_EXPECTED" "$APPIMAGETOOL_BIN" --appimage-extract-and-run "$APPDIR" "$OUTPUT_APPIMAGE" |
||||
|
||||
printf 'AppImage created at %s\n' "$OUTPUT_APPIMAGE" |
||||
@ -1,182 +0,0 @@
|
||||
#!/usr/bin/env bash |
||||
# Deploy Mice! to a Koriki CFW device over SSH. |
||||
# |
||||
# Requirements on host: |
||||
# sshpass, tar, ssh |
||||
# |
||||
# Target: koriki@<IP> (default 10.0.0.199) |
||||
# - ARMv7l Linux, glibc 2.28 |
||||
# - Python 3.11 archive already present at /mnt/SDCARD/python_armv7.tar.gz |
||||
# - SDL2 libs in /mnt/SDCARD/Koriki/lib/ |
||||
# - Internet access via WiFi |
||||
# |
||||
# Usage: |
||||
# ./packaging/deploy_koriki.sh [TARGET_IP] |
||||
|
||||
set -euo pipefail |
||||
|
||||
TARGET_IP="${1:-10.0.0.199}" |
||||
TARGET_USER="${TARGET_USER:-koriki}" |
||||
TARGET_PASS="${TARGET_PASS:-koriki}" |
||||
SDCARD="/mnt/SDCARD" |
||||
PYTHON_ARCHIVE="${SDCARD}/python_armv7.tar.gz" |
||||
PYTHON_DIR="${SDCARD}/python" |
||||
GAME_DIR="${SDCARD}/Ports/mice" |
||||
KORIKI_LIB="${SDCARD}/Koriki/lib" |
||||
VENDOR_DIR="${GAME_DIR}/vendor" |
||||
|
||||
ROOT_DIR=$(CDPATH= cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) |
||||
|
||||
ssh_cmd() { |
||||
sshpass -p "$TARGET_PASS" ssh \ |
||||
-o StrictHostKeyChecking=no \ |
||||
-o ConnectTimeout=10 \ |
||||
-o PreferredAuthentications=password \ |
||||
-o PubkeyAuthentication=no \ |
||||
"${TARGET_USER}@${TARGET_IP}" "$@" |
||||
} |
||||
|
||||
log() { printf '==> %s\n' "$*"; } |
||||
|
||||
# ── 1. Estrai Python 3.11 ────────────────────────────────────────────────────── |
||||
log "Step 1: Extracting Python 3.11 on device" |
||||
ssh_cmd " |
||||
if [ ! -f '${PYTHON_DIR}/bin/python3.11' ]; then |
||||
echo 'Extracting Python archive...' |
||||
tar -xzf '${PYTHON_ARCHIVE}' -C '${SDCARD}' |
||||
echo 'Done' |
||||
else |
||||
echo 'Python 3.11 already extracted, skipping' |
||||
fi |
||||
" |
||||
|
||||
# ── 1b. Fix FAT32: i symlink non possono essere creati su vfat; li sostituiamo |
||||
# con copie reali dei file critici |
||||
log "Step 1b: Fixing missing symlinks on FAT32 (copying critical binaries)" |
||||
ssh_cmd " |
||||
PYBIN='${PYTHON_DIR}/bin' |
||||
PYLIB='${PYTHON_DIR}/lib' |
||||
# Copie necessarie all'interprete |
||||
[ ! -f \"\${PYBIN}/python3\" ] && cp \"\${PYBIN}/python3.11\" \"\${PYBIN}/python3\" |
||||
[ ! -f \"\${PYBIN}/python\" ] && cp \"\${PYBIN}/python3.11\" \"\${PYBIN}/python\" |
||||
[ ! -f \"\${PYBIN}/pip3\" ] && [ -f \"\${PYBIN}/pip3.11\" ] && cp \"\${PYBIN}/pip3.11\" \"\${PYBIN}/pip3\" |
||||
# Libreria condivisa |
||||
[ ! -f \"\${PYLIB}/libpython3.11.so\" ] && cp \"\${PYLIB}/libpython3.11.so.1.0\" \"\${PYLIB}/libpython3.11.so\" |
||||
echo 'Symlink workaround done' |
||||
" |
||||
|
||||
# ── 2. Installa dipendenze Python ────────────────────────────────────────────── |
||||
log "Step 2: Installing Python dependencies (wheel download + extract)" |
||||
ssh_cmd " |
||||
PYTHON='${PYTHON_DIR}/bin/python3.11' |
||||
export TMPDIR='${GAME_DIR}/tmp' |
||||
export LD_LIBRARY_PATH='${PYTHON_DIR}/lib:${KORIKI_LIB}' |
||||
# pip --target su FAT32 puo fallire (rename di file temporanei). |
||||
# Workaround: scarichiamo wheel in /tmp e li estraiamo manualmente in vendor. |
||||
mkdir -p '${VENDOR_DIR}' '${GAME_DIR}/tmp' '${GAME_DIR}/tmp/mice_wheels' |
||||
rm -f '${GAME_DIR}/tmp/mice_wheels'/*.whl |
||||
\"\$PYTHON\" -m pip download --no-cache-dir \ |
||||
--extra-index-url https://www.piwheels.org/simple/ \ |
||||
--dest '${GAME_DIR}/tmp/mice_wheels' \ |
||||
pysdl2 \ |
||||
'Pillow>=10.0' \ |
||||
'numpy>=1.26' \ |
||||
pyaml \ |
||||
requests |
||||
\"\$PYTHON\" - << 'PY' |
||||
import glob |
||||
import os |
||||
import zipfile |
||||
|
||||
vendor = '${VENDOR_DIR}' |
||||
wheels = sorted(glob.glob('${GAME_DIR}/tmp/mice_wheels/*.whl')) |
||||
if not wheels: |
||||
raise SystemExit('No wheels downloaded') |
||||
|
||||
for whl in wheels: |
||||
print('Extracting', os.path.basename(whl)) |
||||
with zipfile.ZipFile(whl) as zf: |
||||
zf.extractall(vendor) |
||||
|
||||
print('Dependencies extracted to', vendor) |
||||
PY |
||||
echo 'Dependencies installed (wheel extraction)' |
||||
" |
||||
|
||||
# ── 3. Crea directory di gioco ───────────────────────────────────────────────── |
||||
log "Step 3: Creating game directory ${GAME_DIR}" |
||||
ssh_cmd "mkdir -p '${GAME_DIR}'" |
||||
|
||||
# ── 4. Trasferisci il gioco ──────────────────────────────────────────────────── |
||||
# Pipe diretta tar → tar: evita di scrivere file intermedi in /tmp (tmpfs 49MB) |
||||
log "Step 4: Transferring game files via direct pipe (no tmp file)" |
||||
tar czf - \ |
||||
-C "$ROOT_DIR" \ |
||||
--exclude='.git' \ |
||||
--exclude='.venv' \ |
||||
--exclude='venv' \ |
||||
--exclude='__pycache__' \ |
||||
--exclude='*.pyc' \ |
||||
--exclude='dist' \ |
||||
--exclude='logs' \ |
||||
--exclude='packaging' \ |
||||
--exclude='tools' \ |
||||
--exclude='server' \ |
||||
--exclude='*.tar.gz' \ |
||||
. \ |
||||
| sshpass -p "$TARGET_PASS" ssh \ |
||||
-o StrictHostKeyChecking=no \ |
||||
"${TARGET_USER}@${TARGET_IP}" \ |
||||
"mkdir -p '${GAME_DIR}' && tar -xzf - -C '${GAME_DIR}' && echo 'Game extracted'" |
||||
|
||||
# ── 5. Crea il launcher ──────────────────────────────────────────────────────── |
||||
log "Step 5: Creating launcher script" |
||||
|
||||
LAUNCHER_CONTENT="#!/bin/sh |
||||
# Mice! launcher for Koriki CFW |
||||
|
||||
export PYTHON_DIR=\"${PYTHON_DIR}\" |
||||
export PATH=\"\${PYTHON_DIR}/bin:\$PATH\" |
||||
export PYTHONPATH=\"${VENDOR_DIR}:\${PYTHON_DIR}/lib/python3.11/site-packages\" |
||||
|
||||
# Puntiamo PySDL2 alle librerie SDL2 di Koriki |
||||
export PYSDL2_DLL_PATH=\"${KORIKI_LIB}\" |
||||
export LD_LIBRARY_PATH=\"${KORIKI_LIB}:\${LD_LIBRARY_PATH:-}\" |
||||
|
||||
# Root del progetto e dati persistenti |
||||
export MICE_PROJECT_ROOT=\"${GAME_DIR}\" |
||||
export MICE_DATA_DIR=\"\${SDCARD}/.mice_data\" |
||||
|
||||
mkdir -p \"\${MICE_DATA_DIR}\" |
||||
|
||||
cd \"\${MICE_PROJECT_ROOT}\" |
||||
exec \"\${PYTHON_DIR}/bin/python3\" rats.py \"\$@\" |
||||
" |
||||
|
||||
ssh_cmd "cat > '${SDCARD}/Ports/mice.sh'" <<< "$LAUNCHER_CONTENT" |
||||
ssh_cmd "chmod +x '${SDCARD}/Ports/mice.sh'" |
||||
|
||||
log "Launcher written to ${SDCARD}/Ports/mice.sh" |
||||
|
||||
# ── 6. Test rapido ───────────────────────────────────────────────────────────── |
||||
log "Step 6: Quick smoke test" |
||||
ssh_cmd " |
||||
export PATH='${PYTHON_DIR}/bin:\$PATH' |
||||
export PYSDL2_DLL_PATH='${KORIKI_LIB}' |
||||
export LD_LIBRARY_PATH='${PYTHON_DIR}/lib:${KORIKI_LIB}' |
||||
export PYTHONPATH='${VENDOR_DIR}:${PYTHON_DIR}/lib/python3.11/site-packages' |
||||
python3 -c \" |
||||
import sys |
||||
print('Python', sys.version) |
||||
import sdl2; print('PySDL2 OK:', sdl2.__version__) |
||||
import numpy; print('NumPy OK:', numpy.__version__) |
||||
import PIL; print('Pillow OK:', PIL.__version__) |
||||
import yaml; print('pyaml OK') |
||||
import requests; print('requests OK') |
||||
print('All dependencies OK') |
||||
\" |
||||
" |
||||
|
||||
log "Deployment complete!" |
||||
log "Run the game from Ports > mice on Koriki, or manually:" |
||||
log " ssh ${TARGET_USER}@${TARGET_IP} '${SDCARD}/Ports/mice.sh'" |
||||
|
Before Width: | Height: | Size: 683 KiB |
|
Before Width: | Height: | Size: 683 KiB |
@ -1 +0,0 @@
|
||||
Mice! is a strategic single-player game where you place bombs and mines to exterminate rats before they reproduce out of control. It features randomly generated mazes, sprite-based graphics, and sound effects. Inspired by the classic Rats! for Windows 95, this version is written in Python and uses a lightweight custom engine with SDL-style rendering. Created by Matteo Benedetto, a bored engineer. |
||||
@ -1 +0,0 @@
|
||||
Mice! is a strategic single-player game where you place bombs and mines to exterminate rats before they reproduce out of control. It features randomly generated mazes, sprite-based graphics, and sound effects. Inspired by the classic Rats! for Windows 95, this version is written in Python and uses a lightweight custom engine with SDL-style rendering. Created by Matteo Benedetto, a bored engineer. |
||||
@ -1,14 +0,0 @@
|
||||
This folder mirrors the muOS catalogue layout for Ports metadata. |
||||
|
||||
Target path on device: |
||||
- `MUOS/info/catalogue/External - Ports/box/` |
||||
- `MUOS/info/catalogue/External - Ports/text/` |
||||
|
||||
Source of truth: |
||||
- `gameinfo.xml` for description and canonical stem |
||||
- `cover.png` for box art |
||||
|
||||
Notes: |
||||
- `mice.*` is the canonical metadata stem because `gameinfo.xml` points to `./mice.sh`. |
||||
- `Mice!.*` is included as a compatibility alias for setups that expose the launcher as `Mice!.sh` in muOS. |
||||
- If the visible launcher name changes again, add matching filenames in both `box/` and `text/`. |
||||
@ -0,0 +1,10 @@
|
||||
import sdl2 |
||||
print("SDL2 imported") |
||||
import sdl2.ext |
||||
print("SDL2.ext imported") |
||||
import PIL |
||||
print("Pillow imported") |
||||
import numpy |
||||
print("Numpy imported") |
||||
import yaml |
||||
print("Yaml imported") |
||||
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
|
Before Width: | Height: | Size: 18 KiB After Width: | Height: | Size: 18 KiB |
@ -0,0 +1,119 @@
|
||||
|
||||
import os |
||||
import sys |
||||
import unittest |
||||
import random |
||||
import json |
||||
import hashlib |
||||
from pathlib import Path |
||||
|
||||
# Add current directory to path |
||||
sys.path.append(os.getcwd()) |
||||
|
||||
# Set SDL to use dummy video driver |
||||
os.environ["SDL_VIDEODRIVER"] = "dummy" |
||||
os.environ["SDL_AUDIODRIVER"] = "dummy" |
||||
os.environ["MICE_DISABLE_JOYSTICK"] = "1" |
||||
|
||||
from rats import MiceMaze |
||||
from engine.state_machine import GameState |
||||
from engine.sdl2 import GameWindow |
||||
|
||||
def mock_init_audio(self): |
||||
self.music_enabled = False |
||||
self.audio_devs = {"base": 0, "effects": 0, "music": 0} |
||||
self.sound_volume = 0 |
||||
self.music_volume = 0 |
||||
|
||||
class LoopParityTester(unittest.TestCase): |
||||
@classmethod |
||||
def setUpClass(cls): |
||||
GameWindow.show_intro = lambda *args, **kwargs: None |
||||
GameWindow.show_loading_screen = lambda *args, **kwargs: None |
||||
GameWindow._init_audio_system = mock_init_audio |
||||
GameWindow.play_sound = lambda *args, **kwargs: None |
||||
GameWindow.stop_sound = lambda *args, **kwargs: None |
||||
|
||||
def setUp(self): |
||||
# We need absolute determinism |
||||
random.seed(12345) |
||||
self.game = MiceMaze("assets/Rat/level.dat", level_index=0) |
||||
|
||||
# Reset and restart to clear initialization entropy |
||||
random.seed(12345) |
||||
# Monkeypatch UUID to be deterministic |
||||
import uuid |
||||
self.uuid_counter = 0 |
||||
def mock_uuid4(): |
||||
self.uuid_counter += 1 |
||||
return self.uuid_counter |
||||
uuid.uuid4 = mock_uuid4 |
||||
|
||||
self.game.start_game() |
||||
self.game.state_machine.transition_to(GameState.PLAYING) |
||||
|
||||
def get_full_snapshot(self): |
||||
"""Captures extremely detailed state of all units.""" |
||||
snapshot = { |
||||
"points": self.game.points, |
||||
"units": [] |
||||
} |
||||
# Sort by ID for stability |
||||
sorted_units = sorted(self.game.units.items(), key=lambda x: int(x[0])) |
||||
|
||||
for uid, u in sorted_units: |
||||
u_data = { |
||||
"id": uid, |
||||
"type": u.__class__.__name__, |
||||
"pos": list(u.position), |
||||
"pos_before": list(u.position_before), |
||||
"partial": float(u.partial_move), |
||||
"age": int(u.age) |
||||
} |
||||
# Optional attributes that affect logic |
||||
if hasattr(u, "pregnant"): u_data["pregnant"] = int(u.pregnant) |
||||
if hasattr(u, "babies"): u_data["babies"] = int(u.babies) |
||||
if hasattr(u, "gassed"): u_data["gassed"] = int(u.gassed) |
||||
if hasattr(u, "direction"): u_data["dir"] = u.direction |
||||
|
||||
snapshot["units"].append(u_data) |
||||
|
||||
# Add a hash of the total unit count and positions for quick check |
||||
flat_state = str(snapshot).encode('utf-8') |
||||
snapshot["hash"] = hashlib.md5(flat_state).hexdigest() |
||||
return snapshot |
||||
|
||||
def test_record_or_verify(self): |
||||
steps = 100 |
||||
parity_file = Path("tests/loop_parity_master.json") |
||||
|
||||
states = [] |
||||
print(f"Running simulation for {steps} steps...") |
||||
|
||||
for i in range(steps): |
||||
self.game.update_maze() |
||||
states.append(self.get_full_snapshot()) |
||||
|
||||
if not parity_file.exists() or os.environ.get("RECORD_PARITY"): |
||||
with open(parity_file, "w") as f: |
||||
json.dump(states, f, indent=2) |
||||
print(f"RECORDED master state to {parity_file}") |
||||
else: |
||||
with open(parity_file, "r") as f: |
||||
master_states = json.load(f) |
||||
|
||||
self.assertEqual(len(states), len(master_states)) |
||||
|
||||
for i, (curr, master) in enumerate(zip(states, master_states)): |
||||
if curr["hash"] != master["hash"]: |
||||
# Detailed comparison on failure |
||||
self.assertEqual(curr["points"], master["points"], f"Points mismatch at step {i}") |
||||
self.assertEqual(len(curr["units"]), len(master["units"]), f"Unit count mismatch at step {i}") |
||||
|
||||
for u_idx, (u_curr, u_master) in enumerate(zip(curr["units"], master["units"])): |
||||
self.assertEqual(u_curr, u_master, f"Unit {u_idx} mismatch at step {i}") |
||||
|
||||
print("PARITY VERIFIED: Optimization is functionally identical.") |
||||
|
||||
if __name__ == "__main__": |
||||
unittest.main() |
||||
Loading…
Reference in new issue