ctx: the script context
What a script's run(ctx) gets: reading the model slice it declared, sending edits, running calcs and reads, proposals, labels and reports.
Every example below is a complete script that passes the kit's checks; the kit's tests run each one.
ctx.model: The model as far as the script's reads go: get(id), levels, elements of a kind, the selection.ctx.id: A new id, the same on every run with the same script, values and model revision.ctx.random: Seeded randomness in [0, 1): use it, never Math.random, so every run gives the same result.ctx.edit: One kernel command, applied at once to the script's working copy (later steps see it).ctx.label: What the edits do, in words, for the Approve card ("Receptacles every 12 ft, Level 2").ctx.report: Shows a value the script read or worked out to the agent: it comes back asreportin bim_run_script's answer, beside the preview.ctx.parts.define: Part scripts only (kind: "part"): one part type (one size of the part) saved under its type id.ctx.calcs: The engineering calculations a script can run: code calcs (NEC, plumbing, fuel gas), duct friction and system pressure, pipe system reports, service size, beams.ctx.calc: Runs one calculation on the model as the script has it so far, and returns its values (each with key, value, unit and citations) or the reason it can't.ctx.editSteps: Sends a plan's edit as an add-on read or proposer returned it (one edit, or a batch such as a room template's circuits or a rebalance's moves), step by step.ctx.reads: The computed reads the model's add-ons offer, by id: panel loads (electrical.loads), the electrical check, rebalance and room-template plans, a feeder size, the electrical and plumbing catalogues, duct size advice (mechanical.duct_size).ctx.read: Runs one add-on read on the model as the script has it so far and returns its answer (plain data; type it with read<T>).ctx.proposers: The proposers the model's add-ons offer: devices placed by a code's spacing or coverage (electrical.receptacles, plumbing.cleanouts…), each with what it places on.ctx.propose: Runs a proposer on rooms: ghost placements, each with the requirement it meets and the code clause, and a summary that says whether the rooms pass.ctx.acceptGhosts: Places the ghosts kept (all, or a filtered list) as one edit on their level, each type pinned from the starter library when the model lacks it.
ctx.model
The model as far as the script's reads go: get(id), levels, elements of a kind, the selection. Edits the script made are visible to later reads.
readonly model: SliceReaderTopics: read, model, levels, selection, find
Example script
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 levels = ctx.model.levels();
const top = levels[levels.length - 1];
if (!top) throw new Error("The model has no levels.");
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: Number(top.elevationMm) + 4000 });
},
});ctx.id
A new id, the same on every run with the same script, values and model revision.
id(prefix?: string): stringTopics: id, deterministic, name
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Mezzanine", elevationMm: 2500 });
},
});ctx.random
Seeded randomness in [0, 1): use it, never Math.random, so every run gives the same result.
random(): numberTopics: random, deterministic
Example script
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 jitter = Math.round(ctx.random() * 100);
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Test", elevationMm: 3000 + jitter });
},
});ctx.edit
One kernel command, applied at once to the script's working copy (later steps see it). Every command a person or the agent can send is accepted; bim_script_reference({ command }) shows a command's fields.
edit(command: EditCommand): voidTopics: edit, command, change the model, any command
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
ctx.edit({ type: "create_level", levelId: "L9", name: "Level 9", elevationMm: 32000 });
},
});ctx.label
What the edits do, in words, for the Approve card ("Receptacles every 12 ft, Level 2").
label(text: string): voidTopics: label, approve card, describe
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
ctx.label("Roof level at 30 ft");
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9144 });
},
});ctx.report
Shows a value the script read or worked out to the agent: it comes back as report in bim_run_script's answer, beside the preview. Plain data only (numbers, text, lists, objects); at most 50 reports and 16 KB a run. A script that only reports and makes no edits still runs (nothing to apply), and a run that stops says what it reported so far. Use it instead of throwing an error to see a value.
report(label: string, value: unknown): voidTopics: report, see values, debug, print, inspect, what is in the model, level ids, return data
Example script
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 levels = ctx.model.levels().map((l) => ({ id: l.id, name: l.name, elevationMm: l.elevationMm }));
ctx.report("Levels (use the id as a level argument)", levels);
},
});ctx.parts.define
Part scripts only (kind: "part"): one part type (one size of the part) saved under its type id. A layout or route script never defines part types: it lists the ids of the types it uses in reads.partTypes ("acme.rtu.*" patterns work) and places them with equipment.place.
parts: { define(typeId: string, definition: PartTypeDefinition): void }Topics: part, custom part, family, part type, equipment type
Example script
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());
},
});ctx.calcs
The engineering calculations a script can run: code calcs (NEC, plumbing, fuel gas), duct friction and system pressure, pipe system reports, service size, beams. Each has an id, a title and whether it reads the model.
calcs(): readonly { id: string; title: string; domain: string; summary: string; readsModel: boolean }[]Topics: calculation, calcs, list calculations, engineering calc, code calc
Example script
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 duct = ctx.calcs().find((c) => c.id === "mech.duct_friction");
if (!duct) throw new Error("No duct friction calc here.");
ctx.label(duct.title);
building.level(ctx, { name: "Roof", elevation: units.ft(30) });
},
});ctx.calc
Runs one calculation on the model as the script has it so far, and returns its values (each with key, value, unit and citations) or the reason it can't. Use the answer to decide edits: a pipe size, a slope, a breaker. Name the code edition (necEdition, plumbingEdition, fuelGasEdition); the host's adopted codes are not read from a script.
calc(request: { calc: string; inputs: unknown; necEdition?: "2020" | "2023"; plumbingEdition?: string; fuelGasEdition?: string; editions?: Record<string, string>; jurisdiction?: string; state?: string }): { ok: true; run: CalcRun } | { ok: false; reason: string }Topics: calculation, size a drain, pipe size, duct size, voltage drop, service size, pressure, calc
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "route",
reads: { levels: true },
parameters: {},
run(ctx) {
const drain = ctx.calc({ calc: "plumbing.size_drain", inputs: { role: "building_drain", dfu: 88, slope_in_per_ft: 0.125, serves_water_closet: true }, plumbingEdition: "2021" });
if (!drain.ok) throw new Error(drain.reason);
const size = Number(drain.run.values.find((v) => v.key === "size_in")?.value);
ctx.label(`Building drain, ${size} in at 1/8 in per ft`);
routes.along(ctx, { level: "L1", domain: "pipe", size: routes.pipe(units.in(size), "pvc"), system: { id: "san-1", kind: "sanitary" }, height: units.ft(1), slope: { rise: units.in(0.125), per: units.ft(1) }, flow: "with_points", points: [{ x: units.ft(0), y: units.ft(5) }, { x: units.ft(40), y: units.ft(5) }] });
},
});ctx.editSteps
Sends a plan's edit as an add-on read or proposer returned it (one edit, or a batch such as a room template's circuits or a rebalance's moves), step by step. One approval still covers them.
editSteps(command: unknown): voidTopics: apply a plan, send the plan, batch, rebalance, room template
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }], closed: true, thickness: units.in(6), height: units.ft(9) });
building.walls(ctx, { level: "L1", points: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }], thickness: units.in(4), height: units.ft(9) });
const bedroom = building.room(ctx, { level: "L1", number: "101", name: "Bedroom", outline: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }] });
const living = building.room(ctx, { level: "L1", number: "102", name: "Living room", outline: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(14), y: units.ft(14) }] });
equipment.place(ctx, { level: "L1", type: "builtin:panelboard-125-208-1ph@1", at: { x: units.ft(1), y: units.ft(13) }, mark: "LP-1" });
const proposal = ctx.propose("electrical.receptacles", { typeId: "builtin:duplex-receptacle@1", roomIds: [bedroom, living], options: { mode: "dwelling", edition: "2023" } });
ctx.acceptGhosts(proposal.ghosts, proposal.summary);
ctx.edit({ type: "save_catalog_entry", entry: { type: "circuit_template", name: "Dwelling unit", description: "Bedroom and living room receptacles", rules: [{ room: "bedroom", devices: "receptacles" }, { room: "living", devices: "receptacles" }] } });
const circuits = ctx.read<{ command: unknown; message: string }>("electrical.circuit_template_plan", { template: "Dwelling unit", units: [{ panel: "LP-1", rooms: ["101", "102"] }] });
ctx.editSteps(circuits.command);
},
});ctx.reads
The computed reads the model's add-ons offer, by id: panel loads (electrical.loads), the electrical check, rebalance and room-template plans, a feeder size, the electrical and plumbing catalogues, duct size advice (mechanical.duct_size).
reads(): readonly { id: string; label: string }[]Topics: what can I read, reads, add-on reads, catalogue, panel loads
Example script
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 ids = ctx.reads().map((r) => r.id);
ctx.label(`Reads here: ${ids.length}`);
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
},
});ctx.read
Runs one add-on read on the model as the script has it so far and returns its answer (plain data; type it with read<T>). A plan's command is sent with ctx.editSteps when the script keeps it. A refusal fails the run with the add-on's words.
read<T = unknown>(id: string, input?: unknown): TTopics: duct size, suggest duct size, panel loads, phase totals, read, computed, catalogue, feeder size
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "route",
reads: { levels: true },
parameters: {},
run(ctx) {
const advice = ctx.read<{ suggested: { size: { width: number; height: number } } }>("mechanical.duct_size", { cfm: 1200, shape: "rect", height_mm: 305 });
const { width, height } = advice.suggested.size;
ctx.label(`Supply main ${Math.round(width / 25.4)}x${Math.round(height / 25.4)} for 1200 CFM`);
routes.along(ctx, { level: "L1", domain: "duct", size: routes.rect(units.mm(width), units.mm(height)), system: { id: "sa-1", kind: "supply_air" }, height: units.ft(9), points: [{ x: units.ft(0), y: units.ft(10) }, { x: units.ft(30), y: units.ft(10) }] });
},
});ctx.proposers
The proposers the model's add-ons offer: devices placed by a code's spacing or coverage (electrical.receptacles, plumbing.cleanouts…), each with what it places on.
proposers(): readonly { id: string; label: string; hosts: string }[]Topics: proposers, what can propose, code spacing
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
ctx.label(ctx.proposers().map((p) => p.label).join(", "));
ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
},
});ctx.propose
Runs a proposer on rooms: ghost placements, each with the requirement it meets and the code clause, and a summary that says whether the rooms pass. Nothing is placed until ctx.acceptGhosts.
propose(proposerId: string, request: ProposerRequest): ProposerAnswerTopics: receptacles, receptacle spacing, outlets, nec 210.52, propose devices, code spacing, cleanouts
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }], closed: true, thickness: units.in(6), height: units.ft(9) });
building.walls(ctx, { level: "L1", points: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }], thickness: units.in(4), height: units.ft(9) });
const bedroom = building.room(ctx, { level: "L1", number: "101", name: "Bedroom", outline: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }] });
const living = building.room(ctx, { level: "L1", number: "102", name: "Living room", outline: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(14), y: units.ft(14) }] });
const proposal = ctx.propose("electrical.receptacles", { typeId: "builtin:duplex-receptacle@1", roomIds: [bedroom, living], options: { mode: "dwelling", edition: "2023" } });
ctx.acceptGhosts(proposal.ghosts, proposal.summary);
},
});ctx.acceptGhosts
Places the ghosts kept (all, or a filtered list) as one edit on their level, each type pinned from the starter library when the model lacks it. Nothing is circuited or connected.
acceptGhosts(ghosts: readonly GhostPlacement[], label: string): voidTopics: accept, place proposed, keep some, receptacles
Example script
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
kind: "layout",
reads: { levels: true },
parameters: {},
run(ctx) {
building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }], closed: true, thickness: units.in(6), height: units.ft(9) });
building.walls(ctx, { level: "L1", points: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }], thickness: units.in(4), height: units.ft(9) });
const bedroom = building.room(ctx, { level: "L1", number: "101", name: "Bedroom", outline: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(14), y: units.ft(0) }, { x: units.ft(14), y: units.ft(14) }, { x: units.ft(0), y: units.ft(14) }] });
const living = building.room(ctx, { level: "L1", number: "102", name: "Living room", outline: [{ x: units.ft(14), y: units.ft(0) }, { x: units.ft(32), y: units.ft(0) }, { x: units.ft(32), y: units.ft(14) }, { x: units.ft(14), y: units.ft(14) }] });
const proposal = ctx.propose("electrical.receptacles", { typeId: "builtin:duplex-receptacle@1", roomIds: [bedroom, living], options: { mode: "dwelling", edition: "2023" } });
ctx.acceptGhosts(proposal.ghosts.filter((g) => g.roomId === bedroom), "Bedroom receptacles");
},
});