Skip to content

Example scripts ​

Whole scripts that each build something complete. Copy the closest one and change it.

Small office ​

Two floors of a 40 x 30 ft office: exterior and interior walls, doors and windows, rooms found from the walls (open office, conference, office), and a plan of each floor on its own sheet.

Run it: npm run example -- small-office, or paste it to an assistant connected to the tool server. Source: packages/bim-script/examples/small-office.ts.

ts
/**
 * Small office: two floors of a 40 ft x 30 ft office.
 *
 * Each floor gets exterior walls, interior walls that split it into an open
 * office, a conference room and a private office, doors and windows, and
 * rooms found from the walls around them (nobody draws a room outline), and
 * a ceiling in each room. Then each floor gets a plan on its own sheet.
 *
 * Level arguments are level ids: building.level returns the id every call
 * below passes as `level`. On a model that already has levels, read them
 * (reads.levels: true) and pass an id from ctx.model.levels(); the kit's
 * helpers also take the name of exactly one level ("Level 2").
 *
 * Run it: paste it to an assistant connected to the MutinyBIM tool server
 * ("run this script"), or `npm run example -- small-office`.
 */
import { defineScript, units, building, documents } from "@permitzip/bim-script";

const ft = units.ft;
const at = (x: number, y: number) => ({ x: ft(x), y: ft(y) });

export default defineScript({
  kind: "layout",
  reads: { levels: true },
  parameters: {},
  run(ctx) {
    ctx.label("Small office: two floors with walls, rooms, ceilings, doors and windows, and a plan sheet per floor");
    const made: { level: string; id: string; rooms: string[] }[] = [];

    const floors = [
      { name: "Level 1", elevation: ft(0), sheet: "A-101" },
      { name: "Level 2", elevation: ft(12), sheet: "A-102" },
    ];

    for (const floor of floors) {
      const level = building.level(ctx, { name: floor.name, elevation: floor.elevation });

      // The outside: four walls, 8 in thick, closed back to the first corner.
      // Wall 1 runs along the south side, wall 3 along the north.
      const outside = building.walls(ctx, { level, points: [at(0, 0), at(40, 0), at(40, 30), at(0, 30)], closed: true, thickness: units.in(8), height: ft(11) });

      // Inside: one wall north to south at 24 ft, and one east of it at 15 ft.
      const split = building.walls(ctx, { level, points: [at(24, 0), at(24, 30)], thickness: units.in(5), height: ft(11) });
      const office = building.walls(ctx, { level, points: [at(24, 15), at(40, 15)], thickness: units.in(5), height: ft(11) });

      // Doors are placed along a wall, from its start. The entry is on the ground floor only.
      if (floor.name === "Level 1") building.door(ctx, { wall: outside.element(1), along: ft(10), width: units.in(36), mark: "101A" });
      building.door(ctx, { wall: split.element(1), along: ft(22), width: units.in(36) });
      building.door(ctx, { wall: office.element(1), along: ft(4), width: units.in(36) });

      // Windows on the north wall (it runs east to west, so 6 ft along it is near the east end).
      for (const along of [6, 18, 30]) building.window(ctx, { wall: outside.element(3), along: ft(along), width: ft(4), height: ft(5) });

      // Rooms from the walls: one point inside each, the kernel traces the enclosure.
      const n = floor.name === "Level 1" ? 100 : 200;
      const open = building.spaceInWalls(ctx, { level, inside: at(10, 15), number: `${n + 1}`, name: "Open office" });
      const conference = building.spaceInWalls(ctx, { level, inside: at(32, 7), number: `${n + 2}`, name: "Conference" });
      const privateOffice = building.spaceInWalls(ctx, { level, inside: at(32, 22), number: `${n + 3}`, name: "Office" });

      // A 9 ft ceiling in each room, its outline 1 ft inside the walls (units.* values, no millimetres by hand).
      const inset = (x0: number, y0: number, x1: number, y1: number) => [at(x0 + 1, y0 + 1), at(x1 - 1, y0 + 1), at(x1 - 1, y1 - 1), at(x0 + 1, y1 - 1)];
      building.ceiling(ctx, { level, space: open, outline: inset(0, 0, 24, 30), height: ft(9) });
      building.ceiling(ctx, { level, space: conference, outline: inset(24, 0, 40, 15), height: ft(9) });
      building.ceiling(ctx, { level, space: privateOffice, outline: inset(24, 15, 40, 30), height: ft(9) });
      made.push({ level: floor.name, id: level, rooms: [open, conference, privateOffice] });

      // A plan of this floor on its own sheet, 1/4" = 1'-0".
      const sheet = documents.sheet(ctx, { number: floor.sheet, name: `${floor.name} floor plan` });
      const plan = documents.planView(ctx, { level, name: `${floor.name} - Plan`, scale: 48 });
      documents.place(ctx, sheet, plan, { x: units.mm(300), y: units.mm(280) });
    }

    // What the script made, for the agent: it comes back as `report` beside the preview.
    ctx.report("Levels and rooms", made);
  },
});

Rooftop unit ​

A 10 ton rooftop unit built as a part type, placed on the roof, its supply and return ducts sized from airflow and routed down into two rooms, every duct tagged, and an equipment schedule on a sheet.

Run it: npm run example -- rooftop-unit, or paste it to an assistant connected to the tool server. Source: packages/bim-script/examples/rooftop-unit.ts.

ts
/**
 * Rooftop unit: a 10 ton unit on the roof, ducted down into two rooms.
 *
 * The script sizes the supply and return ducts with the duct sizing read
 * (the system's friction and velocity limits), builds the unit's part type
 * with connectors of that size, places it on the roof, and routes its
 * supply and return down into the rooms. Then it tags the ducts on a plan
 * and puts an equipment schedule on a sheet.
 *
 * Run it: paste it to an assistant connected to the MutinyBIM tool server
 * ("run this script"), or `npm run example -- rooftop-unit`.
 */
import { defineScript, units, routes, parts, building, equipment, documents } from "@permitzip/bim-script";

const ft = units.ft;
const at = (x: number, y: number) => ({ x: ft(x), y: ft(y) });

/** 10 tons at 400 CFM per ton. */
const SUPPLY_CFM = 4000;

export default defineScript({
  kind: "route",
  reads: { levels: true },
  parameters: {},
  run(ctx) {
    // The building: one floor, 60 ft x 30 ft, two rooms side by side, a 10 ft ceiling.
    const level = building.level(ctx, { name: "Level 1", elevation: ft(0) });
    building.walls(ctx, { level, points: [at(0, 0), at(60, 0), at(60, 30), at(0, 30)], closed: true, thickness: units.in(8), height: ft(14) });
    building.walls(ctx, { level, points: [at(30, 0), at(30, 30)], thickness: units.in(5), height: ft(14) });
    building.spaceInWalls(ctx, { level, inside: at(15, 15), number: "101", name: "Classroom" });
    building.spaceInWalls(ctx, { level, inside: at(45, 15), number: "102", name: "Classroom" });

    // Size the main ducts first: 12 in deep to fit above the ceiling. Sizes come back in mm.
    const advice = ctx.read<{ suggested: { size: { width: number; height: number }; velocityFpm: number } }>("mechanical.duct_size", { cfm: SUPPLY_CFM, shape: "rect", height_mm: 305, system_kind: "supply_air" });
    const { width, height } = advice.suggested.size;
    const duct = routes.rect(units.mm(width), units.mm(height));

    // The unit's part type: a box with supply and return openings on its underside, sized like the ducts.
    // A route or layout script saves a new type as an edit (save_part_types). It never calls
    // ctx.parts.define (only a part script does); to use a type the model or library already has,
    // list its id in reads.partTypes and place it with equipment.place.
    const rtu = parts.part("Rooftop unit", { type: "10 ton", category: "mechanical_equipment" });
    rtu.box({ length: units.in(120), width: units.in(60), height: units.in(48) });
    for (const [id, label, systemKind, x] of [["supply", "Supply", "supply_air", -30], ["return", "Return", "return_air", 30]] as const) {
      rtu.connector("bottom", { id, label, domain: "duct", systemKind, shape: "rect", width: units.mm(width), height: units.mm(height), offset: [units.in(x), units.in(0)] });
    }
    ctx.edit({ type: "save_part_types", label: "Rooftop unit, 10 ton", types: [{ typeId: "example.rtu.10t", definition: rtu.build() }] });

    // On the roof: its base 14 ft above the floor, over the middle wall.
    const unit = equipment.place(ctx, { level, type: "example.rtu.10t", at: at(30, 15), height: ft(14), mark: "RTU-1" });

    // Supply down into room 101, return down into room 102, both at 11 ft (above the 10 ft ceiling).
    routes.along(ctx, { level, domain: "duct", size: duct, system: { id: "sa-1", kind: "supply_air", name: "Supply air" }, height: ft(11), from: unit.connector("supply"), points: [at(15, 15), at(8, 15)] });
    routes.along(ctx, { level, domain: "duct", size: duct, system: { id: "ra-1", kind: "return_air", name: "Return air" }, height: ft(11), from: unit.connector("return"), points: [at(45, 15), at(52, 15)] });

    // A mechanical plan cut above the ducts, every duct tagged with its size.
    const plan = documents.planView(ctx, { level, name: "Level 1 - Mechanical", scale: 48, cutHeight: ft(12), discipline: "mechanical" });
    documents.autoTag(ctx, { view: plan, categories: ["duct", "equipment"] });

    // The plan and an equipment schedule on sheets.
    const planSheet = documents.sheet(ctx, { number: "M-101", name: "Level 1 mechanical plan" });
    documents.place(ctx, planSheet, plan, { x: units.mm(300), y: units.mm(280) });
    const schedule = documents.schedule(ctx, { name: "Mechanical equipment schedule", category: "mechanical_equipment", columns: ["mark", "type_name", "level"] });
    const scheduleSheet = documents.sheet(ctx, { number: "M-601", name: "Mechanical schedules" });
    documents.place(ctx, scheduleSheet, schedule, { x: units.mm(200), y: units.mm(400) });

    ctx.label(`RTU-1 (${SUPPLY_CFM} CFM) with ${Math.round(width / 25.4)}x${Math.round(height / 25.4)} supply and return ducts at ${Math.round(advice.suggested.velocityFpm)} fpm`);
  },
});

Plumbing riser ​

Toilet rooms on two floors with their fixture units counted, branches, a stack and a building drain sized by the plumbing code and sloped 1/4 in per ft, the fixtures connected, water demand from the Hunter curve, and the drain tagged with size and slope.

Run it: npm run example -- plumbing-riser, or paste it to an assistant connected to the tool server. Source: packages/bim-script/examples/plumbing-riser.ts.

ts
/**
 * Plumbing riser: toilet rooms on two floors, drained by a stack into a
 * sloped building drain, every pipe sized by the plumbing code.
 *
 * The script counts drainage fixture units (DFU) and water supply fixture
 * units (WSFU) for the fixtures it places, sizes the floor branches, the
 * stack and the building drain with the code's drain sizing calc (2021
 * plumbing code tables), and the water demand with the Hunter curve. Then it
 * routes the piping with its fall, connects the fixtures, and tags the drain
 * and branches with their size and slope.
 *
 * Run it: paste it to an assistant connected to the MutinyBIM tool server
 * ("run this script"), or `npm run example -- plumbing-riser`.
 */
import { defineScript, units, routes, building, equipment, documents } from "@permitzip/bim-script";

const ft = units.ft;
const at = (x: number, y: number) => ({ x: ft(x), y: ft(y) });

/** Fixture units per fixture, public use (plumbing code drainage and supply fixture unit tables). */
const FIXTURES = [
  { type: "builtin:plumbing-wc-flush-tank@1", mark: "WC", x: 4, dfu: 4, wsfu: 5 },
  { type: "builtin:plumbing-wc-flush-tank@1", mark: "WC", x: 8, dfu: 4, wsfu: 5 },
  { type: "builtin:plumbing-lavatory@1", mark: "L", x: 12, dfu: 1, wsfu: 2 },
  { type: "builtin:plumbing-lavatory@1", mark: "L", x: 15, dfu: 1, wsfu: 2 },
];
/** 1/4 in per ft: the code minimum for drains 3 in and smaller, and the slope the sizing table is read at. */
const SLOPE = { rise: units.in(0.25), per: ft(1) };

export default defineScript({
  kind: "route",
  reads: { levels: true },
  parameters: {},
  run(ctx) {
    /** Size one drain by the code (3 in. at least where a water closet drains to it); the answer is nominal inches. */
    const drainSize = (role: "building_drain" | "horizontal_branch" | "stack", dfu: number): number => {
      const result = ctx.calc({ calc: "plumbing.size_drain", inputs: { role, dfu, slope_in_per_ft: 0.25, serves_water_closet: true }, plumbingEdition: "2021" });
      if (!result.ok) throw new Error(result.reason);
      return Number(result.run.values.find((v) => v.key === "size_nominal_in")?.value);
    };

    const floorDfu = FIXTURES.reduce((sum, f) => sum + f.dfu, 0);
    const floorWsfu = FIXTURES.reduce((sum, f) => sum + f.wsfu, 0);
    const floors = [building.level(ctx, { name: "Level 1", elevation: ft(0) }), building.level(ctx, { name: "Level 2", elevation: ft(12) })];
    const sanitary = { id: "san-1", kind: "sanitary", name: "Sanitary" } as const;
    const branchIn = drainSize("horizontal_branch", floorDfu);
    const stackIn = drainSize("stack", floorDfu);
    const drainIn = drainSize("building_drain", floorDfu * floors.length);

    const [ground, upper] = floors;
    if (!ground || !upper) throw new Error("Two floors expected.");
    const pipe = (inches: number) => routes.pipe(units.in(inches), "pvc");
    const lastPiece = (route: { segment(n: number): string }) => {
      // The kernel numbers a route's pieces s1, s2, … from its start.
      let n = 1;
      while (ctx.model.find(route.segment(n + 1))) n += 1;
      return route.segment(n);
    };

    // Fixtures in the same spot on each floor: two water closets and two lavatories along one wall.
    const fixturesOn = (level: string, floor: number) => FIXTURES.map((f) => equipment.place(ctx, { level, type: f.type, at: at(f.x, 4), mark: `${f.mark}-${floor}` }));

    // Level 2: a branch under the floor, falling west to the stack at x = 1 ft.
    const branch = routes.along(ctx, { level: upper, domain: "pipe", size: pipe(branchIn), system: sanitary, height: ft(-1), slope: SLOPE, flow: "with_points", points: [at(17, 2), at(2, 2)] });
    routes.connectInto(ctx, { from: fixturesOn(upper, 2).map((p) => ({ elementId: p.id, port: "w" })), into: branch.segment(1) });

    // The stack: drawn on Level 1, where it ends. It leaves the branch end straight (1 ft on), then drops
    // to 18 in under the Level 1 floor. The first point takes the branch end's height, after its fall.
    const stack = routes.along(ctx, { level: ground, domain: "pipe", size: pipe(stackIn), system: sanitary, from: routes.atRunEnd(branch.segment(1), "end"), points: [at(1, 2), { ...at(1, 2), height: ft(-1.5) }] });

    // The building drain: from the stack's foot (an elbow turns it), east 2.5 ft under the Level 1 floor to the street, falling 1/4 in per foot.
    const drain = routes.along(ctx, { level: ground, domain: "pipe", size: pipe(drainIn), system: sanitary, from: routes.atRunEnd(lastPiece(stack), "end"), height: ft(-2.5), slope: SLOPE, flow: "with_points", points: [at(2, 2), at(60, 2)] });

    // Level 1's fixtures drain straight into the building drain under them.
    routes.connectInto(ctx, { from: fixturesOn(ground, 1).map((p) => ({ elementId: p.id, port: "w" })), into: lastPiece(drain) });

    // Water demand for every fixture, from the Hunter curve.
    const demand = ctx.calc({ calc: "plumbing.hunter_demand", inputs: { wsfu: floorWsfu * floors.length, building_type: "office" } });
    const gpm = demand.ok ? Number(demand.run.values.find((v) => v.key === "design_gpm")?.value) : null;

    // A plumbing plan of Level 1, the building drain tagged with its size, slope and fixture units.
    const plan = documents.planView(ctx, { level: ground, name: "Level 1 - Plumbing", scale: 48, discipline: "plumbing" });
    documents.tag(ctx, { view: plan, element: lastPiece(drain), at: at(40, -3), fields: ["pipe.size", "pipe.slope", "pipe.carries.dfu"] });
    const sheet = documents.sheet(ctx, { number: "P-101", name: "Level 1 plumbing plan" });
    documents.place(ctx, sheet, plan, { x: units.mm(300), y: units.mm(280) });

    ctx.label(`Riser: ${floorDfu * floors.length} DFU, ${branchIn} in branches, ${stackIn} in stack, ${drainIn} in building drain at 1/4 in per ft${gpm ? `, ${Math.round(gpm)} gpm water demand` : ""}`);
  },
});

Electrical room ​

A one-bedroom unit: walls and rooms, a panel, receptacles placed by NEC 210.52 wall spacing, one circuit per room from a room template, and the panel schedule on a sheet with the code's demand factors.

Run it: npm run example -- electrical-room, or paste it to an assistant connected to the tool server. Source: packages/bim-script/examples/electrical-room.ts.

ts
/**
 * Electrical room: a one-bedroom unit's receptacles, circuits and panel
 * schedule.
 *
 * The script draws the unit's walls and rooms, places a panel, lets the
 * Electrical add-on propose receptacles by the code's wall spacing (NEC
 * 210.52: no point along a wall more than 6 ft from a receptacle), places
 * them, circuits them with a room template (one circuit per room), and puts
 * the panel's schedule on a sheet. The schedule prints the panel's loads
 * with the code's demand factors.
 *
 * Run it: paste it to an assistant connected to the MutinyBIM tool server
 * ("run this script"), or `npm run example -- electrical-room`.
 */
import { defineScript, units, building, equipment, documents } from "@permitzip/bim-script";

const ft = units.ft;
const at = (x: number, y: number) => ({ x: ft(x), y: ft(y) });
const box = (x0: number, x1: number) => [at(x0, 0), at(x1, 0), at(x1, 14), at(x0, 14)];
const NEC = "2023";

export default defineScript({
  kind: "layout",
  reads: { levels: true },
  parameters: {},
  run(ctx) {
    const level = building.level(ctx, { name: "Level 1", elevation: ft(0) });

    // A 32 ft x 14 ft unit: a bedroom and a living room, split by a wall at 14 ft.
    building.walls(ctx, { level, points: box(0, 32), closed: true, thickness: units.in(6), height: ft(9) });
    building.walls(ctx, { level, points: [at(14, 0), at(14, 14)], thickness: units.in(4), height: ft(9) });
    const bedroom = building.room(ctx, { level, number: "101", name: "Bedroom", outline: box(0, 14) });
    const living = building.room(ctx, { level, number: "102", name: "Living room", outline: box(14, 32) });

    // The unit's panel, on the bedroom wall.
    const panel = equipment.place(ctx, { level, type: "builtin:panelboard-125-208-1ph@1", at: at(1, 13), mark: "LP-1" });

    // Receptacles by code spacing: the add-on proposes them, with the clause for each; the script keeps them all.
    const proposal = ctx.propose("electrical.receptacles", { typeId: "builtin:duplex-receptacle@1", roomIds: [bedroom, living], options: { mode: "dwelling", edition: NEC } });
    ctx.acceptGhosts(proposal.ghosts, proposal.summary);

    // One circuit per room, from a room template the script saves into the model.
    ctx.edit({ type: "save_catalog_entry", entry: { type: "circuit_template", name: "One-bedroom unit", description: "Each room's receptacles on their own circuit", rules: [{ room: "bedroom", devices: "receptacles" }, { room: "living", devices: "receptacles" }] } });
    const circuits = ctx.read<{ command: unknown; message: string }>("electrical.circuit_template_plan", { template: "One-bedroom unit", units: [{ panel: "LP-1", rooms: ["101", "102"] }] });
    ctx.editSteps(circuits.command);

    // The panel's loads with the code's demand factors, and its schedule on a sheet printed by the same rules.
    const loads = ctx.read<{ connectedVa: number; demand: { demandVa: number }; rules: { id: string } }>("electrical.loads", { panel: "LP-1", nec_edition: NEC });
    const schedule = documents.formSchedule(ctx, { kind: "panel", name: "Panel LP-1 schedule", element: panel.id, rules: loads.rules.id });
    const sheet = documents.sheet(ctx, { number: "E-601", name: "Panel schedules" });
    documents.place(ctx, sheet, schedule, { x: units.mm(250), y: units.mm(350) });

    // A power plan of the unit on its own sheet.
    const plan = documents.planView(ctx, { level, name: "Level 1 - Power", scale: 48, discipline: "electrical" });
    const planSheet = documents.sheet(ctx, { number: "E-101", name: "Level 1 power plan" });
    documents.place(ctx, planSheet, plan, { x: units.mm(300), y: units.mm(280) });

    ctx.label(`${proposal.ghosts.length} receptacles (${proposal.passes ? "meets" : "short of"} NEC 210.52), ${circuits.message.toLowerCase()} LP-1 ${Math.round(loads.connectedVa)} VA connected`);
  },
});

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