Chicken Exporter

This is the documentation for Chicken R44_nf. The latest version of the script can be found at the script's homepage

1.Introduction
2.Basic Features and Usage
3.Advanced Features - Blender settings that affect your output
    3.1 Exporting double-sided faces
    3.2 Exporting groups within geometry
    3.3 Exporting multiple Actions at once
    3.4 Exporting a texture with an alpha channel
    3.5 Exporting vertex colors for a model that also has UV coordinates
    3.6 Exporting ObjectType flags or Tags for your objects
    3.7 Exporting in Background Mode (for batch processing)
    3.8 Using Motion Extraction
4.Caveats
5.Upcoming Features
6.Version History

1. Introduction
    Chicken is a script for Blender that allows you to export pretty much any kind of mesh-based scene to Panda3D's Egg format. It supports static models whether in a hierarchy or not, with various characteristics such as: vertex colors, UV coordinates, vertex or face normals (smooth or solid shading), materials, textures, and even some basic multitexturing (separate diffuse and alpha textures). It also supports armature animated meshes. The only limitation is that you're only allowed to export one armature at a time. You can export any number of animations with their own framerate, frame range and name; you can even define an animation to export in reverse by making the start > end. It also allows you to automatically invoke tools such as egg-optchar to optimize your character and animations, egg2bam to produce binary representations, and pview to preview the in-engine result of your models and animations.
    In the following sections I'll address all these features and more.

2.Basic Features and Usage
    Using Chicken to export basic scenes is very simple. Here is an overview of the UI:

As you can see, the first thing below the title tells you what kind of objects Chicken has detected among your selection. Note that Chicken doesn't provide a selection UI because in my opinion Blender can do that so much better. For this reason I recommend having a side panel in Outliner mode for the Current Scene. This last detail is important because Chicken will only export selected objects in the Current Scene.
Remember to press the Update Selection button if you wish the exporter to consider changes you've made to it via the Outliner or other means.

In the screenshot, the exporter is in Character Export Mode, which is the most complex and displays all possible options. The possible modes and the conditions that define them are as follows:

Character Export Mode: all selected mesh objects have an Armature modifier, and all of them use the same Armature object. IMPORTANT: Do not use parenting to armature for animation. It might work, but I won't support it.
Static Scene Export Mode: none of the selected mesh objects have an Armature, but they may have a hierarchy which will be considered upon export. Keep in mind that "orphans" i.e. child objects whose parent is not in the selection will be exported as top-level objects.
Character Export Mode (with static props): this is the combination of both modes. The result is a character that also contains static objects in its exported file.
Other: The status bar will display the error, such as the fact that the selection uses multiple armatures, or that no mesh objects are selected.

Right below the Status/Update Selection bar is an input box where you can type in the path to the file you wish to export or use the Select button for a File Selector window. Don't worry about the extension; Chicken will take care of that for you. By default the Export File will be the same path as your .blend file but with the .egg extension.
If you are in one of the Character Export modes you'll see the animation section below that. In this section you can add strips that define an fps value, start/end frames, and a name using the Add Animation button which will be at the bottom of the animation list. You can also delete any strip using the Delete button at its right side.

    By default, when you select a character you'll get one strip named 'anim' with the fps value set in your render panel, and the starting and end frames you've set in your sequence editor.
    When you export animations, each one gets its own file named according to the following convention: [name]-[animname].egg, where [name] is your export file without the extension and [animname] is what you specified in the strip. Note that these animations are produced by evaluating the armature's pose for each frame in the range, so the result depends on whether you have an Action linked to your Armature and/or whether NLA(Non Linear Animation) is the active animation system. For more information on this, see the next section.
    The Motion Extraction button will only appear if your Armature contains a bone named SyntheticRootBone. This feature will be explained in detail in Advanced Features but, in a nutshell, it enables you to make, for instance, walk-cycles where the feet don't slip as the character walks. See the test model and the included script, which you can obtain from the script's homepage.
    If you toggle Animation Only on, the .egg file containing the mesh and armature will not be exported. This can speed things up considerably if you've already exported that part.
    At the bottom of the window you'll find the following:

    If you're running the script in Linux you won't see the input box for PandaPath.
    If you're on Windows however you must use this box to specify the path to your Panda3D binaries if you plan to invoke the utilities. This is because of a Python limitation that doesn't allow invocations to use the path environment variable. Chicken will make an educated guess at what it is by inspecting all the entries in your path variable for one that contains 'Panda3D' in it. If this guess is wrong however you should change it. You only need to set it once, as it will be stored for you when you quit the script. Also keep in mind that the Background Export (see Advanced Features) mode uses this setting so you must set it if you wish to use that.
    The three toggle buttons in the middle indicate whether to call the tool they state. There's also an input box for additional parameters in the case of egg-optchar. The option to invoke this last tool obviously does not appear if you are not exporting a character.

3.Advanced Features - Blender settings that affect your output
    In this section I'll address some not-so-common things you might want to do, and how to accomplish them with Blender settings that Chicken will take into account.

Exporting double-sided faces:
- When you want a face to be exported as double-sided, what you need to do is flag that face or set of faces with the Twoside TexFace attribute. How do you do that? Simple: first go into UV Face Select mode (the F key will get you there fast from Object mode). By doing this you've generated texture coordinates for your object which you might not need, but it will give you greater control over each face's attributes.
  
  While in this mode, in the Editing panel, you'll see a tab called Texture Face. In this tab you will see several toggle buttons; one of them is labeled Twoside. This is the tricky part: even if you've selected all the faces you want to make double-sided, when you activate the toggle only the active face (the one with the green, red and yellow borders) will become double-sided. So, how do you make all selected faces double-sided? You can use the Copy Draw Mode button in the same panel. Beware though, that all active flags will be copied over, not just Twoside.
  A rule of thumb can be drawn from the mesh's appearance in UV Face Select mode: if it looks double-sided in said mode, it will export double-sided.
Exporting groups within geometry:
- There are two sorts of groups Chicken will export. The first type maps directly to a mesh object, which is to say that for every mesh object you've selected, whether it is a static or animated mesh, Chicken exports a group containing its vertices and polygons. But Chicken offers another type of group that allows you to specify up to 16 groups within a mesh object without having to split the geometry up. It does this by grouping together the polygons that share the same material index (16 is the maximum amount of material indices Blender allows). All you need to do is create material indices for your object using the Link and Materials tab on the Editing panel in Object mode. You don't even need to link those to actual materials, but you do need to assign polygons to them if you want them to be of any use; you can do that from Edit Mode using the assign button.
  
  In the Material panel you can see a tab labeled Links and Pipeline, where you can link and unlink materials to your Material indices. Notice that the material is linked to the Mesh and not the Object. This is the default behaviour in Blender, and Chicken will only take Mesh materials into consideration.
  The exported material-index groups will be named like this : [objname][index] where [objname] is the name of the object in question, and [index] is... well, the index. This means that if you have an object named, say, Cube, then the group that contains all polygons with material index 3 will be named Cube3. Keep this in mind when naming your objects. If there were an object named Cube3 its polygons will also be flagged by egg-optchar as being part of the same NodePath.
  In the case of characters, you can flag these groups, or any other group for that matter, with egg-optchar so you can have NodePath access to that group within Panda. Check out this page from the manual for more details. Hint: you only need to specify the parameters, not the filenames since those will be filled in by Chicken.
Exporting multiple Actions at once:
- There are multiple approaches to animation in Blender, and no real way to tell through the Python API whether a user is using any specific one, short of asking them (which can cause quite a bit of frustration if the user thinks he is using one but is actually using another). So, in the interest of generality I chose to define animations only by their fps and range of frames. This allows you to use Actions or NLA, but it does present the problem that you can't export multiple actions at once; at least not directly, that is. One way you can export any number of Actions at once is to make an Action Strip for each one in the NLA editor, place one after the other, activate NLA for animation, and tell Chicken the frame ranges that map to each action.
  
  In the screenshot you see a typical shot of the NLA editor. Highlighted in green is the mythical "button that doesn't look like a button" that allows you to toggle between Action mode and NLA mode. NLA mode is selected in the image; when Action mode is selected beside the Armature name you'll see the Action icon that some people dub the "shark victim" :)
  So all you have to do is create an action strip for every action you want to export with SHIFT+A, and place them in sequence so they don't overlap in the frames. For reference, in the image they are not organized in that way; it is just a regular use of the NLA system.
  
  I'm open to suggestions on better ways to do this.
Exporting a texture with an alpha channel:
- Currently, the only way that Chicken will respect an alpha channel on a texture is if it is specified as having one as a Texture in a Material. You can specify whether a texture has an alpha channel by activating the Alpha toggle in the Map To tab in the Material panel as shown in the picture.
  
  At present this means that only two texture configurations are exported:
  1) one texture that contains color and optionally alpha information and is flagged as having one or both
  2) one texture that contains only color information, and another that is a grayscale image representing the alpha channel; the former being flagged as Col, and the latter as Alpha.
  Mind the fact that if the Alpha toggle appears with yellow text, you are mapping inversely to alpha, and the exported result will be the opposite of what you'd expect.
  You should also check that Map Input is set to UV, or the result will also look nothing like what you see in Blender.
Exporting vertex colors for a model that also has UV coordinates:
- Chicken's default behaviour is to disregard vertex colors for any model that has UV coordinates. If you wish to override this behaviour you can do the following: Assign the object a material if it doesn't already have one. Then, set the VCol Light attribute on the material as shown in the picture. If you don't want a Panda Material to be exported with your .egg file as a consequence of this, you can also set the Shadeless attribute.
Exporting ObjectType flags or Tags for your objects:
- To append an object type or a tag to your object, simply go into the logic panel and use the Add Property button. A string property with the name ObjectType will be exported as the object type (which is shorthand notation for any egg syntax; the defaults are defined in your Confauto.prc file but you can define new ones if you like). Any other property will be exported as a normal Panda tag.
Exporting in Background Mode (for batch processing):
- NOTE: this feature has only been tested under Windows, but in theory it should work under Linux as well.
  To export in background mode you need to put something like the following in a .bat file:
  
  @echo off
  set chicken_sel=Object1;Object2
  set chicken_anims=anim1,30,1,85;anim2,40,1,90
  set chicken_bam=yes
  set chicken_optchar=yes
  set chicken_optparms=-inplace -flag Object1=group1 -flag Object2=group2
  "c:\Program Files\Blender Foundation\Blender\blender.exe" -b myblendfile.blend -P "c:\Program Files\Blender Foundation\Blender\.blender\scripts\chicken_export1.0.py"
  pause
  
  Currently the most practical way to pass parameters to a Blender script running in background mode is through environment variables. In version 1.0 there are 7 environment variables that are considered:
  - CHICKEN_SEL: This defines your selection as a list of object names separated by semicolons. If this variable is not specified, the objects which were saved as selected will be used as the selection.
  - CHICKEN_ANIMS: This defines the animations you want to export as a list of four values (name, fps, start_frame, end_frame) separated by commas. Multiple animations can be specified by separating them with semicolons.
  - CHICKEN_BAM: If defined egg2bam is called on all exported files. NOTE: the value is not checked, so you could do something like 'set chicken_bam=no' and it would still invoke it. You must unset it if you don't want it invoked. The same applies to CHICKEN_OPTCHAR.
  - CHICKEN_OPTCHAR: If defined egg-optchar is called on all exported .egg files with the parameters in the CHICKEN_OPTPARMS variable or '-inplace' in its absence.
  - CHICKEN_OPTPARMS: Defines the parameters for egg-optchar invocation.
  - CHICKEN_MEXTRACT: Enables the Motion Extraction feature.
  - CHICKEN_ANIMONLY: Exports only the animation files.
- Remember to unset any unwanted variables if you're making multiple calls to the script in background mode. In Windows you can do this: 'set variable='
Using Motion Extraction:
- Motion Extraction is a special feature that allows you to export animations where the character has displacement as if the character stayed in the same place, but it stores the displacements for every frame in the animation channel of a special bone and you can use this information in Panda3D to move your character appropriately. It's perfect for things like walk-cycles so the character's feet don't slip, and many other cases where you'd like to keep your characters position clearly known without distorting the animation.
  To enable Motion Extraction all you need to do is add a bone called SyntheticRootBone (which I'll call SRB from now on) to the Armature used by your character. The SRB's orientation and position are considered so if you don't want your character rotated you should make the bone point in the +Y direction.
  If the SRB doesn't move the net effect will be the same as exporting without Motion Extraction so what you want to do is to place a Constraint on the SRB so it follows your character in some way. The most common behaviour of the SRB is as a 'Ground Shadow' that is, it follows the character in the XY plane. To do that just place a Copy Location constraint on the SRB as shown in the image.
  
  As you can see in the image the bone has a constraint that makes it follow the bone named 'bacino', which is the root bone in my test model's armature. In case you don't know how to add a constraint to a bone, you can only do so in the armature's Pose Mode by selecting the bone you want constrained and using the Add Constraint button; then you type the armature's name in the Target box, and finally the bone target's name.
  Now all you need to do, if you haven't already, is animate your character. If your animation is meant to be a loop keep in mind one thing: The movement delta for the first exported frame will be calculated relative to the origin so make sure to do one of the following:
  - Make the first exported frame be displaced relative to the origin as much as if the last frame in your animation were placed at the origin.
  - Export a reference animation that contains only the frame previous to your animation's starting frame in addition to your animation. If you do this you need the last frame's pose copied in the appropriate place to the frame just previous to your start frame.
- The latest version of the test model is a good example of how to use this feature and it also includes a script that shows how you can use the SRB's information to move your character.

4.Caveats

Object level transform issues have mostly been overcome and you can use them pretty safely. There is one exception that I've found to this rule though, and it is negative scaling or mirroring. So, for the moment at least, avoid negative scale on your objects. If you really need to mirror an object, do it in Edit Mode.
When naming your objects keep in mind the Material Index Grouping feature. For instance:
- Object named Cube with material indices up to 3, will produce the following groups: Cube, Cube1, Cube2, Cube3
- Therefore if there are objects named the same as any of those they will be considered as being part of the same group.
When launching pview only the first animation will be displayed. It seems pview can only display one animation at a time; if passed many animations as arguments it will only display the last. Displaying the first seemed more sensible, so I'm only passing that one as an argument.
When launching egg2bam with Animation Only selected, the model's egg, if it exists, won't be converted to BAM.
If you don't specify arguments for egg-optchar, '-inplace' will be used. If you do specify other arguments, you have to specify '-inplace' if that's what you want.
When using Armatures note that Envelopes cannot be exported due to their dynamic nature. If you want Chicken to export your animations just as you see them in Blender you must use only Vertex Groups with your Armatures. You can bake Envelopes into vertex groups by temporarily reparenting your object to the Armature and responding to the relevant dialog with Create From Closest Bones; you can then clear the parent using Alt-P

5.Upcoming Features

I'm open to suggestions :)

6.Version History

Version 1.0:
- Finally works properly on Linux thanks to a few fixes by Simon Groenewolt and myself.
- Simon also added support for exporting Empty objects so you can use them as markers in Panda. I fixed it so the resulting nodes can't be accidentally flattened and also added support for tagging them.
- Fixed the inference of the path to Panda binaries on Windows for Panda 1.3.x
Version 1.0c:
- Fixed a bug in the animation export. It wasn't exporting the correct ranges and could crash under certain circumstances.
- Implemented Motion Extraction
Version 1.0b:
- Corrected vertex color export issue (they were being exported as 0-255 integers instead of 0-1 floating points, which is not valid)
- Implemented forced vertex color export for textured objects through the VCol Light material attribute.
- Implemented the ability to ignore a material through the Shadeless attribute, this way you can use a material only to tell Chicken to consider vertex colours, or to use multitexturing without having a Panda Material exported.
- Completed basic implementation of Background Export mode.
- Implemented Object Type and Tag export.
- Implemented better Panda Path detection for Windows. It now sets the Panda Path to the first entry in your path that contains 'panda3d' (case-insensitive).
- Grouping by Material Index wasn't working properly when some indices didn't have materials assigned to them. Fixed.
- Used to export names with spaces directly, which breaks Egg syntax. Now replaces spaces with underscores.
- Fixed other minor issues
Version 1.0a:
- First release of the completely redesigned and rewritten Chicken.
- Similar feature set to Chicken 0.5.3 but much cleaner code and a performance improvement of ~120%!
- Improved User Interface adapts to what you want to export .
- Supports exporting multiple meshes that use the same armature.
- Supports exporting multiple animations at once.
- And more..!
Version 0.5.3:
- Fixed an obscure bug where textures in materials that didn't have images associated to them caused a crash. Thanks to BoZ from the Panda forums for finding this.
Version 0.5.2:
- Removed the condition where materials with textures overrode face images to avoid the case where meshes with unused textured materials were exported with no texture at all (This has been reinstated, properly, in version 1.0a)
Version 0.5.1:
- Fix for objects that have unused material indices, thanks to ThomasEgi from the Panda forums for finding this.
- Tentative fix for tool invocation under Linux... although I'm told it didn't work :(
Version 0.5:
- First public release of Chicken.
- Based on eggX v.6 by Chris Holland
- Several improvements over eggX