9.6 KiB

Raw Blame History

Copilot Instructions for GLTerrain Project

CRITICAL COMMUNICATION RULES

NEVER claim success without proof:

Don't say "FATTO!", "PERFETTO!", "Done!" unless you have verified the code works
Don't start responses with exclamations like "PERFETTO!", "Ottimo!", "Fantastico!", "Eccellente!" - they feel disingenuous
Be direct and honest - just explain what you did clearly
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, and real-time camera controls.

Version: 1.0.0
Language: Python 3.13+
Graphics: OpenGL with Pygame

Python Virtual Environment Workflow

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

Before Running Any Python Script:

Always activate the virtual environment:

source venv/bin/activate && python <script_name.py>

For installing packages:

source venv/bin/activate && pip install -r requirements.txt

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
Install packages globally
Modify code without testing with activated venv

Project Architecture

Directory Structure:

shader/
├── main.py                 # Entry point (uses modular architecture)
├── isometric_terrain.py    # Legacy monolithic version (preserved)
├── requirements.txt        # Python dependencies
├── config/
│   └── settings.py        # All configuration (TERRAIN, CAMERA, RENDERING, BIOMES)
├── src/
│   ├── app.py             # Main application coordinator
│   ├── camera/
│   │   └── camera.py      # Camera positioning and controls
│   ├── terrain/
│   │   └── generator.py   # Perlin noise terrain generation
│   └── rendering/
│       └── terrain_renderer.py  # OpenGL mesh rendering
└── docs/                  # Italian documentation (8 chapters)
    ├── README.md          # Index with navigation
    ├── 01-introduzione.md
    ├── 02-concetti-base.md
    ├── 03-opengl.md
    ├── 04-perlin-noise.md
    ├── 05-implementazione.md
    ├── 06-rendering.md
    ├── 07-camera.md
    └── 08-personalizzazione.md

Dependencies:

pygame >= 2.5.0: Window management and event handling
PyOpenGL >= 3.1.7: OpenGL bindings for 3D rendering
PyOpenGL-accelerate >= 3.1.7: Performance optimization
numpy >= 1.24.0: Array operations for heightmaps
noise: Perlin noise generation (installed with pygame)

Key Configuration Files

config/settings.py

CRITICAL: All project parameters are centralized here. Never hardcode values in source files.

Main Sections:

TERRAIN - Grid and generation parameters:

grid_size: 20          # 20×20 tiles
tile_width: 30         # 30px width
tile_height: 30        # 30px height
perlin_scale: 8.0      # Noise frequency (≈ grid_size / 2.5)
height_multiplier: 80.0 # Vertical scale
perlin_octaves: 4      # Detail levels
perlin_persistence: 0.6 # Detail influence
perlin_lacunarity: 2.5  # Detail density

CAMERA - View parameters:

distance: 800          # Camera distance from center
height: 450           # Camera height (Y axis)
fov: 45               # Field of view (degrees)
zoom_speed: 10.0      # UP/DOWN key speed
height_speed: 10.0    # LEFT/RIGHT key speed

RENDERING - Visual settings:

line_width: 5.0       # Tile border thickness
line_color: (0,0,0)   # Border color (RGB)
light_position: (1,1,1,0)  # Directional light

BIOME_COLORS - Biome RGB colors:

water, sand, grass_low, grass_mid, grass_high, rock, snow

BIOME_THRESHOLDS - Height thresholds for biome assignment:

water: -10, sand: 0, grass_low: 10, grass_mid: 25, 
grass_high: 40, rock: 55, snow: 70

Architecture Principles

Separation of Concerns:

TerrainGenerator: Only generates heightmaps (Perlin noise)
TerrainRenderer: Only renders geometry (OpenGL calls)
Camera: Only handles view transformations and input
IsometricTerrainApp: Orchestrates all components

Data Flow:

User Input → Camera → App.update()
App → TerrainGenerator.generate() → heightmap array
App → TerrainRenderer.render(heightmap) → OpenGL drawing

Key Design Patterns:

Configuration Object: All settings in one module
Single Responsibility: Each class has one clear purpose
Dependency Injection: Pass dependencies via init
Stateless Rendering: Renderer doesn't store heightmap

Important Implementation Details

Perlin Noise Parameters

Rule of Thumb: perlin_scale ≈ grid_size / 2.5

Grid 10×10 → scale = 4.0
Grid 20×20 → scale = 8.0 (current)
Grid 30×30 → scale = 12.0

Why? Ensures terrain features span multiple tiles for natural appearance.

Isometric View Mathematics

Camera positioned at 45° horizontal and vertical:

camera_position = (distance, height, distance)  # X = Z for 45°
look_at = (0, 0, 0)  # Center of terrain
up_vector = (0, 1, 0)  # Y is up

Tile Rendering

Each tile is a quad with 4 vertices:

Top face: 4 vertices at (x, height, z) corners
Side faces: Only drawn if neighbor is lower

Biome Assignment

if height < threshold['water']:
    color = BIOME_COLORS['water']
elif height < threshold['sand']:
    color = BIOME_COLORS['sand']
# ... etc

Common Modification Patterns

Changing Grid Size:

Update TERRAIN['grid_size'] in settings.py
Adjust TERRAIN['perlin_scale'] (new_size / 2.5)
Consider adjusting CAMERA['distance'] for larger grids

Adding New Biome:

Add color to BIOME_COLORS
Add threshold to BIOME_THRESHOLDS
Update get_color_for_height() in terrain_renderer.py
Ensure thresholds are in ascending order

Modifying Camera Behavior:

Edit Camera class in src/camera/camera.py
All movement logic in handle_input(keys)
Projection setup in setup_projection(aspect_ratio)
View setup in setup_modelview()

Performance Optimization:

Reduce grid_size (20 → 15)
Reduce perlin_octaves (4 → 3)
Disable enable_smoothing
Reduce far_clip (5000 → 3000)

Testing Guidelines

Always Test After Changes:

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

Test Controls:

UP/DOWN: Zoom (should be smooth)
LEFT/RIGHT: Height (should move camera up/down)
R: Regenerate terrain (should create new random terrain)
ESC: Exit

Visual Validation:

Check tile borders are visible (line_width > 3.0)
Verify biome colors match settings
Ensure no Z-fighting (flickering surfaces)
Confirm terrain has variety (not flat)

Documentation

Italian Documentation (docs/):

Complete 8-chapter guide explaining:

Project overview and results
3D graphics and isometric concepts
OpenGL technology
Perlin noise algorithm
Code architecture
Rendering system
Camera system
Customization guide

Target Audience: Non-technical users, no OpenGL knowledge assumed

Update Rule: When changing features, update relevant documentation chapter.

Git Workflow

Repository:

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

Version Tagging:

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

.gitignore Includes:

venv/, pycache/, *.pyc
.vscode/, .idea/
*.png, *.jpg (generated screenshots)
backup.py

Debugging Tips

Common Issues:

Flat Terrain: Increase height_multiplier or reduce perlin_scale
Too Chaotic: Reduce height_multiplier or increase perlin_scale
Invisible Borders: Increase line_width (5.0 → 8.0)
Camera Issues: Check distance and height values match tile scale
Performance: Reduce grid_size or perlin_octaves

OpenGL Debugging:

Enable depth testing: glEnable(GL_DEPTH_TEST) (already enabled)
Check matrix mode: glMatrixMode(GL_MODELVIEW) before drawing
Verify vertex order: Counter-clockwise for front faces

Future Enhancement Ideas

Easy Additions:

Export heightmap to PNG (PIL/Pillow)
Save/load terrain seeds
Multiple camera presets
Minimap in corner
FPS counter

Medium Complexity:

Smooth camera transitions (lerp)
Camera rotation (Q/E keys)
Day/night cycle (lighting animation)
Biome gradients (blend colors)
Water animation (vertex shader)

Advanced Features:

Texture mapping (replace flat colors)
Normal mapping (surface detail)
Shadow mapping
LOD system (level of detail)
Terrain editing tools

Code Style Guidelines

Imports: Standard library → Third party → Local modules
Naming: snake_case for functions/variables, PascalCase for classes
Constants: UPPER_CASE in settings.py
Docstrings: Include for all public methods
Comments: Explain "why", not "what"
Line Length: Max 100 characters
Type Hints: Use where it improves clarity

Contact & Maintenance

Author: enne2
Project: GLTerrain (Isometric Terrain Generator)
License: (Add license info if applicable)
Last Updated: October 2025

9.6 KiB Raw Blame History