Buildable Envelope

Buildable envelope management — create and update parametric zoning envelopes. A buildable envelope is the regulated volume inside which a building may be massed. The host owns envelope identity: create mints a buildableEnvelopeId and returns it; update requires that id to target the existing envelope. Accessed via snaptrude.entity.buildableEnvelope.

Types

PluginBuildableEnvelopePolygonVertex

Site polygon vertex in the request lengthUnit.

Vertices may be passed as { x, z } objects or [x, z] tuples. Numeric values must be finite (no NaN or ±Infinity).

Shape	Type	Description
Object	{ x: number, z: number }	Plan coordinate in the X/Z plane
Tuple	[number, number]	Equivalent [x, z] plan coordinate

PluginBuildableEnvelopeVerticalCap

Vertical cap for a buildable envelope.

Use exactly one shape. Floor-to-floor height is not nested here; it is always supplied as the top-level floorToFloor argument.

Shape	Type	Description
Max height	{ kind: "max_height", maxHeight: number }	Cap the envelope by total height; maxHeight > 0
Max floors	{ kind: "max_floors", maxFloors: number }	Cap the envelope by floor count; positive integer

PluginBuildableEnvelopeSetbackTier

One tier of a buildable envelope's setback profile.

Tiers are ordered by aboveHeight. The first tier (index 0) must have aboveHeight: 0 and describes the ground footprint; each subsequent tier describes the complete setback at a strictly greater height. Each tier carries its own front, side, and rear values — there is no inheritance from earlier tiers.

All numeric values must be finite and nonnegative, in the request lengthUnit.

Property	Type	Description
aboveHeight	number	Height at or above which this tier applies; the ground tier uses 0
front	number	Front setback for this tier
side	number	Side setback for this tier
rear	number	Rear setback for this tier

PluginBuildableEnvelopeCreateArgs

Arguments for create(...), passed positionally in the order below.

Strict schema. The host owns identity — no buildableEnvelopeId is accepted on create; the id is minted by the host and returned in PluginBuildableEnvelopeCreateResult.

Property	Type	Description
sitePolygon	PluginBuildableEnvelopePolygonVertex[]	Site polygon vertices in lengthUnit; minimum 3 vertices
lengthUnit	"ft" | "m"	Unit used by all length fields
setbacks	PluginBuildableEnvelopeSetbackTier[]	Setback profile, ground tier first; minimum 1 tier
verticalCap	PluginBuildableEnvelopeVerticalCap	Maximum height or floor count
floorToFloor	number	Required floor-to-floor height in lengthUnit
farRatio	number (optional)	Optional FAR value, positive when provided
lotCoverageMaxPct	number (optional)	Optional lot coverage cap, 0..100

PluginBuildableEnvelopeCreateResult

Property	Type	Description
buildableEnvelopeId	string	Non-empty unique ID of the created buildable envelope

PluginBuildableEnvelopeUpdateArgs

Arguments for update(...), passed positionally in the order below.

Strict schema. buildableEnvelopeId is required and identifies the prior envelope on the canvas to update.

Property	Type	Description
buildableEnvelopeId	string	Existing envelope ID to update; non-empty
sitePolygon	PluginBuildableEnvelopePolygonVertex[]	Site polygon vertices in lengthUnit; minimum 3 vertices
lengthUnit	"ft" | "m"	Unit used by all length fields
setbacks	PluginBuildableEnvelopeSetbackTier[]	Setback profile, ground tier first; minimum 1 tier
verticalCap	PluginBuildableEnvelopeVerticalCap	Maximum height or floor count
floorToFloor	number	Required floor-to-floor height in lengthUnit
farRatio	number (optional)	Optional FAR value, positive when provided
lotCoverageMaxPct	number (optional)	Optional lot coverage cap, 0..100

PluginBuildableEnvelopeUpdateResult

Property	Type	Description
buildableEnvelopeId	string	Non-empty unique ID of the updated buildable envelope

Functions

create(sitePolygon, lengthUnit, setbacks, verticalCap, floorToFloor, farRatio?, lotCoverageMaxPct?)

Create a new parametric buildable envelope.

• Parameters:
  • sitePolygon: PluginBuildableEnvelopePolygonVertex[] — Site polygon vertices in lengthUnit; minimum 3 vertices
  • lengthUnit: "ft" | "m" — Unit used by all length fields
  • setbacks: PluginBuildableEnvelopeSetbackTier[] — Setback profile, ground tier first; minimum 1 tier
  • verticalCap: PluginBuildableEnvelopeVerticalCap — Maximum height or floor count
  • floorToFloor: number — Required floor-to-floor height in lengthUnit
  • farRatio: number (optional) — Optional FAR value, positive when provided
  • lotCoverageMaxPct: number (optional) — Optional lot coverage cap, 0..100
• Returns: PluginBuildableEnvelopeCreateResult — The buildableEnvelopeId of the created envelope
• Throws: If validation fails or generation produces no renderable geometry

const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create(
  [
    { x: 0, z: 0 },
    { x: 100, z: 0 },
    { x: 100, z: 80 },
    { x: 0, z: 80 }
  ],
  "ft",
  [
    { aboveHeight: 0, front: 10, side: 5, rear: 10 },
    { aboveHeight: 100, front: 20, side: 10, rear: 20 }
  ],
  { kind: "max_height", maxHeight: 150 },
  12
);

---

update(buildableEnvelopeId, sitePolygon, lengthUnit, setbacks, verticalCap, floorToFloor, farRatio?, lotCoverageMaxPct?)

Update an existing parametric buildable envelope. buildableEnvelopeId is required and must match an existing envelope on the canvas.

• Parameters:
  • buildableEnvelopeId: string — Existing envelope ID to update; non-empty
  • sitePolygon: PluginBuildableEnvelopePolygonVertex[] — Site polygon vertices in lengthUnit; minimum 3 vertices
  • lengthUnit: "ft" | "m" — Unit used by all length fields
  • setbacks: PluginBuildableEnvelopeSetbackTier[] — Setback profile, ground tier first; minimum 1 tier
  • verticalCap: PluginBuildableEnvelopeVerticalCap — Maximum height or floor count
  • floorToFloor: number — Required floor-to-floor height in lengthUnit
  • farRatio: number (optional) — Optional FAR value, positive when provided
  • lotCoverageMaxPct: number (optional) — Optional lot coverage cap, 0..100
• Returns: PluginBuildableEnvelopeUpdateResult — The buildableEnvelopeId of the updated envelope
• Throws: If validation fails, the envelope does not exist, or generation produces no renderable geometry

const { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update(
  existingId,
  [
    { x: 0, z: 0 },
    { x: 100, z: 0 },
    { x: 100, z: 80 },
    { x: 0, z: 80 }
  ],
  "ft",
  [{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],
  { kind: "max_height", maxHeight: 175 },
  12
);

Usage Notes

• The host owns identity: create accepts no buildableEnvelopeId; update requires one.
• setbacks is an ordered tier array: setbacks[0].aboveHeight must be 0, and aboveHeight must be strictly increasing across subsequent tiers. Each tier carries its complete front/side/rear values — nothing is inherited from earlier tiers.
• All length-like values use the top-level lengthUnit ("ft" or "m").
• Both args schemas are strict: unrecognized fields are rejected.

Errors

Failed calls reject with a typed PluginError — see Error Handling. Conditions specific to this namespace:

Code	Thrown by	When	details
VALIDATION	create, update	verticalCap + floorToFloor resolve to a non-finite or non-positive height (e.g. an extreme maxFloors × floorToFloor)	verticalCap, floorToFloor
HANDLE_INVALID	update	buildableEnvelopeId does not resolve to an envelope on the canvas	—
OPERATION_FAILED	create, update	Envelope generation / in-place rebuild failed — typically the setbacks/stepbacks leave no buildable footprint on the site polygon	warnings — the engine's reasons (update also carries handles)