Skip to content

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 as report in 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.

ts
readonly model: SliceReader

Topics: read, model, levels, selection, find

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 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.

ts
id(prefix?: string): string

Topics: id, deterministic, name

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) {
    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.

ts
random(): number

Topics: random, deterministic

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 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.

ts
edit(command: EditCommand): void

Topics: edit, command, change the model, any command

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) {
    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").

ts
label(text: string): void

Topics: label, approve card, describe

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) {
    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.

ts
report(label: string, value: unknown): void

Topics: report, see values, debug, print, inspect, what is in the model, level ids, return data

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 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.

ts
parts: { define(typeId: string, definition: PartTypeDefinition): void }

Topics: part, custom part, family, part type, equipment type

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());
  },
});

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.

ts
calcs(): readonly { id: string; title: string; domain: string; summary: string; readsModel: boolean }[]

Topics: calculation, calcs, list calculations, engineering calc, code calc

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 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.

ts
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
ts
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.

ts
editSteps(command: unknown): void

Topics: apply a plan, send the plan, batch, rebalance, room template

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) {
    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).

ts
reads(): readonly { id: string; label: string }[]

Topics: what can I read, reads, add-on reads, catalogue, panel loads

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 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.

ts
read<T = unknown>(id: string, input?: unknown): T

Topics: duct size, suggest duct size, panel loads, phase totals, read, computed, catalogue, feeder size

Example script
ts
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.

ts
proposers(): readonly { id: string; label: string; hosts: string }[]

Topics: proposers, what can propose, code spacing

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) {
    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.

ts
propose(proposerId: string, request: ProposerRequest): ProposerAnswer

Topics: receptacles, receptacle spacing, outlets, nec 210.52, propose devices, code spacing, cleanouts

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) {
    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.

ts
acceptGhosts(ghosts: readonly GhostPlacement[], label: string): void

Topics: accept, place proposed, keep some, receptacles

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) {
    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");
  },
});

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