feat(voxel-renderer): implement APIs for object layers (#232)

Author: fraxken

.changeset/sour-ghosts-feel.md

@@ -0,0 +1,5 @@
+---
+"@jolly-pixel/voxel.renderer": minor
+---
+
+Implement new APIs to manage object layers

packages/voxel-renderer/docs/Hooks.md

@@ -26,13 +26,21 @@ const vr = new VoxelRenderer({
 
 ```ts
 export type VoxelLayerHookAction =
-  | "added"
-  | "removed"
-  | "updated"
-  | "offset-updated"
-  | "voxel-set"
-  | "voxel-removed"
-  | "reordered";
+  // Voxel-layer actions
+  | "added"            // a voxel layer was created
+  | "removed"          // a voxel layer was deleted
+  | "updated"          // layer properties (visibility, …) changed
+  | "offset-updated"   // layer world offset changed
+  | "voxel-set"        // a voxel was placed in a layer
+  | "voxel-removed"    // a voxel was removed from a layer
+  | "reordered"        // layer render order changed
+  // Object-layer actions
+  | "object-layer-added"   // a new object layer was created
+  | "object-layer-removed" // an object layer was deleted
+  | "object-layer-updated" // object layer properties (e.g. visibility) changed
+  | "object-added"         // an object was added to an object layer
+  | "object-removed"       // an object was removed from an object layer
+  | "object-updated";      // an object's properties were patched
 
 // Describes a change related to a layer.
 export interface VoxelLayerHookEvent {

packages/voxel-renderer/docs/Serialization.md

@@ -46,9 +46,21 @@ interface VoxelLayerJSON {
  * and are loaded as if offset is {0,0,0} — identical to the previous behaviour.
  */
 
+/**
+ * Flat key/value bag for custom object properties.
+ * Only primitive scalars (string, number, boolean) survive the round-trip.
+ */
+type VoxelObjectProperties = Record<string, string | number | boolean>;
+
+/**
+ * A single named object placed in the world (spawn point, trigger zone, …).
+ * Coordinates are in voxel/tile space; floats are allowed for sub-tile precision.
+ * `y` is 0 for maps imported from a flat 2-D source.
+ */
 interface VoxelObjectJSON {
-  id: number;
+  id: string;
   name: string;
+  /** Optional semantic type tag (e.g. "SpawnPoint", "Trigger"). */
   type?: string;
   x: number;
   y: number;
@@ -60,16 +72,15 @@ interface VoxelObjectJSON {
   properties?: VoxelObjectProperties;
 }
 
+/** A named layer that holds placed objects rather than voxel data. */
 interface VoxelObjectLayerJSON {
-  id: number;
+  id: string;
   name: string;
   visible: boolean;
   order: number;
   objects: VoxelObjectJSON[];
 }
 
-type VoxelObjectProperties = Record<string, string | number | boolean>;
-
 interface VoxelWorldJSON {
   version: 1;
   chunkSize: number;
@@ -79,7 +90,11 @@ interface VoxelWorldJSON {
    * Auto-registered on load.
    **/
   blocks?: BlockDefinition[];
-  /** Object layers produced by converters from Tiled object layers. */
+  /**
+   * Named object layers (spawn points, triggers, etc.).
+   * Present in converter output and in files saved after object layers
+   * were added at runtime via VoxelRenderer.addObjectLayer().
+   */
   objectLayers?: VoxelObjectLayerJSON[];
 }
 ```
@@ -95,4 +110,5 @@ Converts the world and tileset metadata to a plain JSON-serialisable object.
 
 #### `deserialize(data: VoxelWorldJSON, world: VoxelWorld): void`
 
-Clears `world` and restores it from a snapshot. Throws if `data.version !== 1`.
+Clears `world` and restores it from a snapshot. Voxel layers and object layers are
+both restored. Throws if `data.version !== 1`.

packages/voxel-renderer/docs/VoxelRenderer.md

@@ -271,6 +271,49 @@ referenced tilesets that are not already loaded.
 
 Mark all the chunks as dirty and rebuild them in the next frame
 
+### Object Layer API
+
+Object layers hold placed objects (spawn points, trigger zones, etc.) rather than voxel
+data. Each mutating method fires a `VoxelLayerHookEvent` so external systems stay in sync.
+
+#### `addObjectLayer(name: string, options?: { visible?: boolean; order?: number }): VoxelObjectLayerJSON`
+
+Creates a new object layer in the world and fires `"object-layer-added"`.
+Returns the new layer descriptor.
+
+#### `removeObjectLayer(name: string): boolean`
+
+Removes an object layer from the world. Fires `"object-layer-removed"` on success.
+Returns `false` if not found.
+
+#### `getObjectLayer(name: string): VoxelObjectLayerJSON | undefined`
+
+Returns the layer descriptor for `name`, or `undefined` if it does not exist.
+
+#### `getObjectLayers(): readonly VoxelObjectLayerJSON[]`
+
+Returns a snapshot array of all object layers in insertion order.
+
+#### `updateObjectLayer(name: string, patch: { visible?: boolean }): boolean`
+
+Applies a partial patch to a named object layer and fires `"object-layer-updated"`.
+Returns `false` if not found.
+
+#### `addObject(layerName: string, object: VoxelObjectJSON): boolean`
+
+Appends an object to the named layer and fires `"object-added"`.
+Returns `false` if the layer does not exist.
+
+#### `removeObject(layerName: string, objectId: string): boolean`
+
+Removes the object with the given `id` from the layer and fires `"object-removed"`.
+Returns `false` if the layer or object is not found.
+
+#### `updateObject(layerName: string, objectId: string, patch: Partial<VoxelObjectJSON>): boolean`
+
+Merges `patch` into the matching object and fires `"object-updated"`.
+Returns `false` if the layer or object is not found.
+
 ### Hooks
 
 See [Hooks](./Hooks.md) for more information

packages/voxel-renderer/docs/World.md

@@ -110,5 +110,46 @@ Iterates over chunks whose `dirty` flag is set.
 
 #### `clear(): void`
 
-Removes all layers.
+Removes all voxel layers and object layers.
+
+### Object Layer Management
+
+Object layers hold placed objects (spawn points, trigger zones, etc.) rather than
+voxel data. They are stored by name and serialised as part of `VoxelWorldJSON`.
+
+#### `addObjectLayer(name: string, options?: { visible?: boolean; order?: number }): VoxelObjectLayerJSON`
+
+Creates a new object layer. `order` defaults to the current layer count (appended last).
+Returns the new layer descriptor.
+
+#### `removeObjectLayer(name: string): boolean`
+
+Deletes an object layer by name. Returns `false` if not found.
+
+#### `getObjectLayer(name: string): VoxelObjectLayerJSON | undefined`
+
+Returns the layer descriptor for `name`, or `undefined` if it does not exist.
+
+#### `getObjectLayers(): readonly VoxelObjectLayerJSON[]`
+
+Returns a snapshot array of all object layers in insertion order.
+
+#### `updateObjectLayer(name: string, patch: { visible?: boolean }): boolean`
+
+Applies a partial patch to a named object layer. Returns `false` if not found.
+
+#### `addObjectToLayer(layerName: string, object: VoxelObjectJSON): boolean`
+
+Appends an object to the named layer's `objects` array. Returns `false` if the layer
+does not exist.
+
+#### `removeObjectFromLayer(layerName: string, objectId: string): boolean`
+
+Removes the object with the given `id` from the layer. Returns `false` if the layer or
+object is not found.
+
+#### `updateObjectInLayer(layerName: string, objectId: string, patch: Partial<VoxelObjectJSON>): boolean`
+
+Merges `patch` into the matching object. Returns `false` if the layer or object is not
+found.
 

packages/voxel-renderer/src/VoxelRenderer.ts

@@ -28,7 +28,9 @@ import {
 import { VoxelMeshBuilder } from "./mesh/VoxelMeshBuilder.ts";
 import {
   VoxelSerializer,
-  type VoxelWorldJSON
+  type VoxelWorldJSON,
+  type VoxelObjectLayerJSON,
+  type VoxelObjectJSON
 } from "./serialization/VoxelSerializer.ts";
 import {
   TilesetManager,
@@ -477,6 +479,112 @@ export class VoxelRenderer extends ActorComponent {
     return layer.centerToWorld();
   }
 
+  // --- Object Layer API --- //
+
+  addObjectLayer(
+    name: string,
+    options?: Partial<Pick<VoxelObjectLayerJSON, "visible" | "order">>
+  ): VoxelObjectLayerJSON {
+    const layer = this.world.addObjectLayer(name, options);
+    this.#onLayerUpdated?.({
+      action: "object-layer-added",
+      layerName: name,
+      metadata: {}
+    });
+
+    return layer;
+  }
+
+  removeObjectLayer(
+    name: string
+  ): boolean {
+    const result = this.world.removeObjectLayer(name);
+    if (result) {
+      this.#onLayerUpdated?.({
+        action: "object-layer-removed",
+        layerName: name,
+        metadata: {}
+      });
+    }
+
+    return result;
+  }
+
+  getObjectLayer(
+    name: string
+  ): VoxelObjectLayerJSON | undefined {
+    return this.world.getObjectLayer(name);
+  }
+
+  getObjectLayers(): readonly VoxelObjectLayerJSON[] {
+    return this.world.getObjectLayers();
+  }
+
+  updateObjectLayer(
+    name: string,
+    patch: Partial<Pick<VoxelObjectLayerJSON, "visible">>
+  ): boolean {
+    const result = this.world.updateObjectLayer(name, patch);
+    if (result) {
+      this.#onLayerUpdated?.({
+        action: "object-layer-updated",
+        layerName: name,
+        metadata: { patch }
+      });
+    }
+
+    return result;
+  }
+
+  addObject(
+    layerName: string,
+    object: VoxelObjectJSON
+  ): boolean {
+    const result = this.world.addObjectToLayer(layerName, object);
+    if (result) {
+      this.#onLayerUpdated?.({
+        action: "object-added",
+        layerName,
+        metadata: { objectId: object.id }
+      });
+    }
+
+    return result;
+  }
+
+  removeObject(
+    layerName: string,
+    objectId: string
+  ): boolean {
+    const result = this.world.removeObjectFromLayer(layerName, objectId);
+    if (result) {
+      this.#onLayerUpdated?.({
+        action: "object-removed",
+        layerName,
+        metadata: { objectId }
+      });
+    }
+
+    return result;
+  }
+
+  updateObject(
+    layerName: string,
+    objectId: string,
+    patch: Partial<VoxelObjectJSON>
+  ): boolean {
+    const result = this.world.updateObjectInLayer(layerName, objectId, patch);
+    if (result) {
+      this.#onLayerUpdated?.({
+        action: "object-updated",
+        layerName,
+        metadata: { objectId, patch }
+      });
+    }
+
+    return result;
+  }
+
   async loadTileset(
     def: TilesetDefinition
   ): Promise<void> {

packages/voxel-renderer/src/hooks.ts

@@ -5,7 +5,13 @@ export type VoxelLayerHookAction =
   | "offset-updated"
   | "voxel-set"
   | "voxel-removed"
-  | "reordered";
+  | "reordered"
+  | "object-layer-added"
+  | "object-layer-removed"
+  | "object-layer-updated"
+  | "object-added"
+  | "object-removed"
+  | "object-updated";
 
 export interface VoxelLayerHookEvent {
   layerName: string;

packages/voxel-renderer/src/serialization/VoxelSerializer.ts

@@ -77,7 +77,8 @@ export class VoxelSerializer {
       tilesets: tilesetManager.getDefinitions(),
       layers: world
         .getLayers()
-        .map((layer) => layer.toJSON())
+        .map((layer) => layer.toJSON()),
+      objectLayers: [...world.getObjectLayers()]
     };
   }
 
@@ -133,5 +134,15 @@ export class VoxelSerializer {
         layer.setVoxelAt({ x, y, z }, entry);
       }
     }
+
+    for (const layerJSON of data.objectLayers ?? []) {
+      const layer = world.addObjectLayer(layerJSON.name, {
+        visible: layerJSON.visible,
+        order: layerJSON.order
+      });
+
+      layer.id = layerJSON.id;
+      layer.objects = [...layerJSON.objects];
+    }
   }
 }