Merge pull request #25 from Five-Damned-Dollarz/features/abc-v6-export

ABC v6 export

README.md

@@ -1,12 +1,12 @@
 # io_scene_lithtech
 
-This addon is forked from [io_scene_abc](https://github.com/cmbasnett/io_scene_abc), renamed to io_scene_lithtech due to the increased scope. 
+This addon is forked from [io_scene_abc](https://github.com/cmbasnett/io_scene_abc), renamed to io_scene_lithtech due to the increased scope.
 
-This addon provides limited support for importing and exporting various Lithtech models formats from [No One Lives Forever](https://en.wikipedia.org/wiki/The_Operative:_No_One_Lives_Forever) to and from Blender 2.8x.
+This addon provides limited support for importing and exporting various Lithtech models formats from [various games](https://en.wikipedia.org/wiki/LithTech#Games_using_LithTech) such as [Shogo](https://en.wikipedia.org/wiki/Shogo:_Mobile_Armor_Division), and [No One Lives Forever](https://en.wikipedia.org/wiki/The_Operative:_No_One_Lives_Forever) to and from Blender 2.8x/2.9x.
 
 ## How To Install
 
-Download or clone the repository, and zip up the `src` folder. Go to `Edit -> Preferences` in Blender 2.8x, select `install` and then select the zip file you just created.
+Download or clone the repository, and zip up the contents of the `src` folder. Go to `Edit -> Preferences` in Blender 2.8x/2.9x, go to the `Add-ons` tab, select `install` and then select the zip file you just created.
 
 To download the respository, click the green `Code -> Download ZIP` at the top of the main page.
 
@@ -16,7 +16,8 @@ To download the respository, click the green `Code -> Download ZIP` at the top o
 
 Format | Import | Export
 --- | --- | ---
-ABC | Rigid and Skeletal | Limited
+ABCv6 | Full | Full
+ABCv13 | Rigid and Skeletal | Limited
 LTA | No | Rigid and Skeletal
 LTB (PS2) | Rigid and Skeletal | No
 LTB (PC) | Rigid and Skeletal | No
@@ -31,10 +32,12 @@ Additional format information can be found in [here](https://github.com/haekb/io
  - Imported skeletal meshes are mirrored on the X axis (They're flipped back on export!)
  - Converters may not provide 1:1 source files
  - Converters don't convert lods!
+ - ABCv6 sometimes exports vertex animation nodes with an odd rotation
 
 ![](https://raw.githubusercontent.com/haekb/io_scene_lithtech/master/doc/readme/example.png)
 
 ## Credits
 * **Colin Basnett** - Programming
 * **ReindeerFloatilla** - Research
-* **Haekb** - Programming / Research
+* **Haekb** - Programming / Research
+* **Amphos** - Programming

doc/abc-v6-anim-engine-links.md

@@ -0,0 +1,254 @@
+## ABCv6 Node Names
+
+For dismemberment/locational damage system:
+
+- head
+- neck
+- torso
+- pelvis
+- ru_arm
+- rl_arm
+- r_hand
+- lu_arm
+- ll_arm
+- l_hand
+- lu_leg
+- ll_leg
+- l_ankle
+- l_foot
+- ru_leg
+- rl_leg
+- r_ankle
+- r_foot
+- obj
+- l_gun
+- r_gun
+
+## ABCv6 Animation Names
+
+For (multiplayer?) characters:
+- idle1
+- idle2
+- idle3
+- idle4
+- talk1
+- talk2
+- talk3
+- talk4
+- talk5
+- walk_nogun
+- walk_rifle
+- walk_pistol
+- walk_knife1
+- walk_irleg_rifle (injured right leg)
+- walk_irleg_nogun (injured right leg)
+- walk_illeg_rifle (injured left leg)
+- walk_illeg_nogun (injured left leg)
+- run_nogun
+- run_rifle
+- run_pistol
+- run_knife1
+- jmp_rifle
+- jmp_pistol
+- jmp_knife
+- crouch_1pistol
+- crouch_rifle
+- crouch_knife1
+- crawl_1pistol
+- crawl_rifle
+- crawl_knife1
+- swim_nogun
+- swim_rifle
+- swim_pistol
+- swim_knife1
+- strafe_right_nogun
+- strafe_right_1pistol
+- strafe_right_2pistol
+- strafe_right_rifle
+- strafe_right_nogun
+- strafe_right_1pistol
+- strafe_right_2pistol
+- strafe_right_rifle
+- pickup_weapon
+- switch_weapon_2pistol
+- switch_weapon_rifle
+- switch_weapon_knife
+- switch_weapon_none
+- fire_stand_rifle
+- fire_stand_autorifle
+- fire_stand_1pistol
+- fire_stand_2pistol
+- fire_stand_knife1
+- fire_stand_knife2
+- fire_stand_knife3
+- fire_stand_grenade
+- fire_stand_magic
+- fire_walk_rifle
+- fire_walk_autorifle
+- fire_walk_1pistol
+- fire_walk_2pistol
+- fire_walk_knife1
+- fire_walk_knife2
+- fire_walk_knife3
+- fire_walk_grenade
+- fire_walk_magic
+- fire_run_rifle
+- fire_run_autorifle
+- fire_run_1pistol
+- fire_run_2pistol
+- fire_run_knife1
+- fire_run_knife2
+- fire_run_knife3
+- fire_run_grenade
+- fire_run_magic
+- fire_jump_rifle
+- fire_jump_autorifle
+- fire_jump_1pistol
+- fire_jump_2pistol
+- fire_jump_knife1
+- fire_jump_knife2
+- fire_jump_knife3
+- fire_jump_grenade
+- fire_jump_magic
+- fire_crouch_rifle
+- fire_crouch_autorifle
+- fire_crouch_1pistol
+- fire_crouch_2pistol
+- fire_crouch_knife1
+- fire_crouch_knife2
+- fire_crouch_knife3
+- fire_crouch_grenade
+- fire_crouch_magic
+- fire_crawl_rifle
+- fire_crawl_autorifle
+- fire_crawl_1pistol
+- fire_crawl_2pistol
+- fire_crawl_knife1
+- fire_crawl_knife2
+- fire_crawl_knife3
+- fire_crawl_grenade
+- fire_crawl_magic
+- falling
+- falling_uncontrol
+- roll_forward
+- roll_right
+- roll_left
+- roll_back
+- handspring_forward
+- handspring_right
+- handspring_left
+- handspring_back
+- flip_forward
+- flip_right
+- flip_left
+- flip_back
+- dodge_right
+- dodge_left
+- recoil_head1
+- recoil_chest1
+- recoil_rchest1
+- recoil_lchest1
+- recoil_lleg1
+- recoil_rleg1
+- recoil_head2
+- recoil_chest2
+- recoil_rchest2
+- recoil_lchest2
+- recoil_lleg2
+- recoil_rleg2
+- taunt_dance1
+- taunt_dance2
+- taunt_dance3
+- taunt_dance4
+- taunt_flip
+- taunt_wave
+- taunt_beg
+- spot_right
+- spot_left
+- spot_point
+- death_head1
+- death_chest1
+- death_rchest1
+- death_lchest1
+- death_lleg1
+- death_rleg1
+- death_head2
+- death_chest2
+- death_rchest2
+- death_lchest2
+- death_lleg2
+- death_rleg2
+- humiliation_01
+- humiliation_02
+- humiliation_03
+- humiliation_04
+- humiliation_05
+- special1
+- special2
+- special3
+- special4
+- special5
+- special6
+- special7
+- special8
+- special9
+- corpse_head1
+- corpse_chest
+- corpse_rchest
+- corpse_lchest
+- corpse_lleg1
+- corpse_rleg1
+- corpse_head2
+- corpse_chest2
+- corpse_rchest2
+- corpse_lchest2
+- corpse_lleg2
+- corpse_rleg2
+
+For dismemberment system:
+- limb_head
+- limb_arm
+- limb_leg
+
+Animation names for PV weapon models:
+- static_model
+- idle
+- draw
+- dh_draw
+- holster
+- dh_holster
+- start_fire
+- fire
+- end_fire
+- start_alt_fire
+- alt_fire
+- end_alt_fire
+
+For weapon pickup models:
+- handheld
+
+## ABCv6 Frame String Commands
+
+For characters/enemies:
+- fire_key:optional int attack_num
+- show_weapon:int weapon_num
+- extra_key:string extra_args - this could be anything, depending on the class using the model, see AI_Mgr::MC_Extra
+- play_sound:string sound_file
+  - sound_random:int max
+  - sound_radius:int radius
+  - sound_volume:int volume
+  - sound_chance:int chance [0-100]
+  - sound_voice:bool is_voice
+
+For PV weapons:
+- fire_key
+- sound_key:string sound_file
+- soundloop_key:string sound_file
+- soundstop_key
+- hide_key:string node_name
+- show_key:string node_name
+
+# Examples:
+
+- For a gun's PV animation to deal damage the actual fire frame needs: fire_key
+- To play mon_footstep_1.wav or mon_footstep_2.wav randomly whenever a footstep frame happens: [play_sound:mon_footstep_][sound_random:2][sound_volume:50]

doc/abc-v6-export-basics.md

@@ -0,0 +1,49 @@
+The absolute minimum your Blender scene must have to export successfully to ABCv6 is:
+- One Armature
+- One Mesh with an active UV Map
+- One Action with at least 1 Keyframe
+
+An example .blend can be found [here](./abc-v6-export-basics/minimal_abc-v6_no_anim.blend)
+
+![](./abc-v6-export-basics/minimum_scene.png)
+
+## Making a basic ABCv6 model
+First make an armature, and in object mode set the X rotation to 90 degrees, and the X and Z scale to -1.
+
+![](./abc-v6-export-basics/armature_transform.png)
+
+Next, make a mesh, and set its parent to the armature you just made. Then add an armature modifier for the same armature.
+
+![](./abc-v6-export-basics/mesh_armature_modifier.png)
+
+For every bone in your armature, the mesh *must* have a corresponding vertex group with the same name. Assign vertices you want to be affected by the bone here with a weight 1. *Never* assign multiple nodes to the same vertex, that is not supported by the format.
+
+Finally create an action. Actions start at frame 0, and must have at least 1 keyframe. Actions named with a "d_" prefix will not be exported, it is expected these contain vertex animation keyframes.
+
+Each bone must have the same amount of keyframes. They should be at the same times as the root node's **W Quaternion Rotation lane**. Only **location** and **rotation_quaternion** (other rotation types are not currently supported) lanes will be exported, scaling is not supported by the format.
+
+![](./abc-v6-export-basics/action_editor.png)
+
+## Exporting a basic ABCv6 model
+Finally we can export our model. First we need to make sure the mesh is *triangulated* (ctrl + T).
+
+Then we wind the triangles the correct way by *calculating the inside* (ctrl + shift + N).
+
+Now, go to File -> Export -> Lithtech ABC, select the armature you want to export (should be done automatically), and choose the version: ABC v6 (Lithtech 1.0), and click export.
+
+# Issues you may encounter
+- If some of your bones try to converge at [0, 0, 0] after export, it means they have fewer keyframes than the root node.
+- If you think your exported animation is missing some keyframes, check that you've set a rotation keyframe on your root node at the expected time.
+- If the bounding boxes are too small or too large, make sure you aren't scaling any of your objects.
+- If the export fails with an "active UV index 0 out of range" error, make sure you're not in mesh edit mode, select the mesh object, and click on the UV map you want to export, and try again.
+
+![](./abc-v6-export-basics/uv_error.png)
+
+## Final product
+I named it BERETTA_PU.ABC, and put it in BLOOD2/MODELS/POWERUPS to make it appear in 3rd person and when dropped on the ground:
+
+![](./abc-v6-export-basics/replaced_beretta_pickup.png)
+
+## Misc. Blender
+- There's no way to export a frame command string from Blender yet, so you'll have to put it in ModelEdit after export to do this. Make sure to press enter after typing to confirm the string.
+- If making a first person weapon model it may be helpful to create a camera object. I've found a Z position of 1m, and a rotation of X -90 degrees, and Z 180 degrees, with a 90 degree FOV to look fairly close to the game (in 16:9, with widescreen patches).

doc/abc-v6-vert-anim-basics.md

@@ -0,0 +1,21 @@
+Vertex animations utilize the shape key feature of Blender.
+
+An example .blend can be found [here](./abc-v6-export-basics/minimal_abc-v6_vert_anim.blend)
+
+## Basics
+The exporter will ignore vertex animations entirely if you have less than 2 shape keys.
+
+![](./abc-v6-vert-anim-basics/shape_keys.png)
+
+For every action, you need to add shape keys equal to the number of keyframes in that action. They should be named the same as the corresponding action, eg. if you have an alt_fire animation, your shape keys should be named alt_fire_0, alt_fire_1, alt_fire_2, and so on.
+**Note:** the names after the action name don't matter, but the order does. If alt_fire_2 is the highest in the list it will be attached to the first keyframe.
+
+Even if you don't want vertex animations for a certain action you'll have to create shape keys for it.
+
+# Issues
+- Currently there's a bug that affects few vertex animated nodes, they export with a slightly incorrect rotation or translation.
+
+## Misc. Tips
+- I usually set the shape key to absolute and add "d_" prefixed actions to animate the shape keys, they don't do anything in the export but it's easier to preview with them.
+
+![](./abc-v6-vert-anim-basics/action_list.png)