Summarize engine 3D capabilities
Transcript
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
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/3D_API.mdReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/.claude/CLAUDE.md18:58:01Output not recorded
C:/Users/a327e/Desktop/a327ex/Anchor/engine/.claude/CLAUDE.mdReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/SURFACE.md18:58:01Output not recorded
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/SURFACE.mdReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/AGENT.md18:58:01Output not recorded
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/AGENT.mdReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/reference/plan.md18:58:01Output not recorded
C:/Users/a327e/Desktop/a327ex/Anchor/engine/reference/plan.mdThinking18: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
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
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
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.mdReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md18:58:09Output not recorded
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.mdReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md18:58:09Output not recorded
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.mdReadC:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.md18:58:09Output not recorded
C:/Users/a327e/Desktop/a327ex/Anchor/engine/docs/ENGINE_API_QUICK.mdThinking18: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
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
C:/Users/a327e/Desktop/a327ex/Anchor/engine/playground/main.luaBashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine/engine/src" && echo "---point/sp...18:58:36Output not recorded
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
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
OBJ|obj_load|parse_obj|mesh3_load_objBashcd "C:/Users/a327e/Desktop/a327ex/Anchor/engine" && grep -n "layer3_new before\|...18:58:48Output not recorded
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
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
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:10534default 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 underlayer3_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, pluslayer3_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',ylockfor 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 vialayer3_create(name, w, h, filter), e.g. a chunky PS1-res render) composited under a full-res 2Dlayer_newUI 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_shaderall 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)inframework/anchor/mesh3.lua(confirmed via grep — noobj/.objstring anywhere inanchor.c). It reads viafile_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_meshper-instancecolorargument 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 targetsmesh3_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 multiplelayer3_mesh/layer3_boxcalls (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'viaphysics3_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" (unlikephysics3_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} | nilandphysics3_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. Alsophysics3_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, dyreads per-frame movement. A separatemouse_set_window_grab(grabbed)confines the cursor to the window without hiding it or going relative (RTS-style) — don't confuse the two; comment atanchor.c:16068calls 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 viainput_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." Sokey_is_pressed/mouse_is_pressed/is_pressedetc. must only be polled inupdate(dt), neverdraw().
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?)— notebits<16gives bitcrush andsr_div>1downsampling, both DSP effects rather than spatial audio.- Multiple simultaneous sounds: yes, a pooled voice system (
sound_play_handlereturns-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 anoDevicemix unlessaudio_renderis 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 feedsound_play(sound, volume, pitch, ...)orsound_handle_set_volume/set_pitchmanually — 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 callengine_snapshot.engine_render_setup(dir)+engine_render_save_frame()— saves every rendered frame asdir/frame_NNNNNN.png, meant for the old--rendercapture-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_idgets 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 throughengine_snapshoton a frame where only that content is drawn — there's notexture_save_pngor 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 recordingAlso 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
- Draw origins:
layer_draw_texturedraws centered at (x,y) (ENGINE_API_QUICK.md:29);layer_draw_textdraws from top-left (line 78) — inconsistent origin convention between texture and text drawing, easy to get bitten by. - Callable colors:
color(r,g,b,a)returns a table whose__callmetamethod packs it to thergba()integer engine functions expect (framework/anchor/color.lua:100-103); playground's own code shows the pattern:bg_variants = {dark = color(26,26,26)}thenbg_color()callsbg_variants[...](). Passing the color table itself where a raw packed color is expected via a rawlayer3_*/layer_*binding will not implicitly convert — only the framework'slayer_*wrappers accept either form (Loud-failures note, ENGINE_API_QUICK.md:581-582: "framework: layer_* wrappers accept a Color table or a packed integer"). - Input edges are update-only: calling
is_pressed/key_is_pressed/mouse_is_pressedetc. fromdraw()raises a Lua error on desktop (was silently always-false before) — ENGINE_API_QUICK.md:579. .handlerequirement: 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 (fromlayer3_new,camera3_new, etc.) carry.handle; pass the wrapper table or the raw handle, not some other table.layer3_newbeforemesh3_create: enforced in C —mesh3_create/mesh3_create_skinnedraise "3D pipeline not initialized — create a 3D layer (layer3_new) before creating meshes" if no layer3 exists yet (anchor.c:11306,11357). Create yourlayer3_new('scene')before building any custom meshes.- Spring/joint frequency cap:
spring_add/spring_pull(and by extension joint hertz values) raise aboveSPRING_MAX_FREQUENCY(12) rather than diverging into a screen-sized sprite (ENGINE_API_QUICK.md:582-583). - 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.
- 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*indebug3_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. - 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 inmain.luare-runs on every save, and re-runninglayer3_new/physics3_initetc. inside a reloadable file would rebuild them on every edit (SURFACE.md "Reloading", AGENT.md "Reloading code"). - 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.