Tuesday, January 29, 2013

Building a Scripted Plugin Modifier for Game Characters

In response to  +David Moulder I have detailed a little more of our character "referencing" and scene building process, starting with our custom character modifier. I hope this is helpful.

All of our characters and animated objects have a custom scripted plugin modifier that sits on top of the character mesh modifier stack. It stores references to the skeleton and helper objects in the parameter blocks of the modifier. To store these object references you will see below the parameter type should probably be a #maxObjectTab type.  If you are looking for something similar to the message attributes in Maya the #maxObject parameter type, or what 3dsmax calls weak referencing, is as close as you are going to get. Paul Neale has a pretty good tutorial for weak referencing.

Weak References

I went ahead and wrote up some functional code below to help provide a basic understanding of scripted plugin modifiers and weak referencing. If you evaluate this code a new modifier will appear in the modifier list named "AnimExportTest".  It does not modify your mesh/object it is only a container for storing references and variables relative to your character.
plugin Modifier AnimExportTest
name:"AnimExportTest"
extends:EmptyModifier
 
--- The id here must be unique run genclassid() to generate a unique id for your plugin
classId:#(0x2c608fe8, 0x14804a99)
 
version:1
(
 -- set the file path parameter
 fn set_path &path =
 (
  local file_path = getSaveFilename filename:"C:" types:"Meshx(*.meshx)|*.meshx|ALL|*.*" 
  if file_path != undefined do (
   path = file_path
  )
 )
  
 -- add object weak references to the parameters
 fn add_bones objs =
 (
  for obj in objs do (
   -- this is how you create a weak reference to an object/node
   add_obj = (nodeTransformMonitor node:obj forwardTransformChangeMsgs:false)
   append this.p_bones add_obj
  )
 )
  
 -- object selection filter
 -- boolean check to see if the incoming object has what you are looking for
 fn bone_filter obj =
 (
  is_valid = True

  -- make sure the object is our type of bone
  if ( not superclassof obj == helper ) do ( 
   is_valid = False 
  )

  -- make sure object name has namespace identifier ":"
  if ( not matchpattern obj.name pattern:"*:*") do ( 
   is_valid = False 
  )

  -- make sure the object or object name doesnt already exist in our list
  for bone_obj in this.p_bones do (
   -- since this is a weak reference get the .node to query the actual object
   if ( bone_obj.node == obj ) do ( 
    is_valid = False
    exit    
   )
  )

  -- return bool
  is_valid
 )
  
 --- Store any variable,object references, export paths, values necessary to this modifier
 Parameters export_params
 (
  p_export_mesh type:#string   default:""
  p_export_rig type:#string   default:""

  p_bones   type:#maxObjectTab  tabSize:0  tabSizeVariable:true
  p_bone_names type:#stringTab     tabSize:0  tabSizeVariable:true
 )
 
 -- rollout ui creation
 rollout ro_export "Export Paths"
 (
  Group "Export Paths" (
   Button bn_export_mesh "Export Mesh" width:100
   Button bn_export_rig  "Export Rig"  width:100
  )

  --- Functions to set paths
  On bn_export_mesh pressed do (
   set_path &this.p_export_mesh
  ) 

  --- Functions to set paths
  On bn_export_rig pressed do (
   set_path &this.p_export_rig
  ) 

 )
  
 -- export objects menu
 rollout ro_export_bones "Export Objects"
 (
  Group "Export Bones" (
   MultiListBox lbox_bones "" width:140 height:20
   Button bn_add_bones "+" across:2
   Button bn_remove_bones "-"
  )  
   
  -- Update the rollout interface
  fn update_ui =
  (
   local bone_names = #()
   for obj in this.p_bones do (
    -- since this is a weak reference get the .node to query the actual object name
    append bone_names obj.node.name
   )

   lbox_bones.items = bone_names
  )
    
  --- Functions to add and remove bones
  on bn_add_bones pressed do (
   
   --- object picker dialog
   new_bones = selectByName filter:bone_filter
   if ( new_bones != undefined ) do (
    add_bones new_bones
   )
   
   -- update the interface
   update_ui()
  ) 
  
  -- Update the interface when the rollout is opened
  on ro_export_bones open do (
   update_ui()
  )
 )  
)

Custom Test Modifier
Custom Character Modifier
by  +Nathaniel Albright 
Our version of this modifier has many more methods, attributes and options for storing animation and other references. This is more or less the core interface for evaluating incoming animatable assets to make sure they are properly setup for animation and exporting when building an animation scene, as noted in my previous post.

You may chose to build a similar interface but rather than a modifier it can be a custom shape object that lives in your scene. It's pretty much the same thing just where it lives is different.


Custom Attributes & adding Assets
When adding an asset I will merge the entire scene and inspect this custom modifier to make sure it has everything I need for animation. If it passes the validation process I will collect a list of only the objects necessary for animation and delete the remaining unnecessary objects that came into the scene. Once I have identified the valid objects I will apply a "namespace" prefix to them based on the supplied asset name. I will then stamp additional attributes onto all of the valid objects to sort them and identify them as a unique asset within the scene. You can see my post on Tech-Artists.Org for more on custom attributes. Below is an example of setting the custom asset attributes on the incoming objects.

-- Asset Attributes
-- This attribute block should probably live in your library code
--- so that it is always accessible.
my_asset_data = attributes asset_data
attribid:#(0x6664296c, 0x5dec7a0)
version:1
(
 parameters asset_data
 (
  asset_name  type:#string  default:"none" 
      asset_id  type:#integer  default:0
      asset_type type:#string  default:"Character"
 )
)

-- Loop through all the incoming objects and apply the custom attribute

-- Apply attribute class to an object
add_attribute = custAttributes.add obj my_asset_data baseobject:True

-- update attribute data with your unique asset name, asset Id
-- and anything additional you need to track
obj.asset_name = obj.supplied_asset_name
obj.asset_id = unique_asset_id


A Bulk of the Work
Now that you have brought in a character asset into your scene in a clean and managed fashion the heavy lifting is done by your scene manager. Adding and Deleting should then become fairly trivial as your asset objects should be clearly identified. However, the swapping of your animated characters requires your tool to do much more in the way of saving animation, link constraints and export data defined in your scene. This of course relies heavily on your control rig system be it CAT, custom, or god forbid Biped +Brad Clark.  Once you have a proper save and load, swapping assets should become a "breeze". I will note that 80% of my Asset Manager code is handling the saving and loading of animation. You may find many cases where you have to do a lot of code to preserve the state of your animation in relation to other objects or characters in your scene.

Feel free to ask any additional questions. I will try to follow up.
Until next time.

UPDATE: Fixed some script errors in the plugin modifier. It will now refresh the ui when you reopen it.

Saturday, September 1, 2012

3dsmax Animation Referencing and Scene Building

Having worked on many game titles in the past its quite clear that scene building and having a way to reference or quickly update characters and rigs is very important. If you work in 3dsmax you are probably quite aware and envious of the referencing capabilities that exist in Maya. This functionality is clearly missing from 3dsmax and may likely never appear. Sure there are Xrefs but be my guest if you choose to use them and discover you don't get nearly what you need with the added benefits of instability.

So out of necessity I started work on what ultimately became our Animation Asset Manager ( AM ). The tool merges assets, Characters, Weapons, Vehicles, Props, Environments, etc. in a quick and efficient manner. Straight ahead file merging can result in a very messy file, as 3dsmax does not have native "namespace" functionality, and there may end up being a lot of object name collisions and rig linking errors. The Asset Manager handles all of these issues and bundles all of the incoming file objects into one "Asset". Now working in hugely complex scenes is quite easy as thousands of objects can now be represented as one Asset.

Adding an Asset
  • The artist chooses the asset type to add
  • Selects a file from a list of assets or locate a specific file on disk 
  • Provide a unique name to represent the Asset
  • Add the number of asset instances

AssetManager - Add Character Asset
What actually happens behind the scenes is a bit more complex. The incoming file is first validated to make sure it is export ready. If the AM finds everything it needs for that asset type then it will fully merge the file. After merging, the incoming objects are checked and objects unnecessary for animation/export purposes are removed, shaders are converted to standard materials, all objects are stamped with Asset Attributes, and finally object names and layers are properly namespaced. The attributes that were added to each object were done to easily classify the objects under one "Asset". When the AM updates it scans the scene and represents each asset properly by querying the object attributes. In the past I used very light-weight user defined properties but I have converted to custom attributes as these can be properly transported between DCC apps and maintained in the FBX file format.

AssetManager - Asset Objects


Swapping an Asset - Poor Man's Referencing
As characters, weapons or props are updated the animators need to be able to easily update to the new asset when necessary. Cosmetic changes don't always mean an update needs to happen but specific rig changes may require updates. Scene callbacks are put in place to verify animated assets in files are up to date in regards to explicit external file references that are checked on scene open. The AM ensures that these objects can be swapped and any animation existing in the file is maintained, this is where a great deal of the code in this tool comes into play. This includes full character animation, IK objects, morph animation, external link constraints and any other custom animations related to the asset. We employ our own save animation functions to handle everything outside of the basic biped motion to ensure keys and motions are maintained between potentially different objects. However, making sure everything transfers properly is reliant upon making sure all animated assets are marked up properly during asset creation, another topic for another time.

Weapon Updating
Weapons are connected to our characters in a specific manner and in the past allowing animator's to do this by hand resulted in inconsistent errors and issues between DCC app and the game. The AM brings the updated weapons into the file and makes sure the weapon's are aligned and linked properly to the character. Updating the weapons is just as easy as hitting the update button when necessary. The weapon is removed from the file, the source asset file is synced in source control, and finally updated into the current animation file.

AssetManager - Update Weapons

Demonstration Video
You can watch a demonstration of the scene building and swap process below. The tool and functionality was developed and improved upon over the course of a couple projects. It was used to construct animation scenes and cinematics from our latest title Saints Row: The Third

                     
                           Animation Asset Manager - Randall Hess from Randall Hess on Vimeo.


Saturday, January 28, 2012

Game Skeleton Builder via Biped

Animators using 3dsmax may want to use Biped as their control skeleton but for games you do not necessarily want to use this as your exported skeleton. Ryan Griffin on G+ has recently posed a question regarding building a skeleton based off of a biped. As we have done this for quite some time at Volition I felt I could offer some assistance here using Maxscript.

First we want to create a structure representing the bone data that will be used to create the skeleton. A struct in maxscript is somewhat similar to class objects that exists in other languages such as python or C#. Check out Duber's Blog for a more in depth look on maxscript structs.

struct bone_info (bone_name, parent_name, bone_xform)

Next we create a recursive function that will return the data representing each biped bone name, the parent bone name, and the bone transform. Notice that I am ignoring certain biped helper objects that don't necessarily need to become bones in our skeleton.
-- recursive function to get biped children objects
fn get_bip_children bip_obj bone_data =
(
  -- make sure the current biped object has children
  if (bip_obj.children != undefined) do (
 
    -- loop through all of the current bone's children
    for child in bip_obj.children do (
  
      -- ignore these biped objects
      match_footsteps = matchpattern child.name pattern:"*footsteps"
      match_nubs = matchpattern child.name pattern:"*nub"
   
      -- do not add certain objects as bones, this is a preference
      if (not match_footsteps) and (not match_nubs) do (   
   
        -- create an object for the current child bone
        new_bone = bone_info child.name bip_obj.name child.transform
    
     -- update the bone_data array with the current child
     append bone_data new_bone
    
     -- see if the current child has and children
     if (child.children != undefined) do (
       get_bip_children child bone_data
     )
      ) 
    ) 
  )
 
  return bone_data
)
Next up is the main function that collects the biped bone data, creates the new bones and rebuilds the hierarchy. Something that I should point out here. I am creating the actual bones using point helper objects. Almost any object in max can be used as an animatable bone and work with the Skin modifier to deform meshes. One thing to keep in mind is that I avoid creating max bones using the bone() creation method. This tends to be slow and I have found to crash Skin. You may choose to use bonesys.createbone as an alternative.
-- create a skeleton from a biped skeleton
fn create_skeleton bip prefix =
(
  -- get the biped root node
  bip_root = bip.controller.rootnode

  local bone_data = #()
  
  -- create an object for the root bone
  root_bone = bone_info bip_root.name undefined bip_root.transform
  append bone_data root_bone
 
  -- get bone data (names and hierarchy) from the biped
  bone_data = get_bip_children bip_root bone_data
 
  -- make sure bone data is valid
  if (bone_data.count > 0) do (

  -- create the bones
  for b in bone_data do (
   bone_name = substitutestring b.bone_name "Bip" prefix
   -- using a point object here, this can be changed to any object type
   -- do not use bone()!, that is really slow and crashes skin
   new_bone = point name:bone_name size:5 box:on cross:off
  )

  -- update the hierarchy and set the transforms on the newly created bones
  for b in bone_data do (
   
   -- only update the bone parent if it actually has a parent
   if (b.parent_name != undefined) then (
    
    bone_name = substitutestring b.bone_name "Bip" prefix
    parent_name = substitutestring b.parent_name "Bip" prefix
   
    bone_node = getnodebyname bone_name
    parent_node = getnodebyname parent_name
    
    -- set the bone parent then set the transform
    if (isvalidnode bone_node) and (isvalidnode parent_node) do (
     bone_node.parent = parent_node
     bone_node.transform = b.bone_xform
    )
    
   ) else (
    
    -- get the bone object
    bone_name = substitutestring b.bone_name "Bip" prefix
    bone_node = getnodebyname bone_name
    
    -- set the bone transform without a parent
    if (isvalidnode bone_node) do (
     bone_node.transform = b.bone_xform
    )
    
   )
   
  )

  messageBox "Creating Skeleton Complete!" title:"Create Skeleton"

 )
)
This is the opening of the script that will make sure the user has a single biped object selected and provide the prefix name that will precede the new bone names.
if (selection.count == 1) and (classof selection[1] == Biped_Object) then (
 -- create the skeleton with a new prefix
 create_skeleton selection[1] "Guy"
) else (
 messageBox "Select a single biped node" title:"Create Skeleton"
)
Now since we used point helpers to create the bones you may want to display these objects with links and make them look more like max bones. To do this you can go to the display panel under link display at the bottom and check both options.
The final result with a little object coloring should look like this.

There are many other things you can do once you create this skeleton such as constrain these bones directly to the biped, create additional helper bones to represent bone twists or add your own custom constraints to transform these bones any way you like.

You can download the full script here.
biped_create_skeleton.ms

Monday, October 10, 2011

MotionBuilder Python & Window Focusing

I recently had to do some window handle trickery with Python and MotionBuilder. I have an external python tool that is communicating with MotionBuilder, 3dsmax, and in the near future Maya. For this post I will only be touching on the MotionBuilder implementation of the tool.   When I run the tool it will return a list of scene objects within a list view. If I select on a item in the list view it should select the object within MotionBuilder. While the selection in the scene navigator is updated, since the tool is not a child of the MotionBuilder application, MotionBuilder will not redraw the viewport. I'm quite new to MoBu but the only code I saw to potentially force redraw the scene was.

FBSystem().Scene.Evaluate()

It is likely that the Mobu viewport/rendering is on a separate thread from normal scene processing. Which would explain why the scene navigator updates and the viewport does not. The viewport only seems to update if the application is the focused application. With this in mind I decided to force change the application focus to get the results I wanted.

When the python tool makes a connection to the specific dcc app I will call the following:
import win32gui, win32con
 
def enum_callback(self, hwnd, results): 
 self.winlist.append((hwnd, win32gui.GetWindowText(hwnd)))
 
def get_dcc_hwnd(self, app_name): 
 
 self.toplist = [] 
 self.winlist = [] 
 
 win32gui.EnumWindows(self.enum_callback, self.toplist) 
 
 # look for the specific application window name 
 dcc = [(hwnd, title) for hwnd, title in self.winlist if app_name in title.lower()] 
 if dcc != None and dcc[0] != None: 
  dcc = dcc[0] 
  self.dcc_hwnd = dcc[0]
 
get_dcc_hwnd( 'motionbuilder')               
This will return self.dcc_hwnd and all that really is is a window process handle or long integer. In this example it is. DCC Handle: 3214530

Now that I have stored the window handle when I select an object in my listview it will call the following:
def set_dcc_focus(self):
 if self.dcc_hwnd != None:
 
  # store the current python tool window handle
  current_hwnd = win32gui.GetForegroundWindow()
 
  # use the window handle to set focus
  win32gui.SetForegroundWindow(self.dcc_hwnd)
 
  # important to sleep here as to allow Mobu time to draw
  time.sleep(0.03)

  try:
  # set the focus back to the python tool
   win32gui.SetForegroundWindow(current_hwnd)
  except:
   return
With this I can click on all the objects in my external tool and see the select update 'realtime' within the MotionBuilder viewport. The code will change the window focus momentarily and just long enough to redraw the MotionBuilder viewport then immediately return focus back to the python tool. With the sleep time I have set here it is fast enough that I can be pressing down on the keyboard to step between items in the listview without noticing the app focus switching. However, I have noticed that if Motionbuilder doesn't have enough time to redraw, some things have the possibility of not rendering when the viewport is redrawn. So the sleep here could become variable and dependent on the amount of objects within the viewport.

UPDATE:
In the comments below, Kevin pointed out that you can skip all of this and modify the application.txt by adding the following line under [Timing]
NoFastIdleOnDeactivate = No

Thanks Kevin!