9.1 KiB

Raw Blame History

Copilot Instructions for GLTerrain Project

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.1 KiB Raw Blame History