Render thousands with instancing

quick start Beginner ⏱ 6 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• Run a scene that references an instance-transform asset
• See hundreds of instances drawn as one InstancedMesh
• Understand how a project owns deterministic placement data

What you'll build: A look at the instanced-grid scene — many instances in a single draw call.

Walkthrough — Render thousands with instancing · generated by site/media/lessons/scenes-batch.lesson.ts (4 steps)

A mesh with an instances asset renders as a single native THREE.InstancedMesh — one draw call for many copies. The instanced-grid scene references the project’s checked-in instances/grid.instances.json transform data.

The project owns placement

instances points to an .instances.json asset: an array of [posX,posY,posZ, quatX,quatY,quatZ,quatW, scaleX,scaleY,scaleZ] tuples. Generate it with a project script, export it from Blender, or author it with another tool. Bulk transforms stay in the referenced asset rather than bloating the scene document.

Follow along in the live web editor

Open the scene in your browser — no install: ▶ Open the instanced-grid scene. Every step below — including Play — works right in the browser; the hosted editor transpiles the example in-browser and boots the real runtime.

Steps

1. Open the instanced-grid scene. The scene is already open — if you followed the link above, the instanced-grid scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/feature-scenes npm run dev).

   

   The instanced-grid scene.

2. Enter play mode — the instance asset renders the grid. The checked-in asset contains a 30 × 30 grid (900 transforms) on the XZ plane.

   

   A grid of instances.

3. Hundreds of instances draw in a single InstancedMesh. One draw call covers the whole grid. The owning project’s generator uses a seeded LCG, so regenerating the asset is stable.

   

   One InstancedMesh, many instances.

4. Stop play mode. Press Stop (or Escape).

Recap

New functionality

• Ran a scene using an instance-transform asset
• Saw a 900-object grid drawn in one call

New concepts & skills

• A mesh's instances field -> one InstancedMesh
• .instances.json keeps bulk transforms out of the scene
• The project owns generation and exported data

Next lesson → Manual: Instancing, terrain & splines

On Your Own!

Extend what you built:

• Change countX/countZ in the project's generator script
• Regenerate and confirm the checked-in asset diff
• Export a circular placement set from Blender

See also

• Instancing, terrain & splines · Rendering & meshes