Skip to content

parts ​

Making part types: a part's bodies, connectors and parameters.

Every example below is a complete script that passes the kit's checks; the kit's tests run each one.

  • parts.part: Start one size of a custom part (equipment, a fixture, a device): declare optional hosting ("wall_face" snaps flush onto walls and auto-rotates, "ceiling", "floor", "free"), add bodies, connectors and annotative plan symbols, then build().
  • parts.faces: The faces a connector can go on: top, bottom, front, back, left, right.
  • parts.rect: A rectangle profile (width along the view's first axis, height along its second), centred unless center moves it; corners filleted or chamfered.
  • parts.circle: A circle profile of a diameter, centred unless center moves it.
  • parts.polygon: Any closed polygon profile of fixed corners (wound either way); corners filleted or chamfered.
  • parts.views: The views a profile is drawn in: plan (x right, y up; bodies go up), front (y right, z up; bodies go toward the front, +x), side (x right, z up; bodies go left, +y).
  • parts.starterTypes: The starter library's part types in every discipline, filtered by words in the family, type, category or id.
  • parts.refreshBuiltins: Upgrades stale built-in part types already pinned in an existing model to the latest library symbols (mode: "symbols", default) or full definitions (mode: "full") as one atomic edit, leaving placed parts and custom types untouched.

parts.part ​

Start one size of a custom part (equipment, a fixture, a device): declare optional hosting ("wall_face" snaps flush onto walls and auto-rotates, "ceiling", "floor", "free"), add bodies, connectors and annotative plan symbols, then build().

ts
part(name: string, start: { type: string; category: PartCategory; description?: string; hosting?: "free" | "wall_face" | "ceiling" | "floor"; tagFields?: string[] }): PartBuilder

Topics: custom part, equipment, rooftop unit, rtu, water heater, panel, family, wall_face, hosting

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "part",
  reads: {},
  parameters: { width: { type: "quantity", kind: "length", unit: "in", label: "Width", default: units.in(24) } },
  run(ctx, v) {
    const b = parts.part("Box", { type: "24", category: "generic" });
    b.box({ length: v.width, width: units.in(12), height: units.in(12) });
    ctx.parts.define("acme.box.24", b.build());
  },
});

parts.faces ​

The faces a connector can go on: top, bottom, front, back, left, right.

ts
faces: readonly ("top" | "bottom" | "front" | "back" | "left" | "right")[]

Topics: face, connector, side

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "part",
  reads: {},
  parameters: { width: { type: "quantity", kind: "length", unit: "in", label: "Width", default: units.in(24) } },
  run(ctx, v) {
    const b = parts.part("Box", { type: "24", category: "generic" });
    b.box({ length: v.width, width: units.in(12), height: units.in(12) });
    for (const face of parts.faces) if (face === "top") b.connector(face, { id: "out", label: "Outlet", domain: "duct", systemKind: "supply_air", shape: "round", diameter: units.in(10), endType: "mechanical.slip" });
    ctx.parts.define("acme.box.24", b.build());
  },
});

parts.rect ​

A rectangle profile (width along the view's first axis, height along its second), centred unless center moves it; corners filleted or chamfered.

ts
rect(width: Length, height: Length, opts?: { center?: [Length, Length]; fillet?: Length; chamfer?: Length }): Profile

Topics: profile, rectangle, rounded corners, fillet, chamfer

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "part",
  reads: {},
  parameters: { width: { type: "quantity", kind: "length", unit: "in", label: "Width", default: units.in(24) } },
  run(ctx, v) {
    const b = parts.part("Cabinet", { type: "24", category: "generic" });
    b.extrude(parts.rect(v.width, units.in(18), { fillet: units.in(1) }), { to: units.in(30) });
    ctx.parts.define("acme.cab.24", b.build());
  },
});

parts.circle ​

A circle profile of a diameter, centred unless center moves it.

ts
circle(diameter: Length, opts?: { center?: [Length, Length] }): Profile

Topics: profile, circle, round, tank

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "part",
  reads: {},
  parameters: { width: { type: "quantity", kind: "length", unit: "in", label: "Width", default: units.in(24) } },
  run(ctx, v) {
    const b = parts.part("Tank", { type: "24", category: "plumbing_fixture" });
    b.extrude(parts.circle(v.width), { to: units.in(48) });
    ctx.parts.define("acme.tank.24", b.build());
  },
});

parts.polygon ​

Any closed polygon profile of fixed corners (wound either way); corners filleted or chamfered. Use for curbs, hoods, brackets, odd housings.

ts
polygon(points: [Length, Length][], opts?: { fillet?: Length; chamfer?: Length }): Profile

Topics: profile, polygon, outline, custom shape, hood

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "part",
  reads: {},
  parameters: { width: { type: "quantity", kind: "length", unit: "in", label: "Width", default: units.in(24) } },
  run(ctx, v) {
    const b = parts.part("Hood", { type: "48", category: "mechanical_equipment" });
    b.extrude(parts.polygon([[units.in(0), units.in(0)], [units.in(48), units.in(0)], [units.in(48), units.in(24)], [units.in(12), units.in(36)], [units.in(0), units.in(36)]], { chamfer: units.in(2) }), { on: "side", from: units.in(-12), to: units.in(12) });
    ctx.parts.define("acme.hood.48", b.build());
  },
});

parts.views ​

The views a profile is drawn in: plan (x right, y up; bodies go up), front (y right, z up; bodies go toward the front, +x), side (x right, z up; bodies go left, +y).

ts
views: readonly ("plan" | "front" | "side")[]

Topics: view, plane, orientation, which way

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "part",
  reads: {},
  parameters: { width: { type: "quantity", kind: "length", unit: "in", label: "Width", default: units.in(24) } },
  run(ctx, v) {
    const b = parts.part("Plate", { type: "24", category: "generic" });
    for (const view of parts.views) if (view === "front") b.extrude(parts.rect(v.width, units.in(12)), { on: view, to: units.in(0.5) });
    ctx.parts.define("acme.plate.24", b.build());
  },
});

parts.starterTypes ​

The starter library's part types in every discipline, filtered by words in the family, type, category or id. Place one with equipment.place by its id (the type is pinned into the model with the placement).

ts
starterTypes(ctx: ScriptContext, words?: string): readonly StarterType[]

Topics: starter library, part types, built-in parts, catalogue, panelboard, receptacle type

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: { levels: true },
  parameters: {},
  run(ctx) {
    const panel = parts.starterTypes(ctx, "panelboard")[0];
    if (!panel) throw new Error("No starter panelboard");
    equipment.place(ctx, { level: "L1", type: panel.id, at: { x: units.ft(1), y: units.ft(1) }, mark: "LP-1" });
  },
});

parts.refreshBuiltins ​

Upgrades stale built-in part types already pinned in an existing model to the latest library symbols (mode: "symbols", default) or full definitions (mode: "full") as one atomic edit, leaving placed parts and custom types untouched.

ts
refreshBuiltins(ctx: ScriptContext, opts?: { typeIds?: readonly string[]; mode?: "symbols" | "full" }): readonly { typeId: string; familyName: string; typeName: string }[]

Topics: refresh symbols, upgrade part types, built-in symbols, annotative symbols, stale symbols, refreshBuiltins

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: { levels: true },
  parameters: {},
  run(ctx) {
    const updated = parts.refreshBuiltins(ctx);
    ctx.report("refreshed", updated.length);
  },
});

Apache License 2.0. The reference is generated from the code on every change.