Vibe-HD-2D/AGENTS.md

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

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_ids, 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.