EntityBuilderFaceRef

A lightweight placeholder for a Face created inside an EntitiesBuilder callback.

The EntitiesBuilder is the high-performance path for creating geometry. When you need to draw hundreds or thousands of edges and faces — like generating a mesh or importing model data — the builder batches everything into a single round-trip to SketchUp, making it dramatically faster than calling operation.createFace repeatedly.

When you call faceCreate on a builder, it returns an EntityBuilderFaceRef immediately. This ref is only valid inside the builder callback — to use it after the build completes, convert it with EntityBuilderRefConverter.asRef in an EntityBuilderCall.onPostBuild callback.

Example

let model = await SketchUpApi.getActiveModel();

await model.performOperation(async op => {
  // The builder callback creates geometry in bulk.
  // Return refs you'll need in the post step.
  await op.createBuilder(builder => {
    const darkRefs = [], lightRefs = [];
    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];
        const ebFaceRef = builder.faceCreate(
          [p1, p2, p3, p4]
        );
        if ((x + y) % 2) {
          darkRefs.push(ebFaceRef);
        } else {
          lightRefs.push(ebFaceRef);
        }
      }
    }
    return { darkRefs, lightRefs };
  })
  // onPostBuild runs after geometry is created.
  // Use converter.asRef() to convert builder refs
  // into operation refs.
  .onPostBuild((converter, { darkRefs, lightRefs }) => {
    darkRefs.forEach(ebFaceRef => {
      const faceRef = converter.asRef(ebFaceRef);
      op.faceSetFrontMaterialName(faceRef, 'dimgray');
    });
    lightRefs.forEach(ebFaceRef => {
      const faceRef = converter.asRef(ebFaceRef);
      op.faceSetFrontMaterialName(faceRef, 'white');
    });
  })
  .build(model);
}, 'Build a checkerboard');

See

Properties

mappingId

readonly mappingId: number

type

readonly type: Face = EntityType.Face

Accessors

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

toString()

toString(): string

Returns

string