Creating Items - Dungeons-of-Kathallion/Bane-Of-Wargs GitHub Wiki
Items are the key part of the gameplay. With no items, nothing would be really interesting when playing. There are many different type of times, which are called category, and each of these categories have different required and optional attributes that are defined in the item yaml data.
Items are found in the data/items.yaml file, and are stored by category order. The item category also explicitly tells what is the items for and how to should be used. Some items like weapons or armor pieces can modify the player stats/attributes but other items like utilities can be used to do such actions like displaying the map. So, items are very varied and it'll take some time to learn them all.
You can check the Gameplay Guide for more information about gameplay uses of different items.
Note that you can find further information at the Battle Fights Stats wiki page.
As said sooner, items are classed in categories depending on their use, need or gameplay actions. Depending on the category, yaml data can be a lot different but, each item that are from any category have at least these following attributes in common:
<item id>:
type: <item category(str)>
description: <a short description of the item(str)>
gold: <the value in gold of the item(float)>There are currently 13 different categories of items in the game:
-
Weapons// items that are equipped in the main hand and have damage stats etc. -
Armor Pieces// items that add armor protection when equipped. Can be chestplates, leggings, boots or shields. -
Consumables// items like potions. -
Utilities// items that have special actions like the map. -
Bags// items that increase the player's inventory size. -
Food// items that heal some health. -
Keys// items that unlock new places of the map. -
Notes// items that just display text. -
Maps// items to display an ASCII art. -
Metals// items that are used to upgrade equipment. -
Primary Materials// items that are used to upgrade equipment. -
Misc// random items like bones or wooden sticks.
Each item categories have all 2 attributes in common:
the gold attribute, which defines the price of the item, and the thumbnail attribute, which defines the ASCII art of the item. Here's how the thumbnail attribute should be defined:
[...] # other keys
thumbnail: |
╔════════════════════════════╗
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
║ ║
╚════════════════════════════╝In the box, you'll put the ASCII art with yaml data color codes if you wish. Note that if you don't want to follow the vanilla art charts, you can use any kind of box with any width and height you if want. Note that as map zones, you can also use the thumbnail raw key to save the ASCII art without the yaml data color code. Find a complete guide to items ASCII art here.
There's two main type of weapons: generic weapons and upgrade-able weapons. Upgrade-able weapons often use a special yaml attribute called 'yaml anchors'. We will go trough one by one every attributes that an weapon can have and should have.
display name: <name displayed(str)>This defines the visual in-game name of the weapon.
upgrade tier: <tier(int)>This integer can go up to any number. You'll still need to have this key if your weapon is not upgrade-able, just leave it at 0.
type: "Weapon"This just tells the game it's a weapon.
damage: <damage dealed(int)>This defines the maximum amount of damage this weapon can deal (without taking in count the critical hit stat). The formula using to calculate the random damage while in a battle is:
player_damage = random.randint(1, int(item[player["held item"]]["damage"]))so the damage is randomized from 1 to the damage defined in the weapon dictionary.
defend: <defend stat(int)>This defines the maximum amount of health you can gain when defending in a fight. When defending in a fight, the player's health get added a certain amount of health, defined by this formula:
defend += random.randint(0, int(item[player["held item"]]["defend"])) * player_agilityagility: <agility stat(float)>This is how many agility this item adds. You often see values around .1 to .2 for generic swords, .04 for heavy weapons and .35 for agile and light weapons. The agility defines how much well you can defend and how much well you can dodge an enemy attack or run away. Here is the used formulas:
- defend formula
defend += random.randint(0, int(item[player["held item"]]["defend"])) * player_agility- dodge formula
if round(random.uniform(.30, enemy_agility), 2) > enemy_agility / 1.15:
player_dodged = True- run away formula
if player["agility"] / round(random.uniform(1.10, 1.25), 2) > enemy_agility:
print("You succeeded in running away from your enemy!")
fighting = Falsegold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
critical hit chance: <critical hit chance percentage(float)>This defines the chance of dealing a critical hit to your enemy. This is a value between 0 and 1, making it a percentage.
description: <a clear and concise description(str)>A clear and concise description for the item. Will be displayed on the player's inventory management UI.
for this upgrade: <list of items ids(list)>
- <item id(str)>
[...]This is the list of the required items to upgrade up to the current weapon upgrade tier defined.
Armor pieces are items that are equipped to add protection stats, that lower the damages taken by the player. There is 4 different sub-categories of armor pieces:
- Armor Piece: Chestplate
- Armor Piece: Leggings
- Armor Piece: Boots
- Armor Piece: Shield
Like weapons, armor pieces are upgrade-able and they often use 'yaml templates'. We'll go through every attributes armor pieces can have and should have.
display name: <name displayed(str)>The visual name of the item. Is displayed on the player's inventory management UI.
upgrade tier: <tier(int)>This integer can go up to any number. You'll still need to have this key if your armor piece is not upgrade-able, just leave it at 0.
type: <Armor Piece: <Chestplate | Leggings | Boots | Shield>(str)>This basically defines which equipment slot this armor piece will use.
armor protection: <protection stat(float)>This attributes lower the player's taken damage. Here is the formula used:
damage = random.randint(enemy_min_damage, enemy_max_damage) - player_defend * (
player_armor_protection * round(
random.uniform(.50, .90), 1
)
)agility: <agility stat(float)>This is how many agility this item adds. You often see values around .1 to .2 for generic swords, .04 for heavy weapons and .35 for agile and light weapons. The agility defines how much well you can defend and how much well you can dodge an enemy attack or run away. Here is the used formulas:
- defend formula
defend += random.randint(0, int(item[player["held item"]]["defend"])) * player_agility- dodge formula
if round(random.uniform(.30, enemy_agility), 2) > enemy_agility / 1.15:
player_dodged = True- run away formula
if player["agility"] / round(random.uniform(1.10, 1.25), 2) > enemy_agility:
print("You succeeded in running away from your enemy!")
fighting = Falsegold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
for this upgrade: <list of items ids(list)>
- <item id(str)>
[...]This is the list of the required items to upgrade up to the current weapon upgrade tier defined.
Consumables are items that are consumed to gain health and sometimes, to gain extra max health bonuses and other effects. Check the Gameplay guide to know the effects that exists. Even if consumables are often potions in the vanilla game data, you could also make a cooked beef item be a consumable, even if it should be more in the food category. Note consumables visual name are the dictionary id, unlike weapons and armor pieces. Here are all the attributes that a consumable can have and should have:
type: "Consumable"Tells the game this is a item part of the 'Consumable' category.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
effects:
- effect <digit in logical order starting from 0(int)>:
type: <effect type(str)>
[...] # specific effect keysThis defines each effect this consumable will apply when consumed. Here, you'll define every effect in order with a effect <int> key where can go from 0 to 120 and is in logical order. In this dictionary, you'll enter the type of the effect, and its keys/parameters. You can find every effect types at the Effects Types wiki page.
If you want this consumable to have no effect, put as a value None for the effects key.
description: <a clear and concise description(str)>A clear and concise description of the consumable. Is displayed on the player's inventory management UI.
Utilities are probably the most interesting items to develop. Utilities items are items that defines a special key, that when used in the main game loop, execute your custom scripts, making you able to really interact with the game's engine. Plus, you can ask for the game the yaml data files variables and the player' save variable, letting you really create cool stuff. Unlike other items explanations, here we'll do a step-to-step guide on how to create utilities items.
First, like others items you'll create a new dictionary in the item.yaml file:
type: "Utility:
key: <string of the text to enter to run the script(str)>
script name: <the name of the script you will create later(str)> # use '<name>.py'
gold: <price(float)>
arguments: # not required
- <argument id(str)>Note: you can find the possible arguments at this wiki page. Note that you can also import from your utility script a game's source code class and then use its functions or static variables. If your script doesn't require any argument, don't put the argument key in the item definition. Find a full guide on custom scripting here.
def run(<arguments>):
[...] # here you do all your code
# make the function run
run(<arguments>)You can find an example of use cases here.
Bags are special items that add additional inventory space to the player's inventory. They are basic items but also very important. Here are all the attributes that a bag item can have and should have:
type: "Bag"This tells the game it's a bag item.
inventory slots: <slots(int)>This is how much inventory slots will be added when having this item in the inventory. Note that because of the game engine, the bag itself takes an inventory slot. So if a bag have a key inventory slots of a value of 6, it will actually only add 5 inventory slots, so keep that in mind.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
description: <a clear and concise description(str)>A clear and concise description of the item. Is displayed on the player's inventory management UI.
Food items are crucial to the player, restoring his health for a small cost, compared to consumables. Food items have basically the same attributes as consumables, the only difference being is that food item are not named 'consumables' and that're no effects applied when consuming food items. Here are all the attributes a food item can have and should have:
type: "Food"This tells the game it's a food item
max bonus: <max health addition(int)>This is how much max health the player will gain after eating the item, either from the player's inventory management UI or in a battle. This field is not required.
healing level: <health restoring(int)>This defines how much health will be gained after eating this item. Can go through negatives values (why not?) to 999. When set to 999, it will set the player's health to its max health value.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
description: <a clear and concise description(str)>A clear and concise description of the food. Is displayed on the player's inventory management UI.
Keys are required items to access certain map point, making them crucial to the gameplay. Keys have the most basic definition but at the same time very important. Here are all the attributes a key item can have and should have:
type: "Key"This tells the game it's a key item.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
description: <a clear and concise description(str)>A clear and concise description of the key. Is displayed on the player's inventory management UI.
Notes are useless items, but are used at papers found on the ground, that have text on it. This text in the description of the item, that can be read on the player's inventory management UI. Here are all attributes a note item can have and should have:
type: "Note"This tells the game it's a key item.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
description: <a clear and concise description(str)>A clear and concise description of the note. Is displayed on the player's inventory management UI.
Maps are useful items, that print to the UI a graphical map, that does not represent the map points, but only the representative map. Here are all attributes a map item can have and should have:
type: "Map"This tells the game it's a map item
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
map: <name of file in imgs directory(str)>The name of the ASCII art file, without the .txt at the end, located in the imgs/ directory. In this file you'll put the ASCII art that represents the map. Check the Creating ASCII Art Map wiki page to know what content to put into that file.
description: <a clear and concise description(str)>A clear and concise description of the map. Is displayed on the player's inventory management UI.
Metals are items bought from forges, that are used to upgrade equipment, making them very valuable. Here are all attributes a metal item can have and should have:
type: "Metal"
This tells the game it's a metal item.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
description: <a clear and concise description(str)>A clear and concise description of the metal. Is displayed on the player's inventory management UI.
Primary materials are similar to metals item, the only difference being is they're not metals. The other difference is that primary materials are not bought from forges but more often from blacksmiths or found on enemies. Here are all attributes a primary material item can have and should have:
type: "Primary Material"
This tells the game it's a primary material item.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
description: <a clear and concise description(str)>A clear and concise description of the primary material. Is displayed on the player's inventory management UI.
Misc items are items that don't fit into any categories, like bones or wooden sticks for example. Here are all attributes a misc item can have and should have:
type: "Misc"
This tells the game it's a primary misc item.
gold: <base cost(float)>This is the price in gold of the item. Note that this price vary following the cost value from where you buy/sell it.
description: <a clear and concise description(str)>A clear and concise description of the misc item. Is displayed on the player's inventory management UI.