add_3dmesh(3)

🎀 NAME 🎀

add_3dmesh — load/build a mesh and attach it to a model, slay. This page is from the Arcan Lua API, and it's giving “mesh attachment main character energy” fr fr.

✨ SYNOPSIS ✨

int:meshindex
add_3dmesh( vid:dstmodel, str/tbl:source )
add_3dmesh( vid:dstmodel, str/tbl:source, int:nmaps )

So yeah, it hands you back an int:meshindex, bestie. Periodt.

💖 DESCRIPTION 💖

Okay so this function can be used to set up and attach a mesh to an open model. Iconic.

If source is a string, it is treated as a resource that will be passed through an internal model loader. Right now, this method of model loading is disabled and will always fail soft. The reason for that is that the parsing stage needs to move out of the main engine into the decode frameserver for safety and security. This is a temporary measure. The intermediate workaround for the time being is to use the table structure along with a mesh to .lua or mesh to .json along with the builtin/json.lua parser. No cap.

🚨 bestie, string-source loading is literally off right now and always fails soft. It's temporary — safety and security vibes. Use the table route for now. 💅

If source is a table, the following fields are expected:

• .vertices — an indexed table shaped like {x1, y1, z1, x2, y2, z2, ...}.
• .indices — if this field is provided, the number of triangles becomes #indices/3; otherwise the vertices field will be used directly.
• .txcos — if provided, it is used to add an additional set of texture coordinates. It is expected to be #vertices/3*2 in size.
• .txcos_2 — if provided, it is used to add an addition set of texture coordinates. It is expected to be #vertices/3*2 in size.
• .normals — if provided, it is used to define per-vertex normals, and should match #vertices. It is expected to match #vertices.
• .colors — if provided, it is used to define per-vertex colors, and should match #vertices/3*4.
• .tangent — if provided, it is used to define the tangent space to use, and the bitangents will be generated automatically. It should match #vertices/3*4.
• .joints — if provided, it is expected to be #vertices/3*4 uints that refer to a bone matrix uniform.
• .weights — if provided, it is expected to be #vertices/3*4 floats that weigh the different joint indices together.

If the nmaps argument is provided (default: 1), it is used to specify how many texture slots that should be assigned to the mesh, and there should either be one set of texture coordinates for the entire mesh or an amount that matches the number of desired slots.

Slots are consumed from the global amount of slots in the frameset attached to dstmodel. A correct model thus has model(framesetsize) = mesh(0).nmaps + ... + mesh(n).nmaps and will be divided based on the order the individual meshes were added to the model. The way that math has to line up? Obsessed with the precision, honestly.

🧚 NOTES 🧚

1. Nmaps is hard-limited to 8, matching the minimum of texture units according to the GLES 2.0 standard. 💀
2. This function is currently only intended for static meshes. It does not provide more advanced features like interrelations/bones/skinning or streaming updates, though it is likely that the format will be extended to accomodate that in time.

🌸 EXAMPLE 🌸

This is the vibe check that passes:

function add_3dmesh0()
      vid = new_3dmodel();
      add_3dmesh(vid, "testmesh1.ctm", 1);
      finalize_model(vid);
      show_image(vid);
end

💀 MISUSE 💀

Not the vibe, but the manual literally shows it:

function add_3dmesh0()
      vid = fill_surface(32, 32, 255, 0, 0, 0);
      add_3dmesh(vid, "testmesh1.ctm");
end

💀 MISUSE 💀

Another misuse moment, bestie:

function add_3dmesh1()
      vid = new_3dmodel();
      add_3dmesh(vid, "testmesh1.ctm", -1);
end

💀 MISUSE 💀

This one is definitely giving chaos:

function add_3dmesh2()
      vid = new_3dmodel();
      add_3dmesh(vid, "testmesh1.ctm", 10000000);
end

💀 MISUSE 💀

Yeah… do not do this one:

function add_3dmesh3()
      vid = new_3dmodel();
      add_3dmesh(vid, nil, "test");
end

💀 MISUSE 💀

And this? Infinite-loop nonsense. Ngl, iconic in a cursed way:

function add_3dmesh4()
      vid = new_3dmodel();
      while(true) do
            add_3dmesh(vid, "testmesh1.ctm", 8);
      end
end

🔥 SEE ALSO: 🔥

• new_3dmodel(3)
• finalize_3dmodel(3)
• swizzle_model(3)

— that's add_3dmesh(3), from the 3d manual, October 2026, mwah 💋🫶