### Import/Export Rig File Format This page is intended to explain the file format for the Import Rig and Export Rig commands within Layout in LW8, so that 3rd parties can create or read the rig files with custom applications. A “*.rig” file currently contains information about a hierarchy of bones (if a bone was selected before export command) or a specific object’s bones (if an object was selected prior to export). IK/FK settings and information such as targets and goals are included. The itemshape custom object is included as well. Expressions are not currently supported in LW 8.0. The rig file is an ascii text file. There are, at this time, 6 data card types contained within a rig file. The only nesting of one card inside another occurs with the itemshape custom object data card. Because an itemshape custom object(s) is specific to a null object, it is contained within that null object’s data card. Comment lines may be included in the file, at any place. Comment lines must simply begin with “**” (two asterisks). Lines in the rig file can be up to 256 characters long. Blank lines should not occur within a rig file unless they represent an empty character string. The types of data cards, and the order that they appear in the rig file are listed below. The format of each is explained after that. Header Data Card Bone Data Card Number of Targets Data Card Null Data Card(s) for targets (if any) Number of Goals Data Card Null Data Card(s) for goals (if any) ItemShape Custom Object Data Card (found within Null Data Card) Each data card contains fields, which must be present, or format errors will occur during import. The data cards must be arranged in the file in the order shown above (header, bones, num targets, target nulls, num goals, goal nulls). If a null object is both a target and a goal, it should be listed with either the target nulls or the goals nulls, but it should not be listed twice. Sorting is done by the bones’ targetname and goalname fields since item ids have no meaning within LW8 and this allows 3rd party creation of rig files. To accompany this documentation, an example screenshot, a LW8 scene file, and rig file are provided. The Header Data Card The header data card begins with “BeginHeaderDataCard” text, and ends with “EndHeaderDataCard”. The header data card contains one named field (“Version”), which is 4 lines long. The first line is the version number, currently 2.0. The second line is the creation date for the file (not used for anything, but shown on the panel when imported into LW8). The third line contains the file descriptor text (shown on the panel when imported into LW8). The fourth line contains the file’s path (not used for anything currently). An example of the header data card follows. Header Data Card Example ** Version 2.00 File Created on: Mon Mar 22 20:47:46 2004 Export/Import Rig File Format Example C:\My Documents\ImportExportFileFormatEx\ImpExpFileFormatExample.rig ** EndHeaderDataCard The Bone Data Card The bone data card begins with “BeginBoneDataCard” text, and ends with “EndBoneDataCard”. The bone data card contains many fields in both text and numerical format, they are explained in the table that follows, and are also shown in the example bone data card below. NOTE: Bone hierarchies are written in the rig file in a similar fashion as they are displayed within the SceneEditor, that is, when the SceneEditor has children hierarchies fully expanded for view. Thus if the “no_children” field for a bone is > 0, then the children of that bone’s data cards immediately follow. Thus grandchildren of a bone may be listed before some other children of that same bone, exactly as if they were listed in the SceneEditor. The included example of a LW8 scene demonstrates this. See the SceneEditor window within the example screenshot for an example of this concept. Table of bone data card fields (must be in order, must exist, or format error will occur on import) follows.
Bone Data Card Fields |  |  |
Field Text Descriptor | No. of Lines | Format | Description
bonename | 1 | string | The name of the bone in a character string
no_children | 1 | integer | Number of children this bone has. Bone with children must have its children listed immediately after itself.
rest_length | 1 | double | Rest length of the bone
prestposition | 1 | 3 doubles | Vector defining rest position (rel. to parent)
prestrotation | 1 | 3 doubles | HPB rotation angles (rel. to parent in radians)
wrestposition | 1 | 3 doubles | Rest position rel. to world coordinates
pivot | 1 | 3 doubles | Pivot position
pivotrotation | 1 | 3 doubles | HPB angles of pivot rotation (radians)
right | 1 | 3 doubles | “right” direction vector of bone’s local coord.
up | 1 | 3 doubles | “up” direction vector of bone’s local coord.
forward | 1 | 3 doubles | “forward” dir. vector of bone’s local coord.
scale | 1 | 3 doubles | scaling factor vector
boneflags | 1 | integer | boneflags (see SDK doc for bit settings)
fallofftype | 1 | integer | bone falloff type (see LW8 or SDK doc)
strength | 1 | double | bone strength
weightmapname | 1 | string | character string of weightmapname
minrange | 1 | double | minimuim of range if limits are set in boneflags
maxrange | 1 | double | maximum of range if limits are set in boneflags
jointcompamounts | 1 | 2 doubles | joint compensation amount for self and parent
muscleflexamounts | 1 | 2 doubles | muscle flexing amount for self and parent
target | 1 | hexidecimal | target item ID, not used currently
goal | 1 | hexidecimal | goal item ID, not used currently
limitsflag | 1 | int | item info limits flag, bitwise settings
hpbmin | 1 | 3 doubles | hpb min angles in radians, if limitsflag bit set (see SDK)
hpbmax | 1 | 3 doubles | hpb max angles in radians, if limitsflag bit set (see SDK)
no_tags | 1 | integer | number of itemtags that follow
tag | 1 | string | character string of itemtag, field not present if no_tags = 0, occurs no_tags times
no_custom_obj_servers | 1 | integer | not currently used, bones as bones cannot have custom objects applied
controller | 1 | 3 integers | motion controller flags for head, pitch, and bank, see SDK docs
itemflags | 1 | integer | item flag containing bit settings for the item
goalstrength | 1 | double | goal strength setting for item
stiffness | 1 | 3 doubles | joint stiffness settings for h, p, b angles
lookahead | 1 | double | lookahead interval in time
color | 1 | integer | may be 0 to 14, color for item, see SDK doc
Bone Data Card Example: BeginBoneDataCard LWItemID 40000000 bonename Bone1 no_children 2 restlength 1.802 prestposition -0.063112 0 -0.149333 prestrotation 3.65937 0 0 wrestposition -0.063112 0 -0.149333 pivot 0 0 0 pivotrotation 0 0 0 right -0.868921 0 0.494951 up 0 1 0 forward -0.494951 0 -0.868921 scale 1 1 1 boneflags 21 fallofftype 5 strength 1 weightmapname minrange 0 maxrange 1 jointcompamounts 1 1 muscleflexamounts 1 1 target 0 goal 0 limitsflag 0 hpbmin -3.14159 -3.14159 -3.14159 hpbmax 3.14159 3.14159 3.14159 no_tags 0 no_custom_obj_servers 0 controller 3 0 0 itemflags 1 goalstrength 1 stiffness 1 1 1 lookahead 0.033 color 1 EndBoneDataCard The Number of Targets Data Card The number of targets data card begins with “BeginNumTargetsDataCard” text, and ends with “EndNumTargetsDataCard”. The data card contains 1 line, and not distinct fields, only one integer giving the number of targets witching the rig file that are listed below. If a bone has a target that is a bone within the rig being imported, it is NOT included in this number. Here is an example of the Number of Targets Data Card: BeginNumTargetsDataCard 1 EndNumTargetsDataCard
The Null Object Data Card (for targets or goals) The null object data card begins with “BeginNullDataCard” text, and ends with “EndNullDataCard”. The null object data card contains many fields in both text and numerical format, they are explained in the table that follows, and are also shown in the example of a null object data card. NOTE: Null objects are written in the rig file in 2 places, after the number of targets data card and after the number of goals data card. If either of these are zero, then no null object data cards would follow. As exported and imported currently, null object do not have children. Table of null object data card fields (must be in order, must exist, or format error will occur on import) follows.
|  | Null Object Data Card Fields |
Field Text Descriptor | No. of Lines | Format | Description
LWItemID | 1 | hexidecimal | Not currently used, can be any hex no.
bonename | 1 | string | The name of the null object in a character string
prestposition | 1 | 3 doubles | Vector defining rest position (rel. to parent)
prestrotation | 1 | 3 doubles | HPB rotation angles (rel. to parent in radians)
wrestposition | 1 | 3 doubles | Rest position rel. to world coordinates
pivot | 1 | 3 doubles | Pivot position
pivotrotation | 1 | 3 doubles | HPB angles of pivot rotation (radians)
right | 1 | 3 doubles | “right” direction vector of bone’s local coord.
up | 1 | 3 doubles | “up” direction vector of bone’s local coord.
forward | 1 | 3 doubles | “forward” dir. vector of bone’s local coord.
scale | 1 | 3 doubles | scaling factor vector
itemflags | 1 | integer | item flag containing bit settings for the item
color | 1 | integer | may be 0 to 14, color for item, see SDK doc
no_itemshapes | 1 | integer | number of itemshape custom objects applied to this null object
BeginItemShapeDataCard |  |  | if no_itemshapes is > 0, then a list of no_itemshapes ItemShape data cards will follow.
Null Object Data Card Example: The below example has one itemshape data card within it. BeginNullDataCard LWItemID 10000002 bonename Target prestposition 0 0 0 prestrotation 0 0 0 wrestposition -3.31512 0 -2.72242 pivot 0 0 0 pivotrotation 0 0 0 right 1 0 0 up 0 1 0 forward 0 0 1 scale 0 0 0 itemflags 1 color 10 no_itemshapes 1 ** BeginItemShapeDataCard ItemShapeTime 0 ItemShapeOpacity 1 ItemShapeScale 1 ItemShapeAxis 1 ItemShapeFill 0 ItemShapeShape 8 ItemShapeFlags 0 ItemShapeSelectedColor 0 0 0 ItemShapeUnselectedColor 0 0 0 ItemShapeTextColor 0 0 0 ItemShapeLable Bone1 ItemShapeDescription None Bone6 ItemShapeSelfItemName Target ItemShapeLinkToName EndItemShapeDataCard ** EndNullDataCard
The Number of Goals Data Card The number of targets data card begins with “BeginNumGoalsDataCard” text, and ends with “EndNumGoalsDataCard”. The data card contains 1 line, and not distinct fields: only one integer giving the number of goals within the rig file that are listed below. Here is an example of the Number of Goals Data Card: BeginNumGoalsDataCard 1 EndNumGoalsDataCard
The ItemShape Custom Object Data Card The null object data card begins with “BeginBoneDataCard” text, and ends with “EndBoneDataCard”. The null object data card contains many fields in both text and numerical format, they are explained in the table that follows, and are also shown in the example of a null object data card. NOTE: Null objects are written in the rig file in 2 places, after the number of targets data card and after the number of goals data card. If either of these are zero, then no null object data cards would follow. As exported and imported currently, null object do not have children. Table of itemshape custom object data card fields (must be in order, must exist, or format error will occur on import) follows.
ItemShape Custom Object Fields |  |  |
Field Text Descriptor | No. of Lines | Format | Description (see also itemshape cust obj interface)
ItemShapeTime | 1 | integer | item shape time
ItemShapeOpacity | 1 | double | number from 0 to 1, meaning 0 to 100%
ItemShapeScale | 1 | double | scale factor
ItemShapeAxis | 1 | integer | can be 0, 1, or 2 for orientation
ItemShapeFill | 1 | integer | 0 false, 1 true, only applies to shapes with planar faces
ItemShapeShape | 1 | integer | 0 to 10, corresponding to list on menu of itemshape interface (i.e. standard, tetra, none, …etc.)
ItemShapeFlags | 1 | integer | bitmap having to do with text justification and whether colors for text, selected, unselected have been applied (see itemshape menu or LW8 doc)
ItemShapeLabel | 1 | string | character string item label, must be < 100 characters long.
ItemShapeDescription | 1 | string | not used, actually set by software from shape an label above to be displayed as: “ItemShape: <shape> <label>” in the itemshape user interface.
ItemShapeSelfItemName | 1 | string | name of null object itemshape is applied to
ItemShapeLinkToName | 1 | string | name of item to draw a line to ( may be blank line)
ItemShape Custom Object Data Card Example: BeginItemShapeDataCard ItemShapeTime 0 ItemShapeOpacity 1 ItemShapeScale 1 ItemShapeAxis 1 ItemShapeFill 0 ItemShapeShape 8 ItemShapeFlags 0 ItemShapeSelectedColor 0 0 0 ItemShapeUnselectedColor 0 0 0 ItemShapeTextColor 0 0 0 ItemShapeLable Bone1 ItemShapeDescription None Bone6 ItemShapeSelfItemName RThighBone ItemShapeLinkToName HipBone EndItemShapeDataCard
    Summary
    In order to be sure one fully understands the rig file format, several examples should be generated by the user, exporting a variety of LW scenes so that the resultant files can be examined closely and compared to what item was selected and what entities were contained within the scene upon export.