Skip to content
Skills Library
Programming · Building & coding

mesh-builder-scripting

/mesh-builder-scripting

Runtime MeshBuilder API reference for Lens Studio — construct or mutate meshes from TypeScript (primitive helpers, lathe, extrude, tube, topology examples, dynamic vertex updates, skinned meshes, vertex colors). Use when writing a script that builds or animates geometry at runtime. For author-time static GLB generation (SPECS Text-to-3D / FAST3D / Blender voxel), use `/build-mesh` instead.

Licence
Apache-2.0
Last repository change
01.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
1
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 01.09.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Runtime MeshBuilder API reference for Lens Studio — construct or mutate meshes from TypeScript (primitive helpers, lathe, extrude, tube, topology examples, dynamic vertex updates, skinned meshes, vertex colors). Use when writing a script that builds or animates geometry at runtime. For author-time static GLB generation (SPECS Text-to-3D / FAST3D / Blender voxel), use `/build-mesh` instead.

Original author description

Runtime MeshBuilder API reference for Lens Studio — construct or mutate meshes from TypeScript (primitive helpers, lathe, extrude, tube, topology examples, dynamic vertex updates, skinned meshes, vertex colors). Use when writing a script that builds or animates geometry at runtime. For author-time static GLB generation (SPECS Text-to-3D / FAST3D / Blender voxel), use `/build-mesh` instead.

How it works

  1. API Reference
  2. Resources
  3. Workflow
  4. Reminders
  5. Vertex Layout Attributes
  6. Further Examples
Original SKILL.md headings · 121 lines, 1,269 words
SKILL.md preview
---
name: mesh-builder-scripting
description: Runtime MeshBuilder API reference for Lens Studio — construct or mutate meshes from TypeScript (primitive helpers, lathe, extrude, tube, topology examples, dynamic vertex updates, skinned meshes, vertex colors). Use when writing a script that builds or animates geometry at runtime. For author-time static GLB generation (SPECS Text-to-3D / FAST3D / Blender voxel), use `/build-mesh` instead.
context: fork
---
<!--
Copyright 2026 Specs Inc.
SPDX-License-Identifier: Apache-2.0
-->

# MeshBuilder API (Runtime)

## API Reference

The core classes live in `Support/StudioLib.d.ts`. Grep for each symbol by name to find the current definition:

| Symbol | Purpose |
|--------|---------|
| `MeshBuilder` | Construct and mutate meshes at runtime |
| `MeshTopology` | Topology enum (Triangles, TriangleStrip, TriangleFan, Points, Lines, LineStrip) |
| `MeshIndexType` | Index type enum (None, UInt16) |

Grep for `class MeshBuilder`, `enum MeshTopology`, and `enum MeshIndexType` in `StudioLib.d.ts` to get the current method signatures (`appendVerticesInterleaved`, `setVertexInterleaved`, `appendIndices`, `eraseVertices`, `eraseIndices`, `getMesh`, `updateMesh`, `setBones`, etc.). This is the same discipline as `lens-studio-field-notes` "Verify the API surface before writing" — apply it to any other unfamiliar LS API too.

## Resources

This skill includes a pre-built vertex color package:

```
{skill_base_dir}/resources/SimpleVertexBaseColor.lspkg
```

Contains `vertexBaseColorMaterial` (UUID: `70d03593-c7b4-410a-ae5c-75cb82ee32dc`) — purpose-built for per-vertex color rendering. Use this instead of UberPBR.

### Material Do / Don't

- **Do** import the packaged `SimpleVertexBaseColor.lspkg` and wire `vertexBaseColorMaterial` (UUID above) to the script's `@input material`. This is the default path.
- **Do** alternatively use Uber PBR / UberUnlit with `passInfos.0.Vertex Color` set to `"Base Color"` (`valueType: STRING`) if you need PBR shading on top of vertex colors.
- **Do** query `asset-graphql assetsByName(name: "vertexBaseColorMaterial")` first if you're not sure whether the package is already installed — avoid re-importing.
- **Don't** hand-write `.mat` YAML files. The UUIDs can collide with Lens Studio built-ins silently (producing "Duplicate material id" warnings and leaving `this.material` null at runtime), and `PassesInfo` is non-trivial to construct correctly.
- **Don't** create a material without a shader assigned — an empty `PassesInfo: []` will load but render as null.

## Workflow

1. Grep for `class MeshBuilder` in `Support/StudioLib.d.ts` and read the full class definition for exact method signatures.
2. **Pick the right generator before writing geometry.** Defaulting to `addBox`/`buildCylinder` for smooth shapes produces blocky output. Classify the target (full examples in `references/smooth-surfaces.md`):

   | Shape | Generator | Reference |
   |---|---|---|
   | Rotationally symmetric (chess piece, vase, map pin) | **lathe** | `smooth-surfaces.md` |
   | 2D outline with depth (heart, star, coin, gear) | **extrude** | `smooth-surfaces.md` |
   | Circular cross-section swept along a path (pipe, cable) | **tube** | `smooth-surfaces.md` |
   | Angular / modular / blocky (crates, walls, pixel-art) | stack `addBox`/`buildCylinder` | `primitives.md` |

   Most real assets compose multiple generators — see composing examples in `references/smooth-surfaces.md`. Unless the user specifies otherwise, target an overall size of roughly **50-100 cm** in Lens Studio world units so the mesh is immediately visible from a typical camera setup.
3. Write a TypeScript `@component` class that:
   - Declares `@input material: Material` to accept the vertex color material from outside.
   - Creates a `RenderMeshVisual` directly in `onAwake()` via `this.sceneObject.createComponent("Component.RenderMeshVisual") as RenderMeshVisual` — do **not** rely on a pre-wired mesh visual input.
   - Creates a `MeshBuilder` with the appropriate vertex layout. **Include `color` (4 components, RGBA) by default** — it enables per-vertex coloring.
   - Sets `topology` and `indexType`.
   - Appends vertices via `appendVerticesInterleaved` and indices via `appendIndices`.
   - Assigns the mesh and material to the RenderMeshVisual:
     ```ts
     const rmv = this.sceneObject.createComponent("Component.RenderMeshVisual") as RenderMeshVisual;
     rmv.mesh = builder.getMesh();
     if (this.material) rmv.mainMaterial = this.material;
     builder.updateMesh();
     ```
4. For dynamic meshes (moving vertices each frame), see `references/dynamic-updates.md`.
5. Wire the script into the scene using `scene-graphql` and `asset-graphql`:
   a. Create a SceneObject named after the mesh (e.g. `"Castle"`).
   b. Add a `ScriptComponent` to it — **no need to add RenderMeshVisual via scene-graphql**, the script creates it at runtime.
   c. Wire `scriptAsset` on the ScriptComponent to the `.ts` file you just wrote (`valueType: REFERENCE`).
   d. Query the ScriptComponent's `properties` to confirm `material` appears in `inputNames` — no recompile needed. LS file-watches `.ts` files and updates `inputNames` automatically on save.
6. Set up the vertex color material:
   a. Install the package via the `InstallLensStudioPackage` MCP tool (do **not** `cp` the `.lspkg` — a raw file copy does not register it as a package and it will not appear under "Packages" in the Asset Browser):
      ```
      InstallLensStudioPackage(
        packageUri: "{skill_base_dir}/resources/SimpleVertexBaseColor.lspkg",
        assetName: "SimpleVertexBaseColor"
      )
      ```
   b. The material UUID is stable — wire it directly to the `material` input on the ScriptComponent:
      ```graphql
      mutation {
        setProperty(id: "<script-component-id>", propertyPath: "material", valueType: REFERENCE, value: "70d03593-c7b4-410a-ae5c-75cb82ee32dc") { success message }
      }
      ```
7. Verify by querying the SceneObject's ScriptComponent and confirming `material` input is non-null.
8. **Verify visually** per `lens-studio-field-notes` "See-and-fix loop": capture the mesh from at least two angles (`MovePreviewCamera`) and judge the pixels. Hollow or see-through faces = CW winding (fix the indices per Reminders — do not paper over with two-sided); wrong/faceted lighting = shared-vertex normals (per-face duplication per Reminders).
9. Tell the user: the mesh was added to the scene root at origin with identity transform. Positioning, scaling, and parenting are left to the user.

## Reminders

- Call `updateMesh()` after every change.
- `indexType` should almost always be `MeshIndexType.UInt16`.
- **Winding order — front face = CCW viewed from outside.** Lens Studio has back-face culling on by default (`Cull Back`), so CW triangles are invisible. This is the single most common procedural-mesh bug.
  - **Rule:** each triangle's indices `[v0, v1, v2]` must trace counter-clockwise when viewed from outside the mesh.
  - **Sanity check:** `(v1 - v0) × (v2 - v0)` (cross product) should point the **same direction as the outward normal**. If it points inward, flip the triangle: `tri(v0, v1, v2)` → `tri(v0, v2, v1)`.
  - **Debug:** if your mesh looks inside-out or is invisible, temporarily set the material's Cull Mode to `Front`. If the mesh now renders correctly, your winding is inverted — flip all triangle index orders and switch the material back to `Cull Back`.
  - **Common trap:** copying a winding pattern across helpers. An index pattern is only CCW for the exact vertex labeling it was written for — the cylinder's `[bl, tr, br, bl, tl, tr]` is correct there and CW (culled) on a screen-space-labeled quad. Check each triangle with the cross-product rule above instead of reusing patterns; `references/primitives.md` has numerically verified `addBox` and capped `buildCylinder` helpers.
  - **Common trap:** copy-pasting one face's index pattern to all 6 box faces produces CW winding on at least 3 of them — use the `addBox` helper in `references/primitives.md`.
- **Closed solids need per-face vertices and normals.** A box is 24 vertices — 4 per face, each carrying that face's outward normal — never 8 shared corners. Shared vertices smear lighting across edges and make winding bugs harder to spot. Apply the same per-face duplication to any flat-shaded solid (crates, walls, trunks, towers).
- For genuinely thin sheets (leaves, flags, wing membranes), enable two-sided on the material rather than duplicating reversed indices. Never use two-sided as a band-aid for a see-through *solid* — that is a winding bug; fix the indices.
- **Never use the `script` global inside `BaseScriptComponent` class methods** — it is undefined at runtime. Use `this` instead: `this.sceneObject`, `this.createEvent(...)`, etc.

## Vertex Layout Attributes

```ts
{ name: "position",  components: 3 }           // required
{ name: "color",     components: 4 }           // include by default (RGBA, per-vertex)
{ name: "normal",    components: 3, normalized: true }
{ name: "texture0",  components: 2 }
{ name: "boneData",  components: 4 }           // only for skinned meshes
```

`appendVerticesInterleaved` reads the flat array in strides of `sum(components)`. Each vertex's attributes must appear in the same order as the constructor layout.

## Further Examples

- `references/topology-examples.md` — Points, Lines, LineStrip, TriangleStrip, TriangleFan
- `references/primitives.md` — `addBox`, `buildCylinder` helpers with verified CCW winding (angular/blocky shapes)
- `references/smooth-surfaces.md` — `buildLathe`, `buildExtrude`, `buildTube` for smooth, rotationally-symmetric, or swept shapes (**prefer over stacking primitives for curved geometry**)
- `references/dynamic-updates.md` — `setVertexInterleaved` pattern for per-frame mesh updates
- `references/skinned-meshes.md` — `boneData` attribute, skinned example, and `MeshBuilder.createFromMesh`
Files in this package (7)
  • SKILL.md 10 KB
  • references/dynamic-updates.md 2 KB
  • references/primitives.md 5 KB
  • references/skinned-meshes.md 4 KB
  • references/smooth-surfaces.md 15 KB
  • references/topology-examples.md 3 KB
  • resources/SimpleVertexBaseColor.lspkg 4 KB

Versions

The database has no other skills named mesh-builder-scripting.

Database snapshot: 13.11.2026 · package version 33fe3fc907fc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100specs-optimize-lens-mesh
    Cuts Specs draw calls in a Lens Studio prefab by merging same-material RenderMeshVisuals, then decimating geometry. Trigger on "reduce draw calls", "merge meshes", "optimize this model", "make this Lens faster". Needs Lens Studio MCP.
  • 100lens-api
    Lens Studio TypeScript scripting — component lifecycle, decorators, touch input, screen-to-world conversion, runtime object creation, material cloning, scene queries, and timers. Use when writing any Lens Studio TypeScript script, handling tap/touch events, converting screen to…
  • 100blender-syntax-mesh
    Use when creating or editing mesh geometry in Blender Python -- vertices, edges, faces, BMesh operations, or bulk data access. Prevents the performance mistake of accessing vertices one-by-one instead of using foreach_get/foreach_set for bulk operations. Covers from_pydata,…
  • 100pixijs-scene-mesh
    Use this skill when rendering custom geometry in PixiJS v8. Covers Mesh with MeshGeometry (positions, uvs, indices, topology), MeshSimple for per-frame vertex animation, MeshPlane for subdivided deformation, MeshRope for path-following textures, PerspectiveMesh for 2.5D corners.…
  • 100threejs-geometry
    Build and optimize Three.js geometry with built-in primitives, BufferGeometry, BufferAttributes, indexed meshes, custom vertex data, lines and points, and instanced rendering. Use when creating meshes, editing vertices or UVs, generating shapes, reducing draw calls, or…
  • 100bevy-voxel-pipeline
    Use when meshing voxel chunks with `block-mesh-rs` (`greedy_quads` / `visible_block_faces`), translating a `GreedyQuadsBuffer` into a Bevy 0.19 `Mesh` via `try_insert_attribute`, choosing greedy versus simple meshing, or implementing the worker-side meshing function consumed by…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.