Summarize engine 3D capabilities

Delegated run·Sep 14, 2026  18:57·Prompted by Fable·Run by Sonnet 5Sonnet 5 high
Ctrl + F
Show

Transcript

Fable·18:57:52·Sep 14, 2026Prompter

Orientation read for a first-person 3D game on the Anchor engine. Return CONCLUSIONS with exact function names and doc line references, not file dumps. Do not modify anything.

Read, in C:/Users/a327e/Desktop/a327ex/Anchor/engine/:

  • docs/SURFACE.md (whole), docs/AGENT.md (skim: how an agent instance is driven, engine_step, agent_snapshot/engine_snapshot, what Lua can be eval'd)
  • docs/3D_API.md (whole)
  • docs/ENGINE_API_QUICK.md: the sections on layer3, mesh3, physics3, textures, audio/sound, shaders, input (mouse look: relative mouse / cursor lock?), camera
  • .claude/CLAUDE.md (working agreements) and reference/plan.md (skim for the 3D extension's status and known gaps)
  • playground/main.lua (skim for the canonical style)
  • Also grep engine/src/anchor.c for: "mouse_lock" or "relative" or "cursor" (cursor grab / relative mouse mode for FPS look), "light" (dynamic lights in layer3? point lights? spot? shadows?), "obj" (OBJ mesh loading), "gltf"/"skeleton"/"bone" (skeletal animation support?), "sound_play"/"audio" (formats: wav/ogg?), "heightmap", "fog", "sun", "sky", "billboard", "alpha_cutoff", "render_target"/"canvas" (render to texture, for a photo capture/thumbnail?), "screenshot"/"snapshot" (saving the framebuffer to PNG from Lua), "raycast".

Report: A) What layer3 can render: lighting model (per-vertex? unlit? sun direction? point lights count? any spot/flash light possible?), fog, sky, jitter/affine (PS1 features), transparency/alpha cutoff, billboards, multiple layers (e.g., a low-res 3D layer composited under a 2D UI layer), post shaders, render-to-texture. B) Meshes: mesh3_create from vertex arrays, OBJ loading, per-instance transforms, vertex colors, UV textures, animation approach (any skeletal? otherwise procedural per-frame transforms of parts). C) physics3 (Box3D): what a first-person hovering controller can use (kinematic body? capsule? raycast down for hover height? character mover caveats), raycast/query APIs for "is this creature visible from the camera" (line-of-sight), triggers/sensors. D) Input: mouse look feasibility (relative mouse mode / cursor lock / mouse delta), key handling, the input-edge-in-update trap. E) Audio: playing wav/ogg files, volume, positional audio (any 3D panning?), multiple simultaneous sounds. F) Capture: can Lua save the current frame to a PNG (for the photo album), or grab a region as a texture? G) Agent harness: the exact commands to start/eval/stop an agent instance, take a snapshot image, and step time; anything about --headless --verify. H) Known gaps and traps relevant to the above (cite reference_anchor_gotchas-style traps you find in the docs: draw origins, callable colors, input edges, .handle, layer3_new before mesh3_create, etc.).

Aim for 1200-2000 words. Exact names. Say "not found" when something is not there rather than guessing.

Sonnet 5high·18:58:01·Sep 14, 2026Worked for 2m 40s
Thinking18:58:01

This is an orientation task, so I'll just read through the relevant files directly—docs/SURFACE.md, docs/AGENT.md, docs/3D_API.md, ENGINE_API_QUICK.md, .claude/CLAUDE.md, reference/plan.md, playground/main.lua—and grep anchor.c for key terms, doing this in parallel for efficiency.

ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/3D_API.md18:58:01Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/3D_API.md
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/.claude/CLAUDE.md18:58:01Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/.claude/CLAUDE.md
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/SURFACE.md18:58:01Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/SURFACE.md
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/AGENT.md18:58:01Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/AGENT.md
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/reference/plan.md18:58:01Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/reference/plan.md
Thinking18:58:08

I'll continue reviewing the quick API docs, the playground main.lua file, and search anchor.c for the relevant terms, using whichever tool is most efficient for these reads.

Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && awk '/^## layer3|^## mesh3|^...18:58:09Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && awk '/^## layer3|^## mesh3|^...
Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && grep -n "^## " docs/ENGINE_A...18:58:09Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && grep -n "^## " docs/ENGINE_A...
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md18:58:09Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md18:58:09Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md18:58:09Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md
ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md18:58:09Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md
Thinking18:58:22

I want to grep anchor.c for the specific terms requested, check the physics3 raycast section header, and look at playground/main.lua for reference, though the gotchas memory file may not be directly accessible from the engine repo.

Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && wc -l anchor.c ec...18:58:25Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && wc -l anchor.c ec...
Thinking18:58:35

No OBJ loading is in the C engine, so it must be handled in the Lua framework instead, likely via a mesh3.lua parser mentioned in plan.md. It looks like animation is limited to CPU skinning through a runtime API rather than full skeletal import, and audio seems to rely on stb_vorbis for ogg with wav support probably coming from dr_wav or SDL — I want to verify the wav decoding path, then check raycast, billboard, and render_target.

Also checking on canvas support, screenshot/snapshot capture, positional 3D audio panning, point light counts, and spotlight/flashlight features.

ReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/playground/main.lua18:58:36Output not recorded
Input
C:/Users/a327e/Desktop/a327ex/Anchor/engine/playground/main.lua
Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && echo "---point/sp...18:58:36Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && echo "---point/sp...
Thinking18:58:47

I don't see any positional or 3D panning audio, and no dr_wav or SDL_LoadWAV usage for decoding WAV files. I should search for how sound_load actually works, whether it relies on SDL_mixer, check whether raycast is a general line-of-sight query, and verify if the reference_anchor_gotchas.md file mentioned in memory actually exists.

Since that gotchas reference turns out to be a memory file rather than something in the repo, I can just note key traps already documented — the loud failures section, handle usage, edge queries being update-only, and the requirement that layer3_new precede mesh3_create. I should verify whether that ordering requirement is documented anywhere, and also check how OBJ mesh loading works in framework's mesh3.lua since the C side lacks OBJ parsing.

Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && echo "---sound_lo...18:58:48Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && echo "---sound_lo...
GrepOBJ|obj_load|parse_obj|mesh3_load_obj18:58:48Output not recorded
Input
OBJ|obj_load|parse_obj|mesh3_load_obj
Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && grep -n "layer3_new before\|...18:58:48Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && grep -n "layer3_new before\|...
Thinking18:59:12

Good, miniaudio handles decoding natively for wav, mp3, and flac, with ogg support likely coming through the bundled stb_vorbis as an extension backend.

I don't find any positional or 3D audio panning API — just volume, pitch, and bits controls, so that's confirmed absent. mesh3_load_obj is confirmed as framework-side OBJ loading rather than C bindings, which answers that question, and I don't find dedicated reference docs for anchor3_assessment or the 3D-exploration doc, which is fine since those predate current docs.

For capture, engine_snapshot for PNG is confirmed, and I'm now checking whether a 3D scene can render to a texture separately from a full snapshot — it looks like layer3_create renders into a Layer's FBO, and layer_get_texture could retrieve that texture, meaning you could render a layer3 scene and use its texture elsewhere.

This confirms that render-to-texture already happens internally for layer compositing, so it could be repurposed for something like a photo album feature, but there's no dedicated function to save a texture directly to a file — engine_snapshot only captures the whole composited frame, and engine_render_setup outputs a directory of frames. So the answer is that saving a specific texture requires framing the shot by drawing only the desired content and then calling engine_snapshot, since no generic "texture to PNG" binding exists. Now I want to check physics3 raycasting for line-of-sight and how sensor/trigger tags work.

The character mover API is already noted as deferred due to Box3D's alpha state, and I've confirmed physics3_set_target_transform is the kinematic drive method suitable for a hover controller. As for the reference_anchor_gotchas file, that seems to be a memory reference outside this codebase, so instead I'm compiling the actual gotchas I've found directly from the docs — the loud failures section, the centered draw origin behavior for textures, and callable color conventions.

I'm also examining whether layer3_new needs to precede mesh3_create, since the error message about the 3D pipeline not being initialized implies some setup ordering dependency I should verify.

Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && grep -n "3D pipel...18:59:12Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && grep -n "3D pipel...
Thinking18:59:19

I've confirmed the layer3/mesh3 ordering trap is genuinely enforced via a raised Lua error, not just documented in prose. Now I want to verify the "callable colors" convention by checking whether color() returns a callable, looking for the Color metatable with __call in the framework or anchor.c source.

Bashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && grep -rn "__call" framework/...18:59:19Output not recorded
Input
cd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && grep -rn "__call" framework/...

Confirmed. Now I have everything needed to write the report.

Conclusions

A) layer3 rendering capabilities (docs/3D_API.md + ENGINE_API_QUICK.md lines 402-432, engine/src/anchor.c)

  • Lighting: single directional light only — layer3_set_light(l3, dx, dy, dz, ambient=0.35). Per-fragment Lambert + ambient (anchor.c:11234 l_layer3_set_light, anchor.c:10534 default light dir). No point lights, no count parameter, no spotlight/flashlight primitive, no shadow mapping — "shadow" in the code (shade_shadow, u_shadow_tint) is just a color tint for the unlit side under layer3_set_shade, not a shadow map/shadow-casting system. Stylized shading extras: layer3_set_shade(l3, {wrap, bands, shadow={r,g,b}, rim, rim_color, spec, spec_power}) — cel-shading style bands, rim light, specular, all optional/neutral by default (3D_API.md:138-143).
  • Fog: layer3_set_fog(l3, color, near, far) — linear distance fog (ENGINE_API_QUICK.md:412).
  • Sky: layer3_set_sky(l3, zenith, horizon, ground) / layer3_disable_sky(l3) procedural sky, plus layer3_set_sun(l3, dx, dy, dz, color, sharpness=512) — a separate visual sun disc from the lighting direction (ENGINE_API_QUICK.md:416-418).
  • PS1 features: layer3_set_jitter(l3, res_x, res_y) — vertex snapping to an NDC grid; layer3_set_affine(l3, amount) — 0=perspective-correct, 1=full affine texture warp (3D_API.md:414-415).
  • Transparency/alpha cutoff: layer3_set_alpha_cutoff(l3, cutoff) discards fragments below alpha (cutout look); mesh3_set_transparent(mesh, enabled) puts a mesh in a depth-tested-but-not-depth-written blended pass (no transparency sorting — plan.md lists "transparency sorting" as explicitly out of scope/later).
  • Billboards: layer3_billboard(l3, x, y, z, w, h, color?, texture?, blend?, u0,v0,u1,v1, ylock?) — blend modes 'add'(default)/'alpha'/'cutout', ylock for Y-axis-only rotation (good for flashlight-lit sprites, particles, or a UI marker in 3D space).
  • Multiple layers: up to 8 layer3 instances max per the "Max 8 layer3s" line (3D_API.md:146). Each renders into an ordinary Layer's FBO (layer3_get_layer(l3)), so a low-res 3D layer3 (fixed-size via layer3_create(name, w, h, filter), e.g. a chunky PS1-res render) composited under a full-res 2D layer_new UI layer is exactly the intended pattern — same composite pipeline as any 2D layer (layer_draw, post shaders, etc).
  • Post shaders: yes — layer3's output is a normal Layer, so layer_apply_shader, layer_shader_set_*, set_draw_shader all work on it (3D_API.md:135, "post-process shaders OK").
  • Render-to-texture: implicit — every layer3 already renders into an FBO/texture (layer3_get_layer → layer_get_texture(layer) -> texture_id). There's no separate "render arbitrary scene to an offscreen texture for later sampling" API beyond this — it's the same mechanism as normal layer compositing, not a dedicated render-target system.
  • Limits: 4096 instances per mesh type per frame, 16384-32768 line vertices per frame (two docs disagree slightly: 3D_API.md says 16384, ENGINE_API_QUICK.md says 32768 — treat as approximate).

B) Meshes (3D_API.md:148-176, ENGINE_API_QUICK.md:434-449, framework/anchor/mesh3.lua)

  • mesh3_create(vertices) — flat float array, 8 floats/vertex (x,y,z,nx,ny,nz,u,v), whole triangles only.
  • OBJ loading is NOT a C binding — it's a framework-side Lua parser: mesh3_parse_obj(text) / mesh3_load_obj(path) in framework/anchor/mesh3.lua (confirmed via grep — no obj/.obj string anywhere in anchor.c). It reads via file_read_string (works in packaged builds) and is cached by path.
  • Per-instance transforms: layer3_mesh(l3, mesh, x, y, z, sx?, sy?, sz?, qx?, qy?, qz?, qw?, color?) — position/scale/quaternion-rotation/color per draw call, instanced.
  • Vertex colors: not found as a distinct channel — the vertex format is position/normal/UV only; color comes from the layer3_mesh per-instance color argument or per-mesh texture, not per-vertex.
  • UV textures: yes, mesh3_set_texture(mesh, texture|nil), mesh3_set_uv_offset(mesh, u, v) (for scrolling), shared 1×1 white default texture when none set.
  • Animation: no glTF/skeleton-import, no bone-hierarchy authoring tool in the engine. What exists is CPU skinning against externally-supplied bone matrices: mesh3_create_skinned(vblob, iblob, wblob) (binary blobs: rest-pose verts, 4×u8 bone indices, 4×f32 weights, max 64 bones) + mesh3_skin(mesh, matrices) (flat 16×n column-major mat4s, premultiplied inverse-rest-pose, "once per character per frame") + sparse morph targets mesh3_set_morphs/mesh3_morph. In other words: you supply the pose matrices yourself each frame (e.g. computed procedurally, or from your own IK/animation code) — the engine does the GPU-avoiding CPU blend+reupload, not the animation authoring or import. For anything simpler, procedural per-part transforms via multiple layer3_mesh/layer3_box calls (rigid parts) is the documented alternative ("rigid parts always break open at a bend" — 3D_API.md:150-151).

C) physics3 (Box3D) (3D_API.md:11-117, plan.md status)

  • Body types: 'static'|'dynamic'|'kinematic' via physics3_create_body.
  • Kinematic hover controller: physics3_set_target_transform(body, x,y,z,qx,qy,qz,qw, dt, wake?) is the documented mechanism — "kinematic drive: sets the velocity that reaches the transform after dt... carries real velocity and shoves dynamic bodies properly" (unlike physics3_set_position/set_transform, which teleport and push nothing). This is what you'd use for a first-person hover craft.
  • Capsule shape: physics3_add_capsule(body, tag, height, radius, opts), opts.axis='x'|'y'|'z' default y, height = total height including caps.
  • Raycast-down-for-hover-height: physics3_raycast(x1,y1,z1, x2,y2,z2, tags) -> {body, shape, tag, point_x/y/z, normal_x/y/z, fraction} | nil and physics3_raycast_all. This is also your line-of-sight/"is this creature visible from camera" query — cast from camera eye to target point/creature center, check whether the returned hit body is the creature itself or something occluding it.
  • No dedicated character-mover/ghost-collision API. plan.md explicitly lists this as deferred: "character mover bindings (Box3D lists character movement + ghost collisions as alpha-incomplete — revisit when a walking-character game needs it)." reference/plan.md also flags Box3D-alpha caveats generally (memory note reference_box3d_alpha_caveats.md: "character mover/ghost collisions = future work"). For a first-person controller you're expected to build movement yourself on a kinematic or dynamic capsule body plus raycasts, not use a built-in mover.
  • Sensors/triggers: yes — physics3_enable_sensor(a,b), physics3_get_sensor_begin/end(sensor_tag, visitor_tag), separate from hit/collision events. Also physics3_query_sphere/aabb/box/point/capsule(..., tags) for proximity queries (e.g. "what creatures are within N meters").
  • Joints: only grab (spring, 3D "mouse joint") and spherical (ball-and-socket, ragdoll-capable) are bound; distance/revolute/prismatic/weld/wheel/parallel are explicitly deferred ("bind on demand" — plan.md Phase 3 status).

D) Input (ENGINE_API_QUICK.md:472-517, anchor.c:16060-16073)

  • Mouse look is directly supported: mouse_set_grabbed(grabbed) → SDL_SetRelativeMouseMode — hides the cursor and gives unbounded deltas, exactly FPS-style relative mouse mode. mouse_delta() -> dx, dy reads per-frame movement. A separate mouse_set_window_grab(grabbed) confines the cursor to the window without hiding it or going relative (RTS-style) — don't confuse the two; comment at anchor.c:16068 calls this out ("unlike mouse_set_grabbed / SDL_SetRelativeMouseMode").
  • Keys: key_is_down/is_pressed/is_released(key); also a higher-level action-binding layer (input_bind, is_down(action), input_get_vector(left,right,up,down) for WASD-style movement vectors, gamepad axis support via input_get_axis/gamepad_get_axis).
  • The input-edge trap: from ENGINE_API_QUICK.md's "Loud failures" section (line 579) — "key/mouse/input pressed/released called from draw() RAISE on desktop ('edge queries are update-only') — they were silently always-false there. Web: one console warning." So key_is_pressed/mouse_is_pressed/is_pressed etc. must only be polled in update(dt), never draw().

E) Audio (ENGINE_API_QUICK.md:85-109, anchor.c:93 #include <miniaudio.h>, anchor.c:23861 stb_vorbis)

  • Backend is miniaudio, which natively decodes WAV/MP3/FLAC, plus stb_vorbis is compiled in for Ogg Vorbis — so wav/mp3/flac/ogg are all playable via sound_load(path)/music_load(path).
  • sound_play(sound, volume?, pitch?, bits?, sr_div?, start_sec?) — note bits<16 gives bitcrush and sr_div>1 downsampling, both DSP effects rather than spatial audio.
  • Multiple simultaneous sounds: yes, a pooled voice system (sound_play_handle returns -1 "if no free slot" — there's a hard cap; AGENT.md:224-227 notes agent instances can exhaust "the 512 voice slots" and log "No free sound slots available" since nothing drains a noDevice mix unless audio_render is armed — a known harmless-to-sweeps issue, "fix pending").
  • Positional/3D panning audio: not found. No sound_set_position, no pan parameter, nothing spatial in the audio API — only volume/pitch/bitcrush/downsample per voice. For a first-person game needing "sound gets quieter/pans as you move away," you'd have to compute stereo volume/pitch yourself from world positions and feed sound_play(sound, volume, pitch, ...) or sound_handle_set_volume/set_pitch manually — there's no built-in 3D audio engine.

F) Capture / photo album

  • engine_snapshot(path) (ENGINE_API_QUICK.md:554, anchor.c:22456) — "composite the current frame at game resolution and write it as a PNG at path... captures ONE frame on demand." This is the mechanism for a photo-album feature: draw exactly the frame you want (potentially hiding UI layers that frame) and call engine_snapshot.
  • engine_render_setup(dir) + engine_render_save_frame() — saves every rendered frame as dir/frame_NNNNNN.png, meant for the old --render capture-sequence workflow, not single-shot use.
  • No API to grab an arbitrary region/layer as a standalone texture-to-file. layer_get_texture(layer) -> texture_id gets you the GL texture backing any layer (including a layer3's composited output) for further in-engine use (e.g. drawing it into another layer, a "photo preview" thumbnail composited into UI), but saving that to disk still goes through engine_snapshot on a frame where only that content is drawn — there's no texture_save_png or similar.

G) Agent harness (docs/AGENT.md, docs/SURFACE.md)

Exact commands:

anchor drive start  <game>                       # spawns `anchor <game> --agent`, waits for the eval socket
anchor drive eval   <game> 'engine_step(120)'     # run Lua; expressions return values
anchor drive eval   <game> 'agent_shot()'         # -> replays/shots/<frame>.png (agent.lua kit)
anchor drive eval   <game> --file tests/smoke.lua
anchor drive log    <game>                        # instance's stdout/stderr
anchor drive stop   <game>                        # engine_quit() -> finalizes recording

Also directly through Lua once an agent instance is running: engine_step(n) (agent instances only — advances n rendered frames, "two fixed updates each"), engine_snapshot(path) (on-demand PNG), engine_state() (frame/step/time/dt/agent/visible/recording/sizes — field is frame, not frame_num), input_inject_key/mouse_move/mouse_button/text (through the real SDL pump so update-time edge detection sees them as genuine input), replay_mark(text, kind?). Framework kit in framework/anchor/agent.lua: agent_tap, agent_click, agent_wait_until(pred, max_steps), agent_dump, agent_globals, agent_shot.

No --headless or --verify flags exist anymore — SURFACE.md's table explicitly maps the old flags to functions: --headless is now --agent + engine_set_draw(false); --verify=... is now just the game's own verify_run{} function called through the eval channel. The only command-line surface is anchor <game | file.apr> [--agent] — any other flag prints usage and exits (SURFACE.md:23).

H) Known gaps/traps found in these docs

  1. Draw origins: layer_draw_texture draws centered at (x,y) (ENGINE_API_QUICK.md:29); layer_draw_text draws from top-left (line 78) — inconsistent origin convention between texture and text drawing, easy to get bitten by.
  2. Callable colors: color(r,g,b,a) returns a table whose __call metamethod packs it to the rgba() integer engine functions expect (framework/anchor/color.lua:100-103); playground's own code shows the pattern: bg_variants = {dark = color(26,26,26)} then bg_color() calls bg_variants[...](). Passing the color table itself where a raw packed color is expected via a raw layer3_*/layer_* binding will not implicitly convert — only the framework's layer_* wrappers accept either form (Loud-failures note, ENGINE_API_QUICK.md:581-582: "framework: layer_* wrappers accept a Color table or a packed integer").
  3. Input edges are update-only: calling is_pressed/key_is_pressed/mouse_is_pressed etc. from draw() raises a Lua error on desktop (was silently always-false before) — ENGINE_API_QUICK.md:579.
  4. .handle requirement: every binding taking an engine handle (layer, texture, sound, physics id, video…) now raises "Sound handle expected (got a table with no .handle)" for a wrong type instead of segfaulting — ENGINE_API_QUICK.md:576-578. Framework wrapper tables (from layer3_new, camera3_new, etc.) carry .handle; pass the wrapper table or the raw handle, not some other table.
  5. layer3_new before mesh3_create: enforced in C — mesh3_create/mesh3_create_skinned raise "3D pipeline not initialized — create a 3D layer (layer3_new) before creating meshes" if no layer3 exists yet (anchor.c:11306, 11357). Create your layer3_new('scene') before building any custom meshes.
  6. Spring/joint frequency cap: spring_add/spring_pull (and by extension joint hertz values) raise above SPRING_MAX_FREQUENCY (12) rather than diverging into a screen-sized sprite (ENGINE_API_QUICK.md:582-583).
  7. Spherical-joint cone/twist frames are identity-built, not aimed down the limb — 3D_API.md:109-112 explicitly warns: "on a capsule whose rest rotation aims +Y down the limb, the cone points sideways and the limb starts outside it. Leave limits off unless the frames get built to aim Z down the limb." Directly relevant if you ever ragdoll a first-person creature.
  8. Untested-visually items (3D_API.md:227-234, as of 2026-07-07): lighting orientation, debug-draw box extents (half vs full — "flip the 2* in debug3_draw_box" if colliders render at double size), face winding, heightfield/grid-mesh visuals (no primitive mesh for these — debug draw shows segments "if at all"). Treat any heightfield-based terrain rendering as unproven.
  9. Reloading discipline: one-time work (asset loads, layer3_new, physics init, binds) must live in a boot file named in the init table (boot = {'boot.lua'}); anything else in main.lua re-runs on every save, and re-running layer3_new/physics3_init etc. inside a reloadable file would rebuild them on every edit (SURFACE.md "Reloading", AGENT.md "Reloading code").
  10. Web GLSL caveat: the sky/billboard/PS1-effect shaders "compile in the browser's driver, not in emcc, so a green wasm build says nothing about" whether they actually work under WebGL2 (plan.md, Phase merge-back note) — relevant only if this first-person game targets web export.

Files referenced: Anchor/engine/docs/SURFACE.md, Anchor/engine/docs/AGENT.md, Anchor/engine/docs/3D_API.md, Anchor/engine/docs/ENGINE_API_QUICK.md, Anchor/engine/.claude/CLAUDE.md, Anchor/engine/reference/plan.md, Anchor/engine/playground/main.lua, Anchor/engine/framework/anchor/mesh3.lua, Anchor/engine/framework/anchor/color.lua, Anchor/engine/engine/src/anchor.c (line refs above). No files were modified.

Back to Halumi

Settings