Shadow Man EX Tools Turok 1 EX Tools Turok 2 EX Tools Turok 3 EX Tools Documentation

Turok 2 EX Tools v1.5.2 Documentation

By BehemothProgrammer

Installation

Open Blender and navigate to Edit > Preferences
  1. Click on the Add-ons tab.
  2. Click the Install... button and select the Turok2EXBlenderTools.zip file you downloaded.
  3. If you don't see the Add-on afterwards type in the search field “turok 2” to quickly find the add-on Import-Export: Turok 2 EX Tools.
  4. Enable the add-on by clicking the checkbox and expand the field to see that there are 2 folder paths you must set before using this add-on.
  5. The Unzipped Game Folder field must be assigned to the folder where you unzipped the contents of the Turok2EX game.kpf file. If you haven't done that yet then do that now.
  6. The Turok 2 Folder field must be assigned to the Turok 2 install folder
  7. Click the Save Preferences button
  8. Click the All button in the Load Defs section to load the game def files. It will take a while and you only need to do this once. Once the files are loaded there will be a checkmark beside each one indicating that they were loaded. If you change any def files you can click these buttons to reload them. These buttons are also available in the Tool panel.

Importing

Staticmesh

  1. Navigate to File > Import > Turok 2 Staticmesh (.staticmesh)
  2. Select a .staticmesh file to import.

Skinnedmesh

  1. Navigate to File > Import > Turok 2 Skinnedmesh (.skinnedmesh)
  2. Select a .skinnedmesh file to import.
    • Hide BB & Hot Points - Hides Bounding Boxes and Hot Points.
    • Import Anim - automatically tries to find the .anim animation file that the selected skinnedmesh belongs to.
    • Bake Yaw Offsets - For each animation, rotates the root bone by it's Yaw Offset. (Do not turn on if you intend to export this skinnedmesh back into Turok 2)
  3. If you disabled the Import Anim option or the animation was not found automatically you will have to import the animation manually. To do that follow the same procedure as importing the skinnedmesh except first select the object you want to apply the animation too and then navigate to File > Import > Turok 2 Animation (.anim)


Exporting

Staticmesh

  1. Navigate to File > Export > Turok 2 Staticmesh (.staticmesh)
  2. Enter the file path you want to export the Staticmesh to.
    • Export Materials - Exports all used materials to .kmat files relative to the export directory.
    • Copy Textures - Copies all used textures to their path relative to the export directory.
      • Copy All Textures in Texture Sets - Copies all textures in every used texture set.
    • Use Models Directory - Exports materials, and textures to parent folder of "models" + the sub folders after the models folder if it exists in the export path. Used for convenience when you save your model to the games models directory and you want everything else saved in the correct folders as Turok 2 has it setup.

Skinnedmesh

  1. Navigate to File > Export > Turok 2 Skinnedmesh (.skinnedmesh)
  2. Enter the file path you want to export the Skinnedmesh to.
    • Export Materials - Exports all used materials to .kmat files relative to the export directory.
    • Copy Textures - Copies all used textures to their path relative to the export directory.
      • Copy All Textures in Texture Sets - Copies all textures in every used texture set.
    • Use char Directory - Exports materials, textures, and anims to parent folder of "char" + the sub folders after the char folder if it exists in the export path. Used for convenience when you save your Skinnedmesh to the games char directory and you want everything else saved in the correct folders as Turok 2 has it setup.
    • Export Anim - Export all animations the Skinnedmesh uses into a .anim file.
  3. If you disabled the Export Anim option you will have to export the animation manually. To do that follow the same procedure as exporting the Skinnedmesh except navigate to File > Export > Turok 2 Animation (.anim)

When exporting Animations, make sure you give it a fake user by pressing the little shield icon and then an F will be displayed to the left of the animation name in the list. Otherwise the animation will not be exported. Validate the Skinnedmesh and check the System Console for any errors/warnings.



Creating A Custom Skinnedmesh

When creating your custom Skinnedmesh make sure:

Editing Turok Properties

Object Panel

Type: The Type of Turok Object this Blender Object is: None, Staticmesh, Skinnedmesh, Bounding Box, Hot Point.

AnimID: The Animations ID

FPS: The Frames Per Second the animation will play at

Frame Scale: This value is unused and serves no purpose

Blend Length: The length of frames to blend into this animation (default 5)

Blend Start: The frame to start blending

Blend End: The frame to end blending

Loop Frame: The Frame to go after the animation has finished playing. Setting this to the last frame of the animation will make it stop when it finishes playing. So most of the time you want this at either frame 0 or the last frame.

Action Key Frames: Add/Remove/Select Action Key Frames that will trigger in game. With a Action Key Frame selected you can edit it's properties.

  • Frame - The frame this action will be triggered on.
  • Bone - An unused Bone index. Most of the time is None (65535).
  • Event - The type of action that will be triggered. Enter a number or click the menu button on the right to search for one. The next 8 properties that appear below the event property depend on the Event you are using. Assign them accordingly.
  • Point Offset - The location of this key frame action relative to the Root Bone or Armature. Press the Show Point button to see the point on the model. Pin the object view and select the point in the 3D view and move it around then click Set Offset to set the Key Frame Action Offset. (This is not used in event 11 - Fire Weapon Projectile)


Event ID Name Description
0 Play Sound
1 Spawn Particle
2 Normal Damage
3 Normal Radial Damage
4 Normal Radial Damage
5 Trigger (Unused)
6 Unblock Region
7 Block Region
8 Spawn Particle
9 Screen Flash Only shows the flashes if the player is looking in the direction of the key frame action point. Color should range from 0..255. Time is 15.0 = 1 second.
10 Spawn Trails (Unused)
11 Fire Weapon Particle This will fire the particle specified. If the player is using alternate ammo and the particle ID matches projectileParticle in the weaponInfo def then it will fire the altProjectileParticle. This will also reduce the players ammo by ammoConsumption in the weaponInfo def. The point the particle is spawned at is hardcoded. The offset is not used.
12 Shake Screen Sinwave
13 Shake Screen Random
14 Display Text (Unused)
15 Violent Radial Damage
16 Violent Radial Damage
17 Explosive Radial Damage
18 Explosive Radial Damage
19 Extreme Radial Damage
20 Extreme Radial Damage
21 Gamepad Rumble (Unused)
22 User/Script Event
23 Play Sound On Model If the model index is visible then it will play the sound
24 Spawn Particle On Model If the model index is visible then it will spawn the particle
25 Explosive Ground Radial Damage
26 Turn On Hot Point
27 Turn Off Hot Point
28 Spawn Actor
29 Play Material Sound If the actor is over a staticmesh surface that has the same specified surface type then the sound will play
30 Play Voice
31 Play Looping Sound
32 Stop Looping Sound
33 Nuke Explosion
34 Delete This Actor

Bounding Box: This displays the current min and max values of the bounding box parented to this armatures mesh object. Use the "Show/Hide Bounding Boxes" Dropdown menu to quickly show or hide certain bounding boxes.

Head Tracking: Assign the Start and End Bones that are the Neck and Head of the model so it will look at it's target. Assign None if you don't want any head tracking.

Validate Skinnedmesh: Press this button to make sure everything is setup correctly and ready to be exported to Turok 2. Info/Warnings/Errors will be displayed in the System Console.

Preview TextureSet: Preview how the Skinnedmesh will look with a texture set variant.

Yaw Offset: Add Yaw Offset key frames to your animation to rotate the root bone in game. Yaw Offset key frames are used in AI Turn Animations. So this way the models root bone can rotate differently from the actual way the AI is turning towards in game. (As far as I know this was never used in Turok 2)

Add Hot Point: You can Add a new Hot Point to a Bone in this panel as well. Select a bone from the menu and click Add Hot Point. A new Hot Point Object will be created and added to the Armature.



Bounding Box Object Panel

This displays the min and max values of this Bounding Box. Use the "Show/Hide Bounding Boxes" Dropdown menu to quickly show or hide certain bounding boxes.

Switch to Edit Mode and modify the mesh to edit the min and max values.



Hot Point Object Panel

Use the "Show/Hide Hot Points" Dropdown menu to quickly show or hide certain Hot Points.

Bit: The Hot Point bit value to use for this Hot Point. 3 out of the 32 bits are used in game for specific purposes, the other 29 can be used for custom purposes.

  • 1 - On Fire
  • 3 - Death Blood
  • 6 - Bore Head Blood Gushing

Particle 1 ID: A particle to spawn at the Hot Points location every tick while this Hot Point is on.

Particle 2 ID: Another particle to spawn at the Hot Points location every tick while this Hot Point is on.



Bone Panel

Bone Index: The Bones index value will specify the order the bone is saved. You must give it a unique value starting from 0 to the number of bones in your armature.

Impact Type: The impact type this bone is.

Damage Scalar: Damage multiplier for hitting this bone.

Symbols: These describe the location of the bone.

Collision: Specifies whether or not this bone will have collision depending on attached models, such as don't do collision if head has been blown off, etc. Each number represents the attached model index. If that number is ON then that bone will have collision with that attached model.

Add Hot Point: You can Add a new Hot Point to this Bone in this panel as well. Click Add Hot Point to create a new Hot Point that will be parented to this bone.

Bounding Box: This displays the current min and max values of the bounding box parented to this bone. Use the "Show/Hide Bounding Boxes" Dropdown menu to quickly show or hide certain bounding boxes.

Setup Bone: Sets the bones head/tail position to be correct.

Auto Name Bone: Sets the bones name using the Bone Index and Symbols.

Include Index In Name: If you want to mirror your pose bones as your animating you will need to name your bones without the index. Turn this off and auto name your bones to be easily able to do that.


Animation Action Panel

In Blenders Dope Sheet Viewport, in the action editor, you can select animations and view the Turok 2 Properties panel by pressing N or dragging the right side out. This action panel is the same as the one in the Armatures Object Panel, so see that for the same details.




3D Viewport Tool Panel

In any 3D Viewport window, you can view the Turok 2 Tool panel by pressing N or dragging the right side out.

Clear Unused Blender Data: Removes all Blender Data blocks that are unused. Better then Blenders "Purge All" operator.

Open Add-on folder: Tries to open the folder this add-on is located in with windows explorer.

Online Documentation: Opens a web page in your browser to the Turok 2 EX Blender Tools website.

Setup Player Model Scale: Creates a box object that is the same scale as the Player

All: Loads all the games files. This will take a while since there are so many files and you only need to do this once. Once the files are loaded there will be a checkmark beside each one indicating that they were loaded. If you change any def files you can click these buttons to reload them.

Base: Loads builtin tools files and the defs and your custom blender folder if you have it in your project

Actors: Loads all actor defs in defs/actors/

Particles: Loads all particles in particles/

Sounds: Loads all sound shaders files in sounds/shaders/

Camera Offset: The camera offset value as defined in your defs/weaponInfo.txt file.

Setup Camera: Setup a Weapon Camera which matches the Turok 2 EX camera so you can easily see what your weapon will look like in game (Activate the camera with the default key “0” on keypad).

Preview Sounds: Open a folder that contains .ksnd files to show them in a list. Click on them in the list to play them. You can also select sounds by ID value and play them.

Preview Staticmeshes: Open a folder that contains .staticmesh files to show them in a list. Click on them in the list to quickly load them. Click the Disconnect Button if you want to keep that mesh in Blender.

Preview Skinnedmeshes: Open a folder that contains .skinnedmesh files to show them in a list. Click on them in the list to quickly load them.



Material Panel

If the name of the material is any of the following: _default, _white, _whiteAlpha, _wireframe, _wireframe_selected, _superrok_white, _superrok_black, _superrok_red the games builtin material will be used for it instead.

Texture: Shows the first texture being used in this material. Here you can quickly change all the texture properties you need to. This is similar to the shader node panel so see that for the same details.

Environment Color: Saturates texture by the this color. (Default: Black)

Diffuse Color: Multiplies pixel color by this color. (Default: White)

Cull: Which side to render Tris.

  • Use Settings - Uses whatever Blenders material setting "Backface Culling" is set to.
  • Back - Renders only the back side (mostly used)
  • Front - Renders only the front side. (Should never use this)
  • None - Draws both sides

Sort: The sort type to render this material on.

  • Default - The standard sort type most opaque materials should use.
  • Masked - Used for materials with textures that have alpha. The Blend and Alpha Test material property should also be on when using this sort type.
  • Translucent - Materials that you can partially see through. Should have the Blend property on when using this sort type.
  • Water - For water materials. Should have the Blend property on when using this sort type.

Surface: Surface type of this material

Reflective Power: Screen Space reflection power

Blend: Material transparency

Full Bright: Do not use any lighting.

No Draw: Will not render

Depth Test: Draws behind objects based on Depth buffer, otherwise will always draw on top of current render.

No Depth Mask: Turns off depth mask. The depth mask masks out areas on the model depending on how far from the camera it is.

Alpha Test: Turn ON if you have a texture that uses alpha and use sort type Masked. Discards pixels depending on the outcome of the Alpha Func comparison between the textures alpha value and the Alpha Mask value.

Alpha Func: The alpha comparison function (default: gequal)

Alpha Mask: The alpha cut off value to discard the pixel. (default: 0.6525)

Params: A list of uniform variables the shader will use. Assign the correct names from the shader and specify whether the variable is an Integer or Float. Then assign it's value. There are only 3 uniform variables in the default shader that you can set and you do not need to include them in your materials if you want them OFF.

  • uLimitAlpha - Integer Type. 0 for OFF, 1 for ON. This limits the pixel alpha value to a maximum of 0.5
  • uReflective - Integer Type. 0 for OFF, 1 for ON. This gives the shiny look based on camera projection
  • uPseduoColor - Integer Type. 0 for OFF, 1 for ON. Saturates the Color by Environment/Diffuse Color


*The use of the Environment and Diffuse colors will be slightly different for whatever shader the game uses to draw this material, which depends on the type of mesh the material is used on, the material sort type, and whether the materials Full Bright setting is On/Off. Meshes used for pickup actors are automatically set with Full Bright for all materials the mesh uses.

Staticmesh Shaders:

Settings Shader Used
Sort Default world_deferred.shader
Sort Default, Full Bright world_deferredNoColor.shader
Sort Masked world_deferredMask.shader
Sort Masked, Full Bright world_deferredNoColorMasked.shader
Sort Translucent/Water world.shader
Sort Translucent/Water, Full Bright world_noColor.shader

Skinnedmesh Shaders:

Settings Shader Used
Sort Translucent/Water or is used on a weapon world_skinned.shader
Anything world_skinnedDeferred.shader
Anything, Full Bright world_skinnedDeferredColor.shader

* world_skinnedColor.shader doesn't appear to be used anywhere.

Setup Image Quickly: To quickly assign a texture to this material – select an image by clicking on the image icon or opening a new texture, and select the type: One Sided, Two Sided, or Water. And if the image that you selected has any alpha in it. Then click Quick Image Setup and the shader node with the selected image will be added to the material and the Turok 2 material properties will be setup automatically.

Import Material from .kmat: Import a material from an existing .kmat file.

Use Custom Material Path: If ON will save this material to the specified .kmat file (do not include the extension .kmat in the Material Path). If is OFF will automatically set the material file path to materials/mat_<ExportFileName>



Shader Panel

Edit Material Texture Properties In Blenders Shader Editor Viewport and select a Texture Image Node and bring up the side panel by pressing N or dragging the right side out.

[Node]File Path: Only the filename will be used and not the full path. If the filename is any of the following: _default, _black, _white, _simpleShadow, _wireframeMesh, _wireframeMeshSelected the games builtin texture will be used for it instead.

[Node]Texture Interpolation: Linear, Cubic, and Smart will all use “linear” except if Anisotropic Filter is on then it will use “linear_anisotropic” filtering for the Turok 2 texture. Closest will always use “nearest”.

[Node]Texture Extension: Extend and Clip will use the Turok “clamp” wrapping. Repeat will use Turoks “repeat” wrapping.

Sampler Index: If you only have 1 texture node then keep this at 0.

Mirror Wrap: Overrides texture wrapping to "mirrored" which flips the texture on the x and y when it repeats.

Anisotropic Filter: Overrides texture filtering to "linear_anisotropic" when Linear, Cubic, or Smart is selected.