Item Adding

This wiki page will show how to add in new items to the game. It will start by showing the bare essentials and then discuss how to add features to items that are unessential to make the item functional, but should still be added.

Configuration file

The first thing you should make is the configuration file. The configuration file is a json file containing settings for the item. If have not yet done so, it is recommended to read this short Wiki page to get started on writing JSON configurations. Here is a table of the possible settings:

Name	Data Type	Default Value	Description
iconSize	integer	16	The size (width and height) of the icon used for this item.
maxStackSize	integer	1	How many can be stacked in one inventory slot.
durability	integer	1	The durability of the item. Usually only applicable for usable items such as weapons and potions.
equipType	integer	-1	The equip type of an item. Here are the possible values: -1 => Not equipable 0 => Boots 1 => Pants 2 => Shirt 3 => Gloves 4 => Shoulder Pads 5 => Body (Body is already configured so this should not be used) 6 => Face 7 => Hair 8 => Hat 9 => Usables (any item with a use animation including weapons and potions)
buff	boolean	false	Whether the item can be put in a buff slot.
ammo	boolean	false	Whether the item is used as ammunition for a weapon. Also determines whether it can go in an ammo slot.
consumable	boolean	false	Whether the item is a one-time-use consumable that can go in a consumable slot. Perfect for potions.
material	boolean	false	Whether the item is a material that can be used to craft.
numOfStyles	integer	1	Specifies the number of styles this item type has.
sounds	String[][]	Empty array	Used to specify the sound effects for an item for each use type of each style.
useAnimData	ItemUseAnimationData[]	Empty array	Definitions for each use animation. Will be discussed further below.
Combat Stats
knockback	integer	0	How many pixels entities will be knocked back when hit by this weapon.
minDamage	integer	0	Minimum damage this item can do, before considering critical hits..
maxDamage	integer	0	Maximum damage this item can do, before considering critical hits.
defense	integer	0	Defense this item adds to the player.
damageMultiplier	number	1	How much this item multiplies the overall damage output of the player.
defenseMultiplier	number	1	How much this item multiplies the overall defense of the player.
speedMultiplier	number	1	Affects how quick the player can travel.
critMultiplier	number	1	How much the damage will be multiplied by if a critical hit happens.
critChance	integer	0	Chance from 0-100 (representing a percentage) of getting a critical hit.
hitRange	integer	8	Hit range of the weapon in pixels.

Here is an example of a weapon configuration with an item id of iron_sword.

{
	iconSize: 46,
	durability: 500,
	equipType: 9,
	numOfStyles: 1,
	useAnimData: [
		{timings:[0.08, 0.08, 0.08, 0.04]}
	],
	knockback: 30,
	minDamage: 88,
	maxDamage: 104,
	critMultiplier: 1.25,
	critChance: 25,
	hitRange: 36,
	sounds: [
		["actions/hit"],
	]
}

Naming the file

When putting the configuration file in the game, you must follow a certain pattern. Continuing with our Iron Sword example, we would name the configuration file iron_sword.json. Simply replace spaces with underscores and make sure there are no caps. Also add .json at the end.

When you are done, save the configuration file to core/assets/shared/items/my_item_id.json.

Adding it to the code

The next thing you need to do it add it to the game's code. You will need to do this both on the server and the client. Here are the 2 files you need to edit.

ArchipeloClient/core/src/net/hollowbit/archipeloclient/items/ItemType.java ArchipeloServer/src/net/hollowbit/archipeloserver/items/ItemType.java

In each file you will see a list of all the currently added item with their IDs in all caps. To add yours new item, just add it to that list. Please use all caps to keep consistency.

You may notice that some items have a more complicated definition. This will be discussed later when we cover usable items.

Icons

So, the item is in the game now, but there is no icon for it. Doing this is very simple. Simply add a folder in the core/assets/items/ folder, named after the item id.

In this folder you can place an icon.png file that will be loaded by the game. Make sure that the icon size is the same as specified in the configuration. You may have multiple icons in this one file, for each style of the items, as specified in the configuration as "numOfStyles". Simply put each icon in order of style id horizontally.

Names and descriptions

If you give yourself the item in game, you will notice the name and description of the item will be something like "KEY NOT FOUND". This is because the item's name and description were not defined in the language files of teh selected language.

If you are adding a new item, just edit the english language file under core/assets/languages/english/. They are called item_names.json and item_descs.json.

To add the name, just add an entry in item_names.json with the key as the item id and the value as the name in english, just like the ones already configured. This is the same for the description in the item_descs.json file.

Conclusion (kind of)

This is good enough for a lot of items, basically all the ones where "equipType" is set to -1. But if the item is equipable or usable, you will want to configure the following.

Wearables

This is basically anything with an "equipType" from 0-8. This is for boots, pants, shirts, gloves, hair, faces, shoulder pads and hats.

For these, you will need to create 4, 8 directional animations. These are the roll, thrust, use and walk animations. All other in-game animations are derived off these (ex: sprint is walk, but sped up). This wiki page will not show how to make these animations. Just keep in mind that all frames should be 90x90 pixels in size. Also, when making new wearables, use the player template. It will save you a lot of trouble.

To add these animations to the game, just need to put them in the core/assets/items/my_item_id/ folder. Simply call the animations files roll_0.png, thrust_0.png, use_0.png and walk_0.png.

If the item has multiple styles, as configured by the "numOfStyles" property, add them in the same way but change the end number from "0" to the corresponding style id.

That's basically all that is required.

Usables

Usables are simple to add in, as long as they do not require any special mechanics that are not already implemented. If you feel comfortable adding new mechanics, go ahead, if not, ask Nate for help.

As mentionned previously, you need to add a new property in the 2 ItemType.java files. This is known as the UseType. This basically handles the mechanics of the item and which animations and effects will be played depending on what controls the player used. Simply add an appropriate UseType, just like the other items ask for. Some UseTypes will ask for extra properties, just give them the settings you want for your item.

In the item configuration files, you may have noticed a property called "useAnimData". This is an array of definitions for each of a usable items use animations. It also use json. Look at other items to see how they are configured. Here are the properties:

Name	Data Type	Default Value	Description
canEndEarly	boolean	false	Whether the player can end this animation early. Can be used by items such as bows where the player can release early to shoot a less powerful shot.
thrust	boolean	false	Whether an item should use the thrust animation. Thrust will cause the player to be unable to move until the animation is either finished or canceled. Setting this to false will make the item use the "use" animation. Thrust is only recommended for "heavy" weapons such as hammers.
stick	boolean	false	This determines whether the player may remain in the use animation, if the attack button is still held down. This can be useful for when charged bows are just being held down. This will cause it to stick on the last frame.
One or the other, not both:
timings	number[]	null	The specific time that each frame will be rendered for. This is an array so it must have the same length as the number of frames in the animation. Do not specify "runtime" if you are using this.
runtime	number	0	How long the animation will last for. This is to be used as an alternative to "timings" where each frame should be displayed for the same amount of time.

That's all the settings. Just make sure that you either specify a "timings" property or a "runtime" property, but not both since they provide different functionality.

To add the usable item art, add it in the core/assets/items/my_item_id/ folder and call it use_0_0.png.

The first number represents the style id as configured by "numOfStyles". If the item has multiple styles, just change that number.

The second number represents the use animation id. Items can have multiple use animations that can be played by the UseType. Like with the styles, just adjust that number. The amount of use animations should correspond to the amount of animations you configured in "useAnimaData".

Conclusion

That is a complete guide on how to add items. If you have more questions, just ask Nate.