Item/Effect WML with Base Example Campaign

[Coffee]

After occasionally noticing others having problems with items and events on the forums, speaking to others in-game, and having implemented an item system in a recent campaign (The Great Quest), I thought I'd share what I did with others in a forum post.

Attached is a cut down example campaign (you could put it in the add-ons folder) that adds a random item (from utils/item.cfg) to the first recruit and places an item on the map at (9,5) (in scenarios/Example_scenario1.cfg).

Why is this interesting and different you ask from implementations in other campaigns? Well, because it deals properly with level up events (i.e. leadership adding), adding attacks with item animations, adding traits to units on the fly (such as fearless for drakes only), gives a nice context menu for each object description once a unit has picked it up, and is easy to modify and understand whilst being some advanced WML. To programmers it also shows a useful example of what is essentially MACRO inheritance (where it says extension macro).

The interesting item WML is at the end of utils/items.cfg under the APPLY_ITEM macro. Here's an example of the code for an illuminates giving item:

Code: Select all

{NEW_ITEM _"Light Orb" _"Illuminates" ("items/ball-blue.png~GS()~CS(95,95,95)")
          _"This luminous orb provides light that surrounds the holder, giving them the 'illuminates' ability." (
	{ITEM_EFFECT "new_ability" ([abilities]	{ABILITY_ILLUMINATES} [/abilities])}
) (_ON_PICKUP_AND_POST_ADVANCE) (#extension macro
	{MODIFY_UNIT x,y=$unit.x,$unit.y halo (halo/illuminates-aura.png)}
)}

This macro adds the illuminates aura on level up so that it doesn't disappear (as it does in some other campaigns). It also takes the blue ball image and turns it into a white ball by an image path function. I think it is pretty easy to read and understand.

Another example:

Code: Select all

{NEW_ITEM _"Holy Water" _"Melee arcane, extra damage, arcane resistance" (items/holy-water.png)
          _"This, purest of water changes the attack to arcane type and adds resistance to arcane attacks. It also infuses the melee attack with greater power." (
	{ITEM_EFFECT "attack" (
		range=melee
		set_type=arcane
		increase_damage=25%
	)}
) (_ON_PICKUP_AND_POST_ADVANCE) (#extension macro
	{UNIT 1 ($unit.type) 1 1 (to_variable=temp_base_unit)}
	{ITEM_EFFECT_CHANGE_STATS temp_base_unit resistance arcane -20 less_than 20}
	{CLEAR_VARIABLE temp_base_unit}
)}

This macro adds 25% to melee damage and changes betters the arcane resistance by 20%. You'll notice though that on level up to, say, a lich from dark sorcerer, the base resistance changes. You could just make it 20% better, but if you want to have a limit on the upper and lower defense (say, not to go past 80% defense as I have here in the less_than 20 part), it needs to be recalculated at every level up.

In the scenarios/Example_1.cfg file, the {LOAD_ITEMS} puts the items into memory and sets n_items to the number of items. {APPLY_ITEM <index>} will apply an item (from 0 to n_items-1) to the current $unit.

It is pretty easy to add a new item to this and modify the code to do what ever. I am writing this post in the hope that someone will find this useful.