Entity selection order in animation frame commands

TDM v1.02 added a few new animation frame commands. Among these is the command pickup, which lets the AI pick up an entity from the world and attach it to itself.

Since the animation itself must refer to the entity that is selected, and the animation itself cannot easily be changed (but see below for a method to create your own new animation), the code supports a few sophisticated ways one can specify the entity that the AI will select. This article describes the order in which entities are considered for selection.

Entity Specification And Selection Order

Entity Specification

You can specify either an entity name, or an entity class. Here are two examples:

• Entity name:

frame 42 pickup atdm_some_entity_name hand_r

Only the entity that has exactly this name will be considered.

• Entity class:

frame 42 pickup AIUSE_FOOD hand_r

All entities that have the spawnarg "AIUse" "AIUSE_FOOD" will be considered.

Selection order

1. When the animation runs, all spawnargs with the specified name "COMMAND_ANIMATIONNAME" are considered first. COMMAND here is f.i. "pickup" and ANIMATIONNAME is f.i. "eat_righthand". Since prefixes are properly considered, it is possible to put more than one spawnarg on the AI and all of them will be tried in order. Example:

 "pickup_eat_righthand"   "AIUSE_FOOD"
 "pickup_eat_righthand01" "AIUSE_DRINK"
 "pickup_eat_righthand02" "atdm_my_apple"

From all the entities that fall into the categories specified by the spawnarg(s), the one closest to the joint is used. Entities that are outside a specific minimum distance are discarded.

That means that the selection above might not result in any entity at all, f.i. when the only specified entity is out-of-reach.

2. When the selection from the spawnargs has NOT resulted in any entity, the animation frame command's specification itself will be used. Usually this is something like "AIUSE_FOOD", so if you don't have any spawnargs or these do not result in a suitable entity, the default selection will be considered.

Just like with the specification by spawnarg, from all the entities considered here the one closest to thee joint is taken and entities outside the minimum distance will be ignored.

No entity found

It might be that neither the spawnargs nor the animation frame command result in any suitable entity. In this case the code simply does not pickup any entity at all, but the animation still continues to play.

See also

• Animation frame commands overview