Actor parameters

Actor parameters are properties on actors that you can set in the editor for each instance of an actor. This allows you to control the functionality of an actor without having to change code.

Parameters can be created by adding the @Parameter() decorator on a property in your actor class. The type of the parameter will be inferred by your property's type annotation.

Supported Types

The example below shows all currently supported types.

@Actor()
class ActorWithParameters extends BaseActor {
    @Parameter() aNumber: number
    @Parameter() aBoolen: boolean
    @Parameter() aString: string
    @Parameter() vec2: THREE.Vector2
    @Parameter() vec3: THREE.Vector3
    @Parameter() color: THREE.Color
    @Parameter() rotation: THREE.Euler
    
    // An instance of a 3D model asset
    @Parameter() mesh: THREE.Object3D
    
    // An instance of a material
    @Parameter() material: THREE.Material
    
    // An audio buffer from an audio asset
    @Parameter() audio: AudioBuffer
    
    @Parameter() clip: THREE.AnimationClip
    
    // Refer to another actor in the scene. 
    // You can also use your own actor class to only be 
    // able to select actors of that type
    @Parameter() actor: BaseActor
    
    @Parameter() prefab: Prefab
    @Parameter() specificPrefab: PrefabOf<WeaponActor>
}

Parameter Options

You can pass a configuration object to the @Parameter() decorator to customize how the parameter behaves and appears in the editor.

interface ParameterOptions {
  label?: string      // Custom display name in the editor
  help?: string       // Tooltip text shown on hover
  
  // Number configuration
  range?: [min, max]  // Slider with minimum and maximum values
  stepSize?: number   // Increment size for the input
  precision?: number  // Number of decimal places
  
  // Logic
  optional?: boolean  // Adds a checkbox to enable/disable the parameter (override mode)
  requires?: Record<string, unknown> // Only show this parameter if another property matches a value
}

Examples

Numeric Sliders

Use range to create a slider constraint, which is helpful for values like percentage or intensity.

@Parameter({
  label: 'Movement Speed',
  range: [0, 100],
  stepSize: 1
})
speed: number = 10;

Optional Overrides

Use optional to allow a value to be null or undefined by default, unless explicitly enabled by the level designer. This is useful for overriding default behaviors.

@Parameter({
  optional: true,
  help: 'If enabled, this color will override the default team color'
})
customTint: THREE.Color;

Conditional Visibility

Use requires to declutter the editor UI by hiding parameters that aren't relevant based on other settings.

@Parameter()
canJump: boolean = false;

@Parameter({
  requires: { canJump: true } // Only visible when canJump is checked
})
jumpHeight: number = 2.0;

Prefab Types

Hology supports parameters that refer to prefab assets. While the generic Prefab type allows any prefab to be selected, the PrefabOf<T> type provides additional safety by restricting choices to prefabs that have a specific Main Actor Prefab main actor

For more details, see the PrefabOf actor documentation.