A weapon is a special type of item that a character uses for attacking. When the “Equippable” button is toggled on for an item in the Item Editor, the “Weapon” button will become available. When an equippable item is configured as a weapon, it opens up several additional options which are described in more detail below.
|Type||Determines whether the weapon is a melee weapon or a ranged weapon. Melee weapons can only be used to attack from adjacent tiles, while ranged weapons can be used to attack from a distance.|
|Attack Animation||If set, this will override the character's attack animation and play the specified animation name instead of “attack” (e.g. to play a “throw” animation for a throwing dagger).|
|Ammo/Energy Required||Determines whether or not the weapon requires ammo or energy in order to be used. Refer to the “Consumption Types” table below for a description of each option.|
|Projectile Speed||Determines how fast the weapon's projectile moves, measured in voxels per second. If set to zero, the weapon will hit its target instantly. This setting is only applicable to ranged weapons.|
|Minimum Range||Determines the minimum distance (in tiles) required between the character and target entity in order to use the weapon. A value of 1 indicates that the weapon can be used from adjacent tiles. This setting is only applicable to ranged weapons.|
|Maximum Range||Determines the maximum distance (in tiles) between the character and target entity from which the weapon can be used. This setting is only applicable to ranged weapons.|
|None (Unlimited Use)||Weapon can be used an unlimited number of times (e.g. a sword).|
|None (Single Use)||Weapon is consumed on use (e.g. a throwing dagger). For this type, you would typically want to set the weapon item as stackable so the player can easily carry many at once.|
|Items by ID||Weapon consumes ammo items on use (e.g. a bow or a gun). The required ammo items are defined by one or more item IDs. The items will be consumed from the player's inventory.|
|Items by Tag||Weapon consumes ammo items on use (e.g. a bow or a gun). The required ammo items are defined by one or more item tags. The items will be consumed from the player's inventory.|
In order for a ranged weapon to generate a visual projectile when used (e.g. an arrow, bullet, spinning dagger, etc.), you will need to make use of the “Object Model” item property found below the equippable/weapon settings. If the weapon's projectile speed to set to zero (i.e. instant), you won't need an object model as the weapon will hit its target immediately.
Since projectiles are objects, their “default” animation will be played upon entering the scene, if one exists. This can be used, for example, to make a throwing dagger spin as it moves towards its target. To achieve this, you would simply create a spinning animation for the dagger named “default” and assign its model to the “Object Model” property of your weapon (or ammo item if setting up a ranged weapon that consumes ammo).
To control when and where the visual projectile will specifically appear, you can create an attach point named “projectile” on one frame of the character's attack animation and on the weapon's object model (or ammo item's object model if the weapon consumes ammo).
As there are several components that must be set up properly in order to create a ranged weapon, I've compiled a list of steps you can follow to set one up and to help demonstrate how everything comes together.
1) If you haven't done so already, create a new item in the Item Editor that will represent the weapon. Define a name, description, and image for the item, then add a tag of “weapon” (without the quotes) to the “Tags” field so it can be equipped to the character's “right_hand” slot.
3) Toggle the “Weapon” property to “On”, then select “Ranged” from the “Type” dropdown that appears.
4) If desired, set a custom attack animation to play for the character when using the weapon. For example, “throw” for a throwing dagger or “shoot” for a bow. If one is set, be sure to create an animation for your character with a matching name.
6) Choose the desired consumption type for your weapon from the “Ammo/Energy Required” dropdown. Refer to the “Consumption Types” table above for a description of each option.
7) Assign a model to the “Object Model” property of your weapon. As explained in the “Equipment” section of the attach points documentation, this model will be displayed on the character when equipped, assuming that the proper attach points are setup. If your weapon is unlimited use or single use, this model will also be used for the projectile.
8) If your weapon consumes ammo, you'll need to create at least one ammo item, for example an arrow to use with a bow. You can skip this step if your weapon doesn't consume ammo. As opposed to an unlimited use or single use weapon, a weapon that consumes ammo will use the object assigned to the ammo item for its visual projectile, so be sure to assign a model to the “Object Model” property. Also, you'll most likely want to make this item stackable so the player can carry multiple of them in one slot. Once the ammo item is created, add its item ID to the weapon's “Items by ID” list. If your weapon uses the “Items by Tag” option, be sure to add the appropriate tag (e.g. “arrow”) to the ammo item's list of tags.
9) Optionally, if your weapon generates projectiles, you can control the time and position at which the visual projectile appears. To do so, you will need to create an attach point named “projectile” on both the object for the projectile, and on one frame of the character's attack animation. For example, if the weapon is a throwing dagger you would create a “projectile” attach point on the handle of the dagger, and also one on the throwing hand of the character, specifically on the frame of the “throw” animation where the dagger should be released.