@snaptrude/plugin-core 0.2.3 → 0.2.5

package/src/api/entity/space.ts

@@ -53,18 +53,22 @@ export abstract class PluginSpaceApi {
   /**
    * Create a space by extruding a 2D profile.
    *
-   * The {@linkcode PluginSpaceCreateFromProfileArgs.profile profile} is extruded
-   * upward (along the Y axis) by {@linkcode PluginSpaceCreateFromProfileArgs.extrudeHeight
-   * extrudeHeight}, then offset by {@linkcode PluginSpaceCreateFromProfileArgs.position
-   * position}. The created space is automatically assigned to the active story
-   * and a default department.
+   * The {@linkcode PluginSpaceCreateFromProfileArgs.profile profile} is used as
+   * the outer boundary and extruded upward (along the Y axis) by
+   * {@linkcode PluginSpaceCreateFromProfileArgs.extrudeHeight extrudeHeight},
+   * then offset by {@linkcode PluginSpaceCreateFromProfileArgs.position
+   * position}. Optional {@linkcode PluginSpaceCreateFromProfileArgs.innerProfiles
+   * innerProfiles} are used as holes inside the outer boundary. The created
+   * space is automatically assigned to the active story and a default department.
    *
    * Use {@linkcode PluginProfileApi.fromLinePoints} to quickly build a profile
    * from a list of points.
    *
    * @param args - An object containing:
    *   - {@linkcode PluginSpaceCreateFromProfileArgs.profile args.profile} — A closed
-   *     {@linkcode PProfile} defining the floor shape
+   *     {@linkcode PProfile} defining the outer floor shape
+   *   - {@linkcode PluginSpaceCreateFromProfileArgs.innerProfiles args.innerProfiles} —
+   *     Optional closed {@linkcode PProfile}`[]` loops to subtract as holes
    *   - {@linkcode PluginSpaceCreateFromProfileArgs.extrudeHeight args.extrudeHeight} —
    *     Extrusion height in Babylon units
    *   - {@linkcode PluginSpaceCreateFromProfileArgs.position args.position} — Offset
@@ -77,7 +81,7 @@ export abstract class PluginSpaceApi {
    * ```ts
    * const { vec3 } = snaptrude.core.math
    *
-   * const profile = await snaptrude.core.geom.profile.fromLinePoints({
+   * const outerProfile = await snaptrude.core.geom.profile.fromLinePoints({
    *   points: [
    *     vec3.new(0, 0, 0),
    *     vec3.new(10, 0, 0),
@@ -85,9 +89,18 @@ export abstract class PluginSpaceApi {
    *     vec3.new(0, 0, 8),
    *   ],
    * })
+   * const holeProfile = await snaptrude.core.geom.profile.fromLinePoints({
+   *   points: [
+   *     vec3.new(3, 0, 3),
+   *     vec3.new(7, 0, 3),
+   *     vec3.new(7, 0, 5),
+   *     vec3.new(3, 0, 5),
+   *   ],
+   * })
    *
    * const { spaceId } = await snaptrude.entity.space.createFromProfile({
-   *   profile,
+   *   profile: outerProfile,
+   *   innerProfiles: [holeProfile],
    *   extrudeHeight: 3,
    *   position: vec3.new(0, 0, 0),
    * })
@@ -95,6 +108,7 @@ export abstract class PluginSpaceApi {
    */
   public abstract createFromProfile({
     profile,
+    innerProfiles,
     extrudeHeight,
     position,
   }: PluginSpaceCreateFromProfileArgs): PluginApiReturn<PluginSpaceCreateFromProfileResult>
@@ -152,9 +166,7 @@ export abstract class PluginSpaceApi {
     spaceId,
     profile,
     extrudeHeight,
-  }: PluginSpaceUpdateGeometryFromProfileArgs): PluginApiReturn<
-    PluginSpaceUpdateGeometryFromProfileResult
-  >
+  }: PluginSpaceUpdateGeometryFromProfileArgs): PluginApiReturn<PluginSpaceUpdateGeometryFromProfileResult>
 
   /**
    * Get the IDs of all spaces in the current project.
@@ -252,7 +264,7 @@ export abstract class PluginSpaceApi {
    * ```
    */
   public abstract update(
-    args: PluginSpaceUpdateArgs
+    args: PluginSpaceUpdateArgs,
   ): PluginApiReturn<PluginSpaceUpdateResult>
 }
 
@@ -297,12 +309,14 @@ export type PluginSpaceCreateRectangularResult = z.infer<
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `profile` | {@linkcode PProfile} | Closed 2D profile defining the floor shape |
+ * | `profile` | {@linkcode PProfile} | Closed 2D profile defining the outer floor shape |
+ * | `innerProfiles` | {@linkcode PProfile}`[]` | Optional closed profiles to subtract as holes |
  * | `extrudeHeight` | `number` | Extrusion height in Babylon units |
  * | `position` | {@linkcode PVec3} | Offset position in Babylon units |
  */
 export const PluginSpaceCreateFromProfileArgs = z.object({
   profile: PProfile,
+  innerProfiles: z.array(PProfile).optional(),
   extrudeHeight: z.number(),
   position: PVec3,
 })
@@ -469,7 +483,7 @@ export const PluginSpaceType = z.enum([
   "Pool",
   "Walkway",
   "Envelope",
-  "Parking"
+  "Parking",
 ])
 
 /**