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]).
FromJSONresets all fields first, usingtkHotKeyAndStatesandtmImmediatlyas 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
nilwhile the map has not been built yet. CallTransitions.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/LoadFromFileis owned by the controller and is freed whenModelis reassigned, whenClearis 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:
- a component named like the stored
Id, searched in the owner and its child objects - an existing
TGorillaModelwhoseSourcematches the storedFilename - otherwise the model is loaded from
Filenameas a standalone model owned by the controller, followed by every animation file listed inAnimations
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'andTValue.From<Integer>(1)are equivalent conditions. tmBlendcurrently behaves liketmSequentially; the offset and duration properties have no visible effect yet.- The inherited
Enabledproperty is not evaluated by this unit: dispatching and switching work independently of it.
See Also
- Animation Controller Guide - Concepts, examples and best practices
- Gorilla.Animation Unit - Animation manager and clips
- Gorilla.Controller.Input.Types Unit -
TGorillaCharacterControllerHotKey,TGorillaCharacterControllerState - Gorilla.Controller.Input.Character Unit - Character controller base class
- Gorilla.Model Unit - Models and additional animation clips