The script runs in 2 stages. First run determines the largest motion in the vertex animations to determine the minimum points and range of motion that will be scaled to fit into the color representation of the movements. The second run reads the vertex positions and fits them into the previously calculated range. After the second stage is complete the position and normals animation textures are saved and a new mesh will exist in the scene setup to preview the animation and ready for export.

Controls

• Relative Motion - animation will be defined relative to individual vertex minimum XYZ values and maximum change in XYZ for all vertices. When unchecked the animation will be based on the bounding box minimum and maximum values.
• First Frame Ref. Pose - the first animation frame vertex positions will be included in the bounding box limits of the animation The actual animation will start on the next frame.
• HDR Image Generation - when enabled the position texture will be saved as a float value exr image. When unchecked the position texture will be a saved as a png format file.
• 'Metadata' Rename - the VAT Data node will be renamed to "Metadata" so the information from the node will be included in an fbx export of the mesh.
• Texture Base name - this name is used in the naming of the position and normals animation textures. Below shows naming samples assuming a base name of "AnimTexture"
  • VAT_Delta_AnimTexture_P.png - "Delta" means Relative Motion and "P" means positions
  • VAT_AnimTexture_N.png - "N" at the end means normals, the normals are calculated the same for both types of motion. So there is no BBox or Delta signifiers.
  • VAT_BBox_AnimTexture_P.png - "BBox" means use the extents of the bounding box over the course of the animation. Relative Motion is unchecked.
  • VAT_BBox_AnimTexture_P.exr - hdr image is generated. EXR export does not use BBox despite the naming. The normals animation texture is always generated as a png file.

Relative Motion gives better results. It works by creating an altered version of the mesh that maximizes the use of the color values to give higher resolution motions. This is especially true for small motions.
When unchecked the mesh is not altered and the total motion is fit into a box around mesh. The RGB values are limited to 256 values each, so small motions can be clunky as they jump between the limited number of values.
Relative Motion will add "Delta" to the texture file name. Unchecked will add "BBox" to the name.

The thinking behind the First Frame Ref Pose is that the mesh can be exported with it's original shape. and any other animations exported will work with that shape. Relative Motion can only be used with the shape generated by the Relative Motion process.

The First Frame Ref Pose option does not always work with the Relative Motion option.

HDR will export an exr image and create an 8 bit image internally for tS visualization.

Usage:

1. Be sure the object uses compound d3d materials and they are not scene instanced.
   material converter refers to compound materials as "D3D" materials
2. Name the materials for a better import result later and to avoid other material issues.
3. Animate the object using vertex morphs, skeleton or deformations.
4. note: cyclic animation repeat the first keyframe at the end before conversion
5. If the First Frame Ref. Pose is used, create a keyframe 1 frame before the first frame of animation to define it.
   Set the interpolation to linear to prevent overshoot in the animation.
6. Select the object and set the play range of the animation in the Anim view.
7. Open the Vertex Animation Texture Tool and set a base name for the textures
8. Press Run and choose the folder for the files.
9. The texture files will be generated and saved and a new mesh object will be setup to use the textures.
10. The new object will have a VAT Data or Metadata node inside that shows the scale and offset values needed for the vertex animation shader.
11. The new object will have UV set 2 setup for the animation.
12. Export the new mesh to a format the desired game engine can read
13. Use the values for scale, num frames, and offsets in the custom vertex shader

note the folder dialog will remember the last selected location, but may not scroll to it when opened.

TODO

• test normals in UE4 - not needed in Godot, only 2 uvs allowed so no lighting?
• "real" shader for UE4
• refresh notes for ue5 and godot 4

Cloth Conversion utility can be used to export a cloth animation as a vertex color animation.

Sample Shaders

VAT_SampleMaterials.zip - sample materials

Sample includes 2 Unreal 5 uasset files, one relative and one absolute

Sample includes 2 Godot 4 tres files, one relative and one absolute

These shaders need more work and refinement. They work but can be better.

Godot result does not cast shadows. Does receive shadows from other items.

Unreal 5 object will cast shadow and self shadow.

Godot import - texture import detect 3D > Compress To > Disabled

Godot, time scale about 60, numframes = height of images, no scale of values needed, gltf seems to work well, drag both gltf and bin files in

Unreal 5, texture group = 8 bit data and set data on sampler nodes, this also set compression settings to vectordisplacementmap(rgba8), scale * 100, offset * -100, save fbx scale = 100 and Metadata option works well

Future changes?

• work with physics - maybe modify cloth scripts

Theory

First the script makes a special uv layout in uv2 with the uv coordinates centered on the bitmap first row of pixels representing the first frame of the animation. Then the script finds the mesh vertex with the most amount of motion and uses that value as the maximum value of the bitmap for scaling the arbitrary xyz values into all positive rgb color values between 0 and 1. Then it runs through the animation to read the positions of all the vertices at each frame, saving the difference between the original position and the current xyz values. The scaled and offset difference is stored rgb values in the texture with 1 row for each animation frame and column size equal to the number of vertices in the mesh.

The mesh with the custom uv2 and textures are imported to software that supports vertex animations based on textures. A custom shader is created that moves the uv2 coordinate values through the texture, 1 row of pixels(1 frame) at a time reading the rgb values and converting them back into xyz values and adding them to the original xyz position in the vertex shader.

Notes:

• GLTF file, drag both gltf and bin file into Godot, then rclick New inherited scene and override the materials by dragging the tres files into place.
  copy tres file vertex_animation_vshader_relative_xxx.tres into the Godot FileSystem tab. select mesh in scene and Surface Material Override drag tres into slots
• The HDR option does not have bounding box or relative motion limits. The vertex position values are saved as is into the bitmap without any scaling or offsets.
• tested in Godot and UE4
• Relative Motion gives better results when not using the HDR option and works in UE4
• uv1 for color, uv2 created for vertex animation
• tS can generate a signed floating point format texture and save it to exr format via the plugin
  UE4 wont import hdr as texture, only as cube texture, it will import the exr format.
• tS can load 16bit png but will not write 16bit png
• tS does not have tex2Dlod shader function used to read texture samples for vertex shaders, so it cannot use animated vertex textures internally

Dev Notes

• https://www.youtube.com/watch?v=NQ5Dllbxbz4&t=170s - original blender code used to develop this
• use https://imagemagick.org/ to convert file formats, ImageMagick-7.1.1-39-Q16-HDRI-x64-dll.exe
• tS weird mesh order requirements - uv2 points before uv2 triangles, but reversed in other cases
• also weird had to use MeshModifiers.OptimizeTriangulation on copied actor mesh before it would properly update
  could see issue in 3d view by setting the mesh normals to mooth and seeing a crazy result or edit the mesh and it would jump when moving vertices.
• tS shader node VectorTo and FromComponents definetely weird, W value has an effect on XYZ values - made custom versions to get around the issue.
• used custom renaming script to get around tS safe rename with [comma][space][number]
• test of converted hdr to exr on a mesh with vertex colors sine wave does show higher color image inside unreal with smooth deformations. dont know why cant get high color to work with anim texture
• bilinear filtering may work to smooth out motions - no luck so far, idea was double width image to avoid filtering 2 values from 1 time frame
• https://medium.com/tech-at-wildlife-studios/texture-animation-techniques-1daecb316657 has some good information and some clues to get around low precision color values.
• side note: IRdUVSelection may be only way to work with UV values, via pe mode, correction can set uv selection as well, maybe more rsx work in the future...
• https://forums.unrealengine.com/t/vertex-animation-script-for-blender-3d-users/85580 found this for 3dsmax vertex anim tools https://dev.epicgames.com/documentation/en-us/unreal-engine/vertex-animation-tool---timeline-meshes-in-unreal-engine?application_version=5.4 found this for blender https://github.com/JoshRBogart/unreal_tools?files=1
• animation range is scaled and offset to fit within 0-255(0-1)
• animation range bounding box bbox min and max values
• animation range delta min individual XYZ values for each vertex, maximum change in XYZ values for all vertices, so small motion will expand to fit the full 0-255 range giving smoother result. bbox may be better for large motions
• num vertices limited by texture size maximums
• HDR format saved from tS is not high quality, it has steps like an 8 bit image.

convert all pcx format files to png format:
magick mogrify -format png *.pcx

convert hdr format to exr:
magick mogrify -format exr -compress Piz *.hdr

Godot

• Godot (v3?) Visual Shader - not compatible with Godot 4, right click to save as
• Time Scale - speed of playback
• Num Frames - number of animation frames exported, y size of the texture
• Scale - multiplier to convert rgb 0-1 value back to xyz values
• Offset - xyz offsets to recenter the mesh in it's local space - rgb 0-1 => +- xyz
• Position - TAV texture
• Albedo - mesh color texture
• importing mesh as collada - newer formats better?
• only 2 uv channels allowed so lighting needs to be baked into the color? texture or use unlit? need to learn more godot
• texture import Compress=Lossless or Uncompressed
• texture import Filter=Off
• texture import Mipmaps=Off
• shader flag unshaded?
• Normals - TAN texture not used

UE4

• import as fbx mesh
• shader connections shown above work for quick preview - no scale or offsets or discrete frames

Old version

Vertex Animation Texture Export for trueSpace7.61

Usage:

1. Animate a mesh using vertex morphs.
2. load the Vertex Texture Animation node into the link editor
3. Select the mesh and set the play range of the animation in the anim view.
4. Type a texture name, the file names will be TAV_name.png and TAN_name.png. Where TAV is the vertex position and TAN is the normals.
5. Leave Relative Motion checked
6. Press start and choose the folder for the files.
7. The texture files will be generated and saved and the mesh UV2 will be setup to use the textures.
8. Set the object morph to match the first frame of the animation.
9. Copy the object and manually remove all the vertex morph nodes from the original object
10. export the "Input Mesh" connector from the editable shape
11. connect then disconnect the "Mesh" connector from the copy to the "Input Mesh" of the original to copy the morph state of the first frame
12. export the mesh to a format the desired game engine can read
13. use the values for scale, num frames, and offsets in the custom vertex shader

November 13, 2024

• finished renaming all from VTA to VAT
• add EXR float image export

October 17, 2024

• fix major bug that limited the motion - bad math had negative value assumption, exportable colors only positive
• has installer
• replaces corresponding uu scripts and updates the uu button
• automatic: includes the manual steps needed with the old bare script
• works with actor and deformation animations - uses command node loops to update scene changes for reading
• "absolute", non-relative, mode works
• separate scale controls for X,Y and Z
• naming change VTA to VAT and make naming less confusing
• new system to drive the preview animations inside tS - no longer requires stack view

back to the trueSpace Import Export Plugins Scripts list