@snaptrude/plugin-core 0.0.5 → 0.0.6

package/src/api/tools/transform.ts

@@ -2,14 +2,78 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 import { PVec3 } from "../core/math/vec3"
 
+/**
+ * Transform operations — move and rotate scene components.
+ *
+ * All transform methods accept an array of component IDs and apply the
+ * transformation to each. Operations are recorded in Snaptrude's
+ * command system for undo/redo support.
+ *
+ * Accessed via `snaptrude.tools.transform`.
+ */
 export abstract class PluginTransformApi {
   constructor() {}
 
+  /**
+   * Translate components by a displacement vector.
+   *
+   * Each component's position is offset by the given
+   * {@linkcode PluginMoveArgs.displacement displacement} vector.
+   * This operation is undoable.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginMoveArgs.componentIds args.componentIds} — Array of component
+   *     ID strings to move
+   *   - {@linkcode PluginMoveArgs.displacement args.displacement} — Translation vector
+   *     as a {@linkcode PVec3} in Babylon units
+   * @throws If any component ID is not found in the scene
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * // Move a space 10 units along the X axis
+   * await snaptrude.tools.transform.move({
+   *   componentIds: ["some-space-id"],
+   *   displacement: vec3.new(10, 0, 0),
+   * })
+   * ```
+   */
   public abstract move({
     componentIds,
     displacement,
   }: PluginMoveArgs): PluginApiReturn<void>
 
+  /**
+   * Rotate components around an axis through a pivot point.
+   *
+   * Each component is rotated by {@linkcode PluginRotateArgs.angle angle}
+   * radians around the {@linkcode PluginRotateArgs.axis axis} vector,
+   * pivoting about the {@linkcode PluginRotateArgs.pivot pivot} point.
+   * This operation is undoable.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginRotateArgs.componentIds args.componentIds} — Array of component
+   *     ID strings to rotate
+   *   - {@linkcode PluginRotateArgs.angle args.angle} — Rotation angle in **radians**
+   *   - {@linkcode PluginRotateArgs.axis args.axis} — Rotation axis as a {@linkcode PVec3}
+   *   - {@linkcode PluginRotateArgs.pivot args.pivot} — Pivot point as a {@linkcode PVec3}
+   *     in Babylon units
+   * @throws If any component ID is not found in the scene
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * // Rotate a space 45° around the Y axis at the origin
+   * await snaptrude.tools.transform.rotate({
+   *   componentIds: ["some-space-id"],
+   *   angle: Math.PI / 4,
+   *   axis: vec3.new(0, 1, 0),
+   *   pivot: vec3.new(0, 0, 0),
+   * })
+   * ```
+   */
   public abstract rotate({
     componentIds,
     angle,
@@ -18,6 +82,14 @@ export abstract class PluginTransformApi {
   }: PluginRotateArgs): PluginApiReturn<void>
 }
 
+/**
+ * Arguments for {@linkcode PluginTransformApi.move}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `string[]` | Component IDs to move |
+ * | `displacement` | {@linkcode PVec3} | Translation vector in Babylon units |
+ */
 export const PluginMoveArgs = z.object({
   componentIds: z.array(z.string()),
   displacement: PVec3,
@@ -25,6 +97,16 @@ export const PluginMoveArgs = z.object({
 
 export type PluginMoveArgs = z.infer<typeof PluginMoveArgs>
 
+/**
+ * Arguments for {@linkcode PluginTransformApi.rotate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `string[]` | Component IDs to rotate |
+ * | `angle` | `number` | Rotation angle in radians |
+ * | `axis` | {@linkcode PVec3} | Rotation axis direction |
+ * | `pivot` | {@linkcode PVec3} | Pivot point in Babylon units |
+ */
 export const PluginRotateArgs = z.object({
   componentIds: z.array(z.string()),
   angle: z.number(),

package/src/api/units/index.ts

@@ -1,23 +1,41 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 
+/**
+ * Unit conversion between real-world units and Snaptrude's internal
+ * (Babylon) coordinate system.
+ *
+ * Snaptrude uses an internal unit system (Babylon units) for all
+ * coordinates and dimensions. Use these methods to convert between
+ * real-world measurements and Babylon units.
+ *
+ * Accessed via `snaptrude.units`.
+ */
 export abstract class PluginUnitsApi {
   constructor() {}
 
   /**
-   * Convert a value from the given unit to Snaptrude's internal (Babylon) units.
+   * Convert a value from a real-world unit to Snaptrude's internal (Babylon) units.
    *
    * Use this when you have a measurement in real-world units (e.g. meters, feet)
    * and need to convert it to the coordinate system used by Snaptrude internally.
    *
-   * @param args.unit - The source unit to convert from (e.g. `"meters"`, `"feet-inches"`)
-   * @param args.value - The numeric value in the source unit
-   * @returns An object containing the converted `value` in Snaptrude/Babylon units
+   * @param args - An object containing:
+   *   - {@linkcode PluginUnitsConvertFromArgs.unit args.unit} — The source unit
+   *     to convert from. See {@linkcode PUnitType} for supported values.
+   *   - {@linkcode PluginUnitsConvertFromArgs.value args.value} — The numeric
+   *     value in the source unit
+   * @returns A {@linkcode PluginUnitsConvertFromResult} containing the converted
+   *   `value` in Babylon units
    *
-   * @example
+   * # Example
    * ```ts
+   * // Convert 5 meters to Babylon units for use in API calls
    * const result = await snaptrude.units.convertFrom({ unit: "meters", value: 5 })
-   * // result.value is 5 meters expressed in Babylon units
+   * const { spaceId } = await snaptrude.entity.space.createRectangular({
+   *   position: snaptrude.core.math.vec3.new(0, 0, 0),
+   *   dimensions: { width: result.value, height: result.value, depth: result.value },
+   * })
    * ```
    */
   public abstract convertFrom(
@@ -25,19 +43,30 @@ export abstract class PluginUnitsApi {
   ): PluginApiReturn<PluginUnitsConvertFromResult>
 
   /**
-   * Convert a value from Snaptrude's internal (Babylon) units to the given unit.
+   * Convert a value from Snaptrude's internal (Babylon) units to a real-world unit.
    *
    * Use this when you have a value in Snaptrude's internal coordinate system
    * and need to express it in real-world units (e.g. meters, feet).
    *
-   * @param args.unit - The target unit to convert to (e.g. `"meters"`, `"feet-inches"`)
-   * @param args.value - The numeric value in Snaptrude/Babylon units
-   * @returns An object containing the converted `value` in the target unit
+   * @param args - An object containing:
+   *   - {@linkcode PluginUnitsConvertToArgs.unit args.unit} — The target unit
+   *     to convert to. See {@linkcode PUnitType} for supported values.
+   *   - {@linkcode PluginUnitsConvertToArgs.value args.value} — The numeric
+   *     value in Babylon units
+   * @returns A {@linkcode PluginUnitsConvertToResult} containing the converted
+   *   `value` in the target unit
    *
-   * @example
+   * # Example
    * ```ts
-   * const result = await snaptrude.units.convertTo({ unit: "feet-inches", value: 1.2 })
-   * // result.value is 1.2 Babylon units expressed in feet
+   * // Get a space's area in square meters
+   * const info = await snaptrude.entity.space.get({
+   *   spaceId: "some-id",
+   *   properties: ["area"],
+   * })
+   * const areaInMeters = await snaptrude.units.convertTo({
+   *   unit: "meters",
+   *   value: info.area!,
+   * })
    * ```
    */
   public abstract convertTo(
@@ -68,6 +97,14 @@ export const PUnitType = z.enum([
 
 export type PUnitType = z.infer<typeof PUnitType>
 
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convertFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `unit` | {@linkcode PUnitType} | Source real-world unit |
+ * | `value` | `number` | Numeric value in the source unit |
+ */
 export const PluginUnitsConvertFromArgs = z.object({
   unit: PUnitType,
   value: z.number(),
@@ -75,12 +112,27 @@ export const PluginUnitsConvertFromArgs = z.object({
 
 export type PluginUnitsConvertFromArgs = z.infer<typeof PluginUnitsConvertFromArgs>
 
+/**
+ * Result of {@linkcode PluginUnitsApi.convertFrom}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The converted value in Babylon units |
+ */
 export const PluginUnitsConvertFromResult = z.object({
   value: z.number(),
 })
 
 export type PluginUnitsConvertFromResult = z.infer<typeof PluginUnitsConvertFromResult>
 
+/**
+ * Arguments for {@linkcode PluginUnitsApi.convertTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `unit` | {@linkcode PUnitType} | Target real-world unit |
+ * | `value` | `number` | Numeric value in Babylon units |
+ */
 export const PluginUnitsConvertToArgs = z.object({
   unit: PUnitType,
   value: z.number(),
@@ -88,6 +140,13 @@ export const PluginUnitsConvertToArgs = z.object({
 
 export type PluginUnitsConvertToArgs = z.infer<typeof PluginUnitsConvertToArgs>
 
+/**
+ * Result of {@linkcode PluginUnitsApi.convertTo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The converted value in the target unit |
+ */
 export const PluginUnitsConvertToResult = z.object({
   value: z.number(),
 })

package/src/types.ts

@@ -1,9 +1,16 @@
 /**
- * A ComponentId is a unique identifier for a component in the scene.
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
  */
 export type ComponentId = string
 
 /**
  * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
  */
 export type PluginApiReturn<T> = Promise<T> | T