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.
/**
* 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.
/**
* 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.
/**
* 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.
/**
* 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`);
},
});