Actor Components

Overview

In the Unreal Engine, all game-related objects are derived from the base Actor class. In previous generations of the Unreal Engine, the base Actor class was very heavyweight and any Actor-derived subclass inherited all properties, regardless of their behavior.

Actor Components solve the problem by defining multiple lightweight components that provide an interface for modular extensibility of Actor rendering and collision.

Component prototypes are defined in the default properties of a class, using a modified version of sub-object syntax that was previously defined in Unreal Engine 2. The prototype is named, and is inherited by subclasses. A subclass can override some or all of the default properties of the prototype. To use the component, add it to the Actor’s Components array via the default properties. Component prototypes referenced in the default properties are instanced along with the Actor class. Default property changes are propagated to existing instances of an Actor class saved in a level.

Using Actor Components

ActorComponent versus PrimitiveComponent

An ActorComponent is an object which can be attached to an actor in the world.

A PrimitiveComponent is an ActorComponent which can be rendered and collided against.

Adding a Component

Any Actor that’s instanced has a SpriteComponent that’s instanced along with it (unless a subclass removes Sprite from its Components array).

Components referenced by the components array are bound to the Actor’s location.

Example:

class Actor extends Object;

var const array<ActorComponent>   Components;

defaultproperties
{
   Begin Object Class=SpriteComponent Name=Sprite
      Sprite=S_Actor
      HiddenGame=True
   End Object
   Components.Add(Sprite)
}

Modifying a Component

Example:

class Trigger extends Actor;

defaultproperties
{
   Begin Object Name=Sprite
      Sprite=S_Trigger
   End Object
}

Removing a Component

Example:

class StaticMeshActor extends Actor;

defaultproperties
{
   Components.Remove(Sprite)
   …
}

Since the Sprite component prototype is no longer referenced in the default properties of the StaticMeshActor class, it is not instanced with StaticMeshActors.

Component templates

Component templates are used to declare the default components of an actor class. A component template is a named object which contains the default properties for a component referenced in the default properties of a class. When the class is instanced, any component templates it references are instanced along with it.

Component templates are inherited by subclasses of the class in which they are declared. Each subclass can override individual properties of the inherited template.

An instance of a component template is serialized relative to the template's default properties. This allows instances of actor components to continue to receive changes to the template properties after being placed in a level.

Creating component templates

Component templates are declared in the default properties of a class:

Begin Object Class=SpriteComponent Name=Sprite
   Sprite=Texture2D'EngineResources.S_Actor'
   HiddenGame=True
   AlwaysLoadOnClient=False
   AlwaysLoadOnServer=False
End Object

Instancing and attaching component templates

A component template will not be instanced with the class unless it is referenced by the class's default properties, and an actor component will not be attached to an actor unless it is in the actor's Components array. You can instance an actor component template with an actor class and automatically attach the instanced component to the actor instance by adding the component template to the actor's Components array in the default properties:

Begin Object Class=SpriteComponent Name=Sprite
   // Sprite component properties are assigned values here
End Object
Components.Add(Sprite)

Changing properties of a component template inherited from a super class

Component templates are inherited by subclasses of the class the template is initially declared in. The subclass can override individual properties on inherited templates. This example inherits the Sprite template from Actor and modifies only the sprite texture property:

Begin Object Name=Sprite
   Sprite=Texture2D'EngineResources.S_SkyLight'
End Object

Dynamically created components

To dynamically create an instance of a component, use the UnrealScript new operator and call the actor's AttachComponent method to attach the new component to the actor.

The parameter to the new operator is the outer object to create the component in; this should be the actor which it will be attached to. This ensures that the component's Outer reference doesn't unnecessarily prevent another actor from being garbage collected before the actor the component is attached to.

local StaticMeshComponent NewComponent;
NewComponent = new(self) class'StaticMeshComponent';
// Set the static mesh component's properties here.
AttachComponent(NewComponent);

To detach and free the component which you attached earlier, use the actor's DetachComponent method. Once no references to the component exist, it will be garbage collected.

Common PrimitiveComponent options

Actor collision and PrimitiveComponents

Collision tests will be performed against all of the colliding PrimitiveComponents attached to an actor, but when an actor moves, it only performs a test for a single PrimitiveComponent. This PrimitiveComponent is chosen by setting the Actor property CollisionComponent to reference the component to be used for actor movement collision checks. When the actor moves, it will take the bounding box of the component referenced by CollisionComponent and sweep it against all colliding PrimitiveComponents.

Built-in component types

• PrimitiveComponent
  • ArrowComponent
  • CameraConeComponent
  • CylinderComponent
  • DrawFrustumComponent
  • MeshComponent
    • StaticMeshComponent
    • SkeletalMeshComponent
  • ParticleSystemComponent
  • SpriteComponent
• LightComponent
  • DirectionalLightComponent
  • PointLightComponent
    • SpotLightComponent
  • SkyLightComponent
• AudioComponent
• HeightFogComponent
• SceneCaptureComponent
  • SceneCapture2DComponent
  • SceneCaptureCubeMapComponent
  • SceneCaptureParaboloidComponent
  • SceneCaptureReflectComponent

Creating new component types

To implement a new actor component type, you can override these ActorComponent functions to handle attachment, detachment and movement.

SetParentToWorld

UActorComponent::SetParentToWorld is called whenever the transform the component is attached to changes. It will always be followed with either a call to Attach or UpdateTransform.

Attach

UActorComponent::Attach is called when the component is initially attached. It will always be called after UActorComponent::Scene has been set and SetParentToWorld has been called. Additionally, it will never be called if UActorComponent::IsValidComponent returns false.

UpdateTransform

UActorComponent::UpdateTransform is called whenever the transform the component is attached to moves. It will always be preceded by a call to SetParentToWorld, and will never be called on a component which isn't attached.

Detach

UActorComponent::Detach is called when the component is detached. It will never be called on a component which isn't attached.

IsValidComponent

UActorComponent::IsValidComponent can be overridden to do additional parameter validation on the component's properties. If it returns false, then the component will not be attached.

Additional Notes

Attachments

Previously, Unreal Engine 2 allowed Actors to be attached to a skeletal mesh bone. Unreal Engine 3 only allows Actor components to be attached to a skeletal mesh bone.

For attachments, rather than adding the component to the Components array, add an entry to the Attachments array in the default properties of a SkeletalMeshComponent. Alternatively, an instanced reference can be added to the component and attach the component in script using SkeletalMeshComponent’s AttachComponent and DetachComponent functions.

Garbage Collection

In general, Actors which are destroyed are added to a list. Periodically (based on the ini option TimeBetweenPurgingPendingKillObjects), it clears references to the actors in the list, frees the actors and empties the list.

Deletion of Actor Components is an extension of Actor garbage collection. Components are deleted along with their Actor. References from Actors to components are cleared before the component is deleted.

See the Garbage Collection page for more information.