EntitiesBuilder

A high-performance batch builder for creating large amounts of geometry in one shot.

Instead of calling createEdge() and createFace() one at a time — which generates a separate instruction for each element — the builder batches hundreds or thousands of edges and faces into a single efficient payload. This is essential for importing meshes, generating procedural geometry, or any scenario where you’re creating more than a handful of faces.

You obtain a builder inside an operation via op.createBuilder(container), where container is the model or a group. Add geometry to it using createEdge() and createFace(), then when the operation completes all geometry is committed in one batch.

The builder also supports UV texture positioning for draping materials across your geometry.

Example

let model = await SketchUpApi.getActiveModel();

// Create a 4x4 grid of faces efficiently.
await model.performOperation(async op => {
  await op.createBuilder(builder => {
    for (let x = 0; x < 4; x++) {
      for (let y = 0; y < 4; y++) {
        const s = 20;
        const p1 = [x*s, y*s, 0];
        const p2 = [(x+1)*s, y*s, 0];
        const p3 = [(x+1)*s, (y+1)*s, 0];
        const p4 = [x*s, (y+1)*s, 0];
        builder.createFace([p1, p2, p3, p4]);
      }
    }
  }).build(model);
  // All 16 faces committed in one batch.
}, 'Create grid');

See

Methods

addCallback()

addCallback(callback): void

Inserts a callback into the build sequence. Because the builder batches all geometry into one payload, you can’t track progress by counting individual operations. Use this to create checkpoints for progress reporting — for example, call it every 100 faces to update a progress bar.

Parameters

Parameter	Type	Description
`callback`	() => `void`	Function to invoke at this checkpoint.

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Set up an entities builder to create a huge stack
  // of triangles, and show progress in the console.
  await op.createBuilder(builder => {
    let completed = 0;
    for (let i = 0; i < 1000; i++) {
      builder.createFace([[0,0,i],[10,0,i],[10,10,i]]);
      if (i % 100 === 0) {
        builder.addCallback(() => {
          completed += 100;
          console.log(completed + ' done');
        });
      }
    }
  }).build(model);
}, 'Stack 1000 triangles');

createEdge()

createEdge(start, end): EntityBuilderEdgeRef

Adds a standalone edge to the batch. Use this for wireframes or structural lines that don’t bound a face. If you’re building surfaces, use createFace() instead — it automatically creates the edges that bound the face.

Parameters

Parameter	Type
`start`	`Point3Like`
`end`	`Point3Like`

Returns

EntityBuilderEdgeRef

A reference to the edge being created.

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  await op.createBuilder(builder => {
    builder.createEdge([0, 0, 0], [100, 0, 0]);
    builder.createEdge([0, 0, 0], [0, 100, 0]);
  }).build(model);
}, 'Create edges');

See

createFace

Since

SDK 2.34.0

createFace()

createFace(outerLoop, holes?): EntityBuilderFaceRef

Adds a face to the batch. The outer loop defines the boundary and must be counter-clockwise when viewed from the front — this determines which side receives the front material. All points must be coplanar. Holes (voids within the face) are specified clockwise.

Parameters

Parameter	Type	Default value	Description
`outerLoop`	readonly `Readonly`<`Point3Like`>[]	`undefined`	Counter-clockwise boundary vertices.
`holes`	readonly readonly `Readonly`<`Point3Like`>[][]	`[]`	Clockwise loops for any voids (optional).

Returns

EntityBuilderFaceRef

A reference to the face being created.

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  await op.createBuilder(builder => {
    // Square face with a square hole.
    const outer = [
      [0, 0, 0], [100, 0, 0],
      [100, 100, 0], [0, 100, 0],
    ];
    const hole = [
      [25, 25, 0], [25, 75, 0],
      [75, 75, 0], [75, 25, 0],
    ];
    builder.createFace(outer, [hole]);
  }).build(model);
}, 'Create face with hole');

See

Since

SDK 2.34.0

createTexturePositioning()

createTexturePositioning(material, positions, projection): EntityBuilderTexturePositioningRef

Defines how a textured material maps onto 3D geometry. Texture positioning pins the corners of the material’s texture image to specific 3D points on your faces — like stretching a decal over a surface. Use the returned reference with positionFaceFrontMaterial() or positionFaceBackMaterial() to apply it.

Parameters

Parameter	Type	Description
`material`	`Material` \| `MaterialRef`	Textured material to apply.
`positions`	`TexturePositioning`	1–4 3D points mapping texture corners.
`projection`	`Vector3d` \| `undefined`	Repeating direction (optional).

Returns

EntityBuilderTexturePositioningRef

A reference to the positioning definition.

Example

let model = await SketchUpApi.getActiveModel();

// Generate a gradient texture via canvas
let canvas = document.createElement('canvas');
let ctx = canvas.getContext('2d');
let grad = ctx.createLinearGradient(
  0, 0, canvas.width, canvas.height
);
grad.addColorStop(0, '#f00');
grad.addColorStop(1, '#0f0');
ctx.fillStyle = grad;
ctx.fillRect(
  0, 0, canvas.width, canvas.height
);
let base64 = canvas.toDataURL().split(',')[1];

await model.performOperation(async op => {
  const matRef = op.createMaterial('Grad');
  op.materialSetTextureDataBase64(
    matRef, base64
  );

  await op.createBuilder(builder => {
    const corners = [
      [0, 0, 0], [100, 0, 0],
      [100, 100, 0], [0, 100, 0],
    ];
    const face = builder.createFace(corners);

    // createTexturePositioning takes pairs
    // of [modelPoint, uvPoint] that pin model
    // coordinates to UV values. (The 3rd
    // element of the UV array is ignored.)
    // Double the u,v values to get your head
    // around it.
    const pos =
      builder.createTexturePositioning(
        matRef,
        [
          corners[0], [0, 0, 0],
          corners[1], [1, 0, 0],
          corners[2], [1, 1, 0],
          corners[3], [0, 1, 0],
        ],
        undefined
      );
    builder.positionFaceFrontMaterial(
      face, pos
    );
  }).build(model);
}, 'Textured face');

See

positionFaceBackMaterial()

positionFaceBackMaterial(ref, positioning): void

Applies a texture positioning to the back side of a face. Works like positionFaceFrontMaterial() but affects the reverse side. Useful when you want different UV mapping on each side.

Parameters

Parameter	Type	Description
`ref`	`EntityBuilderFaceRef`	Face to texture (from `createFace()`).
`positioning`	`EntityBuilderTexturePositioningRef`	UV mapping (from `createTexturePositioning()`).

Returns

void

See

positionFaceFrontMaterial()

positionFaceFrontMaterial(ref, positioning): void

Applies a texture positioning to the front side of a face. This tells SketchUp how to drape the material’s texture image across the face’s 3D surface using the UV coordinates you defined with createTexturePositioning().

Parameters

Parameter	Type	Description
`ref`	`EntityBuilderFaceRef`	Face to texture (from `createFace()`).
`positioning`	`EntityBuilderTexturePositioningRef`	UV mapping (from `createTexturePositioning()`).

Returns

void

See

toString()

toString(): string

Returns

string

Show Deprecated

Deprecated

edgeCreate()

edgeCreate(start, end): EntityBuilderEdgeRef

Parameters

Parameter	Type
`start`	`Point3Like`
`end`	`Point3Like`

Returns

EntityBuilderEdgeRef

faceCreate()

faceCreate(outerLoop, holes?): EntityBuilderFaceRef

Parameters

Parameter	Type	Default value
`outerLoop`	readonly `Readonly`<`Point3Like`>[]	`undefined`
`holes`	readonly readonly `Readonly`<`Point3Like`>[][]	`[]`

Returns

EntityBuilderFaceRef