<!--
{
  "availability" : [
    "iOS: 18.0.0 -",
    "iPadOS: 18.0.0 -",
    "macCatalyst: 18.0.0 -",
    "macOS: 15.0.0 -",
    "tvOS: 26.0.0 -",
    "visionOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "RealityKit",
  "identifier" : "/documentation/RealityKit/BillboardAction",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "RealityKit"
    ],
    "preciseIdentifier" : "s:17RealityFoundation15BillboardActionV"
  },
  "title" : "BillboardAction"
}
-->

# BillboardAction

An action that animates the blend factor of an entity’s billboard component.

```
struct BillboardAction
```

## Overview

This action animates the [`blendFactor`](/documentation/RealityKit/BillboardComponent/blendFactor) value of an
entity’s [`BillboardComponent`](/documentation/RealityKit/BillboardComponent).

Over its duration, the action updates the `blendFactor` property to `1.0`.
If you provide a [`transitionIn`](/documentation/RealityKit/BillboardAction/transitionIn) configuration,
the action interpolates the value of the component’s current value for
[`blendFactor`](/documentation/RealityKit/BillboardComponent/blendFactor) towards `1.0`.
If you provide a [`transitionOut`](/documentation/RealityKit/BillboardAction/transitionOut) configuration,
the action interpolates the component’s [`blendFactor`](/documentation/RealityKit/BillboardComponent/blendFactor) value from `1.0` to its
original value for that component.

The example below creates a three-part animation that:

- Interpolates [`blendFactor`](/documentation/RealityKit/BillboardComponent/blendFactor) from `0.0` to `1.0`
- Pauses for one second
- Interpolates [`blendFactor`](/documentation/RealityKit/BillboardComponent/blendFactor) from `1.0` back to `0.0`

```swift
// Load a robot model from a resource file.
let robotModel = try await ModelEntity(named: "vintage_robot")

// A billboard component for the robot model entity.
var billboardComponent = BillboardComponent()

// Disable the billboard at the beginning by setting its blend factor to zero.
billboardComponent.blendFactor = 0.0

// Add the component to the entity.
await robotModel.components.set(billboardComponent)

// A transition that lasts one second.
let billboardTransition = BillboardAction.Transition(
    duration: 1.0,
    timingFunction: .easeInOut
)

// An action that starts and ends with a one second transition.
let billboardAction = BillboardAction(transitionIn: billboardTransition,
                                      transitionOut: billboardTransition)

// A three second animation that adjusts the blend factor twice.
//
// This animation includes a one second pause between both of the action's
// one second transitions in and out by setting the duration one second
// longer than action's total time.
let billboardAnimation = try AnimationResource
    .makeActionAnimation(for: billboardAction,
                         duration: 3.0,
                         bindTarget: .billboardBlendFactor)

// Play the three second billboard animation that adjusts the blend factor.
robotModel.playAnimation(billboardAnimation)
```

![A screen recording of a vintage-style robot toy in a living room scene. At the start, the robot isn't looking at the camera, then its body moves in place to look at the camera, stays still for one second, and its body moves back to its original orientation.](videos/com.apple.RealityKit/billboardaction-simple-loop~dark.mp4)

> Note: If an entity doesn’t have a ``doc://com.apple.RealityKit/documentation/RealityKit/BillboardComponent``, the default
> initializer creates one for you so that it can restore the entity
> back to a state without the billboard.

> Important: This action directly animates the ``doc://com.apple.RealityKit/documentation/RealityKit/BindTarget/billboardBlendFactor`` on the bound entity.
> Ensure a correct bind target is supplied when creating the animation.

Ensure the action can transition back to a non-billboard state by adding
the component to the entity and check the
[`blendFactor`](/documentation/RealityKit/BillboardComponent/blendFactor)
property has a value that you expect.

## Topics

### Structures

[`struct Transition`](/documentation/RealityKit/BillboardAction/Transition)

The duration and timing of how an action event transitions from one
state to another.

### Initializers

[`init(transitionIn: BillboardAction.Transition, transitionOut: BillboardAction.Transition)`](/documentation/RealityKit/BillboardAction/init(transitionIn:transitionOut:))

Creates a new billboard action.

### Instance Properties

[`var animatedValueType: (any AnimatableData.Type)?`](/documentation/RealityKit/BillboardAction/animatedValueType)

The type for the value that the action modifies over time.

[`var transitionIn: BillboardAction.Transition`](/documentation/RealityKit/BillboardAction/transitionIn)

The rate of change at the beginning of the action.

[`var transitionOut: BillboardAction.Transition`](/documentation/RealityKit/BillboardAction/transitionOut)

The rate of change at the end of the action.

## Relationships

### Conforms To

[`EntityAction`](/documentation/RealityKit/EntityAction)

[`Encodable`](/documentation/Swift/Encodable)

[`Decodable`](/documentation/Swift/Decodable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)