From 73b6d9e0b74e7f943714265d552aefe00291b075 Mon Sep 17 00:00:00 2001
From: kaj dijkstra <kajdijkstra@protonmail.com>
Date: Sun, 4 Jan 2026 13:56:27 +0100
Subject: [PATCH] Readme

---
 README.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..31ef95b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,120 @@
+
+# Hex Grid Interaction Demo (Three.js)
+
+## Overview
+
+This is a small interactive Three.js demo created with the assistance of ChatGPU.
+It renders a large instanced grid of hexagonal (pentagram-like) tiles with real-time elevation, coloring, and post-processing effects.
+
+The demo focuses on efficient GPU instancing, smooth interaction, and modern real-time rendering techniques rather than game logic or assets.
+
+---
+
+## Features
+
+* **Instanced hex tile grid**
+
+  * Up to 10,000 tiles rendered efficiently using `THREE.InstancedMesh`
+  * Single draw call for the entire grid
+
+* **Hover-based elevation**
+
+  * Tiles smoothly rise when hovered
+  * Height is sampled from a grayscale heightmap
+  * Optional pulse wave animation propagating outward
+
+* **Per-instance coloring**
+
+  * GPU-driven instance colors via custom shader injection
+  * Color palette selection through UI and mouse wheel
+  * Smooth interpolation between colors
+
+* **Post-processing**
+
+  * Unreal Bloom for glow effects
+  * Optional SSAO pass
+  * Linear color space rendering
+
+* **Lighting and shadows**
+
+  * Directional light with soft shadow mapping
+  * Height-based shading enhances depth perception
+
+* **Camera interaction**
+
+  * OrbitControls with damping
+  * Fixed zoom for consistent interaction scale
+
+---
+
+## Technical Highlights
+
+* Uses **custom `onBeforeCompile` shader modification** to support per-instance colors with `MeshStandardMaterial`
+* Heightmap sampling performed on the CPU with smooth interpolation
+* All transformations applied through instanced matrices for performance
+* Designed to remain responsive even with large grids
+
+---
+
+## Controls
+
+* **Mouse move**
+  Hover tiles to elevate and recolor them
+
+* **Mouse wheel**
+  Cycle through the color palette
+
+* **Pulse button**
+  Triggers a radial elevation wave across the grid
+
+* **Reset button**
+  Restores all tiles to default height and color
+
+---
+
+## Requirements
+
+* Modern browser with WebGL support
+* Internet access (Three.js is loaded via ES module CDN)
+
+---
+
+## Running the Demo
+
+This demo must be served from a web server due to module imports and asset loading.
+
+### Quick local server
+
+```bash
+python3 -m http.server
+```
+
+Then open:
+
+```
+http://localhost:8000
+```
+
+---
+
+## Files
+
+* `index.html`
+  Main entry point
+
+* `heightmap.png`
+  Grayscale heightmap used for tile elevation
+
+---
+
+## Notes
+
+* The demo prioritizes **rendering techniques and interaction** over visual polish
+* All geometry, animation, and coloring are procedural
+* Intended as a rendering and interaction experiment rather than a finished product
+
+---
+
+## License
+
+MIT
\ No newline at end of file