llamamod/notes/editor-render.md

Level editor – render package (editor.render)

Phase 1 of the level editor (notes/editor-design.md): OpenGL viewport, level rendering, overlays, camera, picking, transform gizmo. Package com.eliasmueller.llamamod.editor.render; it has no dependency on editor.model/editor.io – the UI adapts the scene model to RenderScene.

Build / platform

• Gradle: LWJGL 3.4.2 (lwjgl, lwjgl-opengl, lwjgl-jawt, lwjgl-egl) + lwjgl3-awt 0.2.5 (AWTGLCanvas, a heavyweight AWT canvas inside Swing; transitive = false, its POM pulls Vulkan/macOS natives) + JOML 1.10.8 (math). Natives natives-linux and natives-windows of lwjgl and lwjgl-opengl are runtime dependencies, so the fat jar (and with it both packages) carries linux/x64/…/*.so and windows/x64/…/*.dll; LWJGL extracts them to a temp dir at runtime. Fat jar 9.7 MB.
• Fat jar manifest gets Multi-Release: true (LWJGL is a multi-release jar), module-info.class files are excluded. jlink modules + jdk.unsupported (LWJGL/JOML use sun.misc.Unsafe). packageLinux/packageWindows otherwise unchanged.
• OpenGL 3.3 core profile, no 2.1 fallback (decision): shaders are GLSL 330, texture pages are one GL_TEXTURE_2D_ARRAY, VAOs/VBOs. 3.3 is supported by every GPU/driver since ~2010 (Intel HD 2000+, Mesa llvmpipe gives 4.5); a 2.1 path would double the renderer for hardware that cannot run the rest of the toolchain comfortably anyway. The canvas first asks for 4× MSAA and retries without multisampling; if no 3.3 context can be created the viewport shows a message instead of crashing (Viewport.glError()). No swap interval is requested (Xvfb/GLX has no swap control, lwjgl3-awt then fails context creation).
• Tested:
  • Linux native (Xvfb + llvmpipe, DISPLAY=:8): fat jar and the jlinked LlamaMod-linux-x64 runtime – rendering, picking, gizmo drags, fly mode via xdotool.
  • Windows package under Wine 6.0.3 (own win64 prefix, JDK_JAVA_OPTIONS=-XX:ActiveProcessorCount=4, runtime\bin\java.exe -cp LlamaMod.exe …ViewerDemo): Wine's WGL gives a 3.3 core context on the host llvmpipe; the screenshot is pixel-identical to the Linux one. LlamaMod.exe --mods still works. Real Windows hardware not tested.
• -Dllamamod.editor.msaa=0 disables multisampling (2–3× faster on software GL).

Demo

java -cp build/libs/llamamod-*-all.jar com.eliasmueller.llamamod.editor.render.ViewerDemo \
     <level.wad | testworld> [--cd DIR] [--size 1280x720] [--collision] [--no-markers]
     [--hide waypoints,zones] [--view top|front|side] [--cam x,y,z,yawDeg,pitchDeg]
     [--select o12,t5,w3] [--frame] [--gizmo translate|rotate|scale] [--shot out.png] [--bench] [--list]

testworld builds the Testwelt (TestWorldMod) from the CD's village WAD. The window has layer check boxes, view and gizmo mode selectors and a status bar (hover/pick info). --list prints all strats with ids and positions. --bench orbits 120 frames and prints timings.

Controls (Viewport)

Navigation presets (Navigation.Preset, View › Navigation, Preferences › Viewport & navigation, Help › Viewport navigation; setting viewnav.preset, default Fusion 360):

Input	Fusion 360 (default)	Blender	Unity / Unreal
middle drag	pan	orbit	pan
Shift+middle drag	orbit	pan	pan
Ctrl+middle drag	zoom	zoom	zoom
double-click middle	fit all	–	–
Alt+left drag	orbit	orbit	orbit
right drag	look around + W/A/S/D move, Q/E down/up, Shift ×4, wheel = fly speed (all presets)
Alt+right drag	zoom (all presets)
wheel	smooth exponential zoom towards the cursor (all presets)

Input	Action
view cube (top right)	click a face / edge / corner = look from there (animated, pivot and projection kept), drag = orbit, house = home (iso view from front-right-top + frame all)
F / Home	frame selection / frame all tiles (smooth 220 ms transition)
numpad 7 / 1 / 3 / 5	top / front / side (orthographic) / toggle perspective
W / E / R, Q (when not flying)	gizmo translate / rotate / scale, toggle world/local
left click	pick (listener); left drag on a gizmo handle = transform; Ctrl = invert snapping; Esc = cancel drag

• Zoom (2026-11-07): constant percentage per wheel notch (zoomFactor, default 12 %, 2–40 %, "invert zoom"), fractional touchpad deltas scale smoothly, animated 120 ms (ease-out; further notches accumulate on the target). Anchor (anchorDistance): the depth-buffer hit under the cursor if it lies in front of the near plane and closer than 3× the pivot depth (and the far plane), else the current pivot depth along the cursor ray – pointing at the sky or a far cliff no longer makes a huge step, a near wall no longer stalls. The anchor becomes the new pivot depth. Old behaviour: a fixed 0.15 × distance dolly step along the ray, independent of what is under the cursor (sky/near ground felt extremely fast/slow).
• Orbit: pivot = surface point under the cursor at drag start (fallback: selection centre, then view centre), shown as a small RGB cross; the camera keeps its camera-space offset to the pivot, so the pivot stays under the cursor; constant angular speed (default 0.35 °/px), pitch clamped to ±89°. Camera.viewMatrix now uses the mirrored yaw direction as up vector when looking straight up, so pitching across the vertical threshold no longer flips the picture.
• Pan moves the grabbed point (its view depth) exactly with the cursor (sky: pivot depth).
• Viewport API: setNavigation/zoomAt/setZoomSpeed/setInvertZoom/setOrbitSpeed/setViewCubeVisible/ home/snapView; math in Navigation and ViewCube (pure, NavigationTest, ViewCubeTest). Plugin tools.viewnav.ViewNavEditorPlugin (menus, preferences dialog, cheat sheet; the status bar shows a one-line summary on open and when the preset changes).

Orbiting a standard ortho view switches back to perspective. Hover picking runs at most every 40 ms while the mouse moves (setHoverPicking(false) turns it off).

API

RenderScene scene = LevelSceneAdapter.fromWad(wadBytes).scene();   // or built by the editor UI
Viewport vp = new Viewport();               // JPanel; add to any Swing layout
vp.setScene(scene);
vp.setGrid(0, new float[] {0, -H, W, 0});   // grid plane y and bounds (x0, z0, x1, z1)
vp.setLayerVisible(LevelSceneAdapter.LAYER_COLLISION, true);
vp.setSelection(List.of(PickId.of(PickId.OBJECT, 12)));            // highlight (+ unbatched tiles)
vp.gizmo().setVisible(true); vp.gizmo().setTarget(matrix); vp.gizmo().setMode(Gizmo.Mode.ROTATE);
vp.gizmo().setSnap(new Gizmo.Snap(true, 0.25f, 15f, 0.1f));         // grid snapping hook
vp.addViewportListener(new ViewportListener() {
    public void picked(PickEvent e) { … e.id(), e.world(), e.modifiers(), e.clickCount() … }
    public void hovered(int id) { … }
    public void gizmo(GizmoEvent e) { … }                            // START / DRAG / END / CANCEL
    public void cameraChanged(Camera c) { … }
});
vp.frameAll(); vp.frameSelection(); vp.setView(Camera.View.TOP);
vp.pick(x, y); vp.surfacePoint(x, y);       // synchronous id buffer / depth reads
vp.screenshot(); vp.stats(); vp.glInfo(); vp.requestRender(); vp.dispose();

Scene data (render-facing interface)

• RenderScene: pages (TexturePage(w, h, int[] 0xRRGGBBAA)), instances, markers, overlays (world-space Overlay per layer name), background (0xRRGGBB, also fog colour). After edits: changed(instance) (rebuilds only that instance's chunk), changed() (everything, markers/overlays), texturesChanged(). Modify on the Swing thread.
• RenderMesh: triangle mesh in local space – per vertex positions/normals, per triangle corner UVs (normalised to the page), per triangle page (-1 = untextured), colour (multiplied, flat colours / translucency), flags (DOUBLE_SIDED, NO_VERTEX_COLOR, LIT = shade with normals) and blend class (BLEND_OPAQUE = alpha-tested cut-out, BLEND_ALPHA, BLEND_ADD). Optional overlay = local-space helper geometry that follows every instance (collision).
• RenderInstance(id, kind, mesh): transform (JOML Matrix4f), vertexColors (game convention 0x80 = 1.0, doubled with clamp), tint, visible, layer. Kind TILE instances are baked into static batches; OBJECT/PREVIEW are drawn individually with their matrix.
• Marker: pickable icon (cube/diamond/flat arrow, pole, direction tick, colour, layer, label).
• Overlay: coloured lines + translucent triangles (box, line, triangle).
• Pick ids are plain ints, 0 = nothing; PickId is the convention used by the adapter (kind << 24 | index: TILE, OBJECT, WAYPOINT, ZONE, LIGHT, USER…).
• Legend: collision colours by material/slope and marker category colours, same as notes/debugviz.md (Legend.category(stratName)).

Gizmo

Gizmo is pure math (unit-tested in GizmoTest): modes TRANSLATE (3 axes, 3 planes, centre = screen plane), ROTATE (3 rings, back halves faded, edge-on rings fall back to screen angle), SCALE (3 axes in local space, centre = uniform). World or local space (scale always local). Handles keep a constant screen size (sizePx, default 95). Hit testing in screen space (9 px). GizmoEvent carries the total delta since drag start (translation, axis+angle about the start pivot, scale factors) plus the start matrix: e.result() = new target transform, e.applyTo(m) for other selected objects. The UI shows a live preview on DRAG, emits one undoable command on END and restores e.start() on CANCEL; it calls gizmo().setTarget() so the handles follow (axes stay as at drag start). Snapping: Snap(enabled, translate step, rotate degrees, scale step), Ctrl inverts enabled while dragging.

Coordinate conventions (handedness fix, 2026-11-06)

• The view is left-handed like the game's Direct3D renderer. The engine draws export-space data (tile floats, TRAK/STPC vertices, strat (x, y, −z)) with a D3D camera, so a plain OpenGL view of the same coordinates was the game's picture mirrored left-right (owner report: "levels mirrored"). Camera.viewMatrix() = scale(−1, 1, 1) · lookAt(…); the renderer culls with glFrontFace(GL_CW); data, picking (ray/project use the matrices) and the scene model are unchanged.
• Camera.yaw/pitch equal the game camera angles (0x5790a4/0x5790a0, 4096 = 2π): yaw 0 looks along game +z (export −z), yaw 90° along +x, positive yaw turns left. forward() = (sin y·cos p, sin p, −cos y·cos p) (export), right() = screen right = (−cos y, 0, −sin y) (game: (−cos y, sin y), as found by the freecam mod), up() = forward × right. Fly look/orbit: dragging right decreases yaw. ViewerDemo --cam x,y,−gz,yawDeg,pitchDeg [--fov vDeg] reproduces a game camera.
• Rotate gizmo: the edge-on fallback uses the screen angle with the mirrored sign.
• Standard views: top = x to the right, game z (grid rows) downwards (cell (0,0) top left, as the MAP/region grid is laid out; yaw π); front looks along game −z (x right); side looks along −x.
• Spaces: render/export space = (x, y, −z_game); model and inspector values (strats, waypoints, zones, lights, collision) are game space, tiles store export floats. LGHT point lights/directions are stored in game space (engine negates z on load). Strat yaw: rotateY(−ry·2π/4096) in export space with model front = local −z → yaw 0 faces game +z, 1024 faces +x (verified: llama ry 3061 and Pacha at his runtime yaw 830 face the same way as in game). Tiles: rotateY(−rot).
• Evidence: in-game screenshots (apptest + freecam, camera read with winedbg from 0x5790b0 and the look-at target 0x6d9d80) vs. ViewerDemo from the same camera: img/editor/fix_compare_start.jpg (game / before / after), fix_compare_back.jpg, fix_compare_yaw.jpg, fix_compare_top.jpg. The game's horizontal FOV matches 60° vertical at 16:9; its vertical FOV is ~15 % smaller (non-uniform projection, not reproduced). Regression test: CameraHandednessTest (projected pixel x of the llama and Pacha against the game screenshots, axis conventions).

Rendering details

• Batching: tile instances are pre-transformed into 8×8-cell chunks; each chunk is one VBO (36-byte vertices: position, normal, UV, colour, pick id, page layer + flags) sorted into 6 ranges (blend class × double-sided) plus a line VBO (collision outlines/fills). Frustum culling per chunk AABB / per object (Culling, below). All pages live in one texture array (+1 white layer for flat colours), so a chunk needs at most 6 draw calls. Objects use one VBO per mesh. Selected tiles are taken out of their chunk and drawn alone, so dragging them never rebuilds a chunk; changed(instance) on a tile rebuilds its chunk (~20k vertices, a few ms).
• Passes: opaque (alpha test, back-face culling except double-sided faces), back sides (below), overlay lines, translucent (alpha, then additive; depth write off, not sorted), overlay fills, selection (orange tint + hidden-line ghost + wireframe; hover = pale wireframe), gizmo (depth cleared). Optional distance fog (40–160 cells) in the level's backdrop colour.
• Picking: id-buffer pass into an offscreen RGBA8/depth FBO (scissored to a 9×9 window, the nearest non-zero pixel wins so small markers are easy to hit), depth → world hit point. Cut-out texels are not pickable (click through leaves).
• Textures: TEXT pages ABGR1555 → RGBA, 0x0000 transparent, STP=0 = half alpha on blend pages (page class 4/5/7); transparent texels are dilated (no dark fringes), 3 mip levels. Blend class per face: texture entry bits 12–14 (1/3 → alpha, 2/4 → additive) or, for mode 0, page class (4/7 alpha, 5 additive) – an approximation of the engine's table at 0x573eb8; flat colour entries (bit 0) use u0/u1/v0 as RGB, alpha in v1 when a blend mode is set.

Culling and "disappearing objects" (2026-11-07)

Owner report: objects, especially large ones, disappear at the screen edge.

• Root cause: not the frustum culling but the Environment plugin's fog preview (on by default): it sets a FogOverride with clip + aroundPivot, and the mesh shader discarded every fragment farther than the fog end from the orbit pivot (radial). The pivot is the view centre, so geometry towards the screen edges was cut away, and it popped in/out while panning. Evidence: img/editor/cull_root_fogclip.jpg (old build, same camera: fog preview on / off – the left islands are missing with it on). Fix (render package only): with aroundPivot the shader draws a desaturated ghost beyond the radius instead of discarding (uClipGhost); the eye-based far clip is unchanged.
• Frustum culling itself was correct (JOML plane extraction is orientation-independent; the mirrored view only swaps the left/right planes). Hardened anyway: Culling boxes include every vertex and the instance's overlay (collision lines/fills – a collision-only chunk had an empty box and was always culled), objects use their local box transformed with the full instance matrix (rotation/scale, 8 corners), skinned characters are culled with their posed vertices, + a small absolute/relative margin. -Dllamamod.editor.noCull=true disables culling (diagnostics).
• Tests: CullingTest – random perspective/ortho cameras (any yaw/pitch, fov 30–100°, aspect), random rotated/scaled meshes + every village instance: whenever any vertex projects inside the clip volume the box must be visible (no false culls). Pixel check: ViewerDemo village, city (t1l6m003) and Testwelt from inside the level at 8 yaws each, culling on vs noCull: 0 differing pixels in all 24 pairs (img/editor/cull_overview.jpg).

Back sides of one-sided faces

The game culls faces without flag 0x400 from behind; the editor now shows those back sides (View › Show back faces, default on; opacity in Viewport preferences, default 30 %): pass 3 after the opaque pass draws the single-sided opaque/cut-out ranges again with glCullFace(GL_FRONT), depth-tested without depth writes, blended, darkened + desaturated with a fine screen-space diagonal hatch. Front faces look exactly as before (the pass only fills pixels whose depth is not covered). Translucent one-sided faces (island skirts) get no back side (it showed through them everywhere). Picking hits both sides; the shader sets bit 31 of the pick id for a back side (PickHit.backFace, Viewport.lastPickBackFace()/hoverBackFace()), the status bar appends "(back side)" to the hovered item. img/editor/cull_backfaces.jpg (one-sided cliff walls seen from behind: game look / editor).

Level adapter (LevelSceneAdapter.fromWad)

• Tiles: TRAK model per MAP tile, transform translation(x, y, z).rotateY(-rot) (same as Geometry.TileXform), vertex colours = first colour frame (alt models of WFPC 0x10000 tiles are not shown). UVs via Geometry.faceUvs, face flags 0x400 / 0x4000 honoured.
• Collision: every TRAK model's polygons (Collision.decode/polygon) as outlines 1 cm above the face, coloured as in debugviz (floor green, slope yellow-green, wall blue, ceiling orange, materials 16/17/18/30/… fixed colours); fills for material 16 (exit floor) and faintly 17/18. Invisible-collision detection (red fill of the in-game debug mod) is not done.
• Strats: game space → export space (z negated), yaw = ry. Object models: the strat code sets its model with 0xb2 <abs STPC offset of the model header>; 0x54 – StratModels scans the strat from its entry to the next strat's name site and takes the first such pair; spawn stubs (b2 <code> e0) are followed. Characters (skinned models, header +0x84 = 0, nBones × u16 vertex counts) are posed with frame 0 of an animation set with the same bone count (first one referenced by 0xb2 <set> in the strat code, else the first in STPC): bone matrices 4×4 f32, row vectors. Result: villagers, kids, Pacha, Tipo, bunnies look right, the llama is shown in a crouching pose (frame 0 of its set). Village: 20 of 32 placed types get a model (8 of them skinned); the rest are invisible logic objects, except RisingColumns, SwitchPlatformPadVillage and AppearingPlatformsVillage, which set their models some other way (shown as markers).
• Invisible strats (categories of debugviz: start, exit, checkpoint, camera, trigger, force, secret, misc) become markers on poles (exit: purple cell box); start/checkpoint additionally show their model. Objects without a resolvable model: small grey cube; unposable character: grey diamond.
• Waypoints: every path node a pickable diamond (layer waypoints), chains (next ≠ 0 → i+1) and strat → first node as lines. Some chains are point lists across the whole level (e.g. the llama's), so the layer gets busy – the UI should show it for the selection only.
• Environment zones: pink cell boxes + pickable marker (layer zones); the default zone's backdrop colour (file offset 0x4e, 0x00BBGGRR) becomes scene.background (cyan village sky, purple river fog, dark blue city).

Performance (1280×720, llvmpipe software GL on this machine, 4× MSAA / no MSAA)

Level	tiles/objects/markers	triangles drawn	draw calls	orbit avg MSAA 4	no MSAA
village t1l1m001 (+collision)	1458 inst., 218 markers	27k	125–145	17–27 ms	9 ms (109 fps)
river t1l3m002 (+collision)	1494 / 322	22k	145–170	17–40 ms	10 ms (103 fps)
city t1l6m003 (largest WAD)	2177 / 439	41k	120–140	26–50 ms	18 ms (55 fps)

(Ranges: several agents shared the CPU.) Scene conversion from WAD 160–290 ms. On any real GPU this is far below 1 ms of GPU time; the CPU side is ~150 draw calls per frame.

GPU resources (2026-11-07)

• GlRenderer.dispose() frees everything it created: batches, texture array, pick FBO, programs and the dynamic dynVao/dynVbo (gizmo, overlays).
• Chunks that lose their last member are deleted with their batch (before: an empty chunk kept a Chunk entry until the next full rebuild). Shared per-mesh batches (meshBatches, objects and tiles without vertex colours) whose mesh no instance uses any more are freed once there are more than 256 (limit doubles with the live count) – replaced meshes used to stay until a level switch.
• Viewport.liveGlBuffers() counts live VAO/VBO pairs of all batches (diagnostics). ui.view.GlLeakCheck (test sources, X display): 3 rounds over Village 1 / world 4 / Village 2, each load followed by 60 rounds of tile moves, object moves, delete + undo while rendering → the count is identical per level in every round (84 / 87 / 76), 0 with no level loaded.
• SceneRenderer drops the pick ids of nodes that are no longer in the scene every 256 removals (nodes that come back by undo get a new id; selected nodes keep theirs) – SceneRendererIdsTest. Tiles marked "no collision" use a copy of their model mesh without the collision overlay.

Known limits / next steps

• Only the first vertex colour frame and the primary tile model (no alt/swap models).
• Translucent faces are not depth-sorted (as the game does per batch; artefacts are rare).
• Engine blend table only approximated; no texture animations (TEXT nAnim block), no sky/backdrop geometry, no lights (LGHT) yet.
• Characters: frame 0 of a guessed animation set; models whose pose fails show a diamond.
• Collision of object models (moving platforms, doors) is not drawn (same as the debug mod).
• Viewport.dispose() plus disposing the frame can hang on Xvfb without a window manager (AWT focus round trip); the demo exits with System.exit after a shot.

Screenshots: img/editor/01_village.jpg … 12_viewer_ui.jpg (village/river/city/Testwelt with and without collision, ortho top views, translate/rotate gizmo, the demo window with a selection).