 |
|
 |
|
|
|
Please take note! For mod developers working with Unreal Tournament 2003, this documentation is meant to be a starting point for your own explorations into UT2003, not a definitive guide. There will be differences between the documentation here and the product in your hands, and you may have to figure out quite a bit for yourself. Check out the Unreal Tournament 2003 page in the Unreal Powered area for links to community sites if you're having problems. UDN is a licensee support site, and cannot provide technical support or game-specific assistance to end users.
|
|
|
|
|
 |
UKXPackagesTutorial |
 |
|
|
|
|
|
Licensees can log in.
Interested in the Unreal engine? Check out the licensing page.
Questions about UDN itself? Contact the UDN Staff.
|
|
|
|
|
|
|
|
|
|
Using the Animation Browser and UKX Animation Packages
Last updated by Erik de Neve. Original author - Erik de Neve (EpicGames - erik@epicgames.com).
- Using the Animation Browser and UKX Animation Packages
- Introduction
- Art path
- Basics
- View modes
- Importing Meshes
- Importing Animations
- Advanced use of timed animation notifications.
- Interactive static-levels-of-detail mesh preparation
- Optimizing your mesh with rigid part extraction
- Attachment positioning
- UKX package management
- Notes and known issues.
Starting with Unreal Warfare version 829, the bulk of the functionality needed to bring (skeletal) mesh animation data into the engine is now built into 'Animation Browser' window inside the Editor, and a new native resource package format is introduced - the *.ukx animation package. A lot like texture sets (*.utx ), these packages hold binary, digested data in a native Unreal Warfare format loadable at runtime by the engine or editor.
The script-based art-path of linking in animation and mesh data using script #exec commands into packages still works, and for a few types of resources it may still remain the preferred art pathway (see also "Important Notes" below.)
Using UKX packages, you can import meshes and animations directly from .PSA and .PSK binary files, assign materials, and
have the meshes animate in the editor - and in the game, provided the UKX package has been saved and code exists that refers to the mesh and animation data therein by the proper package and name.
Meshes can be previewed, scaled and adjusted; animations can be assigned the proper names, play rates, game-code notification callbacks, and group identifiers.
Three new browser boxes near the top of the animation browser window select which package, mesh and animation
to work with. First, select the package you'll be viewing or updating. If you want to create content in a new package, you'll be able to enter that when importing the mesh or animation. The two combo-boxes right under the package box are used to select the current mesh and animation. If the package has none, one or both boxes may remain empty.
If a selected mesh has any current animation assigned to it, that animation object will always become current as soon as that mesh
gets selected.
To permanently link the current animation to the current mesh as its default animation - equivalent to the "#exec mesh defaultanim ... " assignment - click this chain button once. 
Most if not all of the features for which push buttons are shown here can also be used via the top pull-down menus.
 View visibility bounding box. The visibility boundaries for skeletal meshes are static relative to the mesh's zero-point, and don't depend on any animations.
This bounding box determines visibility. If any part of this box is visible ( if any part of it falls in the view frustrum, and is not totally occluded by the anti-portals etcetera ), then the render code for its mesh will be executed. It has no bearing whatsoever on collision.
Adjustable directly as part of the mesh's properties, you'll want to tuck it in and make this as conservative as possible, otherwise characters that are not visible may waste a lot of resources, for example large bounding boxes can poke down through floors causing
them to get rendered in vain as they get completely overwritten, or z-buffered away by the scenery again in the same frame. If for
certain animations a hand, spike or whatever (or conceivably an attached weapon) pokes through the boundaries occasionally, it isn't a big deal since the cases where only that part of a mesh determines the visibility check outcome are usually rare (e.g. it would have to be just that part poking around the edge of a doorway at that exact moment in its animation. )
  View bones, view bone names - self-explanatory. Multiple presses on the 'view bones' button toggle on and off the rendering of the mesh itself.
 View reference pose. Pops the mesh into the reference pose ( the default pose that resided in the PSK.)
 View normals and influences. Small color-coded normal vectors originate at each vertex, where the coloring signifies the number of bone influences acting on that vertex as follows:
- green - single influence
- red - two
- pink - three
- light blue - four
- white - five or higher
 View at original mesh-space offset. Draws the mesh without any additional translation (see Mesh properties) Specially useful since (at least in UT) the desired mesh-displacement is such that its 'middle' sits at zero-Z - which is a UW specific gameplay code convention, not a renderer issue.
 View with active in-engine style backface culling.
The default mesh rendering mode in the editor does not perform any back-face culling, in contrast to the actual in-engine rendering. However, you may well need to determine whether certain character is properly set up (e.g. with double-sided rendering specifically enabled
for certain flat and/or alpha-translucent parts.
 View mesh in wireframe mode.
 Digest a .PSK file.
Specify the mesh's name and package. A non-existing package will result in the creation of a new one.
If you are importing into an existing package, make sure all contents of the package are loaded before changing anything (use the load-all button). The same goes for any other importing or tweaking.
 Mesh property editing.
The properties exposed here allow adjustment the mesh properties that used to depend on many "#exec MESH" type commands, including adjustment of scale, rotation, visibility bounding box and the assignment of materials.
Materials are assigned by going to the Texture browser and selecting the desired skin material to make it the 'current' material, then pressing 'use current' in the appropriate slot. If desired for skin-linkup work, the Animation and/or Texture browser window can be undocked to put them side by side.
While you do have to import and create textures packages separately, the linkup is automatic at mesh import time if the materials in Max or Maya had names that match materials present in the editor. These are the names as can be seen in the X_ModelInfo log file, and they are matched to any textures - regardless of that texture's package- or group name.
The double-underscore naming convention allows you to specify the materialname tags that are recommended to order the skins ( skin00, skin01, alpha, etc.) without confusing the texture match-up - the editor will only look at the part before the double underscore.
So, a material named bodyarmor_skin00_translucent will be linked up at PSK-import time to a material named bodyarmor, if that material
is present in the editor at that time (i.e., anywhere in the texture browser.)
With these buttons, mesh properties which include the bounding box- and rotation/scaling, can be copied/pasted among meshes from different packages.
 Digest a .PSA file.
The package and name of the animation are specified. You can also add/overwrite individual sequence data into existing animation objects by checking the appropriate options.
Specify the exact existing package/animation name when merging into existing data, and make absolutely sure the .PSA binary data
you're importing is completely compatible with the existing animation sequences - that is, they must have been exported
from a character with the exact same skeleton.
 Animation property editing.
The following work on all sequences of a certain animation object
at once; and when pasting, the properties are assigned to sequences whose names match the original sequence names at the source.
 Notification copy/paste/clear.
 Group assignment copy/paste/clear.
The UT2003 version of the animation browser may not show all of these buttons, but the complete set of options can still be found in the pull-down menus.
* To be written *
 Level-Of-Detail cycle/import/redigest.
The smooth vertex-collapse level-of-detail rendering code has been replaced with a static LOD scheme, which gives the artist more control and is ultimately much faster for the same amount of displayed detail than the older, variable-level-of-detail code.
The new scheme is backward compatible with existing UKX-es, and
uses the collapse data already precomputed inside the UKX mesh
data to generate four static levels of detail, which can be adjusted by artists to find the right trade-off between speed and detail.
Using in-line editing of property lists (under the 'Mesh' tab, in the panel on the right) you can manage a variable number of levels of detail - the maximum is 8.
The process will be familiar to anyone who's worked with the particle system, so I won't go into detail here - you can insert, add, or delete levels-of-detail and adjust individual LOD's parameters.
The levels-of-detail will kick in when you move away from the model
in the central view window, just as it does in the game. This allows quick interactive adjustment of the detail meshes.
All the relevant parameters to adjust static levels of detail
are found under the LOD header in the Mesh property tab of the animation browser.
* LOD_Strength
This is an overall factor to scale the internal distance-detail factor; it is displayed in real time at the end of the status line in the view window.
A list of relevant parameters in each LOD level:
* DistanceFactor
This value will be compared against an internal factor calculated
from a combination of the mesh size, screen resolution and actor
distance.
The active level of detail is shown as 'lod n', - when
you force the level of detail (using the orange cycle-LOD button with the little squares ) you'll see it in upper case like 'LOD [n]'.
Whenever the number displayed in the viewport status header next to the non-forced 'lod n' indicator reaches the DistanceFactor value, the next LOD level will take effect.
* Hysteresis
This value gives a range around the DistanceFactor within which the
level of detail will be 'sticky' and not change. Any reasonably small value ( like 0.01 ) will help eliminate potential flicker that would otherwise occur when a mesh happens to sit at the exact boundary of two LOD's, distance-wise.
Hysteresis and DistanceFactor can be edited and take effect immediately. The remaining three variables in each LOD however determine how to rebuild the individual LOD levels whenever the 'redigest LOD levels' button is pressed.
* MaxInfluences
Limit to the maximum number of bones influencing (deforming) each vertex during animation. Since most of the the CPU's work on skinning a mesh is proportional with the number of influences rather than the number of vertices, limiting this is a good way to gain performance without sacrificing too much detail.
The maximum amount that the (PC) rendering code supports is 7 influences per vertex, but 4 is a more reasonable upper limit for the model at full detail.
* ReductionFactor
An approximate value between 0 and 1, indicating how many vertices to collapse ( 1 forces full detail )
* SwitchRedigest
Indicates whether to rebuild this particular LOD level when the LOD re-digest button is pressed. You'll usually set this to FALSE if
you want to force a user-designed LOD level, which you can import into whatever the current forced level is, with the second orange
button (mesh import button with a little orange block )
* Note on performance and triangle coherence *
Skeletal mesh triangles reordered for optimal coherence. Note that if you made a UKX with a pre-927 version and haven't touched the skeletal meshes in it, the backward-compatible load-time conversion in 927 and later skips the face sorting step to avoid long delays. Pressing the animbrowser's re-digest button, or re-importing the PSK, will do a fresh triangle sort for the current mesh.
With the release of UnrealEd 3.0, you have the option of automatically converting parts of your skeletal mesh to 'rigid parts' - sections of a mesh that are influenced only by a single bone. These parts - as far as the hardware is concerned - can be rendered like static meshes, in that they are uploaded to graphics memory once, without a CPU-intensive
multi-bone skin blending step. When suitable meshes are converted in the right way, this can give very significant rendering speedups. This is a per-LOD-level option, and and disabled by default. In wireframe mode, all rigid parts show up as red, while software skinned polygons remain yellow.
To enable it, in a LOD-level's "rigidize" subsection, first specify the following parameters (see screenshot):
MeshSectionMethod: this can be set to :
- MSM_SmoothOnly : Smooth (software transformed) sections only - this is the default method.
- MSM_Mixed : Convert suitable mesh parts to rigid and draw remaining sections using software skinning.
- MSM_RigidOnly : Only draw rigid parts, throw away anything that can't be rigidized.
- MSM_SinglePiece : Freeze all as a single static piece just as in the refpose. Useful to optimize really far-away LOD levels.
MimPartFaces: The required minimum number of faces in the rigid parts to be extracted. Regions smaller than this are assumed to be not worth the separate hardware calls.
MaxRigidParts: The maximum number of rigid parts allowed. If there are too many parts, try increasing the MinPartFaces requirement rather than limiting MaxRigidParts.
After setting these parameters, press the mesh-redigest button once to redigest all LOD levels; rigid parts will be created automatically. Lock the viewer into the specific LOD level you're tweaking with the LOD-cycle-button, and check the 'I'nfo button after each redigest to see how much smooth and rigid sections you've ended up with; you can keep tweaking the parameters and redigesting until you're happy with the results.
Note that since they are part of the automatic LOD redigest code, rigid parts can be assigned and removed as an afterthought.
Some things to keep in mind when evaluating the trade-off between rigid parts and smooth skinning:
- Mixing rigid and smooth parts implies automatic duplication of any vertices which are shared by both types of polygons.
- Large numbers of rigid parts - cause lots of low-level calls to the hardware ( one extra transform matrix and primitive-drawing call for each section ) which defeats the purpose of using them as a speedup. In many cases it is worth it letting large numbers of small parts that are only linked to a single bone, get handled by the software skinning instead, while only a small number of higher-poly parts are converted to rigid sections.
A post-927 code update (available on the UnEdit FTP site - \Unreal Warfare Versions\Version927\AttachmentCode.zip )
allows in-editor creation and semi-visual adjustment of the 'AttachName' sockets, - visual, as in type-in-new-numbers and see stuff move - the creation of which used to be restricted to the #exec script commands.
This works as follows: take for example this script-based attach tag definition:
#exec MESH ATTACHNAME MESH=WarriorMesh BONE="right_wrist_2" TAG="weaponbone" YAW=-64.0 PITCH=00.0 ROLL=128.0 X=0 Y=0 Z=0
In the animation browser, in the Mesh property tab sheet on the right, there is a new 'Attach' section with an interactive array of 'Sockets'. The array is inline-editable ( like the LOD levels, for example), to manage a variable number of sockets by inserting, adding, or deleting individual ones and adjusting their properties.
Analogous to the script command, AttachAlias contains the "TAG", while BoneName must be an existing bone of the current character to which this tag will apply ( click the "view bones" and "view bone names" buttons to see which one you want.) A_Rotation and A_Translation let you specify the adjustment. These four properties are the same ones as in the above script command, and are all that gets saved for/defines each 'socket'.
The same game code rules still apply - the attachments themselves are not assigned with the mesh data in the UKX package.
From script, game code for an actor needs to call " AttachToBone(Weapon,'righthand') " to attach the actor 'Weapon' to the desired alias or (raw)bone named 'righthand'.
Above the sockets array in the Attach section, 'ApplyNewSockets' is a single-shot 'apply-all-changes' button which when set to true will copy the changes you made back into the mesh data (and it instantly reverts to false again.) To see specific test-attachments change position and scale interactively however, you'll need to set 'ContinuousUpdate' to true.
For visual feedback, the optional temporary TestMesh and TestStaticMesh can be set to any content present in the editor (TestMesh takes precedence if both are selected ) which then will be rendered at the appropriate bones on the skeletal character (use Test_Scale if necessary.) These will be erased as soon as you select some other mesh, since they're only meant to help adjust the sockets and never saved with the actual mesh in the UKX.
You can flip between the 'Animations' and 'Static Mesh' browser tab to select a static mesh which you assign to the TestStaticMesh in a socket with 'use current'.
Selecting a skeletal 3rd person mesh for positioning is a little trickier, because the 'use current' button comes up with the player mesh itself (doh!) so you'll need to type (or copy/paste) the full object name in the TestMesh box - i..e. SkeletalMesh'XWeapons_rc.MinigunHandMesh'
UKX package management
From script, the new animation and mesh resources can now be referenced like any other package content. For example,
when the package CharacterAnims.ukx contains meshes and animations for your player character, you can do:
#exec OBJ LOAD FILE=..\animations\CharacterAnims.ukx PACKAGE=CharacterAnims
Or, in an actor's default properties: Mesh=Mesh'CharacterAnims.MainProtagonistMesh'
Where MainProtagonistMesh is one of the meshes present in the .ukx.
The goal in general will be to have your art pipeline allow artists to update and use UKX files without programmers having to make a new
build; so be sure that any game-code reference to a resource in a UKX package does not pull in data from a UKX to reside into another
package.
This depends on a subtle difference in the use of OBJ LOAD; if the above #exec were changed to:
#exec OBJ LOAD FILE=..\animations\CharacterAnims.ukx PACKAGE='ThisPackage'
Where 'ThisPackage' is the name of the package this script
file sits in, then the data would be duplicated into ThisPackage.
Using #exec commands in script to modify data referenced from a .UKX will be useless unless the data got specifically OBJ-loaded and duplicated into the .u package with that second method.
One easy way to check out new (non-animating) meshes which aren't referenced by any gameplay code yet in a running level, is to place an existing decoration actor in a test level and assign the current mesh to that actor's mesh variable.
* After importing mesh or animation data, as well as when switching
the current package in the selection boxes near the top,
the current mesh and animation selection often resets to
the first object in the list instead of the last one used; therefore,
if necessary make sure that both the current mesh- and animation box have been (manually) set to the desired objects to avoid confusion;
* Always explicitly click the 'chain' button when you want to link up the active mesh run with the active animation, even if just for testing ( and re-link to the desired pairings before saving a modified package ).
* The browser does not distinguish between skeletal meshes in UKX packages and ones that got linked into any other (.u) packages with the #exec command.
So,when manipulating meshes, always make sure you are working on
mesh and/or animation data that either resides in an existing .UKX package ( or which you import into a new package and save out as a fresh UKX.)
While you need to avoid touching skeletal meshes that are in any other
type of package, you can still use such meshes as a source of notifications/groups/mesh-properties settings with the
various copy/paste buttons.
* Some packages may only be partially loaded when you're editing them.
If the data you're working with is part of an on-disk .UKX package,
be sure to click the 'load all' button before you save out the
updated package, to avoid losing mesh and animation objects in the process.
* Importing meshes and animations is a one-way process; for any future adjustments (notably, animation compression re-tweaking )it's important to keep PSA/PSK's and/or their Max/Maya original source
art archived.
* Per-sequence animation compression (as well as overall more efficient compression) tweaking is still being worked on.
* Specifying groups to subdivide animations and meshes in a package
will probably be enabled in an upcoming version. For now, typically
the UKX holds a manageable amount of meshes and animations, and
sensible grouping can be done by creating multiple UKXes.
- the end -
|
|
