Skip to content

documents ​

Views, sheets, schedules, tags, notes, dimensions and the rest of a drawing set.

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

  • documents.sheet: A new sheet (number, name, title block); returns its id.
  • documents.setSheet: Changes a sheet's number, name, title block or fields.
  • documents.planView: A floor plan of one level (for a discipline, scale, detailLevel, symbolScale, showLineCodes, and per-category/service overrides including singleLineBelow); returns the view's id.
  • documents.setView: Changes a view's detail level (coarse/medium/fine), visual style, annotative symbolScale (0.5–3.0), inline service codes, scale, discipline, or per-category/service graphics overrides (including singleLineBelow).
  • documents.ceilingView: A reflected ceiling plan of one level; returns the view's id.
  • documents.sectionView: A vertical building section cut from from to to (direction +1 left / -1 right, depth default 20 ft); supports annotative headExt/tailExt, Revit splitGap break, explicit crop, and levelLeftExtMm/levelRightExtMm datum extensions.
  • documents.elevationView: An interior or exterior elevation looking from from..to (direction +1 left / -1 right, depth default 20 ft); its live elevation marker (circle + pointer arrow with auto-updating detail#/sheet# head) prints automatically on overlapping plans.
  • documents.enlargedPlan: A Revit-style enlarged plan in one step: creates a cropped plan view on the same level at enlarged scale (default 1/4" or 1/2" = 1'-0") AND places a live parametric callout bubble on the parent plan whose detail#/sheet# head auto-updates when the enlarged plan moves sheets.
  • documents.callout: Places a live parametric callout box + split head bubble on a view referencing any existing enlarged plan, 2D detail, section, or elevation view.
  • documents.setCrop: Sets a view's crop box in typed units, toggles cropView/showCropBox, or adjusts section/elevation far clip depth, level datum extensions (levelLeftExtMm/levelRightExtMm), and section mark headExt/tailExt/splitGap.
  • documents.duplicateView: A copy of a view (another discipline's plan of the same level); returns the new id.
  • documents.place: Puts a view (a plan, a schedule, a detail) on a sheet at a point (its centre, from the sheet's lower-left corner), with optional scale and viewport title offset/rule length; returns the viewport's id.
  • documents.setViewportTitle: Moves a placed viewport's title block on its sheet (offset) and/or changes the horizontal title underline length (ruleLength, or null to reset).
  • documents.editSchedule: Edits a list schedule view in one undo step: add, move, remove or rename columns, filter, sort, group, totals (an equipment schedule's sort, a fixture schedule's DFU total).
  • documents.schedule: A schedule view; returns its id.
  • documents.tag: A tag on one element in a plan view (its mark, size or the right text for its kind), with a leader; returns the tag's id.
  • documents.moveTag: Moves an existing tag in a plan view to a clear position (and optionally toggles its leader).
  • documents.planLabels: Returns every rendered text label on a plan view (paper mm coordinates and bounding boxes) plus any overlapping pairs, so scripts can verify legibility and move colliding tags.
  • documents.dimension: A dimension between two points in a view, tied to elements with refs so it follows them; returns its id.
  • documents.tagStyle: A new tag style: field lines, box, orientation, what it applies to, and an arrow along the run (arrow: "down_slope" points downhill on the view's paper, "up_slope" uphill; level pipe shows none); returns its id.
  • documents.setTagStyle: Changes a tag style's look: lines, box, orientation, applies-to, mask, textStyleId or its arrow (arrow: "none" removes it).
  • documents.textStyle: Creates a model-wide Text Type (font family, paper cap height, bold/italic/uppercase, opaque or transparent background mask, default drawing roles) so part marks, circuit labels, tags, dimensions and room labels stay unified and readable over crossing lines.
  • documents.setTextStyle: Updates an existing model-wide Text Type (size, font family, bold/italic/uppercase, opaque background mask, color, or default drawing roles).
  • documents.deleteTextStyle: Deletes a model-wide Text Type by id.
  • documents.flipWireArc: Flips (or explicitly sets) which side an automatic circuit or switch-leg arc bows toward on a plan view.
  • documents.setCircuitGraphics: Sets a plan view's circuit and switch-leg drawing style (showCircuits: false makes a dedicated controls schematic plan), home runs, switch-leg letters, and ANSI/NECA 100 wire hash marks (home_runs, home_runs_and_switch_legs, or all_runs) while keeping existing wire waypoints and home-run offsets intact.
  • documents.setSwitchLegLabelOffset: Repositions (or resets with null) one lowercase switch-leg letter ("a", "b") relative to its device anchor on a plan view.
  • documents.setMwbcGroup: Groups (or splits with null) branch circuits on the same panel into a shared-neutral Multi-Wire Branch Circuit (MWBC, NEC 210.4) drawn as one multi-arrowhead combined home run with shared neutral hash marks.
  • documents.setWirePath: Pins one or more spline/orthogonal control vertices on a circuit or switch-leg wire span (hintKey is the link id or "switch:<leg>"). 1 point draws a smooth arc, 2+ points draw a Catmull-Rom spline, and null resets to automatic routing.
  • documents.setHomeRun: Aims, resizes, curves, re-attaches, or moves the label of a circuit's home run arrow using offsets relative to its host device so the home run still follows when the device moves.
  • documents.keynote: Gives elements a keynote by its key ("P1", "M3"); a keynote tag on a view prints the key and the sheet's keynote list (Sheets › Live table › Keynote list) gives its words from the keynote tables in force.
  • documents.scheduleRows: A schedule's rows as numbers and words, on the model as the script has it so far: cells by column id (quantities in SI), grand totals, the row count.
  • documents.scheduleFields: What a schedule can list and show: every class (no argument), or each named class's fields (path, label, type, unit, how it totals) and relationships for aggregate columns.
  • documents.autoTag: Tag every untagged element of categories (duct, pipe, air_terminal, equipment, fixture, part, room, space, opening) in a view as movable DrawingItem tags placed clear of linework and other tags.
  • documents.autoDimension: Dimensions runs, walls or grid lines in a plan or section as one edit: each (one dimension along every element) or chain (one string across them).
  • documents.packSheet: Arranges a sheet's viewports in its drawing area (the editor's Arrange): packed or a grid, optionally shrinking views to a standard scale that fits, as one edit.
  • documents.diagramKinds: Lists every live diagram kind registered by active packs ("one_line", "electrical_riser", "controls_diagram", "plumbing_riser", …) with its label.
  • documents.diagram: Creates a live diagram view derived from the model by any active pack ("one_line", "electrical_riser", "controls_diagram", "plumbing_riser", …; documents.diagramKinds(ctx) lists all available kinds).
  • documents.oneLine: A one-line, riser, or pack-contributed live diagram in a new drafting view: drawn from a distribution you describe (diagram), or live from the model (live: "one_line", "electrical_riser", "controls_diagram", "plumbing_riser"…).
  • documents.detailLibrary: The 2D detail library: components (id, name, category, default size in mm, whether it stretches), hatch and line patterns, line styles and weights.
  • documents.formKinds: The form schedule kinds the model's add-ons offer (panel, switchboard, feeder, connection_types, equipment_connections, lighting_controls…) and whether each is the schedule of one element.
  • documents.formSchedule: A form schedule view (panel, switchboard, feeder, lighting_controls…) with the add-on's built-in form, filled live from the model; rules (a load read's rules.id) prints code demand factors.

documents.sheet ​

A new sheet (number, name, title block); returns its id.

ts
sheet(ctx: ScriptContext, spec: { number: string; name: string; titleBlock?: TitleBlock; fields?: Record<string, string>; id?: string }): string

Topics: sheet, drawing, title block, sheets

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) {
    documents.sheet(ctx, { number: "M-101", name: "Mechanical plan, Level 1" });
  },
});

documents.setSheet ​

Changes a sheet's number, name, title block or fields.

ts
setSheet(ctx: ScriptContext, sheetId: string, changes: { number: string; name: string; titleBlock?: TitleBlock; fields?: Record<string, string> }): void

Topics: sheet, rename, title block fields

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 s = documents.sheet(ctx, { number: "M-101", name: "Mechanical plan" });
    documents.setSheet(ctx, s, { number: "M-101", name: "Mechanical plan, Level 1", fields: { drawn_by: "KE" } });
  },
});

documents.planView ​

A floor plan of one level (for a discipline, scale, detailLevel, symbolScale, showLineCodes, and per-category/service overrides including singleLineBelow); returns the view's id.

ts
planView(ctx: ScriptContext, spec: PlanViewSpec): string

Topics: view, plan, floor plan, detail level, symbolScale, annotative, single line, double line, line code

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) {
    documents.planView(ctx, { level: "L1", name: "Level 1 - Plumbing", discipline: "plumbing", scale: 48, detailLevel: "medium" });
  },
});

documents.setView ​

Changes a view's detail level (coarse/medium/fine), visual style, annotative symbolScale (0.5–3.0), inline service codes, scale, discipline, or per-category/service graphics overrides (including singleLineBelow).

ts
setView(ctx: ScriptContext, viewId: string, changes: ViewChanges): void

Topics: view, detail level, symbolScale, annotative, category overrides, single line, double line, schematic, line code

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 plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plumbing", discipline: "plumbing" });
    documents.setView(ctx, plan, { detailLevel: "medium", showLineCodes: true, scale: 48 });
  },
});

documents.ceilingView ​

A reflected ceiling plan of one level; returns the view's id.

ts
ceilingView(ctx: ScriptContext, spec: PlanViewSpec): string

Topics: view, ceiling, rcp

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) {
    documents.ceilingView(ctx, { level: "L1", name: "Level 1 - RCP", scale: 48 });
  },
});

documents.sectionView ​

A vertical building section cut from from to to (direction +1 left / -1 right, depth default 20 ft); supports annotative headExt/tailExt, Revit splitGap break, explicit crop, and levelLeftExtMm/levelRightExtMm datum extensions. Its live section mark prints automatically on overlapping plans. Returns the view's id.

ts
sectionView(ctx: ScriptContext, spec: VerticalViewSpec): string

Topics: view, section, section cut, building section, section marker, split gap, level lines

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const sec = documents.sectionView(ctx, { name: "Building Section A-A", from: { x: units.ft(0), y: units.ft(10) }, to: { x: units.ft(30), y: units.ft(10) }, direction: 1, depth: units.ft(15), scale: 48, splitGap: true });
    const sheet = documents.sheet(ctx, { number: "A-301", name: "Sections" });
    documents.place(ctx, sheet, sec, { x: units.mm(400), y: units.mm(300) });
  },
});

documents.elevationView ​

An interior or exterior elevation looking from from..to (direction +1 left / -1 right, depth default 20 ft); its live elevation marker (circle + pointer arrow with auto-updating detail#/sheet# head) prints automatically on overlapping plans. Returns the view's id.

ts
elevationView(ctx: ScriptContext, spec: VerticalViewSpec): string

Topics: view, elevation, interior elevation, exterior elevation, elevation marker

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const elev = documents.elevationView(ctx, { name: "Restroom North Elevation", from: { x: units.ft(2), y: units.ft(8) }, to: { x: units.ft(12), y: units.ft(8) }, direction: 1, depth: units.ft(10), scale: 24 });
    const sheet = documents.sheet(ctx, { number: "A-401", name: "Interior Elevations" });
    documents.place(ctx, sheet, elev, { x: units.mm(400), y: units.mm(300) });
  },
});

documents.enlargedPlan ​

A Revit-style enlarged plan in one step: creates a cropped plan view on the same level at enlarged scale (default 1/4" or 1/2" = 1'-0") AND places a live parametric callout bubble on the parent plan whose detail#/sheet# head auto-updates when the enlarged plan moves sheets. Returns { viewId, calloutId }.

ts
enlargedPlan(ctx: ScriptContext, spec: EnlargedPlanSpec): { viewId: string; calloutId: string }

Topics: view, enlarged plan, callout, callout bubble, plan callout, detail callout

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    const { viewId } = documents.enlargedPlan(ctx, { parent: plan, name: "Enlarged Restroom Plan", from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(12), y: units.ft(10) }, scale: 24 });
    const sheet = documents.sheet(ctx, { number: "P-401", name: "Enlarged Plumbing Plans" });
    documents.place(ctx, sheet, viewId, { x: units.mm(300), y: units.mm(300) });
  },
});

documents.callout ​

Places a live parametric callout box + split head bubble on a view referencing any existing enlarged plan, 2D detail, section, or elevation view. The head reads the target's live detail#/sheet# automatically; returns the callout's id.

ts
callout(ctx: ScriptContext, spec: CalloutRefSpec): string

Topics: callout, callout bubble, view reference, enlarged plan, detail reference

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    const detail = documents.planView(ctx, { level: "L1", name: "Enlarged Core", scale: 24, crop: { from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(10), y: units.ft(10) } } });
    documents.callout(ctx, { view: plan, target: detail, from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(10), y: units.ft(10) }, label: "EEP" });
  },
});

documents.setCrop ​

Sets a view's crop box in typed units, toggles cropView/showCropBox, or adjusts section/elevation far clip depth, level datum extensions (levelLeftExtMm/levelRightExtMm), and section mark headExt/tailExt/splitGap.

ts
setCrop(ctx: ScriptContext, view: string, spec: CropBoxSpec): void

Topics: crop, crop box, view crop, enlarged plan, far clip, section marker, level lines

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.setCrop(ctx, plan, { from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(15), y: units.ft(12) } });
  },
});

documents.duplicateView ​

A copy of a view (another discipline's plan of the same level); returns the new id.

ts
duplicateView(ctx: ScriptContext, viewId: string, name: string, id?: string): string

Topics: view, copy, duplicate

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 m = documents.planView(ctx, { level: "L1", name: "Level 1 - Mechanical", discipline: "mechanical" });
    documents.duplicateView(ctx, m, "Level 1 - Plumbing");
  },
});

documents.place ​

Puts a view (a plan, a schedule, a detail) on a sheet at a point (its centre, from the sheet's lower-left corner), with optional scale and viewport title offset/rule length; returns the viewport's id.

ts
place(ctx: ScriptContext, sheetId: string, viewId: string, at: SheetPoint, scale?: number, title?: { offset?: { x: Measure; y: Measure }; ruleLength?: Measure }): string

Topics: viewport, place, sheet, layout, view title

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 s = documents.sheet(ctx, { number: "M-101", name: "Mechanical plan" });
    const v = documents.planView(ctx, { level: "L1", name: "L1 Mechanical" });
    documents.place(ctx, s, v, { x: units.mm(420), y: units.mm(300) });
  },
});

documents.setViewportTitle ​

Moves a placed viewport's title block on its sheet (offset) and/or changes the horizontal title underline length (ruleLength, or null to reset).

ts
setViewportTitle(ctx: ScriptContext, viewportId: string, spec: { offset?: { x: Measure; y: Measure }; ruleLength?: Measure | null }): void

Topics: viewport, view title, title line, sheet, layout

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 s = documents.sheet(ctx, { number: "A-101", name: "Floor Plan" });
    const v = documents.planView(ctx, { level: "L1", name: "L1 Plan" });
    const vp = documents.place(ctx, s, v, { x: units.mm(420), y: units.mm(300) });
    documents.setViewportTitle(ctx, vp, { offset: { x: units.mm(0), y: units.mm(12) }, ruleLength: units.mm(95) });
  },
});

documents.editSchedule ​

Edits a list schedule view in one undo step: add, move, remove or rename columns, filter, sort, group, totals (an equipment schedule's sort, a fixture schedule's DFU total). The same steps the grid's Columns menu and the agent's bim_schedule_define send; a form schedule (panel slots) refuses.

ts
editSchedule(ctx: ScriptContext, viewId: string, steps: ScheduleEditStep[]): void

Topics: schedule, columns, rename column, sort, filter, group, totals

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: { ids: ["sched-equipment"] },
  parameters: {},
  run(ctx) {
    documents.editSchedule(ctx, "sched-equipment", [{ op: "rename_column", columnId: "mark", heading: "TAG" }, { op: "sort", sort: [{ path: "mark", direction: "asc" }] }, { op: "totals", show: true }]);
  },
});

documents.schedule ​

A schedule view; returns its id. Give classes (rooms, spaces, zones, equipment, any class documents.scheduleFields lists) with field paths or full columns, filters, sort, groups and totals; or a category for a one-category list. Put it on a sheet with documents.place; change it later with documents.editSchedule.

ts
schedule(ctx: ScriptContext, spec: { name: string; category: ScheduleCategory; columns: readonly string[]; title?: string; id?: string } | { name: string; classes: readonly string[]; columns: readonly (string | ScheduleColumn)[]; levels?: readonly string[]; filters?: readonly ScheduleFilter[]; sort?: readonly (string | { path: string; direction: "asc" | "desc" })[]; groups?: readonly (string | { path: string; header?: boolean; footer?: boolean; totals?: boolean })[]; totals?: boolean; includeSubclasses?: boolean; id?: string }): string

Topics: schedule, make a schedule, room schedule, space schedule, equipment schedule, table, classes

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 rooms = documents.schedule(ctx, { name: "Room schedule", classes: ["arch.room"], columns: ["number", "name", "area"], sort: ["number"], totals: true });
    const equipmentSchedule = documents.schedule(ctx, { name: "Equipment schedule", category: "mechanical_equipment", columns: ["mark", "type_name", "level"] });
    const sheet = documents.sheet(ctx, { number: "A-601", name: "Schedules" });
    documents.place(ctx, sheet, rooms, { x: units.mm(150), y: units.mm(400) });
    documents.place(ctx, sheet, equipmentSchedule, { x: units.mm(450), y: units.mm(400) });
  },
});

documents.tag ​

A tag on one element in a plan view (its mark, size or the right text for its kind), with a leader; returns the tag's id.

ts
tag(ctx: ScriptContext, spec: { view: string; element: string; at: { x: Measure; y: Measure }; template?: TagTemplate; fields?: readonly string[]; leader?: boolean; leaderOverride?: boolean; elbow?: "auto" | { x: Measure; y: Measure }; mask?: boolean; textSizeMm?: number; styleId?: string; id?: string }): string

Topics: tag, tags, label, mark, annotate

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.tag(ctx, { view: plan, element: walls.element(1), at: { x: units.ft(10), y: units.ft(-3) } });
  },
});

documents.moveTag ​

Moves an existing tag in a plan view to a clear position (and optionally toggles its leader).

ts
moveTag(ctx: ScriptContext, tagId: string, at: { x: Measure; y: Measure }, opts?: { leader?: boolean }): void

Topics: move tag, tag, label, overlap, legibility

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    const t = documents.tag(ctx, { view: plan, element: walls.element(1), at: { x: units.ft(10), y: units.ft(-3) } });
    documents.moveTag(ctx, t, { x: units.ft(12), y: units.ft(-4) }, { leader: true });
  },
});

documents.planLabels ​

Returns every rendered text label on a plan view (paper mm coordinates and bounding boxes) plus any overlapping pairs, so scripts can verify legibility and move colliding tags.

ts
planLabels(ctx: ScriptContext, viewRef: string): { viewId: string; scale: number; labels: { text: string; at: { xMm: number; yMm: number }; sizeMm: number; anchor: string; box: { minX: number; minY: number; maxX: number; maxY: number } }[]; overlaps: { a: string; b: string; overlapAreaMm2: number }[] }

Topics: plan labels, overlaps, legibility, tags, inspect, qa

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    const report = documents.planLabels(ctx, plan);
    ctx.label(`${report.labels.length} labels, ${report.overlaps.length} overlaps`);
  },
});

documents.dimension ​

A dimension between two points in a view, tied to elements with refs so it follows them; returns its id.

ts
dimension(ctx: ScriptContext, spec: { view: string; from: PlanPoint; to: PlanPoint; refs?: ({ elementId: string; anchor: string } | null)[]; offset?: Measure; kind?: "linear" | "aligned"; id?: string }): string

Topics: dimension, dimensions, measure, annotate

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.dimension(ctx, { view: plan, from: { x: units.ft(0), y: units.ft(0) }, to: { x: units.ft(30), y: units.ft(0) }, refs: [{ elementId: walls.element(1), anchor: "start" }, { elementId: walls.element(1), anchor: "end" }] });
  },
});

documents.tagStyle ​

A new tag style: field lines, box, orientation, what it applies to, and an arrow along the run (arrow: "down_slope" points downhill on the view's paper, "up_slope" uphill; level pipe shows none); returns its id.

ts
tagStyle(ctx: ScriptContext, spec: Omit<Extract<EditCommand, { type: "create_tag_style" }>, "type" | "styleId"> & { id?: string }): string

Topics: tag style, slope arrow, downhill arrow, drain slope tag, tag, arrow

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: {},
  parameters: {},
  run(ctx) {
    documents.tagStyle(ctx, { name: "Drain slope", lines: ["[{pipe.slope}]"], box: "none", orientation: "along", appliesTo: ["pipe"], arrow: "down_slope" });
  },
});

documents.setTagStyle ​

Changes a tag style's look: lines, box, orientation, applies-to, mask, textStyleId or its arrow (arrow: "none" removes it).

ts
setTagStyle(ctx: ScriptContext, styleId: string, changes: Omit<Extract<EditCommand, { type: "update_tag_style" }>, "type" | "styleId">): void

Topics: tag style, slope arrow, edit tag style

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: {},
  parameters: {},
  run(ctx) {
    const style = documents.tagStyle(ctx, { name: "Drain size and slope", lines: ["{pipe.size}[ @ {pipe.slope}]"], appliesTo: ["pipe"] });
    documents.setTagStyle(ctx, style, { arrow: "down_slope" });
  },
});

documents.textStyle ​

Creates a model-wide Text Type (font family, paper cap height, bold/italic/uppercase, opaque or transparent background mask, default drawing roles) so part marks, circuit labels, tags, dimensions and room labels stay unified and readable over crossing lines.

ts
textStyle(ctx: ScriptContext, spec: { name: string; textSizeMm?: number; fontFamily?: string; bold?: boolean; italic?: boolean; uppercase?: boolean; background?: "opaque" | "transparent"; color?: string; defaultFor?: readonly TextStyleRole[]; id?: string }): string

Topics: text type, text style, font, opaque background, text mask, wipeout, typography

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: {},
  parameters: {},
  run(ctx) {
    const ts = documents.textStyle(ctx, { name: "3/32\" Crisp Opaque", textSizeMm: 2.4, background: "opaque", defaultFor: ["part_mark", "link_label", "tag"] });
    documents.setTextStyle(ctx, ts, { bold: true });
  },
});

documents.setTextStyle ​

Updates an existing model-wide Text Type (size, font family, bold/italic/uppercase, opaque background mask, color, or default drawing roles).

ts
setTextStyle(ctx: ScriptContext, styleId: string, changes: { name?: string; textSizeMm?: number; fontFamily?: string | null; bold?: boolean; italic?: boolean; uppercase?: boolean; background?: "opaque" | "transparent"; color?: string | null; defaultFor?: readonly TextStyleRole[] }): void

Topics: text type, text style, edit text style, font, opaque background

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: {},
  parameters: {},
  run(ctx) {
    const ts = documents.textStyle(ctx, { name: "Notes", textSizeMm: 2.4 });
    documents.setTextStyle(ctx, ts, { bold: true, background: "opaque" });
  },
});

documents.deleteTextStyle ​

Deletes a model-wide Text Type by id.

ts
deleteTextStyle(ctx: ScriptContext, styleId: string): void

Topics: text type, text style, delete text style

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: {},
  parameters: {},
  run(ctx) {
    const ts = documents.textStyle(ctx, { name: "Temp", textSizeMm: 2.4 });
    documents.deleteTextStyle(ctx, ts);
  },
});

documents.flipWireArc ​

Flips (or explicitly sets) which side an automatic circuit or switch-leg arc bows toward on a plan view.

ts
flipWireArc(ctx: ScriptContext, viewRef: string, hintKey: string, fromElementId: string, toElementId: string, flipped?: boolean): void

Topics: wire arc, flip wire, circuit graphics, arc side

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.flipWireArc(ctx, plan, "ckt-1", "r-1", "r-2", true);
  },
});

documents.setCircuitGraphics ​

Sets a plan view's circuit and switch-leg drawing style (showCircuits: false makes a dedicated controls schematic plan), home runs, switch-leg letters, and ANSI/NECA 100 wire hash marks (home_runs, home_runs_and_switch_legs, or all_runs) while keeping existing wire waypoints and home-run offsets intact.

ts
setCircuitGraphics(ctx: ScriptContext, viewRef: string, settings: CircuitGraphicsSettingsSpec): void

Topics: circuit graphics, wire style, hash marks, tick marks, switch legs, home runs, controls plan

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.setCircuitGraphics(ctx, plan, { style: "arcs", showCircuits: true, homeRuns: true, switchLegs: true, switchLegLabels: true, hashMarks: "hots_neutral_ground", hashMarksOn: "home_runs_and_switch_legs" });
  },
});

documents.setSwitchLegLabelOffset ​

Repositions (or resets with null) one lowercase switch-leg letter ("a", "b") relative to its device anchor on a plan view.

ts
setSwitchLegLabelOffset(ctx: ScriptContext, viewRef: string, hintKey: string, memberId: string, offset: { x: Measure; y: Measure } | null): void

Topics: switch leg label, move switch letter, control designation

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.setSwitchLegLabelOffset(ctx, plan, "switch:a", "sw-1", { x: units.in(14), y: units.in(8) });
  },
});

documents.setMwbcGroup ​

Groups (or splits with null) branch circuits on the same panel into a shared-neutral Multi-Wire Branch Circuit (MWBC, NEC 210.4) drawn as one multi-arrowhead combined home run with shared neutral hash marks.

ts
setMwbcGroup(ctx: ScriptContext, viewRef: string, linkIds: readonly string[], groupName: string | null): void

Topics: mwbc, multi-wire branch circuit, shared neutral, combined home run, double arrowhead

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.setMwbcGroup(ctx, plan, ["ckt-1", "ckt-3"], "mwbc-1");
  },
});

documents.setWirePath ​

Pins one or more spline/orthogonal control vertices on a circuit or switch-leg wire span (hintKey is the link id or "switch:<leg>"). 1 point draws a smooth arc, 2+ points draw a Catmull-Rom spline, and null resets to automatic routing.

ts
setWirePath(ctx: ScriptContext, viewRef: string, hintKey: string, fromElementId: string, toElementId: string, waypoints: readonly PlanPoint[] | null): void

Topics: spline wire, wire vertices, wire path, bend circuit, arc wire

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.setWirePath(ctx, plan, "ckt-1", "r-1", "r-2", [{ x: units.ft(10), y: units.ft(12) }, { x: units.ft(16), y: units.ft(13) }]);
  },
});

documents.setHomeRun ​

Aims, resizes, curves, re-attaches, or moves the label of a circuit's home run arrow using offsets relative to its host device so the home run still follows when the device moves. Pass null to reset.

ts
setHomeRun(ctx: ScriptContext, viewRef: string, linkId: string, spec: HomeRunSpec | null): void

Topics: home run, move home run, home run arrow, circuit label, home run curve

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.setHomeRun(ctx, plan, "ckt-1", { tipOffset: { x: units.ft(-4), y: units.ft(-1.5) }, bendOffset: { x: units.ft(-2), y: units.ft(-2) } });
  },
});

documents.keynote ​

Gives elements a keynote by its key ("P1", "M3"); a keynote tag on a view prints the key and the sheet's keynote list (Sheets › Live table › Keynote list) gives its words from the keynote tables in force.

ts
keynote(ctx: ScriptContext, elementIds: readonly string[], key: string): void

Topics: keynote, key note, general note, legend, note number

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: { ids: ["duct-1", "duct-2"] },
  parameters: {},
  run(ctx) {
    documents.keynote(ctx, ["duct-1", "duct-2"], "M1");
  },
});

documents.scheduleRows ​

A schedule's rows as numbers and words, on the model as the script has it so far: cells by column id (quantities in SI), grand totals, the row count. Form schedules (panels, feeders) are add-on reads (electrical.loads).

ts
scheduleRows(ctx: ScriptContext, schedule: string, window?: { offset?: number; limit?: number }): ScheduleRows

Topics: schedule rows, read a schedule, totals, room areas, schedule values

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 rooms = documents.schedule(ctx, { name: "Room schedule", classes: ["arch.room"], columns: ["number", "name", "area"], sort: ["number"], totals: true });
    const read = documents.scheduleRows(ctx, rooms);
    const m2 = read.rows.reduce((sum, r) => sum + Number(r.cells.area ?? 0), 0);
    ctx.label(`${read.totalRows} rooms, ${Math.round(m2 * 10.7639)} sq ft`);
  },
});

documents.scheduleFields ​

What a schedule can list and show: every class (no argument), or each named class's fields (path, label, type, unit, how it totals) and relationships for aggregate columns.

ts
scheduleFields(ctx: ScriptContext, classes?: readonly string[]): readonly ScheduleClassFields[]

Topics: schedule fields, schedule classes, what can a schedule show, columns

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 space = documents.scheduleFields(ctx, ["gen.space"])[0];
    const fields = (space?.fields ?? []).filter((f) => f.path === "area" || f.path === "occupants").map((f) => f.path);
    documents.schedule(ctx, { name: "Space schedule", classes: ["gen.space"], columns: ["number", "name", ...fields], totals: true });
  },
});

documents.autoTag ​

Tag every untagged element of categories (duct, pipe, air_terminal, equipment, fixture, part, room, space, opening) in a view as movable DrawingItem tags placed clear of linework and other tags.

ts
autoTag(ctx: ScriptContext, spec: { view: string; categories: readonly AutoTagCategory[]; leaders?: "always" | "never" | "when_away"; includeTagged?: boolean; only?: readonly string[]; textHeight?: Measure; styleId?: string }): { tagged: number; skipped: readonly { elementId: string; reason: string }[] }

Topics: auto tag, tag all, tag every duct, tags, annotate

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 plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Mechanical", scale: 48, cutHeight: units.ft(10) });
    routes.along(ctx, { level: "L1", domain: "duct", size: routes.rect(units.in(20), units.in(12)), system: { id: "sa-1", kind: "supply_air" }, height: units.ft(9), points: [{ x: units.ft(2), y: units.ft(10) }, { x: units.ft(28), y: units.ft(10) }] });
    routes.along(ctx, { level: "L1", domain: "duct", size: routes.rect(units.in(20), units.in(12)), system: { id: "ra-1", kind: "return_air" }, height: units.ft(9), points: [{ x: units.ft(15), y: units.ft(2) }, { x: units.ft(15), y: units.ft(18) }] });
    const done = documents.autoTag(ctx, { view: plan, categories: ["duct"] });
    ctx.label(`${done.tagged} duct tags`);
  },
});

documents.autoDimension ​

Dimensions runs, walls or grid lines in a plan or section as one edit: each (one dimension along every element) or chain (one string across them). Every dimension follows its elements.

ts
autoDimension(ctx: ScriptContext, spec: { view: string; elements: readonly string[]; mode: "each" | "chain"; direction?: "horizontal" | "vertical"; offset?: Measure }): void

Topics: auto dimension, dimension walls, dimension string, chain dimension, dimensions

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 walls = building.walls(ctx, { level: "L1", points: [{ x: units.ft(0), y: units.ft(0) }, { x: units.ft(30), y: units.ft(0) }, { x: units.ft(30), y: units.ft(20) }, { x: units.ft(0), y: units.ft(20) }], closed: true, thickness: units.in(8), height: units.ft(10) });
    const plan = documents.planView(ctx, { level: "L1", name: "Level 1 - Plan", scale: 48 });
    documents.autoDimension(ctx, { view: plan, elements: [walls.element(1), walls.element(2)], mode: "each" });
  },
});

documents.packSheet ​

Arranges a sheet's viewports in its drawing area (the editor's Arrange): packed or a grid, optionally shrinking views to a standard scale that fits, as one edit. Returns how many moved.

ts
packSheet(ctx: ScriptContext, sheet: string, spec?: { mode?: "pack" | "grid"; columns?: number; fitScales?: boolean; minScale?: number; order?: readonly string[]; gap?: Measure }): { moved: number }

Topics: sheet layout, arrange sheet, pack views, sheet packing, fit views

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 sheet = documents.sheet(ctx, { number: "M-101", name: "Plans" });
    for (const level of ctx.model.levels()) {
      const view = documents.planView(ctx, { level: level.id, name: `${String(level.name)} - Mechanical`, scale: 48 });
      documents.place(ctx, sheet, view, { x: units.mm(100), y: units.mm(100) });
    }
    documents.packSheet(ctx, sheet, { fitScales: true });
  },
});

documents.diagramKinds ​

Lists every live diagram kind registered by active packs ("one_line", "electrical_riser", "controls_diagram", "plumbing_riser", …) with its label.

ts
diagramKinds(ctx: ScriptContext): readonly { kind: string; label: string }[]

Topics: diagram kinds, controls diagram, one-line, riser diagram, live diagram

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(documents.diagramKinds(ctx).map((d) => d.kind).join(", "));
    ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
  },
});

documents.diagram ​

Creates a live diagram view derived from the model by any active pack ("one_line", "electrical_riser", "controls_diagram", "plumbing_riser", …; documents.diagramKinds(ctx) lists all available kinds). Returns the view's id.

ts
diagram(ctx: ScriptContext, spec: { name: string; kind: string; hints?: DiagramHints; id?: string }): string

Topics: diagram, live diagram, controls diagram, lighting controls diagram, one-line, riser

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 ctrl = documents.diagram(ctx, { name: "E-501 Lighting Controls Diagram", kind: "controls_diagram" });
    const sheet = documents.sheet(ctx, { number: "E-501", name: "Electrical Diagrams" });
    documents.place(ctx, sheet, ctrl, { x: units.mm(300), y: units.mm(300) }, 1);
  },
});

documents.oneLine ​

A one-line, riser, or pack-contributed live diagram in a new drafting view: drawn from a distribution you describe (diagram), or live from the model (live: "one_line", "electrical_riser", "controls_diagram", "plumbing_riser"…). Returns the view's id.

ts
oneLine(ctx: ScriptContext, spec: { name: string; diagram: { title?: string; roots: readonly OneLineNode[]; notes?: readonly string[] }; id?: string } | { name: string; live: string; hints?: Record<string, unknown>; id?: string }): string

Topics: one-line, single line, riser diagram, electrical diagram, distribution diagram, controls diagram

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 diagram = documents.oneLine(ctx, { name: "E-601 One-line", diagram: { roots: [{ id: "utility", kind: "utility", name: "Utility", children: [{ id: "msb", kind: "switchboard", name: "MSB", ratings: ["800A", "208Y/120V"], children: [{ id: "lp1", kind: "panelboard", name: "LP-1" }] }] }] } });
    const sheet = documents.sheet(ctx, { number: "E-601", name: "One-line diagram" });
    documents.place(ctx, sheet, diagram, { x: units.mm(300), y: units.mm(300) }, 1);
  },
});

documents.detailLibrary ​

The 2D detail library: components (id, name, category, default size in mm, whether it stretches), hatch and line patterns, line styles and weights. Use a component id as the symbol of a detail item.

ts
detailLibrary(ctx: ScriptContext): { components: readonly { id: string; name: string; category: string; widthMm: number; heightMm: number; linear: boolean }[]; hatchPatterns: readonly string[]; linePatterns: readonly string[]; lineStyles: readonly { id: string; name: string }[]; lineWeights: readonly string[] }

Topics: detail components, detail library, hatch patterns, line styles, symbols

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 library = documents.detailLibrary(ctx);
    ctx.label(`${library.components.length} detail components`);
    ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
  },
});

documents.formKinds ​

The form schedule kinds the model's add-ons offer (panel, switchboard, feeder, connection_types, equipment_connections, lighting_controls…) and whether each is the schedule of one element.

ts
formKinds(ctx: ScriptContext): readonly { kind: string; boundToElement: boolean }[]

Topics: form schedule, panel schedule, switchboard schedule, feeder schedule, lighting controls schedule

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(documents.formKinds(ctx).map((f) => f.kind).join(", "));
    ctx.edit({ type: "create_level", levelId: ctx.id("level"), name: "Roof", elevationMm: 9000 });
  },
});

documents.formSchedule ​

A form schedule view (panel, switchboard, feeder, lighting_controls…) with the add-on's built-in form, filled live from the model; rules (a load read's rules.id) prints code demand factors. Returns its id; put it on a sheet with documents.place.

ts
formSchedule(ctx: ScriptContext, spec: { kind: string; name: string; element?: string; rules?: string; id?: string }): string

Topics: panel schedule, form schedule, switchboard schedule, lighting controls schedule, controls schedule, schedule a panel

Example script
ts
import { defineScript, units, routes, parts, building, equipment, documents, checks } from "@permitzip/bim-script";
export default defineScript({
  kind: "layout",
  reads: { levels: true, kinds: ["part"] },
  parameters: {},
  run(ctx) {
    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 panel = ctx.model.ofKind("part").find((p) => p.mark === "LP-1");
    if (!panel) throw new Error("No LP-1");
    const loads = ctx.read<{ rules: { id: string } }>("electrical.loads", { panel: "LP-1", nec_edition: "2023" });
    const schedule = documents.formSchedule(ctx, { kind: "panel", name: "Panel LP-1 schedule", element: panel.id, rules: loads.rules.id });
    const controls = documents.formSchedule(ctx, { kind: "lighting_controls", name: "Lighting controls schedule" });
    const sheet = documents.sheet(ctx, { number: "E-601", name: "Panel & control schedules" });
    documents.place(ctx, sheet, schedule, { x: units.mm(250), y: units.mm(350) });
    documents.place(ctx, sheet, controls, { x: units.mm(620), y: units.mm(350) });
  },
});

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