Melee Weapons (Modding)

Melee weapons are equippable inventory items that can be used to hit things in the world. Right now the process for creating new melee weapons is a bit complicated, but our intention is to improve this whole process with proper tools down the line.

## Creating A Simple Melee Weapon

### Create the Weapon Sprites

The first step is to design the melee weapon's sprite graphics. This is the graphic that you'll hold in your hands with the weapon equipped. The sprite should be saved as a .png image.
The sprite for the wooden sword looks like this:

### Adjust the Weapon Sprite's Canvas For Animations

Once you have your sprite designed, you'll need to adjust the canvas so that the spot you want the player's hand to hold the weapon is at the center of the sprite.

For a sword, where you want the player's hand to grab on to the hilt, the sprite should look something like this (The squares are just there to show the positioning, it should still have a transparent background):

### Create Animations

Now that you have a sprite for the melee weapon, you need to make some animations using a program called Demina. You will need an idle animation and an attack animation, and optionally you can use an alternate attack animation.

* Probably the best way to get started is to edit one of the melee weapons in the Example Mod, such as the Shotel. If you look in the ExampleMod/Items/MeleeWeapons/Shotel/Animations directory, you'll find several sprites and animations. This directory contains the individual sprites used in the animations, as well as the compiled sprite sheet and sprite sheet dictionary files, which must be generated with Demina before the mod can be used.
* If you open the "shotel\_default.anim" file with Demina then you'll find a single frame animation with a pair of arms holding a Shotel, as well as a white circle where the shoulders should be. The white circle is a guide that represents where the melee weapon will be attached to the player in the game, and will not be seen by the player. You can think of the white circle as representing the rest of the player that is not visible in the animation file.
* In order to replace the Shotel's sprite with your new melee weapon's sprite, you'll need to first add the new sprite to the animation. You should first copy your new weapon's sprite to the same directory as the animation, and then, using Demina's navigation bar, use Animation > Add Unassigned Texture to add your new melee weapon sprite. Now, you can click on the shotel's sprite in Demina and use Bone > Next Texture from the navigation bar repeatedly until it has swapped to your new weapon texture. Save that file, and you'll have a "default" animation that you can use to build other animations from.
* Once you have a single frame default animation with all the necessary parts (origin circle, arm bones and melee weapon bones), you can start creating the animations that will actually show up in-game. The idle animation is the animation that will play when you have the weapon equipped but not in use, and you'll also need to make an attack animation. You can take a look at the Example Mod's Shotel animations to see an example of what those animations look like.

#### Keyframe Triggers

* After you have at least an Idle and Attack animation created, you'll need to define when to allow collisions between the melee weapon and creatures in the world. Generally the idea is that we only want collisions to be turned on for weapons during the strong parts of the swing (not during the windup for example), so you need to add some "keyframe triggers" to the attack animation. A "keyframe trigger" is basically a bit of text that gets sent to the game engine when a specific frame of an animation plays. You can add a keyframe trigger to a keyframe by using Demina's navigation bar and going to Keyframe > Set Frame Trigger. You can only have one frame trigger on any given keyframe, and you can only put frame triggers on keyframes (not in between frames).

#### Compiling the Animations

* The final step of creating the animations is to compile them into a format that the game can understand. You do this by opening up Demina, and using File > Pack Animations, which will open up the AnimationPacker utility. First you want to click "Add" and select all of the animations for your melee weapon. Then you need to set the Texture and Dictionary output files. If you're editing an existing Example Mod item such as the Shotel, you can replace the "compiled.png" file and "compiled.tdict" files. Once you've added the animations and defined the output files, you can click build. The AnimationPacker utility doesn't give you any kind of confirmation after you click build, but you should be able to look at the compiled image file to see if it now includes your melee weapon along with the arm sprites. The compiled sprite will probably also still contain the Shotel's sprite if you edited that file, but you can just ignore that, it's fine.

### Create JSON File

Once you have the sprites and animations for your new melee weapon, you'll need to create a JSON file which is used by the game to actually generate the item. This file contains all of the information that defines the item, such as the Name and Description, as well as the paths to the assets used by the item such as the inventory item sprite and animations.

Once again, the best bet here is to probably edit the Example Mod's item\_shotel.json file, which is located in ExampleMod/Items/MeleeWeapons/Shotel.