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]
|