# Copilot Instructions for GLTerrain Project

## CRITICAL COMMUNICATION RULES

**NEVER claim success without proof:**
1. Don't say "FATTO!", "PERFETTO!", "Done!" unless you have verified the code works
2. Don't start responses with exclamations like "PERFETTO!", "Ottimo!", "Fantastico!", "Eccellente!" - they feel disingenuous
3. Be direct and honest - just explain what you did clearly
4. Let the user verify results before celebrating

**ALWAYS:**
- Test before claiming success
- Be honest about uncertainty
- Search web/documentation if unsure
- Wait for user confirmation

---

## Project Overview

**GLTerrain** is an isometric terrain generator using OpenGL, Pygame, and Perlin noise. It creates procedurally generated 3D terrains with RollerCoaster Tycoon-style isometric view, biome-based coloring, procedural pixelated textures, and real-time camera controls.

**Version**: 1.1.0  
**Language**: Python 3.13+  
**Graphics**: OpenGL with Pygame

## Python Virtual Environment Workflow

**IMPORTANT**: This project uses a Python virtual environment located at `./venv`.

### Standard Command Pattern:

```bash
cd /home/enne2/Sviluppo/shader && source venv/bin/activate && python main.py
```

**DO NOT** run Python scripts without activating the virtual environment.

## Project Architecture

### Directory Structure:
```
shader/
├── main.py                 # Entry point
├── isometric_terrain.py    # Legacy version (preserved)
├── requirements.txt
├── config/
│   └── settings.py        # All configuration
├── src/
│   ├── app.py             # Main application
│   ├── camera/camera.py   # Camera controls
│   ├── terrain/generator.py   # Perlin noise terrain
│   └── rendering/terrain_renderer.py  # OpenGL + textures
└── docs/                  # Italian documentation (8 chapters)
```

### Dependencies:
- pygame >= 2.5.0, PyOpenGL >= 3.1.7, numpy >= 1.24.0, noise

## Key Configuration (config/settings.py)

**CRITICAL**: All parameters centralized here. Never hardcode values.

**TERRAIN**: `grid_size: 20`, `tile_width: 30`, `perlin_scale: 8.0`, `height_multiplier: 80.0`  
**CAMERA**: `distance: 800`, `height: 450`, `zoom_speed: 10.0`  
**RENDERING**: `line_width: 5.0`, `side_face_color: (0.55, 0.45, 0.35)`

**Texture settings (v1.1.0)**:
- `texture_enabled: True`
- `texture_detail_scale: 8.0` (noise sampling)
- `texture_variation: 0.25` (color variation 0-1)
- `texture_spots_threshold: 0.6` (dark spots)

**BIOME_COLORS**: water, sand, grass_low, grass_mid, grass_high, rock, snow  
**BIOME_THRESHOLDS**: Heights for biome transitions

## Architecture Principles

### Separation of Concerns:
- **TerrainGenerator**: Heightmaps with random seeds
- **TerrainRenderer**: Geometry + procedural textures (OpenGL)
- **Camera**: View transformations and input
- **IsometricTerrainApp**: Orchestrates components

### Texture System (v1.1.0):
```
Per-Tile Generation:
1. get_texture_for_tile(color, grid_i, grid_j)
2. generate_procedural_texture() → 16×16 pixels
3. 3-layer Perlin noise: detail + pattern + spots
4. glTexImage2D() → OpenGL texture
5. Cache with key: (grid_i, grid_j, color, seed)
6. UV mapping with glTexCoord2f()
```

## Important Implementation Details

### Perlin Noise Scale
**Rule**: `perlin_scale ≈ grid_size / 2.5`  
Grid 20×20 → scale = 8.0 (current)

### Tile Rendering (v1.1.0)
**Top face**:
- 16×16 texture per tile (GL_NEAREST = pixelated)
- GL_LIGHTING disabled (pure colors)
- Unique texture: (grid_i, grid_j, biome, seed)

**Side faces**:
- Uniform brown with shading (0.7 right, 0.8 back)
- GL_LIGHTING enabled

### Random Seeds (v1.1.0)
**Heightmap**: `random_base = random.randint(0, 10000)` in `generate()`  
**Textures**: New `texture_seed` in `set_heightmap()` + cache clear  
**Result**: R key regenerates both completely

## Common Modifications

### Grid Size:
1. Update `TERRAIN['grid_size']`
2. Adjust `perlin_scale` (new_size / 2.5)
3. Adjust `CAMERA['distance']` if needed

### Textures:
- `texture_variation`: 0.0-1.0 (more/less change)
- `texture_detail_scale`: Lower = larger patterns
- `texture_spots_threshold`: Lower = more spots
- `texture_size=16`: Change in `generate_procedural_texture()`
- GL_LINEAR for smooth (non-pixelated)

### Performance:
- Reduce `grid_size` (20→15) = fewer textures
- Reduce `perlin_octaves` (4→3)
- Texture size (16×16 → 8×8)
- `texture_enabled: False` disables textures

## Testing

```bash
source venv/bin/activate && python main.py
```

**Controls**: UP/DOWN (zoom), LEFT/RIGHT (height), R (regenerate terrain+textures), ESC (exit)

**Visual checks**:
- Tile borders visible (line_width > 3.0)
- Textures pixelated and unique per tile
- Dark spots and color variations
- Side faces uniform brown with shading

## Debugging

**Common Issues**:
1. Flat terrain: Increase `height_multiplier` or reduce `perlin_scale`
2. Invisible borders: Increase `line_width`
3. Textures not visible: Check `texture_enabled: True` + GL_LIGHTING disabled for tops
4. Textures not pixelated: Verify GL_NEAREST filtering
5. All tiles same: Check cache key includes `texture_seed`

## Git Workflow

**Remote**: `ssh://git@git.enne2.net:222/enne2/GLTerrain.git`  
**Branch**: `master`

```bash
git tag -a v1.x.x -m "Description"
git push origin master --tags
```

## Documentation

Italian docs in `docs/` (8 chapters). Update relevant chapter when changing features.

## Contact

**Author**: Matteo Benedetto
**Project**: GLTerrain (Isometric Terrain Generator)  
**Last Updated**: October 2025

#**Important**: These instructions must be under 200 lines to ensure clarity and conciseness.