Animations on Smart Objects

From Nexus Mods Wiki
Jump to: navigation, search


Within the world, we have the need to contextually aware choose relevant animations for various types of NPCs in a varying environment. One such example is the necessity of NPCs to sit down and stand up from/to a bench. 

We have Actor Classes (AC) and Animations (A), Tags (T). Every AC representts some entity - e.g. dog, NPC, player. The Animation in our context represents and animation fragmetn (e.g. SitDown, StandUp) which can be manifested by different animations at the lower level. The particular fragment is chosen based on Local and Global Tags (LT and GT). For example, SitDown has different forms - from the front, from the back etc. The LT represent what can be chosen by the scripter at runtime, where GT represent what is the animation 'state' of the given entity (e.g. sitting down). Further the animation can have some variations denoted by [0] or [1] specifying another level of distinction within a certain animation fragment.

One other key property is the capacity of an animation to be aligned to something - e.g. an Smart Object, pivot of an object etc. This is done via the alignemnt proclip and the alignemnt bone. In principle, the entity moves in respect to the alignement bone attached to the point of allignment.

We distinquish two types of animations - aligned animations are also considere incoming animations (e.g. SitDown) and not-aligned animations are considered outgoing (e.g. StandUp) animations. Aligned animations are those having an alignemnt proclip. The alignemnt bone is expected to be present in all animations.

To Use the visualization feature, you have to have the XgenEditor window viewed (not necessarily selected)


The principal idea behind helpers is to provide a reference point and a set of animations to play. These animations may often be limited by specifics at the location - navigation not present, physics intersections etc. Further to provide good visuals, animations are aligned to allow nice visuals (e.g. NPCs sitting in the correct spot). Every animation has an alignemnt bone in its setup, that when used with the alignemnt proclip, provides the necessary information on how the animation is aligned. Imagine the alignemnt to be as a constrain on where the animating entity is present at a specific time in its animation being played. 

The two major groups of helpers are the Lead Helpers (also know as Top Helpers) who are the Sub Helpers. At every smart object helper set, these points create a forest like structure. These helpers carry the necessary information to know what animations can be used at a specific object attached to a helper set. However, animation alignemt is not limited to smart objects and helpers. Entity Pivots are also in principle lead helpers without a name. Every lead helpers is at the root a of a tree of subhelpers. The lead  helper is the main point to which an animation can align to. All the other Sub Helpers only carry information about animations and have no actual spatial meaning. 

At every (lead/sub) helper, we can specify a set of information that filters any relevant search in respect to a helper tree (rooted at the Lead helper) - Category, Animation, AnimationFragment, AnimationTags These information allow the validation or search algorithms to know what animation belongs to what category and what tags can be used. You can understand it as a selection process, where at every node, the algorithm collect the information about its subtree and enriches or limits a set of available animations. 

One important thing is that we have two types of animations - IN and OUT. IN animations are similar to SitDown, where the animation starts on the MNM and ends somewhere specifc, for example sitting on a chair. This animation HAVE an alignemnet proclip and an alignemnt bone. The OUT animations are simliar to StandUp, where they start out of MNM (or somewhere specific) and end on the MNM. These have the align bone but DO NOT have the Alignment proclip. 

There is also a third variant of animations called IDENT which are identities in respect to their start and end location. These animations (like turning on a bed) are exempt from Navigation and Physics checks. This can be disabled (see later). 



The Category property denotes a string about what specific is the helper concerned with. If not specified, it can be view as 'any'. If specified, the Category limits the node and subtree for a specific provided category. For example, a Lead helper may be used only with the category 'fight', so the script has to explicitly state this when using helpers sets (e.g. in playanimation).

The AnimationFragment and AnimationTags are outdated and present only for backward compatibility, but are the same in principle as the Animation markup.

The Animation markup represents a subset of information for animations, it consists of 2 or 4 parts either separated by a comma or colon respectively. The contents are always noted by ' ', the Animation being the first, Tags being the second part and Actor Class the third part., and the disabling of checks being the fourth part (e.g. Animation('AnimationX','Tag,Tag,Tag') or Animation('AnimationX':'Tag,Tag,Tag':'ActorClassX,ActorclassY':'OmmitNav'); ). If nothing is present (i.e. is written), that qualifies as a 'any' not limiting that particular part of the search.


Tag Resolution

Tags are resolved as following - the played tags are the closest (most grandious) subset of the requested tags. Everything beyond the requested set invalidates the candidate.

Simply put - Request (ABC), Database (A, AB, ABX). Candidates are A, AB and AB is chosen. Database (A,BX,ABC), A and ABC are candidates, ABC is chosen. Database(, X) the is candidate and chosen.



Checks can be either Forced or Omitted. The default set of checks and their order is Animation validity, Alignment, Navigation, Physics. 

Specific checks can be disabled or forced by adding a comma separated list of the following keywords, prepended by either Force or Ommit. These checks apply to all animations from the specified node and their child nodes.

Animation - this check being forced is ignored. If the animation check is set to ommit, the animtion variant will be skipped as a whole.
AnimAlign - skips the alignemnt evaluation, the animation is considered to be not aligned.  Use this only if you actually know what you are doing. The alignment is in reference to the end position and checks the minimum alignment. If the align is ommited, the projection of the target does not follow. The navigation tolerances, are set based on the alignment. First, the vertical and horizontal tolerances are set to Navmehs position tracker tolerances if this check is ommited. Otherwise, the vertical is kept at the NavMesh position tracker's setting and the horizontal changes, based on the type of animation. If the animation is aligned (has an alignement proclip, thus is an In animation), the horizontal is the radius of the agent. Otherwise, the Navmesh position tracker's tolerance is kept.

Nav - skips the navigation check, these checks are about being close or on the MNM. 

Phys - skips the physcis check, the check is based on the common height of an NPC

Identity - skips the identity check to identify IDENT animations. the identity means, the animation does have the same start and end positions. Further, if this is set, the Nav and Phys are by default skipped. To enforce them, force these checks manually 


The principle is that the Validator is a mechanism that aids boxes like playanimation or the animatiors or the editor. It receives an initial state, for example an animation (e.g. SitDown) and an initial set of Tags and a Lead Helper (Place0). Neither of these preesnt is considered to be equal to 'any'.  The Helper Set and its trees are used to provide a set of all combinations of animations that can be used with the limitations in mind (i.e. the animation, actor class, category). 

Note: if no helper is presented, the pivot is used as a lead  helper. If any helper is required, a specific (-2) value can be used to facilitete this.

The image above can would provide the combinations for 'SitDown' as follows for Place0 - SitDown +sitTable; SitDown +sitSideFront; SitDown +sitTable, SitDown +SitTable +Left, SitDown +SitTable +Left +Right. Some of these would be filtered out as nonsense (e.g. +Left+Right) when no acutal framgents for it exists. Further variants are filtered based on Phycis collisions and navigational. If the initial animation SitDown would have some tags, all the provided combinations would be enriched by that tag. The initialization of a validator can be seen as the state that is basal to all combinations found. Thus if no animation would be provided, the resulting combinations would include StandUp; StandUp  +Left, Standup +Right. 


Rules of validation

The Lead Helpers may be either valid (Green box) or invalid (Red box). 

(Verification/Lead helper) Rule: for every actor class for every animation fragments used there has to be at least one variant working

All helpers have to be working to have a valid object


When specifying a lead helper, the word Alternatives can be used in conjuction with a set of comma separated list of helper names within the same helper set e.g. Alternatives('Place1,Place2'); This denotes that the lead helper in question has alternatives which when evaluating it, can be evaluated instead of the failed helper. These are only considered when evaluating and displaying helpers, not during actual runtime validation. The linkage is directed thus if Place0 has alternatives in Place1 and Place2, the Place1 may not have an alternative in Place0 (has to be specified at Place1's description).

Having an alternative means that an invalid lead helper is valid if at least one of its alternatives is valid...

Limiting global tags

Prepending a '!' to a global or local tag can force the system to prohibit the existance of such tag in the queries for validation. 

Color Codes

an important thing is that validation resutls are agregated, thus at one location various animations can be as either starting, finishing or god know what.


Yellow -> represents a pt where only IN (like sitdown) animations (present in the debug print) are present

Blue -> represents a pt where only OUT (like stanup) animatiosns are present

Violett -> its mixed...  

Red -> invalidGreen -> valid Lead Helper 


additional color codes

YellowGreen - InvalidMNM

Orange - InvalidAnimation

Blue - InvalidColisions, the box of collision is drawn using this color

Red - Other Errors

Orange - collisions with physics  


WH_AI_SmartObjectHelpers_DebugDraw - turns it all on/off

WH_AI_SmartObjectHelpers_ShowHelperPositions - shows the old helpers from smart objects present in the helper set xml with their locations

WH_AI_SmartObjectHelpers_DrawOnlyValidHelpers - only valid (available, non faulty) helpers are drawn

WH_AI_SmartObjectHelpers_DrawOnlyOnSelectedObjects -  is drawn only when an object is selected and the 'space' key is pressed, otherwise always on selected is drawn

WH_AI_SmartObjectHelpers_ActorClassLimiter - the ID of the limited Actor class, only a singular class (e.g. 8 means NPC)

WH_AI_SmartObjectHelpers_DrawHelpersLimiterByAnimation - what animation+tags can be used to filter the display. the animations are separated by ';' and are specified as "animation:tag,tag,tag" example "SitDown:sitSideRight;SitDown:left"

WH_AI_SmartObjectHelpers_DrawHelpersActorLimiterByName - a set of by comma separated case sensitive names of actor classes are specified. All checks for validation and draw respect this limitation. Use it carefully. Ingame checks are not affected (e.g. playanimation etc)

WH_AI_SmartObjectHelpers_OmmitHelperText - does not draw all the animation related debug information for every helper

WH_AI_SmartObjectHelpers_DrawNavmeshTolerances - draws tolerances for navmesh checks

WH_AI_SmartObjectHelpers_DrawNavmeshToleranceOutline - uses only an outline, not a full debug for mnm tolerances

WH_AI_SmartObjectHelpers_DrawAllNavmeshSolutions - draws all the solutions and the closest points

WH_AI_SmartObjectHelpers_VerifyHelpers - command, runs the check of all registered objects

WH_AI_SmartObjectHelpers_DumpVerificationtoFile - the dump is to be put into a file at outputs/sohelperverification/results.csv file

WH_AI_SmartObjectHelpers_SOVerificationProgress - what is the progress of the verification

WH_AI_SmartObjectHelpers_ZOffsetDebug - debug draw z offset

WH_AI_SmartObjectHelpers_VerticallinkWidth - connection betwen offseted and original positions

WH_AI_SmartObjectHelpers_DrawIntersections - draw the physics collicion pts

WH_AI_SmartObjectHelpers_DrawIntersectionNames- draw what we actually intersect with  


WH_AI_SmartObjectHelpers_VerifyHelpers - checks all currently present smart objects...all other objects using a pivot alignemtn cannot be checked for obvious reasons

The produced CSV has columns Name, Position, InvalidLeadHelpers, InvalidLeadHelpersAtUsability, InvalidLeadHelpersInTotal  

Name - the name of the failed object

Position - its position in the world

InvalidHelpers - invalid helpers, with the addition of which animation fragment and which actor class failed.  

Simply to run it

1) generate navmesh
2) write to your console: WH_AI_SmartObjectHelpers_DumpVerificationtoFile
3) write to your console: WH_AI_SmartObjectHelpers_VerifyHelpers
4) open: w:\WH\outputs\sohelperverification\results.csv and check wrong smartobjects in editor

Kingdom Come: Deliverance: Forum | Before you start | Tutorials & Instructions | Basic Mods | Tools | Documentation | Glossary | EULA