Tags: bar widgets, heightmap, GLSL shaders, gfx_decals, spring engine, widget modding
Custom widgets that draw on terrain need the heightmap texture. The Spring Engine exposes it through the standard GL4 widget pipeline. Getting the coordinates right is the hardest part.
The file gfx_decals_gl4.lua loads the heightmap texture along with other decal data. That widget reads world-space positions and converts them into UV coordinates for heightmap sampling. Anyone building a terrain-overlay widget should follow the same pattern.
The conversion function looks like heightmapUVatWorldPos(v_worldPos.xz), which returns the UV pair you then pass to textureLod(heightmapTex, uv, 0.0). The x component gives you terrain elevation at that point.
A common beginner mistake: writing GLSL fragment logic without calling gl.UseShader() first. The engine silently falls back to the default shader. Nothing draws. The fix is one line before any draw call.
The gui_building_grid_gl4.lua widget is a solid reference example. It draws a grid overlay using the same texture pipeline, and the code is short enough to read top to bottom.
The cameraViewProj uniform comes from the engine itself, defined in UniformConstants.cpp inside the Spring source. Widgets access it through the engine uniform buffer substitution pattern (vsSrc:gsub on the //ENGINEUNIFORMBUFFERDEF marker).
This matrix converts world positions to clip space. Any widget that places 3D geometry on the map needs it for correct perspective rendering. Standard OpenGL space-conversion diagrams apply here.
If a widget needs to map geometry onto terrain, a Vertex VBO carries the world positions into the vertex shader. The fragment shader then uses those positions to sample the heightmap and read back y-values. This keeps terrain-aligned rendering consistent across different zoom levels and camera angles.
The BAR codebase has working implementations already. Read gfx_decals_gl4.lua for texture loading. Read gui_building_grid_gl4.lua for a minimal draw example. Then adapt the relevant pattern to your own widget instead of building from scratch.
Widget modding in BAR rewards the same habits that make good teammates: patient testing, sharing what works, and helping others skip pitfalls. Creed of Champions runs community dojos and team training where that learning culture is the norm.
"Creed of Champions is a great place to learn and play BAR in a friendly atmosphere. Training sessions, team gameplay, even some non-BAR stuff. Large cross section of abilities, time zones, and game mode interests." [Crd]