PLEASE NOTE: this
document is obsolete. Please consult the Unreal Developer Network site for the
latest documentation including detailed tutorials and
plugins.
Contents
Overview
The skeletal animation
support in UT was designed to be almost completely backwards compatible
with the vertex animation. This document assumes the artists/programmers
are somewhat familiar with the process of creating/managing (vertex-)
animation content for Unreal/Unreal Tournament (see "Animation
Basics" )The animating vertices are replaced by an invisible hierarchy
of animating bones, which move vertices of the mesh either directly or in
weighted combinations. Content is created in 3D Studio Max 2.5/3.0/3.1 and
exported to a custom (loss-less) binary format, and the animation data is
digested (compressed) at package-building time.
During content rebuilds
('ucc make'), .PSA files are digested into UAnimation objects, and .PSK
files into USkeletalMesh objects. The animations then work with the exact
same commands and sequence-notification pathways as the classic vertex
animated models.
Model files have the
.PSK extension, animation files have a .PSA extension.
A path name needs to be set at all times, since that also determines the
destination of the log files.
A .PSK (model) file can
be saved at any time when your model is loaded. The .PSA (animation)
file can consist of multiple animations which are 'digested', selected
animations can then be grouped together, renamed, and
saved/loaded.
Animations are 'bundled'
into memory as they are digested by the exporter. The actual saving out to
a file is done from a separate animation manager window (see its button)
which allows saving, loading and parameter tweaking of animations in
previous bundled .PSA files. Changing parameters like the animation names,
grouping names, and frame rates is done on the selected animation in the
first list, which can then be shuffled back and forth to the second list
which represents the .PSA file to be written.
The Maya and Max
exporters share the same user interfaces, but are activated differently.
Exporting
Animations from 3D Studio Max
The exporter,
ActorX is a utility plugin which you install by copying ActorX.dlu
into your Max plugins folder. It can be activated in the utility pane
(hammer tab-> more -> ActorX). ActorX will look for any
hierarchy which has either Physique meshes or other meshes attached to it,
and export either the skin + reference skeleton ('model') or the
animation, using the filenames given in the main exporter utility
pane.
ExampleMax
contains source art for two animated meshes - Piston.max and
Player.max. The script files used to link up content into a native
Unreal package are Thing.uc and Warboss.uc. The exporter was then used
to create the intermediate .PSK (skin, mesh and reference skeleton) and
.PSA (animation) files. The .pcx skins are 8-bit pallettized (and where
desired, downsampled) versions of the original 24-bit image files used for
the Max materials. The ready-made native
Unreal package containing the meshes, animations and textures is " Test.u
". Placing this in the UnrealTournament\System folder along with the
standard .u files allows the engine to access the data during game
runtime. If your scene contains any meshes which need to be exported as
part of a hierarchy while they're not explicitly physique-linked as a skin
to bones or other objects, make sure the 'all
textured geometry' option in the second pane is checked. For all
meshes linked with physique, it is extremely important to initialize and
set them up from the very start exactly as outlined here; otherwise
there is no guarantee that results in the engine will match what you're
seeing in Max.
Exporting Animations from Maya
The different windows can
be called up with specific Maya/Mel commands (easily bound to custom keys
by dragging the marked command text to the toolbar) :
axmain the main exporter
panel axoptions brings up the second options/script
export panel axanim starts
the animation manager, which can save and load the
platform-independent .psa animation files from disk, to edit
the individual UT animation
properties. axbrush non-skeletal .T3D
textured architecture export.
ExampleMaya.zip
contains example source art in Maya 3.0 format: two simple animated
meshes, Piston.mb and Worm.mb. The script files used to link up content
into a native Unreal package are Piston.uc and Worm.uc. The exporter
was used to create the intermediate .PSK (skin, mesh and reference
skeleton) and .PSA (animation) files. The
.pcx skins are 8-bit pallettized (and, where desired, downsampled)
versions of the original 24-bit image files as used for the Maya
materials. The
ready-made native Unreal package containing the meshes, animations and
textures is "Test.u". Placing this in the UnrealTournament\System
folder along with the standard .u files allows the engine to access the
data during game runtime. Note that in Maya, there need to be
actual 'Joint' objects for the exporter to recognize as a hierarchy, in
contrast to the Max exporter, where any parenting of objects will
do.
Exporter
Options (second pane)
- Skin selection
checks ( effective for MAX exporter only )
- All physique
meshes - by default, export only mesh geometry consisting of
Character Studio's Physique modifiers.
- All textured
geometry - export any textured meshes, which may be linked up by
bones, or any parent/child bonds. The exporter treats these bonds like
regular bones. This may also be needed when not all meshes linked to
your skeleton are Physique'd.
- Dummy culling - Checking this option makes the exporter disregard
any dummy boxes which are at the ends of the hierarchy and have no
effective links to any of the skin/geometry. Depending on the linkup, dummy
culling can cause problems like erratic vertices and/or bones.
It works OK though if you
apply it after saving the skin, i.e. to the animation only.
- Root motion
lock - Check this to subtract the net root motion from an
animation. 'Hard lock' will simply freeze the root node at it's frame-0
start position throughout the animation.
Engine Console
Commands
These are in-game console commands that can be used to debug your
meshes and animations.
- stat anim -
detailed real-time report on all animation (skeletal or regular) for
meshes visible on the screen.
- rend bone -
toggles drawing of the bones when in wireframe mode.
- rend blend -
visualize the vertex-influence blending. Green vertices have
single links, red ones have two, pink three, light blue four, white have
five or more.
- rend wire -
enables wireframe mode in normal (lit) render modes, but is currently
disabled (cheating possibilities!) so RMODE 1 is the proper way to enter
wireframe mode.
General Script
Commands
Animation objects are
linked up with actors at runtime. Any bone names that the actor's
USkeletalMesh model has in common with the linked-up animation will
be animated.
Skeletal meshes are imported with the MESH
MODELIMPORT command, eg:
#exec MESH MODELIMPORT
MESH=SkeletalMesh MODELFILE=MODELS\SkelMesh.PSK LODSTYLE=8 X=0 Y=0
Z=0 |
.PSK files as generated
by the Max exporter are 'Reference skin-and-skeleton' raw data
chunks, which are converted to USkeletalMeshes which define a skin,
materials and UV's, bone influences, and the named bones in a
reference pose.
Animation files are imported with the ANIM
IMPORT command:
#exec ANIM IMPORT ANIM=AnimTest
ANIMFILE=MODELS\Male.PSA IMPORTSEQS=1 COMPRESS=0.9
MAXKEYS=9999999 |
UAnimation objects
contain named bones, (compressed), any predefined sequences, and
movement tracks for each bone.
MaxKeys will put
an adjustable squeeze on the number of keys in the animation as a
whole; COMPRESS= does the same but with a simple factor ranging
from 0 to 1. Keys
which can be interpolated most effectively are thrown out first, until
we're left with the suggested number of keys (or lower, because
'perfectly' interpolatable keys are always thrown out, and all static
tracks are collapsed into 1-key tracks). The initial, non-compressed
number of keys in an animation always equals the (number of bones)*(number
of frames) that were exported.
ImportSeqs=1
signifies that the animation sequence info embedded into the binary .PSA
file by the Max exporter is to be used.
You can still specify
animation sequences just like the old format, except that it's done
through #exec ANIM commands and they're now tied to the animation
object, rather than the mesh:
#exec ANIM SEQUENCE
ANIM=SkeletalAnimation1 SEQ=All STARTFRAME=0 NUMFRAMES=25 RATE=0.2
GROUP=Default |
In any case, a specific
DIGEST command needs to be issued, at which point all sequences
(implicit and declared) are compressed into the internal key track
format:
#exec ANIM DIGEST
ANim=SkAnimTest VERBOSE |
Specify VERBOSE to
see more information in UCC.log after the rebuild.
Notification callbacks
need to be placed after the #exec ANIM DIGEST, and have a syntax similar
to the old notify commands:
#exec ANIM NOTIFY
ANIM=SkeletalAnimation1 SEQ=All TIME=0.1
FUNCTION=LandThump |
A UAnimation object is
linked to a certain skeletal mesh at runtime using
LinkSkelAnim:
function
PostBeginPlay() {
LinkSkelAnim(Animation'SkeletalAnimation1' );
LoopAnim('All',1.0,0.0); } |
Or (more useful for
backward compatibility) it can be linked at compile time
using:
#exec
MESH DEFAULTANIM MESH=MeshSk
ANIM=SkAnimTest |
LOD works the same as
regular LOD in Unreal Tournament. See LODTechnologyNotes.htm.
When your skeletal
animation makes your character cover an area far outside its reference
pose or root position, you have the option to override the bounding box
extents that the engine uses to determine visibility.
#exec MESH BOUNDINGBOX MESH=MeshSk
XMIN=-64.0 YMIN=-64.0 ZMIN=-64.0 XMAX=64.0 YMAX=64.0
ZMAX=64.0
|
There is a tradeoff: make the bounding box too big, and the mesh will
be drawn in situations where it is occluded by architecture; make it too
small, and meshes may flicker in and out of view.
Materials
The names of the multi/sub materials
indicate which rendering modes will be activated for the polygon flags.
The following strings fragments, with the familiar Unreal polygon effects,
can be anywhere in the material name and can be combined (if the
combination makes sense to the engine.)
Recommended: when
using multiple textures, always name them skin00, skin01, etc, which will
force the 'multiskin' indices to point at the textures in a predictable
order.
- skinXX -
give your materials numbered skin names to ensure they are linked in the
right order, whenever you have multiple skins for a single mesh.
- twosided -
twosided (flags, fins)
- weapon
(obsolete) See Weapon
Bone.
- invisible
(obsolete)
- modul -
modulated
- mask -
masked
- envir - environment mapped
- mirro -
environment mapped
- nosmo -
'nosmooth', non-bilinear filtered
- unlit -
unlit
- trans -
translucent
You still have to create
your own 8-bit .pcx or .bmp versions of texture files and manually link
them up in the appropriate .uc script files, but you can look at the X_ModelInfo.log
output to see exactly which bitmap files go with what material number
for your model.
Log Files
The exporter does not output explicit '.uc'
template script files, instead it writes X_AnimInfo.log and
X_ModelInfo.log which contain a detailed summary of the exported
data, and have all the information about frames and
material/bitmaps you need when writing the script #exec commands that
link in the data.
The log files are always dumped in the same
folder along with the .PSA/.PSK files.
Weapon Bone
Instead of assigning a
polygon in Max, you now assign any bone as a weapon-carrier using MESH
WeaponAttach, with the name of the bone as visible in Max:
#exec MESH WEAPONATTACH
MESH=MeshSk BONE="Right hand" |
The actual position can
be fixed up. (so you're not forced to link an extra bone to the skeleton
to achieve the right position)
#exec MESH WEAPONPOSITION
MESH=MeshSk YAW=50 PITCH=0 ROLL=10 X=0.0 Y=0.0
Z=0.0 |
This attachment point is
then fully backward compatible with Unreal Tournament's weapon
polygon.
Important notes
- When setting up a
skeleton, regardless of whether you're using Max or Maya, make sure each
and ever bone/joint has a unique name. Take special care to do this
after you've constructed a skeleton using mirroring. The code that
resolves the hierarchy and linkups, both in the exporter and in the
engine, assumes that unique names are used.
- The visibility
bounding-box extents are determined from the reference pose, not the
entire range of animations as was the case for vertex animations.
To compensate for the possibility that animations extend far beyond the
bounds of the reference pose, the code currently uses the reference pose
limits and scales those out once more, to estimate a safe size as used
for visibility determination. If meshes still flicker, it may be because
the animations that were exported stray too far from their reference
pose / origin position, and move beyond the boundaries where the engine
expects it to be. You can override the bounding box extents with the "BOUNDINGBOX"
#exec command.
- Skins: the best way to
currently guarantee that the order of skins isn't messed up is to
strictly follow "skin00, skin01.." naming conventions for your multi/sub
materials in Max.
- Root pose issues: to
prevent anomalous vertex assignments slipping in when exporting the .PSK
file, it is recommended to export it from either an explicit root pose
(as can be activated with bipeds in Character Studio) or in any case,
make sure frame 0 is reachable as part of the active time slider so the
exporter does not get confused with the skin's versus the bones'
reference poses.
- When the mesh shows
messed up in the engine, it's usually a matter of the .PSK not matching
the .PSA. This can happen even if they're exported from the same
Max file in some cases. Reference skin PSK files are saved from
the first available frame; when the first frame is hidden, and the
animation bar is set to show only a subset of the frames, the exporter
may get confused and associate the bone reference pose with the wrong
skin reference pose. It's easiest to keep a special original
.max file which contains this 'reference pose', the right skin/material
linkup, and no animation, so you can always rely on that as the source
for the .PSK file, without having to mess with the start-time of
animations.
- Orientation/height
problems: due to the different 3D axis assignments in Unreal, Max and
Maya, if no adjustments are applied, Max characters come out turned 90'
sideways, and Maya characters turned on their backs. Also, in most cases
it is convenient to have feet placed on the zero plane when
editing/animation characters, while the engine may, depending on game
code, rely on some actors (like player models) to be centered around
zero instead.
Orientation and height can be adjusted in script (at
rebuild time, rather than engine-runtime) right after the .PSK import
statement, using the MESH ORIGIN commands:
Typical maya orientation adjustment: #exec MESH ORIGIN
MESH=PistonMesh X=0 Y=0 Z=-32 YAW=64 PITCH=00 ROLL=64 Max player
height adjustment: #exec MESH ORIGIN MESH=WarBossMesh X=0 Y=0 Z=90
YAW=0 PITCH=0 ROLL=0
[end of document | back to
top] |