Gorilla.Animation.Controller Unit Reference

Animation state machine for automatic clip switching by transitions.

Unit: Gorilla.Animation.Controller

Overview

The Gorilla.Animation.Controller unit implements a transition-driven animation state machine on top of the Gorilla.Animation system. Instead of starting clips manually, you declare transitions between animations and dispatch the events that should trigger them.

Structure:

TGorillaAnimationController
└─ TGorillaAnimationTransitionLayerCollection
   └─ TGorillaAnimationTransitionLayer
      ├─ TGorillaAnimationRefList          (animations referenced by this layer)
      └─ TGorillaAnimationTransitionCollection
         ├─ TGorillaAnimationTransitionsMap  (lookup map, key -> transition list)
         └─ TGorillaAnimationTransition

Dependencies: Gorilla.Controller, Gorilla.Animation, Gorilla.Model, Gorilla.AssetsManager, Gorilla.Controller.Input.Types, Gorilla.Controller.Input.Character

Types

TGorillaAnimationTransitionDetectionKind

TGorillaAnimationTransitionDetectionKind = (tkHotKeyAndStates, tkCustom);

Defines what kind of information triggers a transition.

Value Description
tkHotKeyAndStates A pressed hotkey and the active character states are checked
tkCustom A variable name and its value are submitted

TGorillaAnimationTransitionMode

TGorillaAnimationTransitionMode = (tmImmediatly, tmSequentially, tmBlend);

Defines how switching between two animations is handled.

Value Description
tmImmediatly The destination animation is switched immediately
tmSequentially The controller switches to the destination animation at the end of the current animation
tmBlend Blending between animations. Not supported yet - currently treated like tmSequentially

TGorillaAnimationDispatcher

TGorillaAnimationDispatcher = record
  Kind     : TGorillaAnimationTransitionDetectionKind;
  HotKey   : TGorillaCharacterControllerHotKey;
  States   : TGorillaCharacterControllerStates;
  Variable : String;
  Value    : TValue;
end;

Stores dispatch information for recalling. The controller keeps the last dispatch in DispatchState and replays it when a non-looping animation finishes.

TGorillaAnimationTransitionKey

TGorillaAnimationTransitionKey = record
  class function GetKey(AAnimFrom: String;
    AHotKey: TGorillaCharacterControllerHotKey;
    AStates: TGorillaCharacterControllerStates): String; overload; static;
  class function GetKey(AAnimFrom: String;
    AVariable: String; AValue: String): String; overload; static;
  class function GetKey(AAnimFrom: String;
    AVariable: String; AValue: TValue): String; overload; static;
end;

Builds the lookup key used by TGorillaAnimationTransitionsMap.

  • HotKey form: <AnimationFrom>:0;<Ord(HotKey)>
  • Custom form: <AnimationFrom>:1;<Variable>;<Value>

The states are deliberately not part of the hotkey key. All transitions sharing source animation and hotkey land in one bucket and are checked individually, so state sets can overlap.

TGorillaAnimationTransitionList

TGorillaAnimationTransitionList = TList<TGorillaAnimationTransition>;

TGorillaAnimationTransitionsMap

TGorillaAnimationTransitionsMap = class(TDictionary<String, TGorillaAnimationTransitionList>)
  constructor Create(); reintroduce; virtual;
end;

Maps a transition key to all transitions sharing that key. Owns the sub-lists: removing a value frees the list.

TGorillaAnimationRef

Links an animation to the layer that uses it, plus editor metadata.

TGorillaAnimationRef = class
  property Animation  : TGorillaAnimation read FAnimation write FAnimation;
  property UIPosition : TPointF read FUIPosition write FUIPosition;
  property Visible    : Boolean read FVisible write FVisible;
end;
Member Description
Animation The referenced animation instance
UIPosition Node position in the design-time transition editor; serialized per layer
Visible Editor visibility flag

TGorillaAnimationRefList

TGorillaAnimationRefList = class(TObjectList<TGorillaAnimationRef>)
  function Find(const AId: String): TGorillaAnimationRef; overload;
  function Find(const AAnim: TGorillaAnimation): TGorillaAnimationRef; overload;
  function AddByAnimation(const AAnim: TGorillaAnimation): TGorillaAnimationRef;
end;
Method Description
Find(AId) Returns the reference whose animation has the given Def.Id, or nil
Find(AAnim) Returns the reference for the given animation instance, or nil
AddByAnimation Returns the existing reference, or creates and adds a new one

TGorillaAnimationTransition

Defines the switch between two animations.

Inheritance: TCollectionItem → TGorillaAnimationTransition

Created with Mode = tmSequentially and Loop = True.

Properties

DisplayName

property DisplayName;

The transition name, used by FindTransition and DeleteTransition and shown in the collection editor.

Key

property Key: String read GetKey;

Read-only lookup key built from DetectionKind, AnimationFrom and the detection properties. Used to file the transition into the collection's lookup map.

DetectionKind

property DetectionKind: TGorillaAnimationTransitionDetectionKind
  read FDetectionKind write FDetectionKind;

Selects which properties are evaluated: HotKey / States for tkHotKeyAndStates, Variable / Value for tkCustom. Set automatically by the matching AddTransition() overload.

Mode

property Mode: TGorillaAnimationTransitionMode read FMode write FMode;

How the switch is carried out. See TGorillaAnimationTransitionMode.

Loop

property Loop: Boolean read FLoop write FLoop;

Whether the destination animation loops. With Loop = False and Mode = tmImmediatly, the controller restores looping on the clip when it finishes and replays the last dispatch, so a matching "way back" transition can take over.

HotKey

property HotKey: TGorillaCharacterControllerHotKey read FHotKey write FHotKey;

Hotkey to match. Only evaluated for DetectionKind = tkHotKeyAndStates. Must be equal to the dispatched hotkey.

States

property States: TGorillaCharacterControllerStates read FStates write FStates;

Character states to match. Only evaluated for DetectionKind = tkHotKeyAndStates. Matching is a subset test: every state in States must be present in the dispatched set, which may contain additional states. An empty set matches any state.

Variable

property Variable: String read FVariable write FVariable;

Variable name to match. Only evaluated for DetectionKind = tkCustom. Compared case-sensitively for equality.

Value

property Value: String read FValue write FValue;

Variable value to match, stored as a string. AddTransition() fills it with AValue.ToString(), and dispatched values are compared the same way.

AnimationFrom / AnimationTo

property AnimationFrom: String read GetAnimationFrom write SetAnimationFrom;
property AnimationTo: String read GetAnimationTo write SetAnimationTo;

Source and destination animation, referenced by ID. The instances are resolved lazily through Controller.Model.AnimationManager and cached; assigning a new ID drops the cached link. As long as a model is missing or the ID is unknown, the link stays nil and the transition never triggers.

OffsetAnimationFrom / OffsetAnimationTo / Duration

property OffsetAnimationFrom: Single read FOffsetAnimationFrom write FOffsetAnimationFrom;
property OffsetAnimationTo: Single read FOffsetAnimationTo write FOffsetAnimationTo;
property Duration: Single read FDuration write FDuration;

Blend window for tmBlend: the offsets mark where blending starts in the source and destination animation, Duration defines the length of the blending section. Stored and serialized, but without effect until blending is implemented.

Methods

DispatchInput

function DispatchInput(ACurrent: TGorillaAnimation;
  AHotKey: TGorillaCharacterControllerHotKey;
  AStates: TGorillaCharacterControllerStates): Boolean; overload; virtual;

function DispatchInput(ACurrent: TGorillaAnimation;
  AVariable: String; AValue: TValue): Boolean; overload; virtual;

Checks whether this transition is triggered. Returns False when the detection kind does not match the overload, when ACurrent is not the resolved source animation, or when hotkey / states / variable / value do not match.

Switch

procedure Switch(ACurrent: TGorillaAnimation);

Performs the animation switch. Called automatically after DispatchInput returned True. Does nothing if the destination animation is already current or cannot be resolved.

Mode Effect
tmImmediatly Clears OnFinish on the current clip, makes the destination current, applies Loop, hooks the finish handler when Loop = False, and starts it
tmSequentially Sets the current clip to non-looping and hooks the finish handler; the destination starts when the current clip ends
tmBlend Same as tmSequentially

ToJSON / ToJSONString / FromJSON

function ToJSON(): TJSONObject; virtual;
function ToJSONString(): String; virtual;
procedure FromJSON(AJSON: TJSONObject); virtual;

Serialize all transition settings. Keys: Name, DetectionKind, Mode, HotKey, States, Variable, Value, AnimationFrom, AnimationTo, OffsetAnimationFrom, OffsetAnimationTo, Duration. Enumerations are written by name; the state set is written as a bracketed, comma-separated list (e.g. [fpIdle,fpMoving]).

FromJSON resets all fields first, using tkHotKeyAndStates and tmImmediatly as defaults for missing entries.

Assign

procedure Assign(Source: TPersistent); override;

Copies all settings from another transition. The cached animation links are not copied, so the target relinks against its own controller.

TGorillaAnimationTransitionCollection

Holds all transitions of one layer.

Inheritance: TOwnedCollection → TGorillaAnimationTransitionCollection

Properties

Property Type Description
Layer TGorillaAnimationTransitionLayer The owning layer
Controller TGorillaAnimationController The controller of the owning layer
HashMap TGorillaAnimationTransitionsMap Lookup map, built on demand

Methods

UpdateHashMap

procedure UpdateHashMap();

Rebuilds the lookup map so transitions can be found without iterating the collection. The map is created lazily on the first TryGetTransition call and is not refreshed automatically when transitions are added, changed or removed afterwards - call this method after runtime modifications.

TryGetTransition

function TryGetTransition(ACurrent: TGorillaAnimation;
  AHotKey: TGorillaCharacterControllerHotKey;
  AStates: TGorillaCharacterControllerStates;
  out ATransition: TGorillaAnimationTransition): Boolean; overload;

function TryGetTransition(ACurrent: TGorillaAnimation;
  AVariable: String; AValue: String;
  out ATransition: TGorillaAnimationTransition): Boolean; overload;

Looks up the bucket for the given key and returns the first transition in it whose DispatchInput returns True. Builds the map first if necessary.

ToJSON / FromJSON

function ToJSON(): TJSONArray; virtual;
procedure FromJSON(AJSON: TJSONArray); virtual;

Serializes the collection as an array of transition objects. FromJSON clears the collection first.

TGorillaAnimationTransitionLayer

Groups transitions so complex animation behaviour stays manageable.

Inheritance: TCollectionItem → TGorillaAnimationTransitionLayer

Properties

Property Type Description
DisplayName String The layer name, used by FindLayer / RemoveLayer
Transitions TGorillaAnimationTransitionCollection Transitions of this layer
Animations TGorillaAnimationRefList Animations referenced by the transitions of this layer
Model TGorillaModel The controller's model
Controller TGorillaAnimationController The owning controller

Methods

AddTransition

function AddTransition(const AName: String; const AFrom: String; const ATo: String;
  ADoLoop: Boolean; AHotKey: TGorillaCharacterControllerHotKey;
  AStates: TGorillaCharacterControllerStates;
  AMode: TGorillaAnimationTransitionMode): TGorillaAnimationTransition; overload; virtual;

function AddTransition(const AName: String; const AFrom: String; const ATo: String;
  ADoLoop: Boolean; AVariable: String; AValue: TValue;
  AMode: TGorillaAnimationTransitionMode): TGorillaAnimationTransition; overload; virtual;

Creates a transition and sets DetectionKind to tkHotKeyAndStates or tkCustom respectively. Animation references are refreshed afterwards.

Parameters:

Parameter Description
AName Transition name (DisplayName)
AFrom / ATo Source and destination animation ID
ADoLoop Loop of the destination animation
AHotKey / AStates Trigger condition for the hotkey variant
AVariable / AValue Trigger condition for the custom variant; the value is stored as AValue.ToString()
AMode Switch mode

FindTransition

function FindTransition(const AName: String): TGorillaAnimationTransition; overload; virtual;
function FindTransition(const AFrom: String; const ATo: String): TGorillaAnimationTransition; overload; virtual;

By name, or by animation pair.

The by-name overload searches the collection's lookup map and returns nil while the map has not been built yet. Call Transitions.UpdateHashMap() first, or use the by-pair overload, which always scans the collection.

DeleteTransition

procedure DeleteTransition(const AName: String); overload; virtual;
procedure DeleteTransition(const AFrom: String; const ATo: String); overload; virtual;

Removes the matching transition and refreshes the animation references. Silently does nothing if nothing matches.

DispatchInput

procedure DispatchInput(ADispatcher: TGorillaAnimationDispatcher); overload; virtual;
procedure DispatchInput(AHotKey: TGorillaCharacterControllerHotKey;
  AStates: TGorillaCharacterControllerStates); overload; virtual;
procedure DispatchInput(AVariable: String; AValue: String); overload; virtual;
procedure DispatchInput(AVariable: String; AValue: TValue); overload; virtual;

Evaluates the transitions of this layer against the current animation and switches on the first match. Returns without effect when no model, no transitions or no current animation exist. Every call stores the dispatch in the controller's DispatchState.

The hotkey overload uses the lookup map; the variable overloads iterate the collection in order.

RebuildAnimationReferences / RequestAnimationReferences / AddAllAnimationReferences

procedure RebuildAnimationReferences();
procedure RequestAnimationReferences();
procedure AddAllAnimationReferences();
Method Description
RequestAnimationReferences Adds the source and destination animation of every transition to Animations if not present
RebuildAnimationReferences Clears Animations first, then requests them again
AddAllAnimationReferences Adds all animations of the linked model, whether used by a transition or not

These references carry the editor node positions; they are not needed for triggering.

Clear / Assign / ToJSON / FromJSON

procedure Clear(); virtual;
procedure Assign(Source: TPersistent); override;
function ToJSON(): TJSONObject; virtual;
procedure FromJSON(AJSON: TJSONObject); virtual;

Clear empties transitions and animation references. JSON keys: Id, Animations (each with Id and UIPosition), Transitions.

TGorillaAnimationTransitionLayerCollection

Holds all layers of a controller.

Inheritance: TOwnedCollection → TGorillaAnimationTransitionLayerCollection

Member Description
Controller The owning TGorillaAnimationController
FindLayer(AName) Returns the layer with that name, or nil
DispatchInput(...) Forwards the dispatch to every layer, in collection order
ToJSON / FromJSON Serializes the layers as a JSON array

Because layers are processed in order and each one evaluates against the animation that is current at that moment, a later layer can see and override the switch of an earlier one.

TGorillaAnimationController

The component that switches character animations depending on configured transitions.

Inheritance: TGorillaController → TGorillaAnimationController

Platforms: All Gorilla platforms

Published Properties

Model

property Model: TGorillaModel read FModel write SetModel;

The model the transitions apply to. The controller uses this model's AnimationManager. Without a model, transitions are never triggered.

A model that was auto-loaded by FromJSON / LoadFromFile is owned by the controller and is freed when Model is reassigned, when Clear is called, or on destruction. A model assigned by the user is only unlinked.

DefaultAnimation

property DefaultAnimation: String read FDefaultAnimation write SetDefaultAnimation;

ID of the animation the controller starts with. Assigning it resolves the animation, makes it current and starts it immediately - so assign Model first. Without a default animation there is no current animation and no transition can match.

Layers

property Layers: TGorillaAnimationTransitionLayerCollection read FLayers write SetLayers;

The layer collection. Each layer manages its own set of transitions.

Public Properties

DispatchState

property DispatchState: TGorillaAnimationDispatcher read FLastDispatch;

The last dispatched state. Useful to query the current intent, but not necessarily the currently active state, because animation switches can be delayed.

Methods

GetAnimationManager

function GetAnimationManager(): TGorillaAnimationManager; virtual;

Returns the animation manager of the linked model, or nil if no model is linked.

GetCurrentAnimation

function GetCurrentAnimation(): TGorillaAnimation; virtual;

Returns the currently playing animation, or nil if no model is linked.

DispatchInput

procedure DispatchInput(ADispatcher: TGorillaAnimationDispatcher); overload; virtual;
procedure DispatchInput(AHotKey: TGorillaCharacterControllerHotKey;
  AStates: TGorillaCharacterControllerStates); overload; virtual;
procedure DispatchInput(AVariable: String; AValue: String); overload; virtual;
procedure DispatchInput(AVariable: String; AValue: TValue); overload; virtual;

Forwards the dispatch to all layers.

// custom variable
GorillaAnimationController1.DispatchInput('anim', 1);

// hotkey and states
GorillaAnimationController1.DispatchInput(
  TGorillaCharacterControllerHotKey.KeyboardMoveForward,
  [TGorillaCharacterControllerState.fpMoving]);

TGorillaPhysicsCharacterController calls the hotkey overload automatically when its Model and AnimationController properties are assigned.

AddLayer / RemoveLayer / FindLayer / LayerExists

function AddLayer(const AName: String): TGorillaAnimationTransitionLayer; virtual;
procedure RemoveLayer(const AName: String); virtual;
function FindLayer(const AName: String): TGorillaAnimationTransitionLayer; virtual;
function LayerExists(const AName: String): Boolean; virtual;

AddLayer returns the existing layer when the name is already in use, so it is safe to call repeatedly.

AddTransition

function AddTransition(const ALayer: String; const AName: String; const AFrom: String;
  const ATo: String; ADoLoop: Boolean; AHotKey: TGorillaCharacterControllerHotKey;
  AStates: TGorillaCharacterControllerStates;
  AMode: TGorillaAnimationTransitionMode): TGorillaAnimationTransition; overload; virtual;

function AddTransition(const ALayer: String; const AName: String; const AFrom: String;
  const ATo: String; ADoLoop: Boolean; AVariable: String; AValue: TValue;
  AMode: TGorillaAnimationTransitionMode): TGorillaAnimationTransition; overload; virtual;

Convenience wrappers around the layer methods. Return nil if the named layer does not exist - create it with AddLayer first.

FindTransition / DeleteTransition

function FindTransition(const ALayer: String; const AName: String): TGorillaAnimationTransition; overload; virtual;
function FindTransition(const ALayer: String; const AFrom: String; const ATo: String): TGorillaAnimationTransition; overload; virtual;
procedure DeleteTransition(const ALayer: String; const AName: String); overload; virtual;
procedure DeleteTransition(const ALayer: String; const AFrom: String; const ATo: String); overload; virtual;

Delegate to the named layer; return nil / do nothing if the layer is unknown.

Clear

procedure Clear();

Resets the default animation, clears all layers, unlinks (and frees, if standalone) the model, and resets the stored dispatch state.

SaveToFile / SaveToStream / LoadFromFile / LoadFromStream

procedure SaveToFile(const AFilename: String);
procedure SaveToStream(AStream: TStream);
procedure LoadFromFile(const AFilename: String;
  const APackage: TGorillaAssetsPackage = nil);
procedure LoadFromStream(AStream: TStream;
  const APackage: TGorillaAssetsPackage = nil);

Persist the complete setup as UTF-8 JSON. The optional assets package receives models and textures that have to be auto-loaded.

ToJSON / FromJSON

function ToJSON(): TJSONObject; virtual;
procedure FromJSON(AJSON: TJSONObject;
  const APackage: TGorillaAssetsPackage = nil); virtual;

JSON layout:

{
  "Model": {
    "Id": "GorillaModel1",
    "Filename": "assets\\c.dae",
    "Animations": ["c-idle.dae", "c-run.dae"]
  },
  "DefaultAnimation": "c-idle.dae",
  "Layers": [
    {
      "Id": "Layer0",
      "Animations": [ { "Id": "c-idle.dae", "UIPosition": [120, 80] } ],
      "Transitions": [
        {
          "Name": "idle > run",
          "DetectionKind": "tkHotKeyAndStates",
          "Mode": "tmImmediatly",
          "HotKey": "KeyboardMoveForward",
          "States": "[fpMoving]",
          "Variable": "",
          "Value": "",
          "AnimationFrom": "c-idle.dae",
          "AnimationTo": "c-run.dae",
          "OffsetAnimationFrom": 0,
          "OffsetAnimationTo": 0,
          "Duration": 0
        }
      ]
    }
  ]
}

FromJSON resolves the model in this order:

  1. a component named like the stored Id, searched in the owner and its child objects
  2. an existing TGorillaModel whose Source matches the stored Filename
  3. otherwise the model is loaded from Filename as a standalone model owned by the controller, followed by every animation file listed in Animations

Exceptions: raised when the model cannot be found or auto-loaded, and when an animation file listed in the JSON does not exist.

TGorillaAnimationControllerEditor

TGorillaAnimationControllerEditor = class(TComponentEditor)

Design-time component editor. Adds the verb Transition Editor, which opens the flow-chart editor (TTransitionFlowChartForm) for the selected controller. Available in the IDE design package only.

Registration

The unit registers TGorillaAnimationController, TGorillaAnimationTransitionLayerCollection, TGorillaAnimationTransitionLayer, TGorillaAnimationTransitionCollection and TGorillaAnimationTransition with System.Classes.RegisterClasses on initialization, so the collections survive DFM/FMX streaming, and unregisters them on finalization.

Usage Notes

  • Animation IDs are the IDs registered in the model's animation manager; for clips added with AddAnimationFromFile() that is the file name.
  • Only a resolved source animation can match: a transition naming an unknown ID stays inactive without raising an error.
  • After modifying transitions at runtime, call Transitions.UpdateHashMap() on the affected layer.
  • Custom values are compared as strings, so 1, '1' and TValue.From<Integer>(1) are equivalent conditions.
  • tmBlend currently behaves like tmSequentially; the offset and duration properties have no visible effect yet.
  • The inherited Enabled property is not evaluated by this unit: dispatching and switching work independently of it.

See Also