Tool, Key, custom used by inventory actions

PLACEHOLDER but fairly complete:

DOES NOT WORK FOR DOORS - use the normal key method

Note, this describes how to trigger a script by using any custom 'tool' on an object in the world so you either need some knowledge of scripting or have one available.

You're probably familiar with how you can set used_by and an entity name on a door to make it open with that key. Well, now you can set used_by and an entity name on any entity, and it will call the script in spawnarg "used_action_script" when it is frobhilighted and used by that inventory item.

But wait, there's more. You can also specify an entity in different ways:

"used_by_inv_name" : specify by inventory name in inv_name spawnarg "used_by_category" : specify by inventory category "used_by_classname" : specify by classname spawnarg or entityDef name, e.g., atdm:playertools_compass

Also, if you have multiple items in the used_by arguments, you can specify different scripts to call for different items. Instead of "used_action_script", add on the specifier to the key name afterwards, like "used_action_script_<specifier> " Where the specifier can be the entity name, inv name, category or classname.

The order it checks for scripts in is this: entity name (used_by) inventory name (used_by_inv_name) classname (used_by_classname) inventory category (used_by_category)

And if it doesn't find one, it executes the general "used_action_script" by default.

For example, putting these spawnargs on a frobable entity you want to be usable by stuff: "used_by" "key_12" "used_by1" "key_13" "used_by_inv_name" "Foo" [NOTE THIS MAY BE REPLACED BY inv_id to avoid translation conflict] "used_by_classname" "atdm:playertools_lantern"

"used_action_script_key_12" "UsedByKey12Script" "used_action_script_atdm:playertools_lantern" "UsedByLanternScript" "used_action_script_Keys" "UsedByGenericKey" "used_action_script" "UsedByGeneric"

These scripts could be in the map's script file, for example. Or they could be globally defined scripts if you want to create a new player tool.

In this example, if you call UsedByKey12Script if you use it with an entity named key_12. You can use it with key_13, and it will notice that the inventory category matches Keys, and call UsedByGenericKey. (NOTE: You don't need to set used_by_category to specify by category if it's already covered by another specifier, in this case entity name). If you use it with the lantern, you will call UsedByLanternScript. Finally, if you use it with an inventory item whose inventory name is "Foo", it will call the default script, UsedByGeneric.

This should help a lot with scripting FMs where you have to use item A on item B. Although a lot of you will probably set up fancy stuff where you have to put a moveable into place with the Grabber instead of using an inventory item, so you won't use this. But that's okay.

Additional:

1. All frobable entities (except doors/locks/handles) have a default used_action_script that triggers their targets. (Just like frobbing something triggers its targets by default). So all you have to do is set a used_by variable and it will trigger its targets when inventory used by that item.

2. Don't change anything about the way you handle doors, locks and handles. Because doors work differently, the used_by_* variables won't work, and the script won't get triggered. Just keep using used_by, and the usual methods to call a script when a door is opened.

Extra examples:

So say I wanted to brighten a light with a magic amulet. I add to the light used_by amulet and used_action_script myscript and brighten the light in myscript.

If I also want a skull ring to darken the light I would add used_by1 amulet and usedby2 skullring. Then used_action_script_amulet myscript_amulet and used_action_script_skullring myscript_skullring.