Skip to content

Script recipes ​

Worked tasks: which kit functions to call, in which order. Start from the closest one.

Part definition ​

Task: parts

The part-type definition a part script returns (what PartBuilder.build() makes and bim_save_part_type saves); never write one by hand, build it.

  1. { familyName, typeName, category, description?, typeParams: [{ name, label, kind: length|number|text|boolean|choice, unit? }], typeValues: { name: value (lengths in mm) }, instanceParams: [], connectors: [...], geometry: [], symbol: [], tagFields: ["mark", "type_name"], source: { kind: "script", key?, version? }, model?, clearances? }.
  2. connectors[]: { id, label, domain (duct | pipe | electrical | …), systemKind, position: [x, y, z] mm, direction: [x, y, z] out of the part, shape: rect | round | none, width/height or diameter, flowDirection?, endType?, voltage?, poles? }.
  3. model (solid program, schema 2): { schema: 2, id, referencePlanes, sketches (points, lines, arcs, circles, fixed by constraints), profiles ({ sketch, outer: { edges }, holes? }), features (extrude | revolve | sweep | loft | imported | pattern | mirror, each join | cut | intersect, visibility per detail level), symbols (per view and detail level), planDisplay, types }.
  4. source.kind is "script" for every part a script makes; bim_save_part_type fills key and version with the saved script version.

Uses: parts.part, PartBuilder.build, PartBuilder.draft

Rooftop unit ​

Task: equipment

Make an RTU part type, save it, then place it on the roof and duct it.

  1. Part script (start from the starter.rooftop_unit library script): extrude the curb (a rectangle with a hole), the casing on it, cut the section seams and access-panel recesses, extrude handles and pattern them, pattern the condenser fan guards on top, a louvred outside-air hood; connectorAt / connector for supply and return (duct, rect, bottom), outside air, gas, power (shape none) and the condensate drain; data fields (weight, curb size) as param(); clearance for service; symbol("coarse") for the plan. ctx.parts.define per size. Preview (the pictures are drawn from the solid), then bim_save_part_type.
  2. Layout script: equipment.place on the roof level with the saved type id and onSlab; routes.along from placed.connector("supply") and ("return") down into the building.

Uses: parts.part, PartBuilder.extrude, PartBuilder.cut, PartBuilder.pattern, PartBuilder.connectorAt, PartBuilder.symbol, ctx.parts.define, equipment.place, routes.along

Water heater ​

Task: equipment

A tank water heater with cold, hot and gas connectors, placed and piped.

  1. Part script (starter.water_heater): a revolved jacket with domed head, a drain valve and a relief valve; connectors on top for cold and hot water (pipe), gas or power by fuel, a flue (duct, round) and the T&P discharge. Save it.
  2. Layout script: equipment.place, then routes.along from each connector to the mains (routes.atRunEnd or a branch).

Uses: parts.part, PartBuilder.revolve, PartBuilder.cylinder, PartBuilder.connector, equipment.place, routes.along, routes.branch

Electrical panel and panel schedule ​

Task: electrical

A panelboard, receptacles by code spacing, circuits from a room template, and the panel's loads per phase, in one script.

  1. equipment.place a starter panelboard (parts.starterTypes(ctx, "panelboard") lists them).
  2. ctx.propose("electrical.receptacles") on the rooms, then ctx.acceptGhosts.
  3. Save a room template (save_catalog_entry, type circuit_template); ctx.read("electrical.circuit_template_plan") plans the circuits for whole rooms and ctx.editSteps sends them.
  4. One circuit by hand: each circuit is a service link from the panel to the devices it feeds, sent with ctx.edit({ type: "create_service_link", sourceId: panel.id, positions: [1], members: [{ elementId, connector: "power" }], electrical: { ratingA: 20 } }) (bim_script_reference({ command: "create_service_link" }) lists its fields).
  5. ctx.read("electrical.loads") for connected and demand loads per phase; "electrical.rebalance_plan" to even the phases; "electrical.check" for overloads and unbalance. A panel schedule is a form: make it with documents.formSchedule and documents.place it on an E sheet. documents.editSchedule refuses a form; use it on list schedules such as the lighting fixture schedule.

Uses: equipment.place, ctx.propose, ctx.acceptGhosts, ctx.read, ctx.editSteps, documents.place

Drains with slope ​

Task: pipe routing

Sanitary or storm piping that falls along its run, or many fixtures connected into a main at once.

  1. One route script: routes.along with slope { rise, per } (absent: the system's minimum); routes.connectInto for many fixtures at once.

Uses: routes.along, routes.connectInto, routes.pipe

Walls, doors and windows ​

Task: walls

A building outline with openings and rooms in one layout script.

  1. building.walls closed, building.door / building.window on walls.element(n), building.floor, building.space per room.

Uses: building.walls, building.door, building.window, building.floor, building.space

Sheets per level ​

Task: sheets

One sheet per level with its plan, schedules on a schedule sheet, numbered in print order; a person picks the sheets when printing and issuing.

  1. ctx.model.levels(); per level documents.sheet (numbered in print order: M-101, M-102) + documents.planView + documents.place.

Uses: ctx.model, documents.sheet, documents.planView, documents.place

One script for many steps ​

Task: many edits

Prefer one script over many single tool calls: a layout of dozens of edits is one preview, one Approve and one Undo.

  1. Read what you need once (reads), loop in the script, ctx.label the result; preview with bim_run_script.

Uses: defineScript, ctx.model, ctx.edit, ctx.label

Schedules ​

Task: schedules

A schedule of one category's elements with chosen columns, placed on a schedule sheet.

  1. documents.schedule with the category and columns; documents.place it on a sheet; later changes (sort, totals, renamed columns) with documents.editSchedule.

Uses: documents.schedule, documents.sheet, documents.place, documents.editSchedule

Rooms from walls ​

Task: rooms and spaces

Rooms found from the walls that enclose them, one point inside each room.

  1. building.walls (closed, or meeting other walls), then building.spaceInWalls with a point inside each room; an open room is refused in words.

Uses: building.walls, building.spaceInWalls, building.space

Levels ​

Task: levels

New levels at elevations, or one above the highest level the model has.

  1. ctx.model.levels() to read what exists; building.level for each new one.

Uses: ctx.model, building.level

Duct routing ​

Task: duct routing

A supply main with a branch, sized from a duct friction calculation.

  1. ctx.calc mech.duct_friction to check a size; routes.along for the main; routes.branch off it; routes.drop for a riser.

Uses: ctx.calc, routes.along, routes.branch, routes.rect, routes.round

Pipe routing ​

Task: pipe routing

A drain sized by the plumbing code, then routed with its slope.

  1. ctx.calc plumbing.size_drain (name the edition); routes.along with routes.pipe at that size and the slope; routes.connectInto for many fixtures at once.

Uses: ctx.calc, routes.along, routes.pipe, routes.connectInto

Tags ​

Task: tags

Tags on elements in a plan view.

  1. A plan view (documents.planView, or one the model has); documents.autoTag tags every duct, pipe, terminal or fixture clear of the others; documents.tag places one where you say.

Uses: documents.planView, documents.autoTag, documents.tag

Dimensions ​

Task: dimensions

A dimension tied to the elements it measures, so it follows them when they move.

  1. A plan view; documents.autoDimension for every run, wall or grid line (each, or one chain); documents.dimension for one between two points, with refs to the elements' ends.

Uses: documents.planView, documents.autoDimension, documents.dimension

Checks and lint ​

Task: lint and checks

Find what is wrong with bim_validation_issues (a core read), then fix it in one script; a calculation can check a design before it is drawn.

  1. bim_validation_issues lists the model's own checks (an open end, a missing size, a slope below the minimum).
  2. One script fixes them (ctx.edit with the command that corrects each); ctx.calc checks a size or a slope before the script draws it.
  3. checks.clashes runs the coordination check (clashes, clearances) on the model as the script has it, so a script can route, check and move in one run.
  4. Accepting a coordination finding and lint settings are kept by the host app: not a script's job.

Uses: ctx.calc, checks.clashes, ctx.edit, ctx.model

Imports ​

Task: imports

A plan PDF or image placed under a level to trace over; bringing in an outside model is a host step.

  1. ctx.edit place_underlay with a file the host app stores (its provider and ref), then calibrate_underlay, then trace walls or spaces over it.
  2. Linking or importing an outside model (IFC, another company's cloud) goes through the host app, and the agent asks the person; a script then reads and edits around the linked reference.

Uses: ctx.edit

Calculations ​

Task: calculations

Run an engineering calculation from a script and act on the answer.

  1. ctx.calcs() lists them; ctx.calc runs one on the model the script has (name the code edition); read run.values by key and use them in edits; ctx.label says what was decided.

Uses: ctx.calcs, ctx.calc, ctx.label

Receptacles by code spacing ​

Task: receptacles

Receptacles in rooms by NEC 210.52 wall spacing (or a density preset), each with its clause, placed as one edit.

  1. Rooms (building.room, or the model's); ctx.propose("electrical.receptacles", { typeId, roomIds, options: { mode: "dwelling", edition } }); read proposal.summary (passes or not); ctx.acceptGhosts with the ghosts to keep. Circuiting is a separate step.

Uses: building.room, ctx.propose, ctx.acceptGhosts

Room and space schedules ​

Task: room schedules

A schedule of rooms, spaces or zones (any class) with fields, totals, sorting and grouping, on a sheet.

  1. documents.scheduleFields(ctx, ["gen.space"]) lists the fields; documents.schedule with classes and columns (totals: true adds the grand total); documents.place it on a sheet.

Uses: documents.scheduleFields, documents.schedule, documents.place

Read a schedule's numbers ​

Task: schedule values

A schedule's rows and totals as numbers, to decide edits (sizes, counts, what is missing).

  1. documents.scheduleRows(ctx, schedule) on any list schedule: cells by column id (SI), totals, row count. Panel and feeder forms: ctx.read("electrical.loads").

Uses: documents.scheduleRows

Rebalance a panel ​

Task: panel rebalancing

Move circuits between slots so the panel's phases carry even loads, as one edit.

  1. ctx.read("electrical.rebalance_plan", { panel }) returns the moves, before and after VA per phase, and the command (null when nothing helps); ctx.editSteps(plan.command) sends it.

Uses: ctx.read, ctx.editSteps

Room circuit templates ​

Task: circuit templates

A firm's room convention (bedroom on one circuit, living room on another) applied to dwelling units on the panels you name.

  1. Save the template (save_catalog_entry, type circuit_template) or use the model's; ctx.read("electrical.circuit_template_plan", { template, units: [{ panel, rooms }] }); ctx.editSteps(plan.command). The script names each unit's panel: nothing picks one.

Uses: ctx.edit, ctx.read, ctx.editSteps

Tag and dimension a plan ​

Task: annotate a plan

Every duct tagged clear of the others and the walls dimensioned, in one script.

  1. documents.autoTag(ctx, { view, categories }) then documents.autoDimension(ctx, { view, elements, mode }).

Uses: documents.autoTag, documents.autoDimension

Pack sheets ​

Task: sheet layout

Views placed on a sheet and arranged to fit its drawing area.

  1. documents.place each view (anywhere), then documents.packSheet(ctx, sheet, { mode, fitScales }).

Uses: documents.place, documents.packSheet

One-line diagram ​

Task: one-line

An electrical one-line drawn from a distribution you describe, or a live one-line or riser from the model, on a sheet.

  1. documents.oneLine(ctx, { name, diagram }) or { name, live: "one_line" }; documents.place it at scale 1.

Uses: documents.oneLine, documents.place

Size ducts from airflow ​

Task: duct sizing

The duct size a system's friction, velocity and aspect limits call for, used to route or resize.

  1. ctx.read("mechanical.duct_size", { cfm, shape, height_mm }) or { element_id } for a routed segment; route or resize with the suggested size (mm).

Uses: ctx.read, routes.along

Clash check ​

Task: coordination

Route, check for clashes and adjust in one script.

  1. checks.clashes(ctx) after the routes: each finding names the elements and where; move one with ctx.edit (or route it at another height) and check again.

Uses: checks.clashes, routes.along

Levels from a linked model ​

Task: linked levels

The model's levels matched to a linked architectural model's storeys.

  1. Give the storeys (the host's link lists them; a script takes them as values); building.levelSyncPlan previews; building.syncLevels applies.

Uses: building.levelSyncPlan, building.syncLevels

Catalogues ​

Task: catalogues

What the libraries hold: starter part types, fitting families, detail components, and the electrical and plumbing catalogues.

  1. parts.starterTypes, routes.fittingTypes, documents.detailLibrary; ctx.read("electrical.catalog") and ctx.read("bim_plumbing_catalog") for the add-ons'. The firm's saved library is the host's.

Uses: parts.starterTypes, routes.fittingTypes, documents.detailLibrary, ctx.read

Ceiling and floor heights ​

Task: surfaces

The floor, ceiling, roof and structure over a point, to set a run's or a unit's height.

  1. building.surfacesAt(ctx, { at, level }) or { element }; use ceiling or structureAbove elevationMm to pick a height.

Uses: building.surfacesAt, routes.along

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