Rain and more

AGENTS.md

@@ -0,0 +1,50 @@
+# Notes for AI agents
+
+C++20 / OpenGL 4.5 HD-2D engine (`engine/`) plus a demo (`demo/`). Read
+`README.md` for features and the frame pipeline, and **`docs/ASSET_GUIDE.md`
+before making any sprite, texture or model**.
+
+## Build and run
+
+```sh
+cmake -S . -B build -G Ninja && ninja -C build
+./build/hd2d_demo                                   # interactive (WASD, R = rain, F1 = panels)
+./build/hd2d_demo --screenshot out.png --frames 90 \
+    --pos 25,43.6 --dist 10 --yaw 30 --rain 1 --set dof=0   # scripted capture
+```
+
+There is no test suite; verification is visual. After any rendering, asset or
+gameplay change, capture screenshots of the affected area and look at them.
+Use a Debug build (`-DCMAKE_BUILD_TYPE=Debug`) to get OpenGL errors printed.
+
+## Map
+
+| Path | What |
+| --- | --- |
+| `engine/include/hd2d/`, `engine/src/` | engine library (`Renderer`, `Terrain`, `BillboardBatch`, `ModelLibrary`/`ModelBatch`, `Water`, `ParticleSystem`, `Weather`, `GroundOcclusion`, `DebugUI`) |
+| `assets/shaders/` | GLSL; `common.glsl` holds the shared `Frame` UBO and lighting helpers |
+| `demo/` | meadow scene: terrain layout, prop scattering, bridge, fires, player movement |
+| `tools/pixellab.py` + `tools/assets.json` | pixel-art generation (PixelLab API, key in `.env`) |
+| `tools/scenery_textures.py` | high-res painted textures for models |
+| `tools/blender_scenery.py` | procedural 3D models → `assets/models/scenery.glb` |
+
+## Rules
+
+- `FrameUBO` in `engine/src/Renderer.cpp` must mirror `Frame` in
+  `assets/shaders/common.glsl` exactly (std140, vec4/mat4 only); update the
+  `static_assert` size when adding fields.
+- `pixelart.glsl` uses derivatives: include it only in fragment shaders.
+- Use GL 4.5 DSA calls (`glCreate*`, `glNamed*`, `glTexture*`) like the rest
+  of the code. Shaders hot-reload with F5.
+- Shaders and assets load from `HD2D_ASSET_DIR` (set by CMake to `assets/`).
+- Generated files (`assets/textures/*`, `assets/models/*`) come from scripts in
+  `tools/`; change the script, not the output.
+- PixelLab calls cost credits: check `--balance`, reuse `tile_id`s, and do not
+  regenerate assets that already exist unless asked.
+- The Blender script only touches its `HD2D_Scenery` collection; keep it that
+  way when running it inside a user's open Blender session.
+- New tunables go in `RenderSettings` (or the owning class), get a slider in
+  `DebugUI.cpp`, and, if useful for captures, an entry in `applySetting` in
+  `demo/main.cpp`.
+- Update `README.md` / `docs/ASSET_GUIDE.md` when behavior or conventions
+  change.