I've just finished reworking the item buff code I started ages ago which was fundamentally flawed. It's now ready for testing so I'll get to work on committing it to trunk/dev soon.

The new system follows a system similar to fix_player(). When an item is buffed, an object of type 'BUFF_FORCE' is added to its inventory. The name attribute is a unique identifier of that buff, like "tower_bebeniss_armour_bless". If a BUFF_FORCE with that name is already inside that item, it'll see if that buff can be applied more than once. The BUFF_FORCE's carrying attribute specifies how many times that buff can be applied to the same item. The BUFF_FORCE's nrof attribute specifies how many times that buff has been applied to that item. The item's max_buffs attribute specifies how many times that item can be buffed. If it's -1, it can't be buffed. If it's 0, then it will use the item's condition to determine how many times it can be buffed. An item without max_buffs specified will have a maximum of (88 - condition) / 2.

If this is the item's first time being buffed (or all its buffs were removed and now it's being buffed again) it will create a copy of the original form of the item and store it in the item's original attribute. The item is reverted to its original form before it is saved (in a player or on a map) and when it is reloaded it will be re-buffed.

When fix_buff_stats() is called during the buffing or when the item is being loaded, it is reverted to its original, unbuffed form. Then it loops through each buff and adds the buffable stats to the item.

The buff system is meant to be easily useable via Lua (quest reward buffs) or via server code (trade skills).

Shared constants

The following are bitflags so that multiple reasons for failure can be given. Because they are bitflags, Lua doesn't natively support these. However, bitmasks.lua (which is wrongly-named and should be bitflags.lua) enables a simple system for them. Obviously the server doesn't use the "game" class so ignore that part.

game.BUFF_ADD_SUCCESS = 1 - Nothing went wrong, buff applied successfully.
game.BUFF_ADD_EXISTS = 2 - The buff already exists, although that doesn't mean failure.
game.BUFF_ADD_LIMITED = 4 - The buff already exists, AND it's reached its limit on that item.
game.BUFF_ADD_MAX_EXCEEDED = 8 - The item already has received too many buffs.
game.BUFF_ADD_BAD_PARAMS = 16 - The item object or the buff object is NULL.
game.BUFF_ADD_NO_INSERT = 32 - Something went wrong in insert_ob_in_ob

Server code functions

void revert_buff_stats(object *item)
Changes an item back to its unbuffed state so that its buff effects can be recalculated or it can be saved.

void fix_buff_stats(object *item)
Applies the effects of all BUFF_FORCES inside an item to that item.

object *check_buff_exists(object *item, const char *name)
Searches an item to see if a buff with the specified name exists.
Returns: The BUFF_FORCE of that object or NULL if it does not exist.

int add_item_buff(object *item, object *buff, short just_checking)
Adds a buff to an item. If just_checking is non-zero/true then the buff won't actually be applied, but the function will simulate that buff being applied.
Returns: A flag containing one or more BUFF_ADD_* constants.

int remove_item_buff(object *item, char *name, uint32 nrof)
Removes, or decreases the nrof, the buff with the specified name.
Returns: A flag containing one or more BUFF_ADD_* constants.

Lua code functions

object:AddBuff(buffname, buffstring)

Parameter types:
buffname: string (required)
buffstring: string (required)

Return type: number

Creates a force with specified stats that is added to the object.
The stats of that force are then added to the object. buffstring
should be an arch definition string, excluding the arch, name,
and end attributes.

It's a wrapper for add_item_buff and returns the same values.

object:CheckBuff(buffname)

Parameter types:
buffname: string (required)

Return type: number

Check if this buff can be added. It goes through the same process
as AddBuff but doesn't modify the item at all.

object:RemoveBuff(buffname, nrof)

Parameter types:
buffname: string (required)
nrof: integer (optional)

Return type: number

Removes the specified amount of a buff. Nrof 0 means remove all.

Nrof should be fine - the buff forces are essentially stackable objects like coins. Although I guess being able to apply them might cause issues. The thought behind nrof was so that I could use decrease_ob() or whatever it's called. I can change it, though.

hp/maxhp are no good since those are buffable stats (i.e. buff an armour to give the player more HP). food seems like it's used too much as well, i.e. wands use it to track charges and a buff might give a wand more charges. It looks like last_heal and last_sp are safe, though. They have no special effects on all objects or on forces in particular, except specific forces (diseases). So I guess I'll use them instead.

A note to players: This feature sounds pretty cool but you really won't notice much. Once it hits Main after I'm confident it's bug-free, there will only be one noticeable change - the ToB quest's blessings will be fixed. However, this feature creates opportunities for mappers to make more rewarding quest items, allows coders to make tradeskills (the code for which exists already on my HD but isn't quite ready) and other forms of enhancements. These enhancements have always been possible but are now much easier to keep track of or limit.

Aha! Very clever of you. No, only the buffED item uses that. Now that I think of it, that'd be perfect for use in the buff force. And it makes me feel better about adding object attributes that are hardly used.

I've just committed this code to the trunk. Next I have to update the scripts (smith's cat-slaying quest and the ToB quest) to use the system. Then I'll probably make a map to test the features more fully. I also would like mappers to make a few basic scripts to test the system out. It doesn't need to be a huge, elaborate quest but it should test whatever features you want the buff system to have. I still have a little bit more documentation to write, more on that later.

However, I know there may be some testing issues on Dev. I was working on a fairly outdated copy of the trunk server and when I tested it on the HEAD server I noticed some issues. For example, I recall that a player's stats weren't being updated if their gear was buffed, so I added a fix_player() call and it worked again. On the latest version, however, it doesn't. Also, MW/MM/SAs who drop buffed items will notice that the BUFF_FORCEs inside the item will linger in their inventory - this is a visual bug and can be fixed by re-logging.

EDIT: Also, please test buffed items in map-loading conditions. For example, leave an item on an instanced or unique map for a while (until the map is unloaded -- the fastest way to do this is just to reboot the server, although non-persistent instances like PR will delete the item if this happens), come back, and see if it's still there AND it is still buffed. Also, try buffing an item with one buff, dropping it in your apartment, leaving, rebooting, grabbing it, and buffing it with another. Make sure the stats are as they should be.

I'm trying to use it to work with a new quest.

Do you have any examples, because I think I just about understand but can't get it to work and want to see what I'm doing wrong?

There isn't a copy of the TOB quest on mapwiz?

/unofficial/torchwood/tower/scripts