Official Module System Documentation: Part 05
In Parts 3 and 4, we have learned how to create and equip new troops and party templates. With this background in place, we can now study how to make new items for our troops to use.
Contents |
[edit] 5.1 -- Breakdown of Module_Items
module_items.py begins with a number of constants that are used to govern item modifiers, which adjust the items we see in-game. Bent polearms, chipped swords, heavy axes, they are all created from a tuple in module_items and then given an appropriate item modifier to adjust their stats up or down.
The constants defined here consist of standard item modifiers. The items you find in merchants and in loot will draw their modifiers randomly from these constants. Modifiers that are not listed in an item's modifier constant will not be considered for merchant inventory or battle loot.
For more experienced modders, it is interesting to note that modifiers which aren't listed in the appropriate constant can still be used with the "troop_add_item" operation. For example, longbows usually come only in "plain", "bent" and "cracked" forms; but if we were to add a longbow to the player's inventory with the modifier "balanced" on it, the player will receive a balanced longbow.
After the constants, the list of tuples begins. The first one of interest is the weapon "practice_sword", which will function as a good example.
Example of an item:
["practice_sword","practice_sword", [("practice_sword",0)], itp_type_one_handed_wpn|itp_melee|itp_primary|itp_secondary, itc_longsword, 3,weight(1.5)|spd_rtng(103)|weapon_length(90)|swing_damage(16,blunt)|thrust_damage(10,blunt),imodbits_none],
This is a basic practice weapon, used in Zendar throughout the training and in the arena fights.
[edit] Breakdown of the tuple fields:
1 ) Item id. Used for referencing items in other files. 2 ) Item name. Name of item as it will appear in inventory window 3 ) List of meshes. Each mesh record is a tuple containing the following fields:
3.1) Mesh name. The name of a 3d model in the game or module's resource files. 3.2) Modifier bits that this mesh matches. A list of item modifiers that will use this mesh instead of the default. The first mesh in the list is the default.
4 ) Item flags. 5 ) Item capabilities. This field contains a list of animations that this item can use. 6 ) Item value. The base value in denars. Note, the actual value of the item will be much higher in-game unless the player has a trade skill of 10. 7 ) Item stats. This is where the statistics of the item are defined; weight, abundance, difficulty, armour ratings, etc. 8 ) Modifier bits. Modifiers that can be applied to this item. 9 ) [Optional] Triggers. A list of simple triggers to be associated with this item.
Practice_sword tuple examination:
1 ) Item id = "practice_sword" 2 ) Item name = "practice_sword" 3 ) List of meshes:
3.1) Mesh name = "practice_sword" 3.2) Modifier bits = 0
4 ) Item flags = itp_type_one_handed_wpn|itp_melee|itp_primary|itp_secondary 5 ) Item capabilities = itc_longsword 6 ) Item value = 3 7 ) Item stats = weight(1.5)|spd_rtng(103)|weapon_length(90)|swing_damage(16,blunt)|thrust_damage(10,blunt) 8 ) Modifier bits = imodbits_none 9 ) Triggers = None.
We can now tell all of "practice_sword"'s details from its tuple.
- It uses the mesh "practice_sword" as its default mesh. - It uses item flags that mark it as a one-handed melee weapon. Troops who are equipped with "practice_sword" will consider "practice_sword" when choosing a primary melee weapon from their inventory listing. They will also consider "practice_sword" when choosing a backup (secondary) weapon. (Note: The secondary weapon function is currently nebulous. It's unclear when it's used or if it's used at all. However, melee troops certainly will not switch to different melee weapons during combat.) - It has all the animations defined in the constant itc_longsword, so "practice_sword" is able to be used as a longsword would be. - It weights 1.5 kilogrammes. Its speed rating is 103, its weapon length is 90. It does a base 16 blunt damage while swinging, and a base 10 blunt damage while thrusting. - It uses no item modifiers.
[edit] 5.2 -- Damage Types
As we've observed in the tuple examination, "practice_sword" does blunt damage. Obviously this is because it's a practice weapon, but it provides a good incentive to look into the different damage types available in M&B.
First, there is cut damage. Cut damage represents the slicing action of a sharp blade, such as a sword or an axe. Cut damage gets a bonus against unarmoured or lightly-armoured enemies, but conversely it has a large penalty against heavy armour. Cut damage will kill an enemy if it brings the enemy to 0 hit points.
Next we have blunt damage. Blunt damage represents the bludgeoning effect of weapons without an edge, such as a mace or hammer. Blunt damage gets a 50% bonus against heavy armour, but blunt weapons are often shorter than cutting weapons and they do less damage overall. The largest advantage of blunt damage is that it knocks an enemy unconscious when the enemy is brought to 0 hit points, instead of killing him. Unconscious enemies can be captured and sold into slavery. Charging horses also do blunt damage.
Finally, pierce damage represents the penetrating tip of arrows, crossbow bolts and similar weapons. Pierce damage gets a 50% bonus against heavy armour, but piercing weapons usually do less damage overall in order to balance it with the other damage types. Pierce damage will kill an enemy if it brings the enemy to 0 hit points.
[edit] 5.3 -- Creating An Item
Copy the "practice_sword" tuple and paste it at the bottom of the file, before the closing bracket. Once done, change the name and identifier of this new tuple to "new_mace".
["new_mace","new_mace", [("practice_sword",0)], itp_type_one_handed_wpn|itp_melee|itp_primary|itp_secondary, itc_longsword, 3,weight(1.5)|spd_rtng(103)|weapon_length(90)|swing_damage(16,blunt)|thrust_damage(10,blunt),imodbits_none],
The M&B items system is very flexible; it takes only a few small adjustments to turn a sword into a mace. In the case of "practice_sword", it was already set to do blunt damage. That makes our job even easier.
First, we change the item capabilities of our new mace from itc_longsword to itc_scimitar. This will cause our mace to lose the ability to thrust, because M&B's thrusting animation is not included in the itc_scimitar constant.
["new_mace","new_mace", [("practice_sword",0)], itp_type_one_handed_wpn|itp_melee|itp_primary|itp_secondary, itc_scimitar, 3,weight(1.5)|spd_rtng(103)|weapon_length(90)|swing_damage(16,blunt)|thrust_damage(10,blunt),imodbits_none],
Next, we'll change the item's mesh from "practice_sword" to "mace_pear". This is a mesh that is not used in the Native game, so by doing this we will be giving our new mace a fresh new look.
["new_mace","new_mace", [("mace_pear",0)], itp_type_one_handed_wpn|itp_melee|itp_primary|itp_secondary, itc_scimitar, 3,weight(1.5)|spd_rtng(103)|weapon_length(90)|swing_damage(16,blunt)|thrust_damage(10,blunt),imodbits_mace],
In this example, we have changed the mesh as planned, and also switched the modifier bits from imodbits_none to imodbits_mace. This will allow our new mace to use all the modifiers specified in the constant imodbits_mace at the beginning of the file.
There are only two further changes we need to make to finish up this item. Notably, we're going to increase its swing damage, and we're going to give it an additional item flag.
Observe:
["new_mace","new_mace", [("mace_pear",0)], itp_type_one_handed_wpn|itp_melee|itp_primary|itp_secondary|itp_unique, itc_scimitar, 3,weight(1.5)|spd_rtng(103)|weapon_length(90)|swing_damage(26,blunt)|thrust_damage(10,blunt),imodbits_mace],
As you can see, we have upped the swing damage from 16 to 26, which will make our new mace a good deal more dangerous in a fight. And, more notably, we've added the flag itp_unique to the Flags field. An item with itp_unique cannot be looted via the normal post-battle loot screen. This will keep the player from getting his hands on it too early, because we have plans for this mace.
For our last adjustment, change the item name from "new_mace" to "Geoffrey's_mace". Then, open module_trooops.py and replace the itm_club in Geoffrey's inventory with itm_new_mace.
Save your progress in both files, then click on build_module.bat.
Congratulations! You've made a brand new item and added it to a troop's inventory. The troop in question is a Hero, so he will always have the new mace in his inventory, and he will always use the best weapon in his inventory that he's able to use.
Regulars, on the other hand, will choose their equipment at random from their inventory list. This is why most regulars have a very varied selection -- otherwise they will all look the same.
Now that we know how to create new items, we can take a look at the various different statistics and examine what they all mean.
[edit] 5.4 -- Item Stats
In this segment you will find a comprehensive list of stats and a breakdown of their function. As some stats mean different things for different item types, we have organised the list by item types.
General
abundance -- Percentage value. This stat governs how often the item will appear in merchant inventories and combat loot. 100 is standard; can be more or less than 100 (down to 0).
weight -- Kilogramme value. Defines the weight of the item in kilogrammes.
itp_type_horse
body_armor -- Value. Determines the horse's armour rating and number of hit points. A higher value means more armour and more hit points.
difficulty -- Value. Determines how high the player's Riding skill needs to be to be able to mount this horse.
horse_speed -- Value. The horse's speed on the battle map. Higher values make faster horses.
horse_maneuver -- Value. The horse's manoeuvrability on the battle map.
horse_charge -- Value. Determines how much damage the horse will do when charging infantry, and how much speed the horse will lose during each collision with an infantryman. Higher values will allow horses to do more damage and wade through more infantry.
itp_type_one_handed_wpn
difficulty -- Value. The minimum STR score needed to be able to use this weapon. If a troop does not have greater or equal STR, he will not be able to wield it.
spd_rtng -- Value. The attack speed of the weapon, both swing and thrust.
weapon_length -- Centimetre value. The length of the weapon in centimetres. This stat determines how far the weapon will be able to reach in-game, regardless of the mesh size.
swing_damage -- Value, damage type. The base damage and damage type of the weapon when performing a swing attack.
thrust_damage -- Value, damage type. The base damage and damage type of the weapon when performing a thrust attack.
itp_type_two_handed_wpn
Same as itp_type_one_handed_wpn.
itp_type_polearm
Same as itp_type_one_handed_wpn.
itp_type_arrows
weapon_length -- Centimetre value. The length of the arrow in centimetres.
thrust_damage -- Value, damage type. The amount of damage this type of arrow adds to the bow's base damage, and the damage type.
max_ammo -- Value. The number of arrows in one stack.
itp_type_bolts
Same as itp_type_arrows.
itp_type_shield
difficulty -- Value. The minimum shield skill score needed to be able to use this shield.
hit_points -- Value. The base number of hit points for this shield.
body_armor -- Value. The amount of damage subtracted from every hit to the shield,.
spd_rtng -- Value. The speed with which the shield can be brought up into defensive mode.
weapon_length -- Value. Shield coverage. Higher values allow the shield to cover more body area, offering shield protection from arrows to larger sections of the body.
itp_type_bow
difficulty -- Value. The minimum Power Draw score needed to be able to use this bow. If a troop does not have greater or equal Power Draw, he will not be able to wield it.
spd_rtng -- Value. The bow's reloading speed. IE, how fast a troop will be able to take an arrow from quiver, notch, and draw the bow again. Higher values will mean quicker reload times.
shoot_speed -- Value. The speed at which ammunition from this bow flies through the air. Higher values will mean faster arrows; note, however, that very fast ammunition may clip through nearby enemies without hitting them.
thrust_damage -- Value, damage type. The base damage and damage type inflicted by hits from this bow.
accuracy -- Percentage value. The chance of a shot flying exactly at the troop's aiming point. 100 represents a 100% chance, lower values will greatly decrease the chance of a hit. This is not used on the Native bows and crossbows, but can be added.
itp_type_crossbow
difficulty -- Value. The minimum STR score needed to be able to use this crossbow. If a troop does not have greater or equal STR, he will not be able to use it.
spd_rtng -- Value. The crossbow's reloading speed. IE, how fast a troop will be able to take a bolt from quiver, notch, and pull back the string for firing. Higher values will mean quicker reload times.
shoot_speed -- Value. The speed at which ammunition from this crossbow flies through the air. Higher values will mean faster bolts; note, however, that very fast ammunition may clip through nearby enemies without hitting them.
thrust_damage -- Value, damage type. The base damage and damage type inflicted by hits from this crossbow.
max_ammo -- Value. The number of bolts that can be fired from this crossbow before it must be reloaded.
accuracy -- Percentage value. The chance of a shot flying exactly at the troop's aiming point. 100 represents a 100% chance, lower values will greatly decrease the chance of a hit. This is not used on the Native bows and crossbows, but can be added.
itp_type_thrown
difficulty -- Value. The minimum Power Throw score needed to be able to use this weapon. If a troop does not have greater or equal Power Throw, he will not be able to use it.
spd_rtng -- Value. The reloading rate for this weapon. IE, how fast the next piece of ammunition can be readied for throwing.
shoot_speed -- Value. The speed at which this weapon's ammunition flies through the air.
thrust_damage -- Value, damage type. The base damage and damage type inflicted by hits from this weapon.
max_ammo -- Value. The number of weapons (IE, ammunition) contained in one stack.
weapon_length -- Centimetre value. The weapon's length in centimetres.
itp_type_goods
food_quality The impact a food item will have on party morale. Values above 50 will improve morale while the item is being consumed, lower values will lower morale.
max_ammo The number of consumable parts for this item.
itp_type_head_armor
head_armor -- Value. The amount of damage this piece of armour will prevent to the head of the troop.
body_armor -- Value. The amount of damage this piece of armour will prevent to the body of the troop.
leg_armor -- Value. The amount of damage this piece of armour will prevent to the legs of the troop.
difficulty -- Value. The minimum STR required to wear this piece of armour.
itp_type_body_armor
Same as itp_type_head_armor.
itp_type_foot_armor
Same as itp_type_head_armor.
itp_type_hand_armor
Same as itp_type_head_armor.
itp_type_pistol
difficulty -- Value. The minimum STR score needed to be able to use this pistol.
spd_rtng -- Value. The pistol's reloading speed. IE, how fast a troop will be able to reload the pistol and aim it again.
shoot_speed -- Value. The speed at which ammunition from this pistol flies through the air.
thrust_damage -- Value, damage type. The base damage and damage type inflicted by hits from this pistol.
max_ammo -- Value. The number of bullets that can be fired from this pistol before it must be reloaded.
accuracy -- Percentage value. The chance of a shot flying exactly at the troop's aiming point. 100 represents a 100% chance, lower values will greatly decrease the chance of a hit.
itp_type_musket
Same as itp_type_pistol.
itp_type_bullets
Same as itp_type_arrows.
