Skip to content

Animation System

A workspot is the game's own way of playing a scripted animation sequence on a character: sitting on a couch, leaning on a railing, smoking, working at a terminal. re.AnimationSystem plays any workspot resource on an entity, without the device or spot in the world the game normally needs for it.

The player sitting in mid-air, playing a couch workspot

Animations are part of the client realm API. Workspots are .workspot resources in the game depot, most of them under base\workspots\.

Playing a workspot

cl/Sit.cs
var player = ScriptGameInstance
    .GetPlayerSystem(ScriptGameInstance.Get())
    ?.GetLocalPlayerControlledGameObject();
if (player is null)
{
    return;
}

var result = re.AnimationSystem.PlayWorkspot(
    player,
    new ResRef("base\\workspots\\player\\couch\\player__sit_couch_lean_back__sit_around__01.workspot"),
    new re.WorkspotOptions { AllowForeignRig = true },
    reason => Console.WriteLine($"Workspot finished: {reason}")
);

if (result != re.WorkspotPlayResult.Queued)
{
    Console.WriteLine($"Workspot not started: {result}");
}
  • The entity has to be controlled by this client, like its own player
  • The workspot loads and starts asynchronously. PlayWorkspot returns Queued when loading started, the optional callback then runs once with the reason the playback ended
  • Starting a second workspot on the same entity from your bundle replaces the first one, its callback reports Replaced
  • Workspots started by a bundle stop when the bundle unloads

PlayWorkspot returns one of:

Result Meaning
Queued The workspot loads and starts, the callback reports how it ends
EntityNotFound The entity does not exist on this client
NotOwner The entity is networked and owned by another client
Busy Another bundle's workspot is playing on the entity
InvalidPath The resource could not be loaded

The callback receives a WorkspotFinishReason:

Reason Meaning
Completed The workspot sequence ended by itself
Stopped Stopped without exit animation
Exited Stopped with exit animation, after it finished
Replaced Another workspot was started on the entity
EntityLost The entity or its workspot instance disappeared
ResourceInvalid The path did not load as a workspot
RigUnsupported The workspot has no animations for the entity's rig
RigIncompatible Foreign rigs were allowed, but none shares enough bones with the entity's rig
StartFailed The game rejected the workspot setup

Options

re.WorkspotOptions takes:

  • EntryAnimation - The entry animation of the workspot to start with. Empty uses the workspot's default entry
  • AllowForeignRig - When the workspot has no animations for the entity's rig, retarget the animations of another rig. Rigs with mostly matching skeletons work well, the further the skeletons differ, the more broken the result looks

The couch workspot above has no animations for the rig of multiplayer player characters, so it needs AllowForeignRig. Without it, playback ends with RigUnsupported.

Stopping

re.AnimationSystem.StopWorkspot(player);                  // play the exit animation, then stop
re.AnimationSystem.StopWorkspot(player, playExit: false); // snap out right away
  • With playExit, the entity plays an exit animation first. Either the one you pass, or the workspot's first exit animation when it's empty. The callback reports Exited once it is done
  • StopWorkspot returns false when the entity has no workspot started by your bundle

State

re.AnimationSystem.GetWorkspotState(entity) returns the playback state of the workspot on an entity, regardless of which bundle started it:

State Meaning
None No workspot is playing
Loading The workspot resource (and for foreign rigs, the rigs) are loading
Playing The workspot is playing
Exiting Stopped with exit animation, still playing until that is done