@snaptrude/plugin-core 1.0.2-plainpoint-20261026.2 → 1.1.0-pbr-20261026.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/api/core/camera/index.d.ts +4 -12
- package/dist/api/core/camera/index.d.ts.map +1 -1
- package/dist/api/core/comment/index.d.ts +3 -7
- package/dist/api/core/comment/index.d.ts.map +1 -1
- package/dist/api/core/geom/create/index.d.ts +21 -69
- package/dist/api/core/geom/create/index.d.ts.map +1 -1
- package/dist/api/core/geom/query/circle.d.ts +11 -31
- package/dist/api/core/geom/query/circle.d.ts.map +1 -1
- package/dist/api/core/geom/query/contour.d.ts +7 -19
- package/dist/api/core/geom/query/contour.d.ts.map +1 -1
- package/dist/api/core/geom/query/curve.d.ts +24 -72
- package/dist/api/core/geom/query/curve.d.ts.map +1 -1
- package/dist/api/core/geom/query/profile.d.ts +7 -19
- package/dist/api/core/geom/query/profile.d.ts.map +1 -1
- package/dist/api/core/geom/update/contour.d.ts +12 -36
- package/dist/api/core/geom/update/contour.d.ts.map +1 -1
- package/dist/api/core/geom/update/curve.d.ts +5 -13
- package/dist/api/core/geom/update/curve.d.ts.map +1 -1
- package/dist/api/core/geom/update/profile.d.ts +12 -36
- package/dist/api/core/geom/update/profile.d.ts.map +1 -1
- package/dist/api/core/io/import/index.d.ts +3 -7
- package/dist/api/core/io/import/index.d.ts.map +1 -1
- package/dist/api/core/math/quat.d.ts +2 -2
- package/dist/api/core/math/quat.d.ts.map +1 -1
- package/dist/api/core/math/vec3.d.ts +15 -15
- package/dist/api/core/math/vec3.d.ts.map +1 -1
- package/dist/api/design/boolean/index.d.ts +4 -20
- package/dist/api/design/boolean/index.d.ts.map +1 -1
- package/dist/api/design/create/bulk-items.d.ts +4 -20
- package/dist/api/design/create/bulk-items.d.ts.map +1 -1
- package/dist/api/design/create/index.d.ts +27 -67
- package/dist/api/design/create/index.d.ts.map +1 -1
- package/dist/api/design/delete/index.d.ts +7 -14
- package/dist/api/design/delete/index.d.ts.map +1 -1
- package/dist/api/design/dimensions.d.ts +6 -14
- package/dist/api/design/dimensions.d.ts.map +1 -1
- package/dist/api/design/edit/index.d.ts +3 -7
- package/dist/api/design/edit/index.d.ts.map +1 -1
- package/dist/api/design/erase/index.d.ts +2 -10
- package/dist/api/design/erase/index.d.ts.map +1 -1
- package/dist/api/design/family.d.ts +12 -5
- package/dist/api/design/family.d.ts.map +1 -1
- package/dist/api/design/index.d.ts +5 -0
- package/dist/api/design/index.d.ts.map +1 -1
- package/dist/api/design/lights/index.d.ts +504 -0
- package/dist/api/design/lights/index.d.ts.map +1 -0
- package/dist/api/design/lock.d.ts +0 -3
- package/dist/api/design/lock.d.ts.map +1 -1
- package/dist/api/design/materials/index.d.ts +63 -7
- package/dist/api/design/materials/index.d.ts.map +1 -1
- package/dist/api/design/transform/index.d.ts +8 -28
- package/dist/api/design/transform/index.d.ts.map +1 -1
- package/dist/api/design/windows/index.d.ts +34 -1
- package/dist/api/design/windows/index.d.ts.map +1 -1
- package/dist/api/entity/space.d.ts +6 -30
- package/dist/api/entity/space.d.ts.map +1 -1
- package/dist/api/presentation/drawings.d.ts +1 -1
- package/dist/handles.d.ts +0 -8
- package/dist/handles.d.ts.map +1 -1
- package/dist/index.cjs +2570 -2428
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +2553 -2427
- package/dist/index.js.map +1 -1
- package/package.json +13 -13
- package/src/api/core/camera/index.ts +5 -5
- package/src/api/core/comment/index.ts +3 -3
- package/src/api/core/geom/create/index.ts +25 -25
- package/src/api/core/geom/query/circle.ts +11 -11
- package/src/api/core/geom/query/contour.ts +6 -7
- package/src/api/core/geom/query/curve.ts +25 -25
- package/src/api/core/geom/query/profile.ts +6 -7
- package/src/api/core/geom/update/contour.ts +11 -12
- package/src/api/core/geom/update/curve.ts +5 -5
- package/src/api/core/geom/update/profile.ts +11 -12
- package/src/api/core/io/import/index.ts +2 -3
- package/src/api/core/math/quat.ts +2 -2
- package/src/api/core/math/vec3.ts +16 -16
- package/src/api/design/boolean/index.ts +2 -2
- package/src/api/design/create/bulk-items.ts +2 -3
- package/src/api/design/create/index.ts +26 -27
- package/src/api/design/delete/index.ts +7 -14
- package/src/api/design/dimensions.ts +4 -5
- package/src/api/design/edit/index.ts +3 -3
- package/src/api/design/erase/index.ts +2 -2
- package/src/api/design/family.ts +12 -2
- package/src/api/design/index.ts +5 -0
- package/src/api/design/lights/index.ts +406 -0
- package/src/api/design/lock.ts +0 -6
- package/src/api/design/materials/index.ts +58 -7
- package/src/api/design/transform/index.ts +7 -15
- package/src/api/design/windows/index.ts +38 -1
- package/src/api/entity/space.ts +4 -5
- package/src/handles.ts +0 -11
- package/api-manifest.json +0 -10607
- package/test/handles.test.mjs +0 -36
|
@@ -5,7 +5,6 @@ import {
|
|
|
5
5
|
DimensionHandle,
|
|
6
6
|
Vec3Components,
|
|
7
7
|
Vec3Handle,
|
|
8
|
-
Vec3Input,
|
|
9
8
|
} from "../../handles"
|
|
10
9
|
|
|
11
10
|
/**
|
|
@@ -95,8 +94,8 @@ export abstract class PluginDesignDimensionsApi {
|
|
|
95
94
|
* ```
|
|
96
95
|
*/
|
|
97
96
|
public abstract create(
|
|
98
|
-
from:
|
|
99
|
-
to:
|
|
97
|
+
from: Vec3Handle,
|
|
98
|
+
to: Vec3Handle,
|
|
100
99
|
anchor: ComponentHandle,
|
|
101
100
|
options?: { anchorTo?: ComponentHandle; offset?: number },
|
|
102
101
|
): PluginApiReturn<DimensionHandle>
|
|
@@ -363,8 +362,8 @@ export type PluginDimensionsChangeResult = z.infer<
|
|
|
363
362
|
* TRANSPORT: positional args — validated host-side as this object.
|
|
364
363
|
*/
|
|
365
364
|
export const PluginDesignDimensionsCreateArgs = z.object({
|
|
366
|
-
from:
|
|
367
|
-
to:
|
|
365
|
+
from: Vec3Handle,
|
|
366
|
+
to: Vec3Handle,
|
|
368
367
|
anchor: ComponentHandle,
|
|
369
368
|
anchorTo: ComponentHandle.optional(),
|
|
370
369
|
offset: z.number().finite().optional(),
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as z from "zod"
|
|
2
2
|
import { PluginApiReturn } from "../../../types"
|
|
3
|
-
import { ComponentHandle,
|
|
3
|
+
import { ComponentHandle, Vec3Handle } from "../../../handles"
|
|
4
4
|
import { OffsetSplitOutcome } from "../shared"
|
|
5
5
|
|
|
6
6
|
/**
|
|
@@ -41,7 +41,7 @@ export abstract class PluginDesignEditApi {
|
|
|
41
41
|
public abstract offsetSplit(
|
|
42
42
|
component: ComponentHandle,
|
|
43
43
|
offsetDistance: number,
|
|
44
|
-
options?: { profilePickPoint?:
|
|
44
|
+
options?: { profilePickPoint?: Vec3Handle },
|
|
45
45
|
): PluginApiReturn<OffsetSplitOutcome>
|
|
46
46
|
}
|
|
47
47
|
|
|
@@ -49,6 +49,6 @@ export abstract class PluginDesignEditApi {
|
|
|
49
49
|
export const PluginDesignOffsetSplitArgs = z.object({
|
|
50
50
|
component: ComponentHandle,
|
|
51
51
|
offsetDistance: z.number(),
|
|
52
|
-
profilePickPoint:
|
|
52
|
+
profilePickPoint: Vec3Handle.optional(),
|
|
53
53
|
})
|
|
54
54
|
export type PluginDesignOffsetSplitArgs = z.infer<typeof PluginDesignOffsetSplitArgs>
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as z from "zod"
|
|
2
2
|
import { PluginApiReturn } from "../../../types"
|
|
3
|
-
import { ComponentHandle,
|
|
3
|
+
import { ComponentHandle, Vec3Handle } from "../../../handles"
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* The erase strategies exposed to plugins. `SplitAndUnion` is *enumerable* but
|
|
@@ -38,7 +38,7 @@ export const ErasableEdgeRef = z.object({
|
|
|
38
38
|
/** The components this edge is incident to — one for external (DirectDelete); two or more for internal (DirectUnion; 3+ at T-junctions where several masses share the edge). */
|
|
39
39
|
components: z.array(ComponentHandle),
|
|
40
40
|
/** A representative point on the edge (its head endpoint). Diagnostic only. */
|
|
41
|
-
snapPoint:
|
|
41
|
+
snapPoint: Vec3Handle,
|
|
42
42
|
})
|
|
43
43
|
export type ErasableEdgeRef = z.infer<typeof ErasableEdgeRef>
|
|
44
44
|
|
package/src/api/design/family.ts
CHANGED
|
@@ -5,7 +5,6 @@ import {
|
|
|
5
5
|
ComponentHandle,
|
|
6
6
|
Vec3Components,
|
|
7
7
|
Vec3Handle,
|
|
8
|
-
Vec3Input,
|
|
9
8
|
} from "../../handles"
|
|
10
9
|
import { NetworkFamilyContract } from "./networks"
|
|
11
10
|
|
|
@@ -19,6 +18,17 @@ import { NetworkFamilyContract } from "./networks"
|
|
|
19
18
|
* compiles that into a live parametric definition the user can place, flex and
|
|
20
19
|
* save to their library.
|
|
21
20
|
*
|
|
21
|
+
* New light fittings use schema 1.3, category `Lighting Fixtures`, and
|
|
22
|
+
* `root.fixture.emitters`. A tube declaration generates its no-cap cylindrical emitting side
|
|
23
|
+
* and physical light together: key, kind:"tube", expression-valued center/axis/length/radius/
|
|
24
|
+
* luminousFluxLm, optional colorTemperatureK/enabled; optional numeric tint and material key.
|
|
25
|
+
* Read getReference() for exact grammar and a runnable example. A glowing finish alone is
|
|
26
|
+
* not an emitter and incomplete 1.2 fixture definitions fail before scene mutation. Existing
|
|
27
|
+
* 1.0/1.1 retain legacy semantics; changing only the marker is not a conversion.
|
|
28
|
+
* Per-instance lights.setEnabled overrides survive flex/save/reload; set/reset reject generated
|
|
29
|
+
* sources. Edit geometry/output using setParameters. V1 excludes end-cap emission, rectangles,
|
|
30
|
+
* elliptical/sheared transforms, and complete transport through a surrounding shade.
|
|
31
|
+
*
|
|
22
32
|
* ## Generic component workflow
|
|
23
33
|
*
|
|
24
34
|
* ```
|
|
@@ -1320,7 +1330,7 @@ export type PluginDesignFamilyDeleteArgs = z.infer<
|
|
|
1320
1330
|
export const PluginDesignFamilyPlaceArgs = z.object({
|
|
1321
1331
|
id: z.string().optional(),
|
|
1322
1332
|
version: z.number().int().positive().optional(),
|
|
1323
|
-
position: z.union([
|
|
1333
|
+
position: z.union([Vec3Handle, Vec3Components]).optional(),
|
|
1324
1334
|
rotation: z.number().optional(),
|
|
1325
1335
|
values: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
|
|
1326
1336
|
storey: z.number().int().optional(),
|
package/src/api/design/index.ts
CHANGED
|
@@ -7,6 +7,7 @@ import { PluginDesignDoorsApi } from "./doors"
|
|
|
7
7
|
import { PluginDesignWindowsApi } from "./windows"
|
|
8
8
|
import { PluginDesignFurnitureApi } from "./furniture"
|
|
9
9
|
import { PluginDesignMaterialsApi } from "./materials"
|
|
10
|
+
import { PluginDesignLightsApi } from "./lights"
|
|
10
11
|
import { PluginDesignEraseApi } from "./erase"
|
|
11
12
|
import { PluginDesignDeleteApi } from "./delete"
|
|
12
13
|
import { PluginDesignBooleanApi } from "./boolean"
|
|
@@ -36,6 +37,7 @@ import {
|
|
|
36
37
|
* - {@linkcode PluginDesignApi.doors} / {@linkcode PluginDesignApi.windows} — fenestration reads + edits
|
|
37
38
|
* - {@linkcode PluginDesignApi.furniture} — furniture catalog reads
|
|
38
39
|
* - {@linkcode PluginDesignApi.materials} — material library + assignment
|
|
40
|
+
* - {@linkcode PluginDesignApi.lights} — physical point/spot lights on furniture and family containers
|
|
39
41
|
* - {@linkcode PluginDesignApi.boolean} — CSG boolean ops (union / subtract / intersect)
|
|
40
42
|
* - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
|
|
41
43
|
* - {@linkcode PluginDesignApi.delete} — hard entity removal
|
|
@@ -63,6 +65,8 @@ export abstract class PluginDesignApi {
|
|
|
63
65
|
public abstract furniture: PluginDesignFurnitureApi
|
|
64
66
|
/** Material library + assignment. See {@linkcode PluginDesignMaterialsApi}. */
|
|
65
67
|
public abstract materials: PluginDesignMaterialsApi
|
|
68
|
+
/** Physical lights attached to furniture and family containers. See {@linkcode PluginDesignLightsApi}. */
|
|
69
|
+
public abstract lights: PluginDesignLightsApi
|
|
66
70
|
/** Plan-level adjacency-edge erase (NOT hard delete). See {@linkcode PluginDesignEraseApi}. */
|
|
67
71
|
public abstract erase: PluginDesignEraseApi
|
|
68
72
|
/** Hard entity removal. See {@linkcode PluginDesignDeleteApi}. */
|
|
@@ -286,6 +290,7 @@ export * from "./doors"
|
|
|
286
290
|
export * from "./windows"
|
|
287
291
|
export * from "./furniture"
|
|
288
292
|
export * from "./materials"
|
|
293
|
+
export * from "./lights"
|
|
289
294
|
export * from "./lock"
|
|
290
295
|
export * from "./erase"
|
|
291
296
|
export * from "./delete"
|
|
@@ -0,0 +1,406 @@
|
|
|
1
|
+
import * as z from "zod"
|
|
2
|
+
import { PluginApiReturn } from "../../../types"
|
|
3
|
+
import { ComponentHandle } from "../../../handles"
|
|
4
|
+
import { PluginDesignChangeResult } from "../lock"
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Most lights one component can store. This is a **storage quota**, enforced by the host:
|
|
8
|
+
* a well-formed list longer than this is refused with `RESOURCE_QUOTA_EXCEEDED` (it is not
|
|
9
|
+
* a schema rule, so the schemas below do not reject it as malformed `VALIDATION`). How many
|
|
10
|
+
* lights the renderer shades in a frame (and how many shadow layers it can afford) is a
|
|
11
|
+
* separate, renderer-wide budget; lights over that budget are simply not drawn, they are
|
|
12
|
+
* never rejected here.
|
|
13
|
+
*/
|
|
14
|
+
export const PLUGIN_MAX_COMPONENT_LIGHTS = 64
|
|
15
|
+
|
|
16
|
+
/** A light's `key`: 1-32 characters, lower-case start, unique within its component. */
|
|
17
|
+
export const PLUGIN_LIGHT_KEY_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/
|
|
18
|
+
|
|
19
|
+
const finite = z.number().refine(Number.isFinite, "must be a finite number")
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* A light's strength. Exactly one of:
|
|
23
|
+
* - `{ luminousFluxLm }` — total luminous flux in lumens. For a spot this is the flux of
|
|
24
|
+
* the whole shaded cone (full intensity inside the inner cone, smooth falloff to zero
|
|
25
|
+
* at the outer cone), not the flux of a uniform cone.
|
|
26
|
+
* - `{ luminousIntensityCd }` — on-axis luminous intensity in candela (a spot's peak).
|
|
27
|
+
*
|
|
28
|
+
* Values are physical (not unit-converted): `[0, 10_000_000]`.
|
|
29
|
+
*/
|
|
30
|
+
export const PluginLightIntensity = z.union([
|
|
31
|
+
z.strictObject({ luminousFluxLm: finite.min(0).max(1e7) }),
|
|
32
|
+
z.strictObject({ luminousIntensityCd: finite.min(0).max(1e7) }),
|
|
33
|
+
])
|
|
34
|
+
export type PluginLightIntensity = z.infer<typeof PluginLightIntensity>
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* A spot's cone in degrees. `outerHalfAngleDeg` is in `(0, 90)`; `innerHalfAngleDeg`
|
|
38
|
+
* (default 70 % of the outer) is where full intensity ends, in `[0, outerHalfAngleDeg]`.
|
|
39
|
+
*/
|
|
40
|
+
export const PluginLightCone = z.strictObject({
|
|
41
|
+
outerHalfAngleDeg: finite.gt(0).lt(90),
|
|
42
|
+
innerHalfAngleDeg: finite.min(0).optional(),
|
|
43
|
+
}).refine(
|
|
44
|
+
(c) => c.innerHalfAngleDeg === undefined || c.innerHalfAngleDeg <= c.outerHalfAngleDeg,
|
|
45
|
+
{ message: "innerHalfAngleDeg must not exceed outerHalfAngleDeg" }
|
|
46
|
+
)
|
|
47
|
+
export type PluginLightCone = z.infer<typeof PluginLightCone>
|
|
48
|
+
|
|
49
|
+
const Vec3 = z.tuple([finite, finite, finite])
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* One light stored on a component (a family container or a furniture item).
|
|
53
|
+
*
|
|
54
|
+
* The light lives in the component's **local frame** and follows its host transform:
|
|
55
|
+
* moving, rotating, scaling, mirroring or copying the component carries the light, the
|
|
56
|
+
* offset scales with the component, and a spot's direction is rotated/mirrored by the
|
|
57
|
+
* full host transform. Photometric values are physical; lengths are metres, never
|
|
58
|
+
* engine units.
|
|
59
|
+
*
|
|
60
|
+
* | Property | Type | Description |
|
|
61
|
+
* |---|---|---|
|
|
62
|
+
* | `key` | `string` | Unique within the component; `^[a-z][a-z0-9_-]{0,31}$`. Names this light in `setEnabled`. |
|
|
63
|
+
* | `kind` | `"point" \| "spot"` | A point radiates in all directions; a spot needs a `cone`. |
|
|
64
|
+
* | `offsetMeters` | `[x, y, z]` | Position in the component's local frame, metres. |
|
|
65
|
+
* | `directionLocal` | `[x, y, z]` | Spot axis in the local frame (default straight down `[0, -1, 0]`); need not be unit length. |
|
|
66
|
+
* | `intensity` | {@linkcode PluginLightIntensity} | `{ luminousFluxLm }` or `{ luminousIntensityCd }`. |
|
|
67
|
+
* | `colorTemperatureK` | `number` | 1000-40000 K (default 2700). |
|
|
68
|
+
* | `tint` | `[r, g, b]` | Linear multipliers in `[0, 4]` on the temperature colour (default white). |
|
|
69
|
+
* | `cone` | {@linkcode PluginLightCone} | Required for a spot. |
|
|
70
|
+
* | `sourceRadiusMeters` | `number` | `[0, 1]` m (default 0.02): soft-shadow penumbra and highlight size. |
|
|
71
|
+
* | `castShadow` | `boolean` | Default `true`; `false` lets light pass through walls. |
|
|
72
|
+
* | `enabled` | `boolean` | Default `true`; `false` is lamp-off without losing the description. |
|
|
73
|
+
*/
|
|
74
|
+
const PointSpotLight = z
|
|
75
|
+
.strictObject({
|
|
76
|
+
key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN, "key must match ^[a-z][a-z0-9_-]{0,31}$"),
|
|
77
|
+
kind: z.enum(["point", "spot"]),
|
|
78
|
+
offsetMeters: Vec3,
|
|
79
|
+
directionLocal: Vec3.optional(),
|
|
80
|
+
intensity: PluginLightIntensity,
|
|
81
|
+
colorTemperatureK: finite.min(1000).max(40000).optional(),
|
|
82
|
+
tint: z.tuple([finite.min(0).max(4), finite.min(0).max(4), finite.min(0).max(4)]).optional(),
|
|
83
|
+
cone: PluginLightCone.optional(),
|
|
84
|
+
sourceRadiusMeters: finite.min(0).max(1).optional(),
|
|
85
|
+
castShadow: z.boolean().optional(),
|
|
86
|
+
enabled: z.boolean().optional(),
|
|
87
|
+
})
|
|
88
|
+
.superRefine((light, ctx) => {
|
|
89
|
+
if (light.kind === "spot" && !light.cone) {
|
|
90
|
+
ctx.addIssue({ code: "custom", path: ["cone"], message: "a spot needs a cone" })
|
|
91
|
+
}
|
|
92
|
+
if (light.directionLocal && Math.hypot(...light.directionLocal) < 1e-6) {
|
|
93
|
+
ctx.addIssue({
|
|
94
|
+
code: "custom",
|
|
95
|
+
path: ["directionLocal"],
|
|
96
|
+
message: "directionLocal must be a non-zero vector",
|
|
97
|
+
})
|
|
98
|
+
}
|
|
99
|
+
})
|
|
100
|
+
/** An outward-emitting circular cylindrical SIDE, never a point with a wider highlight.
|
|
101
|
+
* End caps do not emit. Dimensions are local metres; the host preserves final total lumens
|
|
102
|
+
* under circular radial/axial scale and reflection. Shear/elliptical transforms are unsupported.
|
|
103
|
+
* Tube tint is chromaticity: normalized after tint so output remains luminousFluxLm. A zero
|
|
104
|
+
* tint is invalid; use enabled=false for lamp-off. Surrounding shade transport is not solved.
|
|
105
|
+
* Prefer schema 1.3 family.fixture.emitters: creation then owns side geometry and light together.
|
|
106
|
+
*/
|
|
107
|
+
export const PluginFixtureTube = z.strictObject({
|
|
108
|
+
key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN),
|
|
109
|
+
kind: z.literal("tube"),
|
|
110
|
+
offsetMeters: Vec3,
|
|
111
|
+
directionLocal: Vec3.refine((v) => Math.hypot(...v) >= 1e-6, "tube axis must be nonzero"),
|
|
112
|
+
lengthMeters: finite.gt(0),
|
|
113
|
+
radiusMeters: finite.gt(0),
|
|
114
|
+
intensity: z.strictObject({ luminousFluxLm: finite.min(0).max(1e7) }),
|
|
115
|
+
colorTemperatureK: finite.min(1000).max(40000).optional(),
|
|
116
|
+
tint: z.tuple([finite.min(0).max(4), finite.min(0).max(4), finite.min(0).max(4)])
|
|
117
|
+
.refine((v) => v.some((channel) => channel > 0), "tube tint must have nonzero luminance").optional(),
|
|
118
|
+
castShadow: z.boolean().optional(),
|
|
119
|
+
enabled: z.boolean().optional(),
|
|
120
|
+
})
|
|
121
|
+
export type PluginFixtureTube = z.infer<typeof PluginFixtureTube>
|
|
122
|
+
|
|
123
|
+
/** Stored authored light, discriminated by kind; tube geometry and flux cannot be omitted. */
|
|
124
|
+
export const PluginFixtureLight = z.union([PointSpotLight, PluginFixtureTube])
|
|
125
|
+
export type PluginFixtureLight = z.infer<typeof PluginFixtureLight>
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* A component's whole light list, replace-all, unique keys. Its length is not limited here:
|
|
129
|
+
* the {@linkcode PLUGIN_MAX_COMPONENT_LIGHTS} quota is the host's to enforce and report as
|
|
130
|
+
* `RESOURCE_QUOTA_EXCEEDED`.
|
|
131
|
+
*/
|
|
132
|
+
export const PluginFixtureLightList = z.array(PluginFixtureLight).superRefine((lights, ctx) => {
|
|
133
|
+
const seen = new Set<string>()
|
|
134
|
+
lights.forEach((l, i) => {
|
|
135
|
+
if (seen.has(l.key)) {
|
|
136
|
+
ctx.addIssue({
|
|
137
|
+
code: "custom",
|
|
138
|
+
path: [i, "key"],
|
|
139
|
+
message: `duplicate light key "${l.key}"`,
|
|
140
|
+
})
|
|
141
|
+
}
|
|
142
|
+
seen.add(l.key)
|
|
143
|
+
})
|
|
144
|
+
})
|
|
145
|
+
export type PluginFixtureLightList = z.infer<typeof PluginFixtureLightList>
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Arguments for {@linkcode PluginDesignLightsApi.set}.
|
|
149
|
+
*
|
|
150
|
+
* | Property | Type | Description |
|
|
151
|
+
* |---|---|---|
|
|
152
|
+
* | `component` | {@linkcode ComponentHandle} | A furniture item or family container |
|
|
153
|
+
* | `lights` | {@linkcode PluginFixtureLight}`[]` | The complete new list (replaces the old one); at most 64 |
|
|
154
|
+
*/
|
|
155
|
+
export const PluginDesignLightsSetArgs = z.object({
|
|
156
|
+
component: ComponentHandle,
|
|
157
|
+
lights: PluginFixtureLightList,
|
|
158
|
+
})
|
|
159
|
+
export type PluginDesignLightsSetArgs = z.infer<typeof PluginDesignLightsSetArgs>
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* Arguments for {@linkcode PluginDesignLightsApi.setEnabled}.
|
|
163
|
+
*
|
|
164
|
+
* | Property | Type | Description |
|
|
165
|
+
* |---|---|---|
|
|
166
|
+
* | `component` | {@linkcode ComponentHandle} | The component that owns the light |
|
|
167
|
+
* | `key` | `string` | The light's key |
|
|
168
|
+
* | `enabled` | `boolean` | `true` = on, `false` = off |
|
|
169
|
+
*/
|
|
170
|
+
export const PluginDesignLightsSetEnabledArgs = z.object({
|
|
171
|
+
component: ComponentHandle,
|
|
172
|
+
key: z.string().regex(PLUGIN_LIGHT_KEY_PATTERN),
|
|
173
|
+
enabled: z.boolean(),
|
|
174
|
+
})
|
|
175
|
+
export type PluginDesignLightsSetEnabledArgs = z.infer<typeof PluginDesignLightsSetEnabledArgs>
|
|
176
|
+
|
|
177
|
+
/** Arguments for {@linkcode PluginDesignLightsApi.reset}: the components to clear. */
|
|
178
|
+
export const PluginDesignLightsResetArgs = z.object({
|
|
179
|
+
components: z.array(ComponentHandle),
|
|
180
|
+
})
|
|
181
|
+
export type PluginDesignLightsResetArgs = z.infer<typeof PluginDesignLightsResetArgs>
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Options for {@linkcode PluginDesignLightsApi.list}.
|
|
185
|
+
*
|
|
186
|
+
* | Property | Type | Description |
|
|
187
|
+
* |---|---|---|
|
|
188
|
+
* | `includeDisabled` | `boolean` | Keep lights whose `enabled` is `false` (default `true`). `false` drops them, and components left with none. |
|
|
189
|
+
*/
|
|
190
|
+
export const PluginDesignLightsListOptions = z.object({
|
|
191
|
+
includeDisabled: z.boolean().optional(),
|
|
192
|
+
})
|
|
193
|
+
export type PluginDesignLightsListOptions = z.infer<typeof PluginDesignLightsListOptions>
|
|
194
|
+
|
|
195
|
+
/** One entry of {@linkcode PluginDesignLightsApi.list}: a component and its lights. */
|
|
196
|
+
export const PluginComponentLights = z.object({
|
|
197
|
+
component: ComponentHandle,
|
|
198
|
+
lights: z.array(PluginFixtureLight),
|
|
199
|
+
})
|
|
200
|
+
export type PluginComponentLights = z.infer<typeof PluginComponentLights>
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* The kind of light fitting a component is recognised as, which gives it default lights while it
|
|
204
|
+
* has no stored list (see {@linkcode PluginDesignLightsApi.effective}).
|
|
205
|
+
*/
|
|
206
|
+
export const PluginLightFitting = z.enum([
|
|
207
|
+
"floor-lamp",
|
|
208
|
+
"table-lamp",
|
|
209
|
+
"pendant",
|
|
210
|
+
"pendant-cluster",
|
|
211
|
+
"downlight",
|
|
212
|
+
"linear-batten",
|
|
213
|
+
"wall-sconce",
|
|
214
|
+
"luminaire",
|
|
215
|
+
])
|
|
216
|
+
export type PluginLightFitting = z.infer<typeof PluginLightFitting>
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* What a component lights the model with ({@linkcode PluginDesignLightsApi.effective}).
|
|
220
|
+
*
|
|
221
|
+
* | Property | Type | Description |
|
|
222
|
+
* |---|---|---|
|
|
223
|
+
* | `source` | `'stored' \| 'default' \| 'none'` | `stored`: its stored list (an empty list included: explicitly no lights). `default`: nothing stored and it is a light fitting, so it lights with its fitting's defaults. `none`: neither |
|
|
224
|
+
* | `fitting` | {@linkcode PluginLightFitting} `\| null` | The fitting it is recognised as, or `null` |
|
|
225
|
+
* | `lights` | {@linkcode PluginFixtureLight}`[]` | The lights it lights with |
|
|
226
|
+
*/
|
|
227
|
+
export const PluginEffectiveLights = z.object({
|
|
228
|
+
source: z.enum(["stored", "default", "none"]),
|
|
229
|
+
fitting: PluginLightFitting.nullable(),
|
|
230
|
+
lights: z.array(PluginFixtureLight),
|
|
231
|
+
})
|
|
232
|
+
export type PluginEffectiveLights = z.infer<typeof PluginEffectiveLights>
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* `snaptrude.design.lights` — physical point, spot and cylindrical-side tube sources.
|
|
236
|
+
* New fixtures should be schema 1.3 families with fixture.emitters, not glow-only meshes.
|
|
237
|
+
* Generated source geometry and output are one recipe: set/reset reject recipe-owned lights
|
|
238
|
+
* with PRECONDITION_FAILED. Edit family parameters instead. setEnabled stores a keyed override
|
|
239
|
+
* surviving flex/save/reload; removed recipe keys lose the override, and undo restores it.
|
|
240
|
+
*
|
|
241
|
+
* A light belongs to a **furniture item or a parametric family container** and is
|
|
242
|
+
* stored with it: it is saved, reloaded, copied, pasted and restored by undo with the
|
|
243
|
+
* component, and follows its transform (offsets scale with the component, a spot's
|
|
244
|
+
* direction follows the full rotation/mirroring). Build a light fitting as a family
|
|
245
|
+
* (or place a furniture item), then attach its lights to the returned
|
|
246
|
+
* {@linkcode ComponentHandle}. Other kinds (walls, masses, spaces) are rejected with
|
|
247
|
+
* `PRECONDITION_FAILED`.
|
|
248
|
+
*
|
|
249
|
+
* Light fittings (lamps, pendants, downlights, battens, sconces) light by **default** while
|
|
250
|
+
* nothing is stored on them; {@linkcode PluginDesignLightsApi.effective} reads those defaults.
|
|
251
|
+
*
|
|
252
|
+
* Lists are **replace-all**: {@linkcode PluginDesignLightsApi.set} sends the whole list.
|
|
253
|
+
* `get` and `list` return exactly what was stored (no defaults are filled in). Each mutation is one
|
|
254
|
+
* undo step; writing the value already stored is a no-op. A component holds at most 64
|
|
255
|
+
* lights (more is `RESOURCE_QUOTA_EXCEEDED`, not `VALIDATION`); how many the renderer draws in one frame is a separate budget and never
|
|
256
|
+
* rejects a write.
|
|
257
|
+
*
|
|
258
|
+
* Errors: bad light data → `VALIDATION` (`details` lists the issues); unknown/stale
|
|
259
|
+
* handle → `HANDLE_INVALID`; unsupported component kind, locked component or missing
|
|
260
|
+
* geometry → `PRECONDITION_FAILED`; more than 64 lights → `RESOURCE_QUOTA_EXCEEDED`.
|
|
261
|
+
*/
|
|
262
|
+
export abstract class PluginDesignLightsApi {
|
|
263
|
+
constructor() {}
|
|
264
|
+
|
|
265
|
+
/**
|
|
266
|
+
* Read the lights stored on a component, exactly as written (`[]` when it has none).
|
|
267
|
+
*
|
|
268
|
+
* @param component The furniture item or family container
|
|
269
|
+
* @returns The component's {@linkcode PluginFixtureLight}`[]`
|
|
270
|
+
*
|
|
271
|
+
* @examplePrompt What lights does this lamp have?
|
|
272
|
+
* @examplePrompt Show me the light settings on the pendant I just built
|
|
273
|
+
* @examplePrompt Is there a light attached to this fixture?
|
|
274
|
+
* @examplePrompt Read the lighting of the selected furniture
|
|
275
|
+
*
|
|
276
|
+
* # Example
|
|
277
|
+
* ```ts
|
|
278
|
+
* const lights = await snaptrude.design.lights.get(lamp)
|
|
279
|
+
* console.log(lights.map((l) => l.key))
|
|
280
|
+
* ```
|
|
281
|
+
*/
|
|
282
|
+
public abstract get(component: ComponentHandle): PluginApiReturn<PluginFixtureLight[]>
|
|
283
|
+
|
|
284
|
+
/**
|
|
285
|
+
* Read what a component lights the model with: its stored lights when it has a stored list
|
|
286
|
+
* (an empty one included), else the default lights of the light fitting it is (a floor lamp,
|
|
287
|
+
* a pendant, a downlight...), else none. Defaults are derived, never stored. Read-only.
|
|
288
|
+
*
|
|
289
|
+
* @param component The furniture item or family container
|
|
290
|
+
* @returns {@linkcode PluginEffectiveLights}
|
|
291
|
+
*
|
|
292
|
+
* @examplePrompt Does this lamp light the room?
|
|
293
|
+
* @examplePrompt What light does the pendant give off by default?
|
|
294
|
+
* @examplePrompt Which lights in this room come from the fittings' defaults?
|
|
295
|
+
* @examplePrompt Show the effective lighting of the selected fixture
|
|
296
|
+
*
|
|
297
|
+
* # Example
|
|
298
|
+
* ```ts
|
|
299
|
+
* const { source, fitting, lights } = await snaptrude.design.lights.effective(lamp)
|
|
300
|
+
* console.log(source, fitting, lights.length)
|
|
301
|
+
* ```
|
|
302
|
+
*/
|
|
303
|
+
public abstract effective(component: ComponentHandle): PluginApiReturn<PluginEffectiveLights>
|
|
304
|
+
|
|
305
|
+
/**
|
|
306
|
+
* List every component that has lights, with its lights. Disabled lights are included
|
|
307
|
+
* unless `includeDisabled` is `false`.
|
|
308
|
+
*
|
|
309
|
+
* @param options Optional {@linkcode PluginDesignLightsListOptions}
|
|
310
|
+
* @returns {@linkcode PluginComponentLights}`[]`
|
|
311
|
+
*
|
|
312
|
+
* @examplePrompt Which fixtures in the model have lights?
|
|
313
|
+
* @examplePrompt List all the lamps that are switched on
|
|
314
|
+
* @examplePrompt How many lights are in this project?
|
|
315
|
+
* @examplePrompt Show every light fixture and its settings
|
|
316
|
+
*
|
|
317
|
+
* # Example
|
|
318
|
+
* ```ts
|
|
319
|
+
* const lit = await snaptrude.design.lights.list({ includeDisabled: false })
|
|
320
|
+
* console.log(lit.length, "components are lighting the model")
|
|
321
|
+
* ```
|
|
322
|
+
*/
|
|
323
|
+
public abstract list(
|
|
324
|
+
options?: PluginDesignLightsListOptions
|
|
325
|
+
): PluginApiReturn<PluginComponentLights[]>
|
|
326
|
+
|
|
327
|
+
/**
|
|
328
|
+
* Replace a component's lights with `lights` (replace-all; `[]` removes them all).
|
|
329
|
+
* Recipe-owned fixture sources reject this operation; edit the family parameters instead.
|
|
330
|
+
* One undo step. Writing the list already stored does nothing. The whole list is
|
|
331
|
+
* validated first; on any problem nothing changes.
|
|
332
|
+
*
|
|
333
|
+
* @param component The furniture item or family container to light
|
|
334
|
+
* @param lights The complete new list, at most 64, unique keys
|
|
335
|
+
* @returns The affected component
|
|
336
|
+
*
|
|
337
|
+
* @examplePrompt Add a warm 1600 lumen bulb to the pendant lamp
|
|
338
|
+
* @examplePrompt Put a 38 degree downlight spot in this ceiling fixture
|
|
339
|
+
* @examplePrompt Make this lamp glow at 3000K
|
|
340
|
+
* @examplePrompt Give the table lamp a shadow-casting point light
|
|
341
|
+
*
|
|
342
|
+
* # Example
|
|
343
|
+
* ```ts
|
|
344
|
+
* await snaptrude.design.lights.set(pendant, [
|
|
345
|
+
* {
|
|
346
|
+
* key: "bulb",
|
|
347
|
+
* kind: "point",
|
|
348
|
+
* offsetMeters: [0, -0.3, 0],
|
|
349
|
+
* intensity: { luminousFluxLm: 1600 },
|
|
350
|
+
* colorTemperatureK: 2700,
|
|
351
|
+
* },
|
|
352
|
+
* ])
|
|
353
|
+
* ```
|
|
354
|
+
*/
|
|
355
|
+
public abstract set(
|
|
356
|
+
component: ComponentHandle,
|
|
357
|
+
lights: PluginFixtureLight[]
|
|
358
|
+
): PluginApiReturn<PluginDesignChangeResult>
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* Switch one light on or off without resending its description. One undo step; a
|
|
362
|
+
* no-op when it already has that state.
|
|
363
|
+
*
|
|
364
|
+
* @param component The component that owns the light
|
|
365
|
+
* @param key The light's `key`
|
|
366
|
+
* @param enabled `true` = on, `false` = off
|
|
367
|
+
* @returns The affected component
|
|
368
|
+
*
|
|
369
|
+
* @examplePrompt Turn off the bulb in this lamp
|
|
370
|
+
* @examplePrompt Switch the downlight back on
|
|
371
|
+
* @examplePrompt Dim the room by turning off the pendant light
|
|
372
|
+
* @examplePrompt Toggle the lamp
|
|
373
|
+
*
|
|
374
|
+
* # Example
|
|
375
|
+
* ```ts
|
|
376
|
+
* await snaptrude.design.lights.setEnabled(pendant, "bulb", false)
|
|
377
|
+
* ```
|
|
378
|
+
*/
|
|
379
|
+
public abstract setEnabled(
|
|
380
|
+
component: ComponentHandle,
|
|
381
|
+
key: string,
|
|
382
|
+
enabled: boolean
|
|
383
|
+
): PluginApiReturn<PluginDesignChangeResult>
|
|
384
|
+
|
|
385
|
+
/**
|
|
386
|
+
* Remove all lights from the given components. Every component is checked first and
|
|
387
|
+
* recipe-owned fixture sources reject the entire batch before any component changes.
|
|
388
|
+
* nothing changes if any is invalid; components without lights are skipped. One undo
|
|
389
|
+
* step for the whole call.
|
|
390
|
+
*
|
|
391
|
+
* @param components The components to clear
|
|
392
|
+
* @returns The components that were affected
|
|
393
|
+
*
|
|
394
|
+
* @examplePrompt Remove the lights from this fixture
|
|
395
|
+
* @examplePrompt Clear all the lamps' lighting
|
|
396
|
+
* @examplePrompt Take the light off the selected pendants
|
|
397
|
+
* @examplePrompt Reset the lights on these components
|
|
398
|
+
*
|
|
399
|
+
* # Example
|
|
400
|
+
* ```ts
|
|
401
|
+
* const lit = await snaptrude.design.lights.list()
|
|
402
|
+
* await snaptrude.design.lights.reset(lit.map((e) => e.component))
|
|
403
|
+
* ```
|
|
404
|
+
*/
|
|
405
|
+
public abstract reset(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
|
|
406
|
+
}
|
package/src/api/design/lock.ts
CHANGED
|
@@ -9,12 +9,6 @@ import { ComponentHandle } from "../../handles"
|
|
|
9
9
|
*/
|
|
10
10
|
export const PluginDesignChangeResult = z.object({
|
|
11
11
|
affected: z.array(ComponentHandle),
|
|
12
|
-
/** Derived BIM (walls/floors/slabs) the parametric engine removed with its host. Delete only. */
|
|
13
|
-
cascaded: z.array(ComponentHandle).optional(),
|
|
14
|
-
/** Handles that no longer resolved when the call ran and were skipped. Delete only. */
|
|
15
|
-
missing: z.array(ComponentHandle).optional(),
|
|
16
|
-
/** Handles the engine accepted but left standing; delete them again or report them. Delete only. */
|
|
17
|
-
rejected: z.array(ComponentHandle).optional(),
|
|
18
12
|
})
|
|
19
13
|
export type PluginDesignChangeResult = z.infer<typeof PluginDesignChangeResult>
|
|
20
14
|
|