Difference between revisions of "Custom Characters"

From Wolfire Games Wiki
Jump to: navigation, search
(Basics)
m (File path conventions: Updated link to renamed page)
(34 intermediate revisions by 3 users not shown)
Line 1: Line 1:
''based on [http://forums.wolfire.com/viewtopic.php?f=16&t=24827 this] forum post by member Markuss.''
+
{{About||custom character scripts|Character_Scripting}}
 +
'''TODO: Put this link graciously provided by Markuss in its appropriate section:'''<br />
 +
https://cdn.wolfire.com/techsupport/ExampleMan.zip<br />
  
There are two linked .zip file attached to the forum post. they can be found here:
+
'''TODO: Write introduction'''
  
http://www.markstockton.com/misc/Guide2/ExampleMan.zip
+
== Overview ==
  
http://www.markstockton.com/misc/Guide2/Blender-Overgrowth-Win.zip
+
[[Image:custom_character_file_structure.png|right|thumb|caption|All required files and what they contain]]
  
This guide assumes you are familiar with [[3D Objects]].
+
Characters in overgrowth consist of the following files.
  
==Basics==
+
{| class="wikitable"
 +
|-
 +
! Name !! File format !! Description
 +
|-
 +
! Script
 +
| XML || Links the character xml with an AI script
 +
|-
 +
! Character
 +
| XML || Links an object xml with rigging data, animations and attacks
 +
|-
 +
! Object
 +
| XML || A regular object xml file, links to a model and textures
 +
|-
 +
! Rigging data
 +
| XML || Links a model and a skeleton together so the model can be animated
 +
|-
 +
! Textures
 +
| TGA || The textures used by the character
 +
|-
 +
! Model
 +
| OBJ || The 3D mesh used by the character
 +
|-
 +
! Hull
 +
| OBJ || The simplified collision to use for the character
 +
|-
 +
! Skeleton
 +
| PHXBN || The bone structure used by the character for animation
 +
|-
 +
! Ragdoll collision
 +
| FZX || Convex hulls used for ragdoll physics
 +
|}
 +
 
 +
To create a character for Overgrowth you need to...
 +
# Model and texture the character; [[#Model_and_Texture_Considerations|be sure to get these points right]]
 +
# '''Optional:''' Create a simplified hull model for collision
 +
:::'''Note:''' Thrown weapons won't collide with characters if they don't have a hull-object.
 +
# [[#Rigging_the_Character|Rig the character using one of the included skeletons and export it to the '''.phxbn''' format]]
 +
# [[#Object_XML|Create an object XML linking the model and the texture]]
 +
# [[#Rigging_data_XML|Create a rigging data XML linking the model and the skeleton]]
 +
# [[#Character_XML|Create a character XML linking the rigging data XML and the object XML with a set of attacks and animations the character should use]]
 +
# [[#Script_XML|Create a script XML linking the character XML with an AI script]]
 +
 
 +
The final script XML is the file that's actually loaded in the game to create the character. This article goes through all the above steps.
 +
 
 +
== Model and Texture Considerations ==
 +
[[Image:ExampleMan_mesh.jpg|thumb|Character Model Faces Z-axis and has reset ]]
 +
The model and textures for the character have the same requirements as when creating any other [[3D Objects|3D Object]], but with a few extra considerations.
 +
 
 +
It's extra important for characters that the model is centered to the middle of the scene, standing on the grid floor with location and rotation set to zero, and scale set to one. It should loosely match the pose and proportions of the Overgrowth characters, you can use the following file for pose and size reference: ''../Overgrowth/Data/Models/Characters/Rabbit/rabbit.obj''.
 +
 
 +
There is no character shader that supports tangent space normal maps. If you want to use a tangent space normal map anyway, the cubemap shader can be used. Though doing so will make the object look a bit different in the engine. More information about these shaders can be found in the [[3D_Objects#Shaders|3D Objects]] article.
 +
 
 +
[[Image:ExampleMan_Norm.jpg|thumb|This is what a Blank/Flat object-space normal map might look like]]
  
Characters in overgrowth consist of 4 .XML files, an .OBJ file, a .PHXBN file, a .fzx file and a hull .OBJ file. The .PHXBN and .fzx files are created in Blender, the PHXBN file contains the skeleton and skin weighting info. The .fzx file contains the collision information that the ragdolled character uses. The XML files just contain links to themselves and other files. They contain the following:
+
=== Fur Fins ===
 +
'''TODO:''' Write about how fur fins work
  
1 - Links to the .OBJ and .PHXBN files that the engine needs to rig the character.
+
== Rigging the Character ==
<pre>
+
Overgrowth uses one of the custom [[Binary_File_Formats|binary file formats]], namely the [[Binary_File_Formats#PHXBN|PHXBN (Phoenix Bones) format]] to store skeletons. To export a skeleton to a PHXBN file you need to use Wolfire's custom export addon for Blender. A repackaged version of Blender for Windows with the export addons and with the UI set up for this task can be downloaded [https://cdn.wolfire.com/techsupport/Blender-Overgrowth-Win.zip here]. You may need to restart the program once to get the export options to show up.
<?xml version="1.0" ?>
+
 
<rig bone_path = "Data/Custom/Markuss/ExampleMan/Models/ExampleMan.phxbn"
+
'''TODO: How do you set this up yourself, if you're not using Windows for instance?'''
    model_path = "Data/Custom/Markuss/ExampleMan/Models/ExampleMan.obj"/>
+
 
</pre>
+
This article won't teach you how to use Blender, it only gives the information essential to get a character into the game. If you need to learn the basics of Blender, [https://cgcookie.com CG Cookie] has a good free video tutorial series that introduces you to the software.
 +
 
 +
Here are the steps you need to take in Blender to create the PHXBN file:
 +
 
 +
# Open '''Data\BlendFiles\rabbit_rig.blend''' in Blender 2.55 with the PHXBN-add-on installed
 +
:::'''Note:''' If you download Blender from the link provided at the top of this page, the right file is already loaded.
 +
# Replace the white/pink rabbit
 +
#* Press '''File > Import > Wavefront (.obj)''' to import an obj file.
 +
# Bind your own mesh to the skeleton
 +
#* First select the mesh, then shift-select the skeleton to add it to your selection before you press Ctrl + P and select '''Armature Deform → With Empty Groups/With Envelope Weights/With Automatic Weights''' depending on what you want to bind them.
 +
# Paint weights if you need to, or use the automatic weights
 +
#* You may want to look up a tutorial on painting weights in blender.
 +
#* It is recommended that you test your character in engine with automatic weights to check that you have no errors before you start working on a final weight paint. It won’t look pretty, but will let you know early on if the character is going to work in the engine.
 +
# Export your files
 +
#* With skeleton selected in object mode, export as .PHXBN, same for mesh but as .OBJ. Your model needs to be in rest position when doing this.
  
2 - A regular object file as described in the [[3D_Objects#Basics | 3D reference guide]].
+
== Object XML ==
 +
This is a regular object file as described in the [[3D_Objects#Basics | 3D reference guide]]. Note that the ShaderName flags (like #TANGENT for instance) don't make any difference for characters since they use a pre-detemined path through the uber shader.
 
<pre>
 
<pre>
 
<?xml version="1.0"?>
 
<?xml version="1.0"?>
 
<Object>
 
<Object>
<Model>Data/Custom/Markuss/ExampleMan/Models/ExampleMan.obj</Model>
+
    <Model>Data/Custom/Markuss/ExampleMan/Models/ExampleMan.obj</Model>
<ColorMap>Data/Custom/Markuss/ExampleMan/Textures/ExampleMan_Color.TGA</ColorMap>
+
    <ColorMap>Data/Custom/Markuss/ExampleMan/Textures/ExampleMan_Color.TGA</ColorMap>
<NormalMap>Data/Custom/Markuss/ExampleMan/Textures/ExampleMan_Norm.TGA</NormalMap>
+
    <NormalMap>Data/Custom/Markuss/ExampleMan/Textures/ExampleMan_Norm.TGA</NormalMap>
<ShaderName>cubemapobjchar</ShaderName>
+
    <ShaderName>envobject</ShaderName>
 
</Object>
 
</Object>
 
</pre>
 
</pre>
  
3 - Links to the first 2 files, and a load of animation files for each action.
+
== Rigging data XML ==
 +
Links to the .OBJ and .PHXBN files that the engine needs to rig the character.
 +
<pre>
 +
<?xml version="1.0" ?>
 +
<rig bone_path = "Data/Custom/Markuss/ExampleMan/Models/ExampleMan.phxbn"
 +
    model_path = "Data/Custom/Markuss/ExampleMan/Models/ExampleMan.obj"/>
 +
</pre>
 +
 
 +
== Character XML ==
 +
Links to the object XML and rigging data XML files as well as the animations and attacks the character will use.
 
<pre>
 
<pre>
 
<?xml version="1.0" ?>
 
<?xml version="1.0" ?>
Line 60: Line 139:
 
</pre>
 
</pre>
  
4 - Links to the third file and an AI script, this is the file you choose when loading a character.
+
== Script XML ==
 +
Links to the character XML file and an AI script, this is the file you choose when loading a character.
 
<pre>
 
<pre>
 
<?xml version="1.0" ?>
 
<?xml version="1.0" ?>
 
<Actor>
 
<Actor>
<Character>Data/Custom/Markuss/ExampleMan/XMLFiles/ExampleMan_AnimList.xml</Character>
+
    <Character>Data/Custom/Markuss/ExampleMan/XMLFiles/ExampleMan_AnimList.xml</Character>
 
     <ControlScript>enemycontrol.as</ControlScript>
 
     <ControlScript>enemycontrol.as</ControlScript>
 
</Actor>
 
</Actor>
 
</pre>
 
</pre>
  
==Model and Texture Requirements==
+
== Adding Characters to the spawner menu ==
[[Image:ExampleMan_mesh.jpg|thumb|Character Model Faces Z-axis]]
+
 
Models have to be triangles only and centered to the middle of the scene with location, rotation and scale set to zero. It should loosely match the pose and proportions of the Overgrowth characters, you can use the following file: ''../Overgrowth/Data/Models/Characters/Rabbit/rabbit.obj''.
+
Short version:
 +
* You must add it in a mod.
 +
* You can add as many characters to the spawner menu as you want in a single mod, you just need to follow the below instructions for each, and add multiple <code><Item></code> tags to your mod.xml file.
 +
 
 +
In your mod.xml file, add this xml tag:
 +
('''TODO''': Make these paths more specific to characters)
 +
 
 +
<pre><Item category="My Custom Mod Characters"
 +
      title="Some Character To Spawn"
 +
      path="Data/Objects/example_item_pack/mod_item_example.xml"
 +
      thumbnail="Data/UI/example_item_pack/thumbs/mod_item_example.png" /></pre>
 +
 
 +
* '''<code>category</code>''' is the top level category where the character will show up, in the '''Load''' menu.
 +
* '''<code>title</code>''' is the name of the character, as it will show up in the spawner menu.
 +
* '''<code>path</code>''' is the path to the character XML that will get spawned. See [[#How_to_create_a_character|the '''How to create a character''' section]] for which XML file to target (either the character XML itself, or a version you saved off that has modified default parameters).  '''TODO''': Be careful to advise ''which'' character XML to add to the spawner - there are multiple character XML files!
 +
* '''<code>thumbnail</code>''' is the image that will be used for a tooltip when you hover over your character in the spawner menu.
 +
 
 +
See '''<code>GameInstallDir/Data/ExampleMods/mod_xml_specification.txt</code>''' for full information.
 +
 
 +
== TODOs ==
 +
'''TODO: Make sure all these headings are covered in this or some other article that we link to'''
  
If your character is not symmetrical, ignore the center line in the geometry, it has to be the "true" the center of the model, otherwise you will get errors.
+
=== File path conventions ===
  
There is no character shader that supports tangent space normal maps. If you want to use a tangent space normal map anyway, the cubemap shader can be used. Though doing so will make the object look a bit different in the engine. More information about these shaders can be found in the [[3D_Objects#Shaders|3D Objects]] article.
+
'''TODO''': Description of where to add files in mods so they don't conflict. Ala [[Hotspot_Scripting#File_path_conventions]]
 +
 
 +
=== Hull ===
 +
 
 +
'''TODO''': Links to or docs on character hulls
 +
 
 +
=== Animations ===
 +
 
 +
'''TODO''': Links to or docs on animations and export, tagging, etc
 +
 
 +
=== Morph targets ===
 +
 
 +
'''TODO''': Links to or docs on morph target animations for hands, face, etc
 +
 
 +
=== Eyes ===
  
[[Image:ExampleMan_Norm.jpg|thumb|This is what a Blank/Flat object-space normal map looks like]]
+
'''TODO''': Links to or docs on morph target animations for eyes (might roll this up into other sections/other pages?)
  
==Blender==
+
=== Attacks ===
A repackaged version of Blender with the export addons and with the UI set up for making characters can be downloaded at the top of this article. It does not require an install and can be run from its folder. You may need to restart it once to get the export options to show up.
 
  
This article is not intended to teach how to use Blender, it only gives the information essential to get a character into the game. If you would like to learn more about Blender, the website cgcookie.com has a good free tutorial video series that will introduce you to the software. With that in mind, here are the basic controls that you will need in Blender:
+
'''TODO''': Links to or docs on attacks system and export, tagging, etc - related partly to animations.<br>
{| class="wikitable"
 
|-
 
! Control !! Function
 
|-
 
! Middle mouse
 
| Orbit
 
|-
 
! Shift + middle mouse
 
| Pan
 
|-
 
! Ctrl + middle mouse or scroll wheel
 
| Zoom
 
|-
 
! Right click
 
| Select object
 
|-
 
! Delete or X
 
| Remove selection
 
|-
 
! Shift + right click
 
| Select more then 1 object
 
|-
 
! Ctrl + P
 
| Bind selected mesh to active skeleton (armature deform)
 
|-
 
! Tab
 
| Toggle between object mode and last active mode
 
|}
 
  
# Replace the white rabbit
+
'''TODO''': Possibly also scripting attacks and animations, and character-bound input, etc - though maybe that should be in a different section?
#* Press '''File > Import > Wavefront (.obj)''' to import an obj file.
 
# Bind your own mesh to the skeleton
 
#* First select the mesh, then shift-select the skeleton to add it to your selection before you press Ctrl + P to bind them.
 
#Paint weights
 
#* You may want to look up a tutorial on painting weights in blender.
 
#* It is recommended that you test your character in engine with automatic weights to check that you have no errors before you start working on a final weight paint. It won’t look pretty, but will let you know early on if the character is going to work in the engine.
 
# Export your files
 
#* With skeleton selected in object mode, export as .PHXBN, same for mesh but as .OBJ. Your model needs to be in rest position when doing this.
 

Revision as of 06:51, 20 April 2018

TODO: Put this link graciously provided by Markuss in its appropriate section:
https://cdn.wolfire.com/techsupport/ExampleMan.zip

TODO: Write introduction

Overview

All required files and what they contain

Characters in overgrowth consist of the following files.

Name File format Description
Script XML Links the character xml with an AI script
Character XML Links an object xml with rigging data, animations and attacks
Object XML A regular object xml file, links to a model and textures
Rigging data XML Links a model and a skeleton together so the model can be animated
Textures TGA The textures used by the character
Model OBJ The 3D mesh used by the character
Hull OBJ The simplified collision to use for the character
Skeleton PHXBN The bone structure used by the character for animation
Ragdoll collision FZX Convex hulls used for ragdoll physics

To create a character for Overgrowth you need to...

  1. Model and texture the character; be sure to get these points right
  2. Optional: Create a simplified hull model for collision
Note: Thrown weapons won't collide with characters if they don't have a hull-object.
  1. Rig the character using one of the included skeletons and export it to the .phxbn format
  2. Create an object XML linking the model and the texture
  3. Create a rigging data XML linking the model and the skeleton
  4. Create a character XML linking the rigging data XML and the object XML with a set of attacks and animations the character should use
  5. Create a script XML linking the character XML with an AI script

The final script XML is the file that's actually loaded in the game to create the character. This article goes through all the above steps.

Model and Texture Considerations

Character Model Faces Z-axis and has reset

The model and textures for the character have the same requirements as when creating any other 3D Object, but with a few extra considerations.

It's extra important for characters that the model is centered to the middle of the scene, standing on the grid floor with location and rotation set to zero, and scale set to one. It should loosely match the pose and proportions of the Overgrowth characters, you can use the following file for pose and size reference: ../Overgrowth/Data/Models/Characters/Rabbit/rabbit.obj.

There is no character shader that supports tangent space normal maps. If you want to use a tangent space normal map anyway, the cubemap shader can be used. Though doing so will make the object look a bit different in the engine. More information about these shaders can be found in the 3D Objects article.

This is what a Blank/Flat object-space normal map might look like

Fur Fins

TODO: Write about how fur fins work

Rigging the Character

Overgrowth uses one of the custom binary file formats, namely the PHXBN (Phoenix Bones) format to store skeletons. To export a skeleton to a PHXBN file you need to use Wolfire's custom export addon for Blender. A repackaged version of Blender for Windows with the export addons and with the UI set up for this task can be downloaded here. You may need to restart the program once to get the export options to show up.

TODO: How do you set this up yourself, if you're not using Windows for instance?

This article won't teach you how to use Blender, it only gives the information essential to get a character into the game. If you need to learn the basics of Blender, CG Cookie has a good free video tutorial series that introduces you to the software.

Here are the steps you need to take in Blender to create the PHXBN file:

  1. Open Data\BlendFiles\rabbit_rig.blend in Blender 2.55 with the PHXBN-add-on installed
Note: If you download Blender from the link provided at the top of this page, the right file is already loaded.
  1. Replace the white/pink rabbit
    • Press File > Import > Wavefront (.obj) to import an obj file.
  2. Bind your own mesh to the skeleton
    • First select the mesh, then shift-select the skeleton to add it to your selection before you press Ctrl + P and select Armature Deform → With Empty Groups/With Envelope Weights/With Automatic Weights depending on what you want to bind them.
  3. Paint weights if you need to, or use the automatic weights
    • You may want to look up a tutorial on painting weights in blender.
    • It is recommended that you test your character in engine with automatic weights to check that you have no errors before you start working on a final weight paint. It won’t look pretty, but will let you know early on if the character is going to work in the engine.
  4. Export your files
    • With skeleton selected in object mode, export as .PHXBN, same for mesh but as .OBJ. Your model needs to be in rest position when doing this.

Object XML

This is a regular object file as described in the 3D reference guide. Note that the ShaderName flags (like #TANGENT for instance) don't make any difference for characters since they use a pre-detemined path through the uber shader.

<?xml version="1.0"?>
<Object>
    <Model>Data/Custom/Markuss/ExampleMan/Models/ExampleMan.obj</Model>
    <ColorMap>Data/Custom/Markuss/ExampleMan/Textures/ExampleMan_Color.TGA</ColorMap>
    <NormalMap>Data/Custom/Markuss/ExampleMan/Textures/ExampleMan_Norm.TGA</NormalMap>
    <ShaderName>envobject</ShaderName>
</Object>

Rigging data XML

Links to the .OBJ and .PHXBN files that the engine needs to rig the character.

<?xml version="1.0" ?>
<rig bone_path = "Data/Custom/Markuss/ExampleMan/Models/ExampleMan.phxbn"
     model_path = "Data/Custom/Markuss/ExampleMan/Models/ExampleMan.obj"/>

Character XML

Links to the object XML and rigging data XML files as well as the animations and attacks the character will use.

<?xml version="1.0" ?>
<character>
    <appearance obj_path = "Data/Custom/Markuss/ExampleMan/XMLFiles/ExampleMan_Object.xml"
                skeleton = "Data/Custom/Markuss/ExampleMan/XMLFiles/ExampleMan_RigFiles.xml"/>
    <animations idle = "Data/Animations/r_idle2.xml"
                jump = "Data/Animations/r_jump.xml"
                roll = "Data/Animations/r_roll.xml"
                movement = "Data/Animations/r_movement.xml"
                wall = "Data/Animations/r_wall.xml"
                ledge = "Data/Animations/r_ledge.anm"
                medrightblock = "Data/Animations/r_activeblockmedright.anm"
                medleftblock = "Data/Animations/r_activeblockmedleft.anm"
                highrightblock = "Data/Animations/r_activeblockhighright.anm"
                highleftblock = "Data/Animations/r_activeblockhighleft.anm"
                lowrightblock = "Data/Animations/r_activeblocklowright.anm"
                lowleftblock = "Data/Animations/r_activeblocklowleft.anm"
                blockflinch = "Data/Animations/r_activeblockflinch.anm"/>
    <attacks moving_close = "Data/Attacks/haymaker.xml"
             stationary_close = "Data/Attacks/thrustpunch.xml"
             moving = "Data/Attacks/spinkick.xml"
             stationary = "Data/Attacks/frontkick.xml"
             moving_low = "Data/Attacks/soccerkick.xml"
             low = "Data/Attacks/sweep.xml"
             air = "Data/Attacks/legcannon.xml" />
 </character>

Script XML

Links to the character XML file and an AI script, this is the file you choose when loading a character.

<?xml version="1.0" ?>
<Actor>
    <Character>Data/Custom/Markuss/ExampleMan/XMLFiles/ExampleMan_AnimList.xml</Character>
    <ControlScript>enemycontrol.as</ControlScript>
</Actor>

Adding Characters to the spawner menu

Short version:

  • You must add it in a mod.
  • You can add as many characters to the spawner menu as you want in a single mod, you just need to follow the below instructions for each, and add multiple <Item> tags to your mod.xml file.

In your mod.xml file, add this xml tag: (TODO: Make these paths more specific to characters)

<Item category="My Custom Mod Characters"
      title="Some Character To Spawn"
      path="Data/Objects/example_item_pack/mod_item_example.xml"
      thumbnail="Data/UI/example_item_pack/thumbs/mod_item_example.png" />
  • category is the top level category where the character will show up, in the Load menu.
  • title is the name of the character, as it will show up in the spawner menu.
  • path is the path to the character XML that will get spawned. See the How to create a character section for which XML file to target (either the character XML itself, or a version you saved off that has modified default parameters). TODO: Be careful to advise which character XML to add to the spawner - there are multiple character XML files!
  • thumbnail is the image that will be used for a tooltip when you hover over your character in the spawner menu.

See GameInstallDir/Data/ExampleMods/mod_xml_specification.txt for full information.

TODOs

TODO: Make sure all these headings are covered in this or some other article that we link to

File path conventions

TODO: Description of where to add files in mods so they don't conflict. Ala Hotspot_Scripting#File_path_conventions

Hull

TODO: Links to or docs on character hulls

Animations

TODO: Links to or docs on animations and export, tagging, etc

Morph targets

TODO: Links to or docs on morph target animations for hands, face, etc

Eyes

TODO: Links to or docs on morph target animations for eyes (might roll this up into other sections/other pages?)

Attacks

TODO: Links to or docs on attacks system and export, tagging, etc - related partly to animations.

TODO: Possibly also scripting attacks and animations, and character-bound input, etc - though maybe that should be in a different section?