Release Introducing the Item Options System

[Sephus 203]

Introducing the Item Options System!

 

 

Commit

https://github.com/HerculesWS/Hercules/commit/974222a8d3f189083205bf5d330de04a43226ad3

 

Feature Information

The Item Option System is a feature that was implemented in 2015-02-26 clients, allowing equipments to have up to 5 additional effects similar to cards or enchants. Each equipment is capable of having 5 information bars above the card slot/enchant bar that describes the effect of the option it is infused with.

 

New Script Commands (The following snippet is available in doc/script_commands.txt.)

*getequipisenableopt(<equipment slot>)

This function checks if the equipped item allows the use of bonus options.

Returns 1 if allowed, 0 if not.

---------------------------------------

*getequippedoptioninfo(<info_type>);

This function is to be used with the scripts of contents listed in
db/item_options.conf only.

Returns the value of the current equipment being parsed.
If the equip was not found or the type is invalid, -1 is returned.

---------------------------------------

*getequipoptioninfo(<equip_index>,<slot>,<type>);

Gets the option information of an equipment.

<equipment_index> For a list of equipment indexes see getequipid().
<option_slot> can range from 1 to MAX_ITEM_OPTIONS
<type> can be IT_OPT_INDEX (the ID of the option bonus, @see "Id" or "Name" in db/item_options.conf)       or IT_OPT_VALUE (the value of the bonus script of the equipment, @see "Script" in db_item_options.conf).

returns the value of the slot if exists or -1 for invalid slot, type or slots.

---------------------------------------

*setequipoption(<equip_index>,<slot>,<opt_index>,<value>);

Set an equipment's option index or value for the specified option slot.

<equipment_index> For a list of equipment indexes see getequipid().
<option_slot> can range from 1 to MAX_ITEM_OPTIONS
<type> can be IT_OPT_INDEX (the ID of the option bonus, @see "Id" or "Name" in db/item_options.conf)
<value> The value of the type to be set.

returns 0 if value couldn't be set, 1 on success.

 

 

Release Notes

• This system allows the infusing of equipments with bonus item options.
• This feature is constrained to clients of packet versions greater than or equal to 20150226.
• Item Options and their effects are defined server-side in db/item_options.conf and client side in data/luafiles514/lua files/datainfo/addrandomoptionnametable.lub
• The ID of the option must tally with the correct index of the description provided in the client side file.
• IT_OPT_* keys and MAX_ITEM_OPTIONS macro are also exported from the source as constants.
• If you wish to disable item options for certain (equipment) items, an additional flag `disable_options` has been added to the item sql tables, and as `DisableOptions: true/false (boolean, defaults to false !!for equipments only!!)` to the item_db.conf files.
• Documentation is provided for script commands.
• If upgrading, don't forget to run the sql upgrade files!

Credits

A big thanks to all the reviewers that helped make the code closer to perfection. -

Emistry, dastgir, MishimaHaruna, Jedzkie, Ridley8819, Asheraf, 4144.

 

Style and Script Fixes by Asheraf (https://github.com/Asheraf)
Initial design Idea in rAthena commit.

[IndieRO 33]

awasome

[Klutz 2]

Amazing! 

[Legend 43]

Thank you so much Herc devs

[fiction 14]

Thank you !

[tedexx 7]

Awesome! Great work.

[tedexx 7]

Wouldn't be

 

setequipoption(<equip_index>,<opt_index>,<slot>,<value>);

 

Instead of

 

setequipoption(<equip_index>,<slot>,<opt_index>,<value>);

 

?

 

The Item Option NPC released has the variables inverted in the method call too.

 

 

Also, I found a possible exploit:

Using the NPC to put options on an item, if you put an option the NPC will unequip the item, but if the item has options values already, the bonuses will stay with the character even without the equipment.

Removing the equipment manually removes the bonus, its just the "autoremove" from setequipoption that doesn't.

Edited April 11, 2017 by tedexx

[Sephus 203]

Wouldn't be

 

setequipoption(<equip_index>,<opt_index>,<slot>,<value>);

 

Instead of

 

setequipoption(<equip_index>,<slot>,<opt_index>,<value>);

 

?

 

The Item Option NPC released has the variables inverted in the method call too.

Yes, this will be fixed soon. The correct order is setequipoption(<equip_index>,<slot>,<opt_index>,<value>);

 

Edit: Fixed in the latest commit.

 

 

Also, I found a possible exploit:

Using the NPC to put options on an item, if you put an option the NPC will unequip the item, but if the item has options values already, the bonuses will stay with the character even without the equipment.

Removing the equipment manually removes the bonus, its just the "autoremove" from setequipoption that doesn't.

Addressed in PR#1673 Thank you for the report.

[GmOcean 92]

OMG!! Finally an official system to do what I've created through script. Hmm, may pop back in just to release something using this in the future.

[jupeto 3]

AWESOME ADDITION!!!

 

 

I'm trying to add a custom option

 

[EnumVAR.VAR_CUSTOMMAXHP[1]] = "Custom MaxHP +%d"

 

but an error comes up after starting the client

 

attempt to index field '?' (a nil value)

 

 

    [EnumVAR.MDAMAGE_SIZE_SMALL_TARGET[1]] = "Magical damage against Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_TARGET[1]] = "Magical damage against Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_TARGET[1]] = "Magical damage against Large size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_SMALL_USER[1]] = "Magical resistance Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_USER[1]] = "Magical resistance Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_USER[1]] = "Magical resistance Large size monster +%d%%",    [EnumVAR.VAR_CUSTOMMAXHP[1]] = "Custom MaxHP +%d",    [EnumVAR.EnumVAR_LAST[1]] = "END"}

 

Also, I don't see any command to remove specific item option.

Edited April 15, 2017 by jupeto

[Sephus 203]

 

 

    [EnumVAR.MDAMAGE_SIZE_SMALL_TARGET[1]] = "Magical damage against Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_TARGET[1]] = "Magical damage against Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_TARGET[1]] = "Magical damage against Large size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_SMALL_USER[1]] = "Magical resistance Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_USER[1]] = "Magical resistance Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_USER[1]] = "Magical resistance Large size monster +%d%%",    [EnumVAR.VAR_CUSTOMMAXHP[1]] = "Custom MaxHP +%d",    [EnumVAR.EnumVAR_LAST[1]] = "END"}

 

Also, I don't see any command to remove specific item option.

 

 

This would be *setequipoption(<equip_index>,<slot>,0,0);

[jupeto 3]

 

 

    [EnumVAR.MDAMAGE_SIZE_SMALL_TARGET[1]] = "Magical damage against Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_TARGET[1]] = "Magical damage against Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_TARGET[1]] = "Magical damage against Large size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_SMALL_USER[1]] = "Magical resistance Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_USER[1]] = "Magical resistance Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_USER[1]] = "Magical resistance Large size monster +%d%%",    [EnumVAR.VAR_CUSTOMMAXHP[1]] = "Custom MaxHP +%d",    [EnumVAR.EnumVAR_LAST[1]] = "END"}

 

Also, I don't see any command to remove specific item option.

 

This would be *setequipoption(<equip_index>,<slot>,0,0);

 

Already tried that but the console says

 

[Error]: buildin_setequipoption: Option index 0 does not exist!

[Sephus 203]

 

 

 

    [EnumVAR.MDAMAGE_SIZE_SMALL_TARGET[1]] = "Magical damage against Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_TARGET[1]] = "Magical damage against Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_TARGET[1]] = "Magical damage against Large size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_SMALL_USER[1]] = "Magical resistance Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_USER[1]] = "Magical resistance Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_USER[1]] = "Magical resistance Large size monster +%d%%",    [EnumVAR.VAR_CUSTOMMAXHP[1]] = "Custom MaxHP +%d",    [EnumVAR.EnumVAR_LAST[1]] = "END"}

 

Also, I don't see any command to remove specific item option.

 

This would be *setequipoption(<equip_index>,<slot>,0,0);

 

Already tried that but the console says

 

[Error]: buildin_setequipoption: Option index 0 does not exist!

Ah right, then there needs to be a script command for its removal.

[jupeto 3]

 

 

 

 

    [EnumVAR.MDAMAGE_SIZE_SMALL_TARGET[1]] = "Magical damage against Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_TARGET[1]] = "Magical damage against Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_TARGET[1]] = "Magical damage against Large size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_SMALL_USER[1]] = "Magical resistance Small size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_MIDIUM_USER[1]] = "Magical resistance Medium size monster +%d%%",    [EnumVAR.MDAMAGE_SIZE_LARGE_USER[1]] = "Magical resistance Large size monster +%d%%",    [EnumVAR.VAR_CUSTOMMAXHP[1]] = "Custom MaxHP +%d",    [EnumVAR.EnumVAR_LAST[1]] = "END"}

 

Also, I don't see any command to remove specific item option.

 

This would be *setequipoption(<equip_index>,<slot>,0,0);

 

Already tried that but the console says

 

[Error]: buildin_setequipoption: Option index 0 does not exist!

Ah right, then there needs to be a script command for its removal.

Yah, hopefully I'm trying to create a new script command for that...

 

Also, can you please help me create a new set of options, both client and server side

 

[EDIT]

 

I successfully added a remove option command, still not sure if it's the best way to do it LOL... I managed to add, remove option with this...

 

ALSO... fixed the (I think a bug) where the equipment is not forcefully equipped to the character after calculating the new stats by storing the current equipped item id of the user in a variable (eid) and use that variable to force equip (pc->equipitem(sd, i, eid);) the item

 

/**
 * Remove an equipment's option value.
 * *removeequipoption(<equip_index>,<slot>);
 *
 * @param equip_index     as the inventory index of the equipment.
 * @param slot            as the slot of the item option (1 to MAX_ITEM_OPTIONS)
 * @return 0 on failure, 1 on success.
 */
BUILDIN(removeequipoption)
{
    int equip_index = script_getnum(st, 2);
    int slot = script_getnum(st, 3);
    int i = -1;
    int eid = 0;

    struct map_session_data *sd = script->rid2sd(st);

    if (sd == NULL) {
        script_pushint(st, 0);
        ShowError("buildin_removeequipoption: Player not attached!\n");
        return false;
    }

    if (slot <= 0 || slot > MAX_ITEM_OPTIONS) {
        script_pushint(st, 0);
        ShowError("buildin_removeequipoption: Invalid option index %d (Min: 1, Max: %d) provided.\n", slot, MAX_ITEM_OPTIONS);
        return false;
    }

    if (equip_index > 0 && equip_index <= ARRAYLENGTH(script->equip)) {
        if ((i = pc->checkequip(sd, script->equip[equip_index - 1])) == -1) {
            ShowError("buildin_setequipoptioninfo: No equipment is equipped in the given index %d.\n", equip_index);
            script_pushint(st, 0);
            return false;
        }
    } else {
        ShowError("buildin_removeequipoptioninfo: Invalid equipment index %d provided.\n", equip_index);
        script_pushint(st, 0);
        return false;
    }

    if (sd->status.inventory[i].nameid != 0) {
        
        eid = sd->status.inventory[i].equip; // Store the current equipped item id to a variable to use for equiping again after calculating new stats
        
        /* Add Option Index */
        sd->status.inventory[i].option[slot-1].index = 0;
        /* Add Option Value */
        sd->status.inventory[i].option[slot-1].value = 0;

        /* Unequip and simulate deletion of the item. */
        pc->unequipitem(sd, i, PCUNEQUIPITEM_FORCE); // status calc will happen in pc->equipitem() below
        clif->refine(sd->fd, 0, i, sd->status.inventory[i].refine); // notify client of a refine.
        clif->delitem(sd, i, 1, DELITEM_MATERIALCHANGE); // notify client to simulate item deletion.
        /* Log deletion of the item. */
        logs->pick_pc(sd, LOG_TYPE_SCRIPT, -1, &sd->status.inventory[i],sd->inventory_data[i]);
        /* Equip and simulate addition of the item. */
        clif->additem(sd, i, 1, 0); // notify client to simulate item addition.
        /* Log addition of the item. */
        logs->pick_pc(sd, LOG_TYPE_SCRIPT, 1, &sd->status.inventory[i], sd->inventory_data[i]);
        pc->equipitem(sd, i, eid); // force equip the item at the original position.
        clif->misceffect(&sd->bl, 2); // show effect
    }

    script_pushint(st, 1);

    return true;

}


BUILDIN_DEF(removeequipoption, "ii"),

Edited April 16, 2017 by jupeto

[Like it~* 15]

As you might imagine, Smoke is always involved in big, cool projects. I would like to congratulate you and thank you on behalf of the whole community.

 

However, I do not see so many great utilities in this ... I do not know if it is due to the difficulty of understanding the language, or because the text has not been clarified, but I have not really seen it. (Please do not get me wrong, I'm just curious)

 

Is this system official?

Is there any utility besides not having to create custom cards to give players bonuses?

 

I'm sorry I looked ignorant, but I'm just curious.

[raPalooza~ 102]

Are we also getting an 
"getitem3"/"makeitem3" ? This would be awesome to have too. ;D

Edited April 24, 2017 by raPalooza~

[bWolfie 139]

 

As you might imagine, Smoke is always involved in big, cool projects. I would like to congratulate you and thank you on behalf of the whole community.

 

However, I do not see so many great utilities in this ... I do not know if it is due to the difficulty of understanding the language, or because the text has not been clarified, but I have not really seen it. (Please do not get me wrong, I'm just curious)

 

Is this system official?

Is there any utility besides not having to create custom cards to give players bonuses?

 

I'm sorry I looked ignorant, but I'm just curious.

 

i guess it is a different way of displaying flavor text and equipment bonuses

[Sephus 203]

 

As you might imagine, Smoke is always involved in big, cool projects. I would like to congratulate you and thank you on behalf of the whole community.

 

However, I do not see so many great utilities in this ... I do not know if it is due to the difficulty of understanding the language, or because the text has not been clarified, but I have not really seen it. (Please do not get me wrong, I'm just curious)

 

Is this system official?

Is there any utility besides not having to create custom cards to give players bonuses?

 

I'm sorry I looked ignorant, but I'm just curious.

 

This is an official system yes.

This doesn't have anything to do with creating custom cards.

 

This system makes it possible to do things such as -

1. creating unique equipments in the game with unique stats.
2. creating dynamic equipments with options. (possibly with an equipment levelling system)
3. if one is lazy, not having to put a description in the item and providing it with desired stats through an npc?

 

The use of it ultimately depends on one's creative capabilities.

[Like it~* 15]

 

 

As you might imagine, Smoke is always involved in big, cool projects. I would like to congratulate you and thank you on behalf of the whole community.

 

However, I do not see so many great utilities in this ... I do not know if it is due to the difficulty of understanding the language, or because the text has not been clarified, but I have not really seen it. (Please do not get me wrong, I'm just curious)

 

Is this system official?

Is there any utility besides not having to create custom cards to give players bonuses?

 

I'm sorry I looked ignorant, but I'm just curious.

 

i guess it is a different way of displaying flavor text and equipment bonuses

 

 

 

 

As you might imagine, Smoke is always involved in big, cool projects. I would like to congratulate you and thank you on behalf of the whole community.

 

However, I do not see so many great utilities in this ... I do not know if it is due to the difficulty of understanding the language, or because the text has not been clarified, but I have not really seen it. (Please do not get me wrong, I'm just curious)

 

Is this system official?

Is there any utility besides not having to create custom cards to give players bonuses?

 

I'm sorry I looked ignorant, but I'm just curious.

 

This is an official system yes.

This doesn't have anything to do with creating custom cards.

 

This system makes it possible to do things such as -

1. creating unique equipments in the game with unique stats.
2. creating dynamic equipments with options. (possibly with an equipment levelling system)
3. if one is lazy, not having to put a description in the item and providing it with desired stats through an npc?

 

The use of it ultimately depends on one's creative capabilities.

 

Thank you very much for clarifying my doubts. What I meant by custom cards is that bonuses could be given by creating custom cards too, you know?

[Heph 0]

Wow.

[Dduwsmitt 4]

LONG LIVE HERCULES EMULATOR!!! 

[Aeromesi 180]

Any news on makeitem3/getitem3/delitem3?

[Rebel 23]

So how can we remove an option on specific slot?