# Diesel Engine Category for Diesel Engine related docs # SystemFS SystemFS is a class to read and write files and more. Currently, it works only in the Windows version of the game. I'll add more info later right now I'll just list the functions and their parameters. ## Functions: ### open(path, flags) ### close(file) ### exists(path) ### is_dir(path) ### system_path(path) ### parse_xml(path) ### make_dir(path) ### delete_file(path) can delete a folder also. ### list(dir, directories) returns a table of files by default and folders if directories parameter is true ### copy_file(from, to) ### copy_files_async(files, callback) each file needs to be inside the files table so for example if I want to move file x to path y it's gonna be: SystemFS:copy_files_async({"x", "y"}) the callback has two parameters - success and message if the copy failed then success will be false and message should say something. ### can_write_to(path) ### checksum(path) # GUI # Sizes Each GUI element has a width and height, commonly written as W and H. # Position **Some things here are true only if you have a positive width and height.** The GUI System's position is pretty simple to understand, we have: **x or left, y or top, right, bottom and center** * **X or Left** - Moves the object left the more you add to it. * **Y or Top** - Moves the object bottom the more you add to it. * **Right** - Combination of the width and X position gives us the "right" position of the object, goes left the more you add. * **Bottom** - Same as right but now with Y position and height, goes bottom the more you add. * **Center** - Combination of the X or Y position and half of the width or height, there's center x and center y both act the same as normal x and y. ### World positions Normally the object's position is its position **inside** its parent, the world position is where the object really is in the screen(most of the times) ## Set functions set_name(string name) : Sets a name for the object, panels can find the object using the child function. **For world positon just add _world after set(like set_world_x)** * set_x(number x) / set_left(number x) : Sets the X position. * set_y(number y) / set_top(number y) : Sets the Y position. * set_position(number x, number y) / set_lefttop(number x, number y) : Same as set_x and set_y but combined. * set_w(number width), set_width(number width) : Sets the width of the object. * set_h(number height), set_height(number height) : Sets the height. * set_size(number width, number height) : Same as set_w and set_h but combined. * set_shape(number x, number y, number width, number height) : Sets the position and size of the object. * set_right(number right) : Sets the right position(sets the X position to your number minus the object's width) * set_bottom(number bottom) : Sets the bottom position(sets the Y position to your number minus the object's height) * set_center_x(number center_x) : Sets the center x position(sets the X position to your number minus the half of the object's width) * set_center_y(number center_y) : Sets the center y position(sets the Y position to your number minus the half of the object's height) * set_center(number center_x, number center_y) : Same as the two top but combined. * set_leftbottom(number x, number bottom) : set_x and set_bottom but combined. * set_rightbottom(number right, number bottom) : set_right and set_bottom but combined. * set_righttop(number right, number y) : set_right and set_y but combined. ## Get functions * name() : Returns the name of the object **For world positon just add 'world_' to the function name(like world_x)** * x(), left() : Returns the X position. * y(), top() : Returns the Y position. * position(), lefttop() : Returns X, Y positions. * w(), width() : Returns the width. * h(), height() : Returns the height. * size() : Returns width, height. * shape() : Returns X,Y,width,height. * right() : Retruns X + Width. * bottom() : Returns Y + Height. * center_x() : Returns X + (Width / 2) * center_y() : Returns Y + (Height / 2) * center() : returns center X, center Y positions. * leftbottom() : returns X, bottom positions. * rightbottom() : returns right, bottom positions. * righttop() : returns right, y positions. ## Animation * animate(function controller) : Make a coroutine out of controller and resume it every frame until it returns, passing in delta time in seconds. * stop() : Cancel the currently running animation. A few related global functions are defined in the `CoreEvent` module for use in animation controllers: * over(number s, function f, bool? fixed_dt) : Call f every frame for s seconds, with two arguments. The first increases from 0 to 1 over the period, the second is delta time. * wait(number s, bool? fixed_dt) : Yield for s seconds. * seconds(number s) : Iterator allowing an animation to be expressed as a for loop. Produces three variables: elapsed time since the start of the loop, elapsed/s, and delta time. If fixed_dt is truthy, over() and wait() assume 30fps regardless of the actual framerate. ## Input control GUI Workspaces have some functions to manage their connection to input devices: * connect_mouse(controller c) * connect_controller(controller c, bool b) * connect_keyboard(keyboard k) * disconnect_mouse() * disconnect_all_controllers() * disconnect_keyboard() * feed_mouse_position(? pos) : pos is the type GuiItem:world_position() returns. * feed_mouse_pressed(idstring button) * feed_mouse_released(idstring button) Known button idstrings are: * `0` * `1` * `mouse wheel down` * `mouse wheel up` * `mouse wheel left` * `mouse wheel right` # Bundle File ***Originally written by Simon W.** # Bundle Database (BLB) The Bundle Database file, also known as “bundle_db.blb” and “all.blb”, defines all file entries with their hashed path, hashed extension, language, and a unique ID. Special things to note: “idstring_lookup.idstring_lookup” has an ID that is equal to the count of file entries. ## File structure of the .blb format ### Header ``` uint32 languages_tag //Payday 2 = "8C F2 18 00" Payday: The Heist = "9C 2B F2 00" uint32 languages_count uint32 languages_count //should be same value as previous uint32 uint32 languages_offset //offset to the beginning of languages section uint32 unknown uint32 unknown uint32 unknown uint32 file_entries_count uint32 file_entries_count //should be same value as previous uint32 uint32 file_entries_offset //offset to the beginning of file entries section uint32 unknown uint32 unknown uint32 unknown uint32 unknown ``` ### Languages section ``` FOREACH( languages_count ) uint64 language_hash uint32 language_representation uint32 unknown END FOREACH ``` ### File entries section ``` FOREACH( file_entries_count ) uint64 file_entry_extension_hash uint64 file_entry_path_hash uint32 file_entry_language //one of the language representations uint32 unknown uint32 file_entry_ID uint32 unknown END FOREACH ``` # Packages (bundles) Bundles are diesel's packages containing files with corresponding IDs. The package name can be looked up with Bundle Modder by using the hash converter on the bundle name with “use hex” and “swap endianness” (this does not work with all_x bundles). Which then can be used in lua to load packages. Bundles are split into two files, header and data. The header files end with “\*_h.bundle” while data files end with “\*.bundle”. ## File structure of the _h.bundle (Header) ### Header section ``` uint32 section_size uint32 section_tag //Since update 70, this tag is present in every file. Payday: The Heist is present only if bundle is all_x uint32 file_entries_count uint32 file_entries_count //should be same value as previous uint32 uint32 file_entries_offset //if section_tag == "00 00 00 00" then file_entries_offset += 4 uint32 file_entries_tag //Payday 2 = "E8 EB 18 00" Payday: The Heist = "88 EE 18 00" FOREACH( file_entries_count ) uint32 file_entry_ID uint32 file_entry_address //address within the *.bundle file IF bundle is all_x then uint32 file_entry_length //the length of this file entry END IF END FOREACH ``` ### Footer section Please note that footer items correspond to the header file_entries in same order. ``` uint32 section_tag //Payday 2 and Payday: The Heist = "F8 C5 FC EB" uint32 section_size uint32 section_item_count uint32 unknown uint32 unknown uint32 unknown //tag? FOREACH( section_item_count ) uint64 item_extension_hash uint64 item_path_hash uint32 unknown //end tag? END FOREACH uint32 zero //end ``` ## File structure of the h.bundle (Data) This file consists of a collection of files. Each file entry starts at a specified address in header with a specified length, if length is not specified then it is calculated as a difference between current entry address and next. ``` FOREACH( file_entries_count ) byte[] file_entry END FOREACH ``` # Unit File This is an explanation of how units work in Payday 2. This may not be 100% perfect, but it should give the basic idea of what's going on. A “unit” in Payday 2 is an object like a mask or an enemy. It basically sets properties, applies effects, and specifies textures for the units. # Files * **.unit** - Points to a \*.object file for further loading data about the unit. Specifies dependencies like sounds, effects, or animations. Establishes the extensions, which consist of properties for the unit like inventory, AI, damage, movement, sounds, or interactions. Sometimes can specify a path for the .unit file that is supposed to be loaded when the unit is spawned over network. And finally can specify the location of sound sources for the unit. * **.object** - Points to a **.material_config** file, **.sequence_manager** file and the animations. For some units, there are “bodies” that establish which parts of bodies are enabled, and sets properties for them like friction, collision class, and a template. Then, there are “constraints”, which mostly establish how far limbs can rotate. After that, “decal_surfaces” are established, which basically assigns a specific decal material to parts of bodies. And finally, “graphics” are specified, they set which parts of model are enabled, and sometimes sets a LOD for them depending on distance from the unit. * **.model** - This is the model for the unit. * **.material_config** - Contains a list of materials with specified templates that are applied to the textures. Points to \*.texture files to use for reflections, diffused textures and normal maps. * **.cooked_physics** - Not much is known about this file but it is related to physics of the unit. * **.sequence_manager** - This file contains sequences which can be run on the unit. * **.texture** - This is a renamed **.dds** texture file. # Loading Order Units in Payday are loaded in a specific order. If a file in this chain has an error, the unit will not work correctly and potentially crash the game. The loading order is as follows: .unit file is loaded first (this file has to point to the .object file to load it next), next the .object file is loaded (this file often points to the .material_config file, which contains textures for the model to use), next either .model or .material_config is loaded (.material_config has specified texture files that it loads and applies a specific template with effects to them. And .model contains the model and retrieves materials from the .material_config). # .unit Details The .unit file is the first to get loaded when accessing the unit. This file is in .xml format, with a fairly simple structure. Most of the things in these .unit files are pretty self explanatory. However, the weapon units, mask units, and character units are all different. As they are obviously none of them are the same at all! Here is a sample of a .unit file. ## Sample Breakdown of a .unit file As an example, I will be looking at the cloaker's (spook's) unit files. First, the .unit file of a cloaker are located at (units\\payday2\\characters\\ene_spook_1\\ene_spook_1.unit). ```xml ``` Please notice the structure: anim_state_machine, then object, then dependencies, then extensions, then network, then sounds. Sometimes, if this structure is not followed, the game will crash. (Note, Payday: The Heist sometimes does not follow this structure, so PD1 .unit files would often result in a crash). Let's breakdown this file by sections. ```xml ``` The first section states that this unit is a human being (I am assuming when you hit it, blood will come out). And that it's in slot 12 (I believe slot number can be ignored). ```xml ``` The second section establishes the animations that this unit will use. In this case, the cloaker will be using cop animations. ```xml ``` The third line establishes where the next file is, the .object file. This file will be loaded after the .unit (Please note that the path does not contain an extension, the game already knows that you pointed at a .object file. ```xml ``` This block of code establishes the dependencies that this unit has. This unit is dependent on the cop animations using the cop animation definitions. Next, this unit is dependent on the sound bank “soundbanks/regular_vox” (this soundbank is related to speech). Next, this unit is dependent on an effect, the “effects/particles/character/cloaker_goggle”, in the .object file this effect will be assigned to a specific location. And finally, this unit is dependent on another unit “units/payday2/characters/ene_acc_baton/ene_acc_baton” (this counts as an enemy accessory, thus the name “ene_acc”). And once again, not a single path has an extension, the game knows. ```xml ``` This chunk of code assigns basic unit things, like AI, inventory, sounds, etc. Most of them stay the same, but variables change. The “unit_data” extension is present practically in every .unit file and does not seem to change. The “base” extension is usually present on characters or usable objects. In “base” the class changes depending on the unit, and the variables in the extension also change. For this unit, the variables set the identity of this unit as “spooc” and assigns it “mp5_tactical” as a default weapon. The “inventory” seems to be only present on units that can carry items (like ammo or other weapons). The class usually stays as “CopInventory”, but there could be multiple kinds of “inventory”. The “brain” assigns AI to the unit, in this case “CopBrain” is assigned. The “anim_data” is currently unknown to me, but I am guessing that these are the kinds of animations a unit can perform, “PlayerAnimationData” is assigned. The “character_damage” assigns various things regarding the damage the unit will take, “CopDamage” is assigned. Two variables are assigned as well, “_head_body_name” signifies what part of body (according to model) is considered to be the head, the “_deadh_sequence” signifies what sequence this unit will perform at death. The “movement” assigns what kind of movement this unit will perform, “CopMovement” is assigned, as well as two other variables. The first variable “_footwear” states what kind of shoes the unit will have, “boots” are assigned. Second variable “_anim_global” states what kind of movement animations this unit will perform, “cop” animations are assigned. The “interaction” is usually present with units that can be interacted with, I am lacking detail as to what kind of interaction, “IntimateInteractionExt” is assigned, with one variable. The variable “tweak_data” is pretty much always present with “interaction”, “intimate” is assigned. The “network” extension is usually present on units that can be spawned or changed during the game, “NetworkBaseExtension” is assigned. The “damage” extension is usually present with units that can deal damage, “UnitDamage” is assigned with one variable. The variable “_skip_save_anim_state_machine” is related to animations and I am unsure about the exact usage of this, variable is set to “true”. The “contour” extension is usually present with units that can have an outline, class of “ContourExt” is assigned. The “sound” extension determines what kind of sounds this unit can make, “CopSound” is assigned. ```xml ``` This section is usually present with units that can be spawned or changed during the game. This is responsible for syncing the spawn, by specifying the .unit file to be loaded on the clients. (Lobby host does not use this, only the client). ```xml ``` This section specifies the source of sound for the unit. Apparently the cloaker (and all other enemies) make sounds from their “Hips”. After the .unit file is loaded, the .object gets loaded. Not all commands were listed in this example, so other commands will be listed below in the “Other .unit commands” section with their explanations. ## Other .unit commands Other .unit commands will be added here as research progresses. # .object Details The .object file is second to get loaded when accessing the unit. This file is in .xml format, with a fairly simple structure. Most of the things in these .object files are pretty self explanatory, and about 80% unique to the unit, as it heavily replies on the model and the names of body parts in the model. The .object file usually contains properties of model parts like materials, sequence_manager, bodies, constraints, effects, graphics, and lights. Here is a continuation of the unit breakdown from previous section. ## Sample Breakdown of a .object file Following from the previous section, the .object file path of a cloaker was assigned as “units/payday2/characters/ene_spook_1/ene_spook_1” (that's without the .object at the end). The .object files tend to be repetitive, as they assign each “body” in a model, specific settings. And for sake of space, the .object file will be cut down to include as little repetition as possible. ```xml ***PART OF THE FILE WAS SNIPPED HERE*** ***PART OF THE FILE WAS SNIPPED HERE*** ***PART OF THE FILE WAS SNIPPED HERE*** ``` Please notice the structure: diesel materials, then sequence_manager, then animation_def, then bodies, then constraints, then decal_surfaces, then effects, then graphics, and then lights. Sometimes, if this structure is not followed, the game will crash. (Note, Payday: The Heist sometimes does not follow this structure, so PD1 .object files would often result in a crash). Like before, Let's breakdown this file by sections. ```xml ``` This section specifies the location of the the .material_config file, along with the orientation position. This is present in most units that have a model (some weapons don't seem to specify this). The .material_config file is specified to be “units/payday2/characters/ene_spook_1/ene_spook_1” (once again, no .material_config, game knows) with the orientation at “root_point” of the model. ```xml ` ` ``` This section specifies what sequence_manager file to use. And what animations to use. (Sometimes these are separated into two lines). The sequence_manager file is specified to be located at “units/payday2/characters/ragdoll” (no .sequence_manager extension). And the “anims/units/enemies/cop/cop_def” animation definition is set to be used. ```xml ***PART OF THE FILE WAS SNIPPED HERE*** ***PART OF THE FILE WAS SNIPPED HERE*** ``` This section pretty much defines collisions and ragdolls per body parts in the model. For the first “body” is enabled (as it's set to true), the templace for “character” is used with friction of “0.6”, and a collision class of “ragdoll”. This seems to include the object “Spine1” and “c_capsule_body” of collision type “capsule”. Both of those objects are most likely defined in the .model file. **THIS IS NOT FINISHED!!!** ```xml ***PART OF THE FILE WAS SNIPPED HERE*** ``` This section deals with constraints of rotations and movement. **THIS SECTION NEEDS MORE EXPLANATION, BUT IS SELF EXPLANATORY!!!** ```xml ``` This little section states that the default material for the unit is “flesh”. There are a few other default materials besides flesh, and sometimes they're even applied per body part in this section. ```xml ``` This section applies effects to the unit. I am not 100% certain on the application process. I believe that the effect under the name “es_light” is being applied to the object “e_light” (probably stated in .model) from effect file “effects/particles/character/cloaker_goggle” (once again, .effect extension is not needed). The name of the effect does not matter; it can be set to anything you want. It seems to be only for referential purposes. The effect does not necessarily need to be applied to an "e_light" object, as other objects in the file will work as well (such as "g_body" or "root_point"). ```xml ``` In this section, there are two things happening. First, the LOD is being set per distance (in centimeters). So at distance < 3000 cm the default LOD model with be drawn to screen. If distance > 3000 cm then the LOD1 will be drawn. Second, some elements of the model are enabled/disabled in this section. As you can see, the “s_body” is enabled (with “true”) and is set to cast a shadow with shadow_caster set to “true”. And then there is “g_il” which is disabled. Please note that not all elements of the .model can be disabled here. Only the ones you know (i.e. the ones already listed in this .object file) or the ones you know from the model (currently there is no way of looking up element names from models. ```xml ``` This section is for creating a light on the unit. For this unit in particular, it creates a glow around them that gets enabled via the sequence_manager. This “point_light” has a range of 1 - 25 with the falloff of “4.0” (I think the falloff is for the type) and type of “omni|specular”. I am not certain about what this type specifically does, but it certainly acts as an effect on this “point_light”. After the .object file is loaded, either the .model or the .material_config file get loaded. Not all commands were listed in this example, so other commands will be listed below in the “Other .object commands” section with their explanations. ## Other .object commands Other .object commands will be added here as research progresses. # .model Details Currently there are no details on the .models, as the filetype has not been completely reverse engineered. Research Notes: `.model contains hashed names of objects using Hash64, uint64. (Currently looking into editing elements)` `Bones have been redone since `[`Payday:`` ``The`` ``Heist`](Payday:_The_Heist "wikilink")`, they now don't include 4th elements of fingers.` `Each bone is specified as a 3D Object, which contains rotation matrix, position, and a parent ID.` `Observations:` `*It's near impossible to find model names, as they are hashed and unhashing them would be near impossible. They are not part of idstring.` `*I'm assuming .material_config hashes the name of material, and applies it to the model. If it doesn't exist, it still applies (to nothing).` `*It would be easier to create models from scratch, as you will know the names of all objects and materials, so you would have full control over the model.` # .material_config Details The .material_config file is loaded sometime after the .object file. This file is in .xml format, with a fairly simple structure. Most of the things in these .material_config files are pretty self explanatory, and is unique to the unit, as it heavily replies on the model and the names of body parts in the model. The .material_config file contains texture paths (diffused and bump map textures), sometimes reflection textures, sometimes material_textures, and sometimes some variables for the render_template. Here is a continuation of the unit breakdown from previous section. ## Sample Breakdown of a .material_config file In this example we will be using the cloaker. The .material_config file path of a cloaker was assigned as “units/payday2/characters/ene_spook_1/ene_spook_1” (that's without the .material_config at the end). The .material_config files tend to be repetitive, as they assign each the requested material names in the model, specific textures and effects. And for sake of space, the .material_config file will be cut down to include as little repetition as possible. ```xml ``` There is no specific structure to follow. This file seems to be a list of materials with some variables attached. The only real problems that can occur are incorrect textures, broken model, no model at all (but a floating blob of gray). Let's breakdown this file by sections. ```xml ``` This establishes the group that these materials belong to. I am not sure as to what group names can be given, but it's best to keep them similar to the original model names. The version does not seem to matter. ```xml ``` This section identifies a material “mtr_body” with a render_template of “generic:DIFFUSE_TEXTURE:NORMALMAP:RL_COPS:SKINNED_3WEIGHTS” and version of “2” (once again, does not seem to matter). The material name has to match the one listed in the .model file, otherwise the model will be broken. The render_template is a predefined template, and **CANNOT SIMPLY BE APPENDED**, there is a list of available render_templates with explanations [HERE](Payday_2/Render_Templates_List "wikilink"). This material has two variables included (these are present with almost every material). The “bump_normal_texture” specifies where the bump map of this material is, for this example it's located at “units/payday2/characters/shared_textures/spook_heavy_nm” (once again, the .texture extension is not needed). Followed by a “diffuse_texture”, which is the actual texture of the material, located at “units/payday2/characters/shared_textures/spook_heavy_df”. Both the “bump_normal_texture” and the “diffuse_texture” are passed to the render_template to be handled. ```xml ``` This section right here is almost identical to the previously viewed material. To differentiate this new material, it has a different, uses a different render_template, and has a few new variables. The diffuse texture serves the same purpose as before. The new, “self_illumination_texture” points to the path of “units/payday2/characters/shared_textures/spook_il”. This “self_illumination_texture” is related to the render_template. Same with "opacity_texture " and the “variable”. All of them are passed to to the render_template to be handled. ```xml ``` This last section is responsible for casting shadows. With name “shadow_caster” and render_template of “shadow_caster_only:SKINNED_1WEIGHT”. A list of available render_templates with explanations [HERE](Payday_2/Render_Templates_List "wikilink"). After the .material_config file is loaded, nothing else loads. Not all commands were listed in this example, so other commands will be listed below in the “Other .material_config commands” section with their explanations. ## Other .material_config commands Other .material_config commands will be added here as research progresses. # Skin map textures (df_cc) # Skin map texture The _cc_df textures are used instead of diffuse on models when skin is applied and each channel controls specific aspect of it: ## Red Red channel is used as material map for 6 defined types of it. ![](https://i.imgur.com/XuNQC4j.pnghttp://) ###### Materials shown in overkill base gradient template. ![](https://i.imgur.com/MlRBikY.pnghttp://) ###### Example of PD2 Aimpoint material map layer. ## Green Green channel seems to be mix of various maps with diffuse as main goal of this channel is to give skin a shape and details like a diffuse but with colors controlled by skin. ![](https://i.imgur.com/SvmQzIM.pnghttp://) ###### Example of PD2 EOTech sight. ## Blue Blue channel is used to create "wear and tear" damage to skin as quality of skin lowers and gradient timeline progresses. ![](https://i.imgur.com/FxJOzSu.pnghttp://) ###### Example of wear and tear on PD2 EOTech sight. # Creating skin textures for custom models ## Red Material map can be either created by manually painting parts on channel or using exported UV layouts of selected meshes. Painted parts must only use solid color as any form of gradients or blending will results in artifacts. ![](https://i.imgur.com/ZUV6tc7.pnghttp://) Use these RGB color values to assign specific material: * Metal - #000000 * Plastic - #525252 * Wood/Rubber - #5a5a5a * Sec. Metal - #848484 * Cloth - #adadad * Details - #efefef ![](https://i.imgur.com/v1wpbkp.pnghttp://) ## Green Diffuse texture in grayscale can be reused for this channel. Image must be in edited be around light gray colors (Too dark image will results in missing details on models). ![](https://i.imgur.com/aqIL0AU.pnghttp://) ## Blue For wear and tear layer any texture of scratches with transparency or on white background can be used. ![](https://i.imgur.com/qUfjxkX.pnghttp://) Example of random texture with scratches. For best transition between skin quality scratches should have some black/white range can go fully from 0 to 255. ![](https://i.imgur.com/q9174uK.pnghttp://) Black color = Part of texture that will get damaged/White = Solid. Optional: Very subtle outlines of AO map for easier visualization what parts of texture get damaged. ![](https://i.imgur.com/i5mIvBq.pnghttp://) Preview of example texture in-game. # Note about Payday 2 Model Tool For GLTF/GLB format: New objects and models can include more UV layers. * UV0 (Default "UVMap" in blender) will be used as the "pattern UV" if a second UVMap is not present. * UV1 (Second listed UVMap in blender) will be used as the "pattern UV" for patterns and stickers when present. For OBJ format: Not recommended to use but new objects or models are free of any problems with skins but in case of replacing existing objects in PD2 models remember to use "Pattern UV" option to prevent patterns being missing/broken in most cases. ![](https://i.imgur.com/FiqgxBg.pnghttp://) ![](https://i.imgur.com/Oexc8Uz.pnghttp://) # Additional notes about UV coordinates Some CC textures have parts that do not utilise the skin materials and will show their original textures (Example, Commando 101 rocket launcher), this effect can be achieved by moving the pattern UVs outside of the 0-1 region. # Animated Models (WIP PAGE ON ANIMATED MODELS USED IN PAYDAY 2) # Page Notes: * Animations missing X Y or Z rotations dont seem to work properly. (tested on 32-Bit Floats with Discard) * Animations missing X Y or Z loations work fine. * Animations using scale likely dont work. # Importing Animations wip # Exporting Animations wip # Building an animated model wip Object File Portion: ```xml ``` # Sequence Manager `animation_group` is the type of sequence you want to play animations in the model. * enabled: Is it playing or paused (true/false) * name: The animation group name you want to use ("'string'") * from: The start of where you are playing * to: where you want to end (not using this will make it continue until the end of the animation) Example: ```xml ``` # Material Config XML Example XML: ```xml ``` TEMPLATES ARE **NOT** MODULAR! A full list of template variables can be found in `shaders/base.render_template_database` - `` contains all of the material xml for the file. - Typically uses `version="3"` - `` contains the information of a material. - Typically uses `version="2"` - `` a variable that often uses a texture with the identifier _df at the end. - `` a variable that often uses a texture with the identifier _nm at the end. - `` a variable that often uses a texture with the identifier _gsma at the end. (Gloss, Specular, Metalness, Alpha) - `` is a variable that loads a cubemap to a material that accepts cubemaps. - `` will use a locked cubemap and wont change from environments. # Special Use Cases - `` control options: - `name="mat_name"` give your material a name to go with your models material name. - `render_template="template_name"` a full list of templates can be found in `shaders/base.render_template_database` - `unique="true"` is usually used for materials that will change per-unit. Unit contours for example. - `src="name"` will clone the values from an existing `` to your current material. - cloned materials can be modified further by including variables or textures to override the source copy. - `decal_material="id"` graphic mesh faces with the material will use the `decal_material` variable for hit effects. - List of decal IDs can be found in `lib\tweak_data\tweakdata.lua` `self.materials = {list}` - `diffuse_color="255 255 255 255"` potentially unused. (Red, Green, Blue, Alpha) - `version="2"` most if not all templates use version 2. - `` control options: - Animations can control some variables using the listener type. - Standard variable: `` - Listener variable: `` # Object Xml Example XML: ```xml ``` - `` is a required table that holds a path to the materials and root object. - `materials="path"` leads to the material config the unit will use. - `orientation_object="rp_rootpoint"` the object that acts as the origin of the unit, must be an Empty object. - `` is its own table defining the sequence manager the unit will use. - **Warning!** `` is required in the units extensions! - `` is the table that holds collision information. - `` is the table that holds the objects that will be used as collision. - `name` is the name of the body you are making. - `enabled` is a toggle for if collision should be enabled. - `template` is the physics template of the body. - `static` is solid collision. - `editor` is editor only collision. - a full list of templates can be found in `settings/physics_settings.physics_settings`. - templates can be edited in object by adding properties seem in the physics_settings file. - `` is the table that holds the referenced object. (The same object can be used more than once) - `name` is the name of the object being used. - Using empties will bind the body to the empty for constraints. - `collision_type` is the shape/type of collision. - `box` is a box. - `sphere` is a sphere. - `capsule` is a pill shape. - `convex` is a convex shape based on your used object mesh. - `mesh_mopp` is a paper thin collision that is 1:1 the shape of your objects mesh. - `two_sided` is a toggle for if your collision should be double sided. (Very buggy!) - `padding` is the additional thickness in cm of your object. - Default 0 leaves models 2.5cm thicker, use -2.5 to correct it. - Does not apply to mesh_mopp collision. - `` is the table that holds a list of meshes to act as decal surfaces. (Blankets that allow decals to spawn) - `default_material` is used if no decal material information is avaliable when hit. - `` is a table that holds a specific object to act as a decal surface. - `name` is the name of the object being used as the decal mesh. - `enabled` is a toggle for if decal_mesh should be enabled. - `material` to be used when shot/hit. - `` is the table that holds all of the graphics objects. - `` is a table that is used to control the selected graphic. - `name` is the name of the object being used as the graphic. - `enabled` is a toggle for if the graphics should be visible. - `shadow_caster` is a toggle for if the graphics object should cast a shadow. (typically used by shadow_caster material objects. `s_shadowcaster`) - `` is a table that holds all of the constraint information. - `` is a table that constrains objects together. - `enabled` is a toggle for if the constraint should be active. - `type=""` sets the type of constrant. - `static` - `ragdoll` - `` Attaches A to B. - Attaching to world requires `@world` to be used as `body_a`. - `` Sets the position to pivot from. - `` Sets the twist axis and control. - `` - `` Limit the angle the constrant can rotate. - `` Spring settings. # Sequence Manager XML ### Unit extension ```xml ``` ### Include in object file ```xml ``` Example XML: ```xml
``` **Important: Strings need to have `'` at the beginning and end, otherwise they do not work.** ### Sequences - `` - `name` The name of your sequence. This will show up in the mesh variation dropdown and UnitSequence/UnitSequenceTrigger elements. - `editable_state` Makes the sequence show up in the mesh variation dropdown and UnitSequence element. * - `triggable` Makes the sequence show up in the UnitSequenceTrigger element * * Both editable_state and triggable are optional. Sequences will run and trigger without them, you just have to type in the sequence name manually into the elements. * ****That's probably how it's supposed to work, however testing showed that having either of them set to true will make it show in both UnitSequence and UnitSequenceTrigger, as well as the mesh variation dropdown.*** - `once` true / false | Sequence can only run once. - `` Used to toggle individual graphic objects. - `name` Name of the object. Usually start with "g_". - `enabled` true / false - `` Used to toggle graphic groups. - `name` Name of the graphic group. - `visibility` true / false - `` Used to toggle bodies/collisions. - `name` Name of your body. - `enabled` true / false - `` Used to toggle decal meshes. - `name` Name of your decal mesh. Usually start with "dm_". - `enabled` true / false - `` Used to toggle lights. - `name` Name of your light object. - `enabled` true / false - `` Used to change the material config of your unit. - `name` path to the new .material_config you want to apply. - `` Used to play sounds from your unit. - `action` play / stop - `event` ID of the sound you want to play. - `object` Source object the sound is played from. - `source` Alternative to `object`, use a soundsource which has been defined in the .unit file. - `` Used to play effects from your unit. - `name` Path to the effect you want to play. Example: `name="'effects/particles/explosions/explosion_grenade'"` - `parent` object you want to play the effect from. Example: `parent="object( 'smoke' )"` - `position` (Not sure what it does exactly, every effect I found had `position="v()"` in it too) - `` Plays an animation. - `enabled` true / false - `name` Name of your animation group. - `from` The frame that this animation should start on. Example: `from="0/30` will make the animation play at 30fps. - `to` End frame of your animation. Example: `to="64/30` - `speed` How fast your animation is playing. 1 is normal speed, can be a negative value to play backwards. - `` Used to run another sequence. - `name` The name of the sequence you want to run. - `` Spawns a new unit. - `name` Path to the unit you want to spawn. - `position` Object position, usually an empty, that the unit will be spawned on. Example: `position="object_pos('spawn_doors')"` - `rotation` Same as position, but for rotation. Example: `rotation="object_rot('spawn_doors')"` - `` Toggle interactions on your unit. - `enabled` true / false


- `start_time` can be used on pretty much everything to add delays. - `startup` true / false ### Hitboxes You can take any body from your .object and use it as a hitbox to trigger sequences. ```xml
``` - `` This defines a body from your .object as a hitbox. - `name` The name of the body. - `` Controls how much damage the hitbox can take before it triggers the sequences inside. - `bullet` How many times you need to shoot it. - `explosions` How many explosions you need. - `melee` How many melee hits you need. - `lock` Doors, deposit boxes and basically anything you can use a saw on use this. (For Example: `lock="15"` on deposit boxes.) ### Filters and Variables You can define variables and filter sequences based on the value of a variable. ```xml
``` Add `filter="your_filter_name"` to a sequence to make it only run if the variable and the filter have the same value. Use `` to change variable values. ##### Example: ```xml
``` To be continued... #### (old notes from rex) Vector3 form in sequence manager: `v(0, 0, 0)` **MaterialElement** - `` material sequences affect materials of the functioning unit. `Unique="true"` is required to only affect this unit. - `name` is the name of the material you are modifying. - `time` set the time of animated materials, Joys mask uses this feature. - `state` sets a state argument, Joys mask uses this feature to pause the UV scrolling. - `render_template` sets the render template. - `glossiness` sets the glossiness value. - If you use a custom `key="value"` you can affect material config elements on your own. - Example: `` - This will modify the il_multiplier of an illuminated material. - Vector3 values need to be written like so `key="v(1, 2, 3)"` ___ pick random sequence thingy ` ... network syncs ... ... the rest of the unit definition ... ``` ## Initial `.object` setup ```xml ... material_config and sequence_manager ... ... the rest of the object definition ... ``` Additionally, make sure that animated collisions follow the `animated` template, otherwise they will not move. ## Files ### `animation_state_machine` This file needs to be referenced inside the unit's `.unit` file. Let's break down a sample `animation_state_machine` file. *Note that the purpose of some attributes is currently unknown.* ```xml ``` * **Segments** are used to allow for multiple states to be active at once; say, a medic can be crouching while playing the upper body "heal" animation. Every state will need to be assigned to a segment, and only one state can play at once per segment. **HOWEVER**, you can play multiple animations together from separate states in a single segment by using blend sets; see the section on `animation_def`. * Globals allow for **weights**: a single state can have multiple animations (if it is of the "mix" type), however, it will only play the animation with the highest weight value. These can be controlled through scripting (see the corresponding section). * A **default empty state**, with no animations, is set when the unit is loaded. This is standard on any `animation_state_machine` file unless you want the unit to start doing stuff as soon as it loads. If a invalid state is specified, no other states will work. * An **`animation_states`** file is defined. *There exists the possibility of defining the states directly in this file; however, it is recommended to still create individual files.* ### `animation_states` This file needs to be referenced inside the `animation_state_machine` file. It contains all of the playable states for the ASM. A valid animation state file resembles the following: ```xml ... ALL OTHER STATES ... ``` * A state of the type `template_state`: here, you define **the names of the animation redirects to call from the sequence manager**, that is, any name of your choice, and a reference to the state that will be played, for each state. **You can't trigger states from the sequence manager if you use their `name/formatted/like/this` directly**. * The default empty state we specified in the `animation_state_machine` file. #### State types * **`template_state`**: a state that serves as a property template for other states under the hierarchy. See the section on [state groups](#bkmrk-state-groups). **For it to apply to children states, it needs to be defined before them.** * **`emptyloop`**: a state that does not play an animation until it is overriden by another state. * A special blending effect occurs when entering a state of this type when using multiple segments; see the `from` action description below. * **`once`**: a state that plays a single, **pre-determined** animation, once. If given multiple animations, it will always pick the same one, regardless of weights. For the correct behaviour in that case, use `mix`. * **`loop`**: a state that plays a single, **pre-determined** animation, repeatedly, until another state is triggered. * **`mix`**: a state that plays the animation with the most weight from a list of possible animations, once. * **`mixloop`**: a state that plays the animation with the most weight from a list of possible animations, repeatedly, until another state is triggered. * **`timeblend`**: a state that "plays" the position of the bones defined in its animation at a time `t`, which is an implicit parameter of the state, settable from Lua. The bones won't move from that position until another state is played or this one is re-entered with another `t` value. When using this state, animations will need to define a `time=` parameter alongside them for reference purposes. This state also allows weights. E.g. ``: * When **`t = 0`**, the state will place the bones at their **starting** position in the animation. * When **`t = 1`** (the value specified in the XML), the state will place the bones at their **ending** position in the animation. * When **`0 < t < 1`**, the state will place the bone at that position in the animation given the reference `time` parameter. * **`snapshot`**: unknown. Used once in `core/units/locator/locator.animation_state_machine`. The following states are referenced in engine decompilations, but never used in the game: * **`sequence`**: untested, but should play its animations in a sequence as specified. * **`empty`**: unknown. * **`offset_once`**: unknown. * **`offset_loop`**: unknown. #### State actions * **`to`**: define a redirect to a state. E.g. `` * **`anim`**: play an animation with the specified name, which should have been defined in the `animation_subset` files. If the state is of the type `mix` or `mixloop`, you also need to include a `weight=` parameter. E.g. `` * **`exit`**: when the animation that the state played finishes, enter the named state. This will never trigger on `loop` and `mixloop` states. E.g. ``. *If exiting a state in a particular segment to a state in another segment, the second state will break.* * **`block`**: Block the specified state from triggering during this state. E.g. `` * **`unblock`** * **`block_group`** * **`unblock_group`** * **`from`**: blend the specified "amount" between the animation that the specified state was playing when exited and the animation that will now be played by this state. E.g. ``. * *`from` only works for same-segment state switching; to blend finished animations on a segment with playing animations on another segment, exit on the finished segment to an emptyloop state on that same segment which uses `from`. See the [video resource on blending for more info](#bkmrk-video-resources).* * **`from_group`**: same as with `from`, applying instead to an entire group. * **`keys`**: a table of `key` elements. More information below. * **`param`**: similar to `animation_state_machine` globals, except these are defined and stored on a per-state basis. They can also be used to set weights, just like globals, and controlled through Lua. E.g. `` * **`default`**: set default properties for states under the hierarchy. E.g. ``. * `blend`: amount of blend-in; see the [video resource on blending for more info](#bkmrk-video-resources). * `blend_out`: unknown... pretty sure that it doesn't do what it's supposed to. If you want to actually blend out, use `from_group`. * **`modifier`**: Enable the specified modifier. E.g. ``. * **`remove_modifier`** #### State groups You might have noticed that state names follow `a/structure/like/this`. Think of them as paths; this naming scheme allows for states deeper in the tree to inherit nodes from **template states** higher up. Some examples of how you might use this in a state structure: * `std` is a template state, and has a `from_group` and `exit` node for proper blending and clearing. * `std/death`, another template state, will be interpreted as if the `from_group` and `exit` nodes were defined inside it; additionally, it has keys for toggling an `animation_is_playing` value in an extension class. * `std/death/animation_1` will play as if the `from_group`, `exit` and keys were defined explicitly in it. #### Keys What should happen at certain points in the state. There are two types of keys, callbacks and key setters: ```xml ``` The former will result in the callback function being called as `callback_function(param1, param2, param3, param4, ...)` when the condition specified in `at` is met. Parameters are optional. ```xml ``` The former will make the key `extension_key` have the value `extension_value` inside the extension class `extension_class`. For the `at` parameter, you can use: * **`enter`**: when the state is entered. * **`exit`**: when the state is exited, **not when the animation finishes**. * **`loop`**: when the state loops. This will only trigger on `loop` and `mixloop`. * **`trigger`**: when the animation reaches a certain marker. E.g. `` * **`full_blend`**: when a blend-in finishes. Does not work on emptyloop states. * *Any number*: when the animation is at that keyframe. #### Example A base-game example of a state, with comments indicating what its doing. This particular one is the state for reloading the Reinfeld 880: ```xml ``` ### `animation_def` This file needs to be referenced inside the unit's `.object` file. The following is a simplified version of `anims/units/enemies/cop/cop_def.animation_def`, which I reckon showcases this file well. ```xml ... modifier params ... ``` * Animatable sets are where you **directly reference the bones in your model**. You can also give them aliases, separated by spaces, in the `alias` key. Take `root_point`, which not only is declared as the root bone, but also assigned both `all` and `root` aliases. For every animatable set you will need: * Blend sets, which define how two animations **playing at once** blend together. This does not refer to switching between animations, but rather, how much weight the animations have over the bones; every animation needs to be specified a blend set to use. *See the [video resource on blending for more info](#bkmrk-video-resources).* * When you don't want to blend (that is, play your animation with full bone influence), you can use an "all" set which applies a weight of 1 to all the bones. You use these in your animation subset. * Animation sets, which **need to define one or more `animation_subset` files.** **Make sure that when you name your animatable set and your animation set, they don't match a segment's name! Otherwise, you'll crash when changing states.** #### Modifiers For procedural animation, such as those seen with VR arm movements, or peer upper body rotation when they move their camera. **They don't work on empty states.** **Types**: group, stand, **ik**, shoulder, displacement, offset, link, mirror. The IK type requires either a `rotation` or a `position` node. These can be of type `script`, `lock` or `animation` (this last one might be of interest for animated IK, however, I haven't managed to make it work); * When using `script`, they are controllable from Lua. * When using `animation`, the `rotation/position` node also needs to include a `target` attribute, otherwise the game will crash when enabling the modifier. `rotation` can also use an `axis` (x, y or z) attribute when set to this type. ```xml ``` The mirror type requires a `config` attribute which can only be `biped`. For each of its entries, it needs a `first` and a `second` attribute, with an optional `transform` attribute which can either be `inverse` or `root`. ### `animation_subset` This file needs to be referenced inside the `animation_def` file. It's arguably the easiest to get a grip on. ```xml ``` * For each animation file, you define an animation name and a blend set to use. **This animation name is what animation states reference to play the animation file.** The folks that worked with these files actually left us some extra info on making animations: `If the animation finishes inside the viewable area and does not finish outside of the viewable area, you must animate the root point. Or else the animation will not sync at drop in. For eample the police car arrives and stop in the viewable area, here the root point shoul be animated. The heicopter arrives and leaves the the viewable area, here all_no_root is allowed.` Make sure to follow that guideline in order to avoid sync issues! ### Controlling animations through Sequence Managers Use `animation_redirect`. Example: ```xml ``` Remember that this is the name you specify in `to` state actions that redirects you to a state. ## Video resources [Animation Blending](https://www.youtube.com/watch?v=3eRSwQs_UtE) ## Common crash-causers When working with these files, it is especially frustrating to try to track down the source of access violations. Below is a list of issues to check: - Paths are misspelled on any of the files - An XML structure was not properly closed - `animation_def` or `animation_state_machine` are missing from the unit's dependencies list - `animation_def` was not defined in the `object` file - A bone specified in `animation_def` is not actually a bone, or is the root bone and does not exist - An animation was specified in an `emptyloop` state - An animation specified in a state does not exist If none of these solved your issue, read this page carefully again, from top to bottom. ## Appendix A: Lua methods ### Animation State Machine The ASM of an unit can be referenced through the unit's `anim_state_machine()` method. * `ASM:set_global(name, value)`: sets the global to the specified **number** value. * `ASM:set_global_soft(name, value)` * `ASM:get_global(name)`: get the value of the global. * `ASM:set_parameter(state, parameter, value)`: Set the parameter inside the specified state to a **number** value. * `ASM:set_parameter_soft(state, parameter, value)` * `ASM:set_speed(animation_idstring, speed)`: sets the speed of the animation. * `ASM:set_speed_soft(animation_idstring, speed)` * `ASM:get_speed(state)`: get the speed of the state. * `ASM:is_playing(animation_idstring)`: return whether the animation is playing or not. * `ASM:segment_real_time(segment_idstring)`: return the current time of the segment. * `ASM:segment_relative_time(segment_idstring)` * `ASM:segment_muted(segment_idstring)` * `ASM:stop_segment(segment_idstring)` * `ASM:segment_state(segment_idstring)`: get the playing state on the specified segment. * `ASM:segment_state_object(segment_idstring)` * `ASM:config():states()`: return a list of states in the ASM. * `State:name():s()`: return the state name. * `ASM:state_in_group(state)` * `ASM:set_enabled(enabled)` * `ASM:set_animation_time_all_segments(time)` * `ASM:play_raw(animation)` * `ASM:play(animation)` * `ASM:root_blending()` * `ASM:set_root_blending(bool)` * `ASM:instant_blending()` * `ASM:set_instant_blending(bool)` * `ASM:set_callback_object(lua_object)` * `ASM:index_to_state_name(index)` * `ASM:state_name_to_index(state)` * `ASM:enabled_modifiers()` * `ASM:force_modifier(modifier)` * `ASM:allow_modifier(modifier)` * `ASM:forbid_modifier(modifier)` * `ASM:get_modifier(modifier)` * `ASM:set_modifier_blend(modifier, blend)` * `ASM:reset()` To play a ASM state, use the unit's `play_redirect(redirect_name, time_offset)` method. This returns an Idstring identifier for the animation. Alternatively, you can also use the unit's `play_state(state_idstring, time_offset)`. ### Modifiers #### IK IK modifiers can be accessed through `ASM:get_modifier(idstring_modifier_name)`. If the rotation/position type is `script`, they are controllable through: Directly set the target bone's position/rotation: * `IKModifierInstance:set_target_position(vector3)` * `IKModifierInstance:set_target_rotation(rotation)` Set the rotation of the target bone by making one of its axis have the direction of the provided **normalized** vector, taking the bone's position as the point of reference: * `IKModifierInstance:set_target_x(vector3)` * `IKModifierInstance:set_target_y(vector3)` * `IKModifierInstance:set_target_z(vector3)` Set the rotation of the target bone by making one of its axis point towards the provided point in world space: * `IKModifierInstance:set_target_x_look_at(vector3)` * `IKModifierInstance:set_target_y_look_at(vector3)` * `IKModifierInstance:set_target_z_look_at(vector3)` Unknown: * `IKModifierInstance:set_object(?)` * `IKModifierInstance:blend()`