@hology/core 0.0.179 → 0.0.180

package/dist/scene/model.d.ts

@@ -41,15 +41,30 @@ export declare enum SerializedParamType {
     Curve = 22,
     ColorLayer = 23,
     MaskLayer = 24,
-    Prefab = 25
+    Prefab = 25,
+    PrefabActor = 26
 }
 export type CustomParamValue = {
     type: SerializedParamType;
     value: unknown;
+    /**
+     * When true, this value explicitly overrides any default.
+     * When false or undefined, the parameter uses its default value.
+     * Only meaningful in contexts where overrides are supported
+     * (prefab instances, actor params with optional).
+     */
+    override?: boolean;
 } | {
     type: SerializedParamType.Array;
     element: SerializedParamType;
     value: unknown[];
+    /**
+     * When true, this value explicitly overrides any default.
+     * When false or undefined, the parameter uses its default value.
+     * Only meaningful in contexts where overrides are supported
+     * (prefab instances, actor params with optional).
+     */
+    override?: boolean;
 };
 /**
  * This serialized float param value take take multiple forms
@@ -161,7 +176,28 @@ export type Asset = {
     };
     /** Prefab settings only for asset type prefab */
     prefab?: {
+        /**
+         * Objects that make up the prefab. These are the canonical structural data
+         * for the prefab asset. Structure (components, child actors) lives in the
+         * prefab and cannot be changed per-instance.
+         */
         objects: SceneObject[];
+        /**
+         * Optional: the local id (within `objects`) of the single actor that the
+         * prefab exposes as its identity. When set, the prefab exposes exactly one
+         * actor. Prefab instances behave like instances of that actor type for the
+         * purposes of typed references and parameter overrides.
+         *
+         * Important semantics:
+         * - This id is local to the prefab asset's object graph and must not be
+         *   treated as a global actor id.
+         * - A prefab may expose zero or one actor. Multiple exposed actors are not
+         *   supported.
+         * - External references should point to the prefab instance id (not this
+         *   internal actor id). At runtime, resolving a reference to a prefab
+         *   instance returns the exposed actor instance inside the prefab.
+         */
+        mainActorId?: string;
     };
     components?: AttachedComponent[];
     /** Texture settings only for asset type texture */
@@ -213,4 +249,58 @@ export interface SceneBlobV0 {
     data: string;
     sceneId: string;
 }
+/**
+ * A lightweight reference that may point to either a concrete actor id or a
+ * prefab instance id. Gameplay code should resolve this transparently:
+ * - If it points to an actor id, return that actor.
+ * - If it points to a prefab instance id, return the exposed actor instance
+ *   inside the prefab (if any).
+ *
+ * Important: Prefab assets internally identify actors using local ids. External
+ * references must never store those internal ids directly; they should store
+ * the global actor id or the prefab instance id instead.
+ */
+export type ActorReference = {
+    type: 'actor';
+    id: string;
+} | {
+    type: 'prefab';
+    id: string;
+};
+/**
+ * Representation of a prefab instance within a scene. Prefab instances are
+ * stable identities that reference a prefab asset and may provide data-only
+ * overrides for the prefab's exposed actor.
+ *
+ * - `params` maps actor parameter paths to serialized values. Only
+ *   parameter values are allowed to vary per-instance; structural changes are
+ *   not permitted here.
+ */
+export type PrefabInstanceSettings = {
+    /**
+     * Map from actor parameter path -> serialized value. Keys are editor-specific
+     * parameter path strings (for example, a path to the exposed actor's param).
+     * Values are serialized using the existing CustomParamValue format where
+     * appropriate, or primitives for simple types.
+     */
+    params?: Record<string, CustomParamValue>;
+    /**
+     * Per-inner-component overrides for the exposed actor. Stored in the same
+     * shape as `ActorSettings.innerParams` so it mirrors actor-local inner
+     * parameter groups.
+     *
+     * Example:
+     * [ { path: ['gun','mesh'], params: { color: { type: SerializedParamType.Color, value: '#fff' } } } ]
+     */
+    innerParams?: {
+        path: string[];
+        params: Record<string, CustomParamValue>;
+    }[];
+    /**
+     * Optional denormalized copy of the prefab asset's mainActorId to make
+     * lookups inexpensive. This is informational and can be derived from the
+     * prefab asset; it is not authoritative for prefab structure.
+     */
+    mainActorId?: string;
+};
 //# sourceMappingURL=model.d.ts.map

package/dist/scene/model.js

@@ -1,4 +1,4 @@
-export var DetailTier;!function(e){e[e.low=0]="low",e[e.medium=1]="medium",e[e.high=2]="high"}(DetailTier||(DetailTier={}));export var SerializedParamType;!function(e){e[e.FloatNode=0]="FloatNode",e[e.Number=1]="Number",e[e.Texture=2]="Texture",e[e.Sampler2DNode=3]="Sampler2DNode",e[e.Boolean=4]="Boolean",e[e.BooleanNode=5]="BooleanNode",e[e.Vector2=6]="Vector2",e[e.Vec2Node=7]="Vec2Node",e[e.Vector3=8]="Vector3",e[e.Vec3Node=9]="Vec3Node",e[e.Color=10]="Color",e[e.RgbNode=11]="RgbNode",e[e.String=12]="String",e[e.BaseActor=13]="BaseActor",e[e.Euler=14]="Euler",e[e.Object3D=15]="Object3D",e[e.Material=16]="Material",e[e.AudioBuffer=17]="AudioBuffer",e[e.Vector4=18]="Vector4",e[e.Vec4Node=19]="Vec4Node",e[e.VisualEffect=20]="VisualEffect",e[e.Array=21]="Array",e[e.Curve=22]="Curve",e[e.ColorLayer=23]="ColorLayer",e[e.MaskLayer=24]="MaskLayer",e[e.Prefab=25]="Prefab"}(SerializedParamType||(SerializedParamType={}));/*
+export var DetailTier;!function(e){e[e.low=0]="low",e[e.medium=1]="medium",e[e.high=2]="high"}(DetailTier||(DetailTier={}));export var SerializedParamType;!function(e){e[e.FloatNode=0]="FloatNode",e[e.Number=1]="Number",e[e.Texture=2]="Texture",e[e.Sampler2DNode=3]="Sampler2DNode",e[e.Boolean=4]="Boolean",e[e.BooleanNode=5]="BooleanNode",e[e.Vector2=6]="Vector2",e[e.Vec2Node=7]="Vec2Node",e[e.Vector3=8]="Vector3",e[e.Vec3Node=9]="Vec3Node",e[e.Color=10]="Color",e[e.RgbNode=11]="RgbNode",e[e.String=12]="String",e[e.BaseActor=13]="BaseActor",e[e.Euler=14]="Euler",e[e.Object3D=15]="Object3D",e[e.Material=16]="Material",e[e.AudioBuffer=17]="AudioBuffer",e[e.Vector4=18]="Vector4",e[e.Vec4Node=19]="Vec4Node",e[e.VisualEffect=20]="VisualEffect",e[e.Array=21]="Array",e[e.Curve=22]="Curve",e[e.ColorLayer=23]="ColorLayer",e[e.MaskLayer=24]="MaskLayer",e[e.Prefab=25]="Prefab",e[e.PrefabActor=26]="PrefabActor"}(SerializedParamType||(SerializedParamType={}));/*
  * Copyright (©) 2025 Hology Interactive AB. All rights reserved.
  * See the LICENSE.md file for details.
  */

package/dist/scene/objects/prefab.d.ts

@@ -1,11 +1,16 @@
 import { Object3D } from "three";
-import { Asset } from "../model";
 import { BaseActor } from "../../gameplay/actors/actor.js";
+import { Asset } from "../model";
 export declare class Prefab {
     asset: Asset;
 }
 export declare class PrefabInstance {
     object: Object3D;
     actors: BaseActor[];
+    mainActor: BaseActor | null;
+}
+export declare class PrefabOf<T extends BaseActor> {
+    readonly prefab: Prefab;
+    constructor(prefab: Prefab);
 }
 //# sourceMappingURL=prefab.d.ts.map

package/dist/scene/objects/prefab.js

@@ -1,4 +1,4 @@
-export class Prefab{constructor(s){this.asset=s}}export class PrefabInstance{}/*
+export class Prefab{constructor(s){this.asset=s}}export class PrefabInstance{}export class PrefabOf{constructor(s){this.prefab=s}}/*
  * Copyright (©) 2025 Hology Interactive AB. All rights reserved.
  * See the LICENSE.md file for details.
  */

package/dist/shader/parameter.d.ts

@@ -4,10 +4,10 @@ import { BaseActor } from '../gameplay/actors/actor.js';
 import { Color, Euler, Material, Object3D, Texture, Vector2, Vector3, Vector4 } from 'three';
 import { BooleanNode, FloatNode, RgbNode, Sampler2DNode, Vec2Node, Vec3Node, Vec4Node } from '../shader-nodes/index.js';
 import { VisualEffect } from '../effects/vfx/vfx-param.js';
-import { Prefab } from '../scene/objects/prefab.js';
+import { Prefab, PrefabOf } from '../scene/objects/prefab.js';
 import { Curve2 } from '../utils/curve.js';
 import { ColorLayer, MaskLayer } from './color-layer.js';
-export type ParameterType = Type<FloatNode | Number | Texture | Sampler2DNode | Boolean | BooleanNode | Vector2 | Vec2Node | Vector3 | Vec3Node | Vector4 | Vec4Node | Color | RgbNode | String | BaseActor | Euler | Object3D | Material | VisualEffect | Prefab | Curve2 | ColorLayer | MaskLayer>;
+export type ParameterType = Type<FloatNode | Number | Texture | Sampler2DNode | Boolean | BooleanNode | Vector2 | Vec2Node | Vector3 | Vec3Node | Vector4 | Vec4Node | Color | RgbNode | String | BaseActor | Euler | Object3D | Material | VisualEffect | Prefab | PrefabOf<BaseActor> | Curve2 | ColorLayer | MaskLayer>;
 export type ParameterOption<T> = {
     name: string;
     value: T;
@@ -24,6 +24,24 @@ export interface ParameterOptions {
     help?: string;
     /** Only show this parameter when the specified properties have the required values */
     requires?: Record<string, unknown>;
+    /**
+     * When true, enables override mode for this parameter.
+     * The parameter will show an override checkbox in the editor,
+     * allowing the user to explicitly opt-in to overriding the default value.
+     */
+    optional?: boolean;
+    /**
+     * Restrict prefabs to be possible to select to those that have a main actor
+     * that inherits from the given actor class.
+     * This option should be used together with the property type PrefabOf<T>
+     * The property value can then be using in world.spawnActor which instantiates
+     * the prefab and returns the actor with a correct type.
+     *
+     * Example:
+     * @Parameter({prefabOf: BaseActor})
+     * prefab: PrefabOf<BaseActor>
+     */
+    prefabOf?: Type<BaseActor>;
 }
 export interface PropertyParameter {
     name: string;

package/dist/shader/parameter.js

@@ -1,4 +1,4 @@
-import"reflect-metadata";import{reflect as t,decorateProperty as e}from"@plumier/reflect";import{ArrayMap as r}from"../utils/collections.js";Symbol("format");class o{constructor(t){this.options=t,this.isParameterDecorator=!0}}new Map;const a=new r;export function Parameter(t){return function(r,n,c){if(null!=r){a.push(r.constructor,{name:n,options:t??{}});try{e(new o(t))(r,n,c)}catch(t){console.warn("Failed to decorate method ",r,n,c)}}}}export function extractShaderParameters(t){if(null==t)return[];const e=a.get(t).map(({name:e,options:r})=>{const o=Reflect.getMetadata("design:type",t.prototype,e),a=r.type??o;return r.array=o===Array,{name:e,type:a,options:r}});return[...extractShaderParameters(Object.getPrototypeOf(t)).filter(t=>e.every(e=>e.name!==t.name)),...e]}export function ParameterCategory(t){}/*
+import"reflect-metadata";import{reflect as t,decorateProperty as e}from"@plumier/reflect";import{ArrayMap as r}from"../utils/collections.js";Symbol("format");class o{constructor(t){this.options=t,this.isParameterDecorator=!0}}new Map;const a=new r;export function Parameter(t){return function(r,n,c){if(null!=r){a.push(r.constructor,{name:n,options:t??{}});try{e(new o(t))(r,n,c)}catch(t){console.warn("Failed to decorate method ",r,n,c)}}}}export function extractShaderParameters(t){if(null==t)return[];const e=a.get(t).map(({name:e,options:r})=>{const o=Reflect.getMetadata("design:type",t.prototype,e),a=r.type??o,n=Reflect.getMetadata("prefab:type",t.prototype,e);return r.prefabOf??(r.prefabOf=n),r.array=o===Array,{name:e,type:a,options:r}});return[...extractShaderParameters(Object.getPrototypeOf(t)).filter(t=>e.every(e=>e.name!==t.name)),...e]}export function ParameterCategory(t){}/*
  * Copyright (©) 2025 Hology Interactive AB. All rights reserved.
  * See the LICENSE.md file for details.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hology/core",
-  "version": "0.0.179",
+  "version": "0.0.180",
   "description": "",
   "main": "dist/index.js",
   "type": "module",