GLTerrain/.github/copilot-instructions.md

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:

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

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

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.