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.
- { 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? }.
- 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? }.
- 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 }.
- 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.
- 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.
- 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.
- 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.
- 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.
- equipment.place a starter panelboard (parts.starterTypes(ctx, "panelboard") lists them).
- ctx.propose("electrical.receptacles") on the rooms, then ctx.acceptGhosts.
- 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.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- bim_validation_issues lists the model's own checks (an open end, a missing size, a slope below the minimum).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- building.surfacesAt(ctx, { at, level }) or { element }; use ceiling or structureAbove elevationMm to pick a height.
Uses: building.surfacesAt, routes.along