Blue Mars Sandbox Animation Editor
From Blue Mars Developer Guidebook
Sandbox Animation Editor is a tool for converting animation files in Collada format into Blue Mars animation files, that can be used for full-body and facial animations of avatars.
- Navigate in the Editor
- Create and test a sample walk animation
- Pass upload data checks (technical limitations on uploaded content)
- Pass Q/A checks (quality control guidelines)
- Export animation, using MAX
- Set up character for animation in Blender
Recently added or changed features:
- Allowed multiple "Check in Blue Mars" command, without restarting the client.
- Fixed a bug which prevented creating animations longer than 10 seconds (approximately).
- For complete list of new features, please see Release notes.
Animation Editor converts animation data in Collada format (file extension .DAE) into a compressed animation data file that can be uploaded to Blue Mars and used for full-body avatar animation (file extension .DBA) or facial expression (file extension .MRP). The location of the source data in Collada format (anim.dae) is called "project folder". This folder must be placed under <Blue_Mars_Installed_Path/Game/Objects/> directory. It is highly recommended that your use separate project folders for each animation that you plan to convert and upload to Blue Mars. Initially, the project folder should have a single file in it, the source animation file in Collada format, for example, anim.dae. After the animation is converted and tested, the project folder will contain the following files:
- anim.dba -- a compresssed binary file with animation data in Blue Mars format;
- anim.*.log -- log files, for troubleshooting purposes;
- asset.xml -- this file contain additional information used by Blue Mars client to access and playback your animation in game;
Files anim.dba and asset.xml completely define how the animation will be used on Blue Mars. In addition, Animation Editor creates a "billboard" geometry model, which is a simple box textured with a sequence of slides that will represent your animation at a point-of-sale in a shop on Blue Mars. Billboard is required, if you are planning to put your animation for sale. Details on how to create and test a billboard are provided in Billboard section of this page. All billboard files are also stored in the project folder. They are:
- billboard.cgf -- geometry file;
- billboard.mtl -- material file;
- slide00-NN.dds -- slides that will be displayed on the billboard;
- display.xml -- display file for billboard; this file is created after running "Animation -> Pack animation for upload" menu command.
After the animation is packed for uploading, itemdata.zip file will be created and placed in the project folder, which will contain all the above files. Finally, before uploading your files, you must create a 400x400 icon.jpg file, using "Animtion -> Capture icon" command. This icon.jpg file should show the most representative pose of your animation. This file is not included into the itemdata.zip pack, but it is required for uploading your submission.
Sandbox Animation Editor Commands
Animation Editor has two groups of commands for processing animation data: (1) "Animation" menu commands and (2) "Animation Editor" dialog window, as shown in the image below. All other menu commands ("File", "Edit", "Display", etc.) are nearly identical to Item Editor's commands. They are explained in great detail on this page.
Animation Editor menu commands outline the general process of making, previewing and uploading custom avatar animations.
- Make animation...
Opens the "Animation Editor" dialog window, which provides controls for converting animation data from Collada to Blue Mars data format. These controls are explained in detail in section Animation Editor Dialog Commands.
- Pack animation for upload...
This command creates a zipped archive file, called itemdata.zip, that can be uploaded to Blue Mars for quality assurance and distribution. Also, this command creates a display.xml file with the information about animation billboard. You must use the "Pack" command prior to viewing your billboard in Blue Mars client. Note: unlike other content Editors (Item, Cloth, Body, ...), Animation Editor does not offer options for compressing geometry or textures at during data packing. The reason for that is that animation data in .DBA format is already compressed and slide textures are compressed (optionally) during billboard creation.
- Capture icon
Creates a 400x400 snapshot icon.jpg file, with the current view. This snapshot is required for uploading animation data. Before calling this command, use the time slider in the "Animation Editor" window and make your avatar assume an expressive pose, that represents your work best.
- Check animation in Blue Mars...
Once an animation data file is created, it can be previewed using the Blue Mars client. Reminder: when you login into Blue Mars, make sure that you are using an avatar of correct gender!
- Open upload page
Open developer page https://dev.bluemars.com/MyPage/DeveloperPageLogin.html#. After login, you can upload your newly created itemdata.zip and the icon.jpg for Q/A testing and distribution.
Animation Editor Dialog Commands
Animation Editor dialog commands allow to convert and test animation data and test it using various options. Also, there is a group of commands for creating and editing a billboard, a static box with animated slide show, that will be used to show your animation at point-of-sale in Blue Mars shops. A billboard must be created before you pack your data for uploading. For testing purposes, you can customize your avatar using custom-built cloth and/or body. Body and cloth customization will not be included into the itemdata.zip. Below, all Animation Editor commands are described in groups, as they appear in the main dialog window.
Selecting the source model and setting animation options
These commands set the avatar, animation file and animation playback options.
Select an avatar type: female or male. The requested avatar will appear on scene automatically, wearing default body and cloth.
Select type of animation data: body or facial animation.
This field is needed to categorize your animation for later use in Blue Mars client. By selecting an appropriate slot from the provided list, you will be able to replace default animations, available in the client, such as walk, run, sit, and so on, with your own. If none of provided slot names fit your animation, please user "Other".
Use <Browse> button to select the source animation file in Collada format. The source file must be located somewhere below <Blue_Mars_Installed_Path/Game/Objects/> folder, otherwise the Animation Editor will not be able to find and use it. Once the input Collada file is selected, the Animation Editor sets the project folder to this location. All files that will be created afterwards (animation .DBA file, itemdata.zip, icon.jpg, screen snapshots, billboard files) will be stored in that project folder.
- Look at camera
When this option is checked, the avatar will look at the player ("the camera") during animation playback. This is the default setting for most animations in Blue Mars. Un-check this option to disable this feature. Note: checking/unchecking this box does not affect the standard avatar idle animation in the Animation Editor.
- Look around
When this option is checked, the avatar will turn his or hear head towards other players in game, when they appear close enough. This option has no effect in the Animation Editor.
Avatar, Type, Slot, File, Look-at-camera and Look-around parameters completely define how your animation will be used on Blue Mars. Any changes in these values will be saved in the asset.xml file automatically. All other controls and commands, described below, are provided for local viewing and testing in the Animation Editor.
Create and play animation
The following commands do the conversion from Collada to Blue Mars data files and allow to playback the result in Animation Editor.
- Create And Play
This single button converts the selected Collada file and, on success, plays back the animation in the editor. It is equivalent to clicking "Create animation", "Load avatar" and "Play", in sequence.
Enable the step-by-step control over animation conversion and playback commands. This option is set to true by default. Using these commands, you can set looping and blending options, use the animation timeline, play, pause, start idle animation and examine the content on the project folder.
- "Create animation" command converts the source Collada file to Blue Mars .DBA file, using the same base filename. Conversion is a two-step process. Before conversion starts, you will be prompted to confirm file overwrite operation, because the Animation Editor does not create back up files. This behavior is consistent with all other Editors, performing conversion of Collada files. Each step leaves a log file, with progress report and error messages (if any). These files should be used for troubleshooting. On successful conversion, a message will be displayed in the status bar "Animation file created". Hint: keep status bar open, by using "View -> Show status bar" menu command.
- "Load avatar" brings a fresh avatar of requested gender, wearing default clothing and default body.
- "Play" command starts the selected animation, observing "loop" and "blend" options.
- "Loop" option forces the animation to auto-rewind and auto-repeat continuously. To stop animation, press the Pause button (||). Alternatively, you can stop animation and return to either idle motion or make the avatar assume the T-pose, using corresponding buttons below.
- "Blend with idle" option will force the animation to start with standard "Idle" motion, transitioning into the selected animation over the interval of approximately 0.5 seconds. Then, the selected animation will continue normally and will transition back into "Idle", if "loop" option is not checked. Note, that in Blue Mars, all animations are blended with the idle motion, thus, it is highly recommended to test the animation in this mode before packing and uploading to Blue Mars. Also, please be aware that due to blending, the first and last half second of the animation will be somewhat less pronounced than they appear in its "raw" form.
- "First-frame" ( |<< ), "Pause" ( || ), "Last-frame" ( >>| ) and the time slider provide full control over the animation playback. These options are only enabled in non-blending mode.
- "Idle" and "T-pose" buttons interrupt the currently playing animation and make the avatar assume idle or static T-pose, respectively.
- "Open folder" command opens the current project folder.
Besides creating animation data, Animation Editor allows to make a "billboard", which is a simple square panel, textured with a sequence of image files in .DDS format (slides). A billboard will represent your animation at a point-of-sale in a shop on Blue Mars. The following commands allow to create, examine and edit a billboard model. All files are stored in the current project folder and will be packed into the itemdata.zip file, along with the animation .DBA and asset.xml files.
- "Slide resolution". Select one of the following texture sizes: 128, 256, 512. You may need to experiment with these values and the number of slides (below) to find a good combination for your animation.
- "Number of slides". Select the number of slides to display.
- "Delay, in seconds" Set the duration for each slide.
- "Compress slides". This option will force the slide images to be compressed using lossy JPG compression. After compression, the slides will be converted back to DDS format again. With this option turned on, please make sure to examine the results using the "Load billboard" button on the same panel, or using "Animation -> Check animation in Blue Mars..." menu command. Compression will help to produce smaller files, but image degradation can be quite noticeable.
- "Create billboard". This command will copy pre-defined billboard geometry and material files into the project folder, asking for overwrite confirmation. Also, it will automatically capture frames from your animation, from the current camera location. The frames will be spaced evenly in time, covering the whole length of the animation. Depending on the number of slides requested, this command may take some time to finish; you can watch the progress in the status bar. When finished, "Billboard created" message will be displayed. Hint: before capturing the slides, you may want to hide the default terrain, using "Display -> Render settings -> Terrain" command.
- "Load billboard". The billboard shape will be loaded into the Animation Editor, replacing the avatar, for viewing and editing with Material Editor, if needed.
- "Re-capture slides". These commands allow to overwrite existing slides. Use "Recall camera" to place the camera to the same position that was used for "Create billboard" command, select the slide number that must be re-captured, pose the avatar using the time slider and click "Grab" button to capture this slide. All commands in this group can be repeated any number of times.
Cloth, shoes, and bodies
Commands in this section provide extra functions for customizing your avatar for testing, using custom-made cloth and/or custom made bodies.
- "Bottom", "Top", "Casual shoes" (for men), High heels" (for women), "User defined". These items can me selected from the drop-down menu, following by "Wear" or "Remove" comamnds.
- "Wear". The selected cloth item will be attached to the avatar. If "User defined" item is selected, "Wear" button is replaced by "Select" button, producing a "File Open" menu, for selecting an asset.xml file with custom cloth.
- "Remove". The selected cloth item will be removed.
- "Remove all". All attachments will be removed from the avatar, leaving a bare skin.
- "Select body". Using a "File Open" menu, select asset.xml file with custom body data. All currently attached cloth items will be "transferred" to the new body.
- "Screenshot". A full-screen snapshot will be taken and saved as "screenshot_NNNN.jpg" in the project folder. If project folder is not yet defined (no .DAE file is selected), the screen shot will be saved in "Game/Objects/MyData/" folder.
Example 1: creating and testing sample walk animation
In this example, we will import and test a short running animation, previously exported from MAX in Collada format, and create a billboard for it. The source Collada file is provided with the Animation Editor installation, it is located in Game/Objects/MyData/test_animation/ folder.
- Start the Animation Editor, by clicking this icon:
- Use "Animation -> Make Animation" menu command to open up "Animation Editor" dialog window. Wait until female avatar appears on the screen. On some PCs, you might need to click left mouse button on the main window to force the editor to redraw the scene.
- Use the top section of the "Animation Editor" dialog window and set controls as described below:
Avatar = Female00
Type = BodyAnimation,
Slot = Run
File = "MyData/test_animation/Female_Run.dae"
Look at camera = true
Look around = true
- Click "Create And Play" button, answer "Yes" to confirm file overwrite. The animation file will be created and played once, as shown. Time time slider will be placed at the end of the range. You can grab and move the slider and watch the avatar move.
- Next, create a billboard model. Set "Slide resolution = 512", "Number of slides = 5", "Delay = 1", "Compress slides = true" and click "Create billboard". The screen will flicker for a few seconds. Click "Load billboard" -- the editor will display the newly created billboard object with running slide show:
Five automatically captured slide images (scaled down for better view)
- The billboard appears to be of acceptable quality. To make sure that the total size of the animation file and the slide image files is under 512K submission limit, run "Animation -> Pack animation for for upload..." menu command. After packing, the itemdata.zip fill be created, size 234Kb, with the following content:
- To test animation in Blue Mars, run "Animation -> Check animation in Blue Mars..." menu command. Set the checkbox "Go straight to Preview level" and log in with female avatar. After logging, you will see the avatar with running animation. Also, you will see the billboard with animated texture on it. To check the animation with customized cloth and/or body, you must load and customize the avatar in the Animation Editor first. Click "Load avatar" button and apply custom cloth/body, then use "Animation -> Check animation in Blue Mars..." menu command.
- Finally, create an icon file. Load and pose the avatar, using "Load avatar" button and setting the time slider as desired and run "Animation -> Capture icon" menu command. The result might look something like this:
Now, the animation pack is ready for upload.
The process of creating Blue Mars animation file from Collada format consists of 2 steps: import and compile. The import step is performed by bmImportCmd.exe utility, the second by bmConvertAnim.exe utility. Both are shipped with the Animation Editor and reside in the same Bin32 folder. Each utility creates log files, that are stored in the project folder, that contain progress report and error messages, that should be used for trouble-shooting. The following list explains the meaning of these messages, at every stage (this section will be expanded as needed).
(1) "Error opening COLLADA file" The file can not be found at specified location. This may happen when the source collada file name is typed in manually into "File" control in the "Make animation" dialog window.
(2) "Error in file.dae: no root element found" Meaning: the Collada document is corrupt and/or incomplete. What to do: re-export your model.
(3) "Error in file.dae: unsopported version N." Meaning: the collada document is too old or too new. Presently, the Blue Mars converter supports Collada versions 1.4 and 1.4.1. What to do: re-export your data using tools with supported version.
(4) "Error in file.dae: Missing Bip01 biped skeleton." Meaning: the collada document does not contain animation data or the root node of the character has other name than "Bip01". What to do: make sure that your source file has animation data and the root name is "Bip01" ("Bip" stands for "biped").
(5) "ERROR : checkPassFn() : Missing skeleton animation, ..\ColladaCry\check.cpp" Meaning: no animation data is found in the collada document. What to do: make sure the character is not static.
Animation Editor is designed to work only with character animation data and not as a general tool for creating animation for other objects. Thus, the number of bones in the character must be strictly compliant with the provided character-setup template, which can be found in <Template\Avatar\Male00\Animation\Body\> and <Template\Avatar\Female00\Animation\Body> folders, shipped with the Blue Mars Developers Tools.
To post a discussion topic, or report a bug, please use the Blue Mars Developer Forum page. Please be as specific as possible, use screen capture of troublesome cases and debug output from "Create Animation" command, as described above.
- Start the Animation Editor, by clicking this icon: