Keys

INTRODUCTION:

I've been seeing questions on this being asked over and over. I'll do my best to answer questions on how to make and use custom items in your maps.
Since we have something to actually use our custom items on, I'll be using a simple array based door system with "useable keys".
I'll start from the basics for some of the newer map makers (print this out and follow along and learn from doing). If you're a bit more advanced,
just download the attached map, it has a simple array based door system that works with custom useable items (the keys).

MAKE A MAP:

Make a simple 64x64 map with rooms separated by 4 doors.

CREATING CUSTOM USEABLE ITEMS:

There are many ways of creating items that will actually run triggers, some people like to use the summon ability,
but ill show you how to do it using the Item Temporary Speed.

We will start by making a custom key, bring up your unit editor (F6), press CTL-N and enter "Iron Key" for the name and pick a silver colored key,
then press "ok." Now we will need to edit your new key so it's useable, make the following changes:
- change "number of charges" to the value of 1
- change "actively used" box checked
- change "dropped when carrier dies" box checked
- change the tooltip to "an Iron Key"
- change the extended tool tip and description to "An Iron Key. Use it near a door"

We need to actually give the key an ability. Double click on "abilities" to bring up a dialog for editing them. Here you will
see the "Edit Unit Value - Ability List" dialog. Click the "Add Ability" button. You will see a pull down menu
that defaults to "Unit"; change that to "Item".

Scroll down on that list and select "Item Temporary Speed Bonus", it's near the bottom of the list. Then press the Ok Button.
You should see the speed bonus ability listed now. Press Ok again.

Repeat this process for 3 more keys: Fire Key, Mine Key, and a Study Key (you can of course call them whatever you like)

MAKING AN ARRAY BASED DOOR SYSTEM:

Before we can use one of our keys, we need something to use them on. Rather than make a set of triggers for each door,
we will use arrays to handle all of them. The concept of array variables can be daunting for some, so ill try to explain what they are.
An array variable is actually a "set" of variables. Picture a street with ten houses down one side, the first house has a street address of 0,
then second house has a street address of 1, the 3rd has 2, and so on to the last house which is 9.
You can "access" each house by their street address.

Using arrays is alot like the "street" example above, but in this case, we are going to address "doors" not houses.
We will also need to know which of the 4 keys opens each door and whether or not the door is already open.

To get started on the door system we need to make a few variables. Open the trigger editor by pressing F4, then open the variable editor by pressing CTL-B.
You should now see a dialog that says "variables" on the top. Press the "New Variable" button. Enter "door" for the variable name,
enter "Destructible" for the variable type, and check the array box to make it an array variable. Then press OK.
Our first array variable is done, now for the other 2.

- Make an array variable of type "item-type" and call it "DoorKey"
- Make an array variable of type "boolean" and call it "DoorOpen"

Ok, now the "street" is done, but now we need another variable to address a specific door and we will also need to know how many doors there are.

- Make an integer variable and call it"DoorIndex", for this variable we don't need an array so be sure the array box is NOT checked.
- Make an integer variable and call it"NumberOfDoors", this variable should, also, NOT be an array.

That should be all of the variables we need to work with this example. Whew.

NOW TO MAKE IT ALL WORK:
It's all-well-and-good to have all of our array variables done, but we need to actually do something with them. Time for triggers.
From the Trigger Editor (F4), make a new category (CTL-G) and name it "Door System". Make a new trigger (CTL-T)
and call it "Initialize Doors", be sure the new trigger is within the "Door System" category, if it's not, just drag it there.
Go ahead and enter the following:

Events: Map Initialization
Condition: None
Actions:
--- Comment: Remember that the first door has the index of 0, so if we have 4 doors, the last door will have index 3. ---
Set NumberOfDoors = 3
--- Comment: For each of these lines, select the door from the map ---
Set Door[0] = Dungeon Gate (Horizontal) 0000
Set Door[1] = Dungeon Gate (Diagonal 2) 0001
Set Door[2] = Dungeon Gate (Horizontal) 0002
Set Door[3] = Dungeon Gate (Diagonal 1) 0003
--- Comment: Now to decide which key opens which door ---
Set DoorKey[0] = Iron Key
Set DoorKey[1] = Fire Key
Set DoorKey[2] = Mine Key
Set DoorKey[3] = Study Key
--- Comment: Now to close all of the doors ---
--- (yes, I know, they are closed by default, but its good to make sure) ---
--- ---
For each (Integer A) from 0 to NumberOfDoors, do (Destructible Doodad - Close Door[(Integer A)])
--- ---
--- Comment: We don't want players to be able to just bash through the doors, make em invulnerable ---
--- ---
For each (Integer A) from 0 to NumberOfDoors, do (Destructible Doodad - Make Door[(Integer A)] Invulnerable)
--- Comment: All doors are closed, lets Set our DoorOpen array to indicate that ---
For each (Integer A) from 0 to NumberOfDoors, do (Set DoorOpen[(Integer A)] = False)


Okay now our map knows all it needs to know about all of our doors. Now we need to make a couple more triggers to open the doors,
one when our custom item (one of the keys) is used and one to refresh the charges on the keys. Lets make the trigger to refresh the charges on the keys first.

When an item is used by the player, one of its charges is used. If when we use the key, we are not standing at the proper door,
its charge will be used, and therefore, the item will be no longer useable. We need a trigger to refresh the charges of the items used.
The problem that arises here is that if the hero is carrying more than one of the type key being used, we dont want to refresh
the wrong one and leave the used one with no charges. So we will refresh all of them. This next trigger uses a programming technique called recursion,
basically it calls itself. I'm not going to go into detail on how this works, but if you enter this trigger in correctly,
it should work fine to refresh all items of the type being used.

We will also need one more variable to keep track of the type of item being used, because we will be removing the item, and we cannot access it once its removed.
Create an item-type variable named "ItemTypeUsed"

Enter this trigger:

Name: Refresh Item Used
Event: None
Condition: None
Actions:
Item - Remove (Item carried by (Hero manipulating item) of type ItemTypeUsed)
--- Comment: A bit of recursion ---
If (((Hero manipulating item) has an item of type ItemTypeUsed) Equal to True) then do (Trigger - Run Refresh Item Used (ignoring conditions)) else do (Do nothing)
Hero - Create ItemTypeUsed and give it to (Hero manipulating item)
Unit - Remove positive buffs from (Hero manipulating item)

The benifits of using recursion is that you can do quite a bit with just 4 lines, the down side is it can be tougher to de-bug. You may want a bit of sound when a door opens, so lets go ahead and make a sound variable. Open the sound editor (F5) and in the box on the left, open the folder named "Sound" then open "Destructibles" then you will see a sound named "CrateDeath1.wav". RIGHT click on CrateDeath1.wav and select "Use Internal Sound." This will create a sound variable. This sound is a 3d sound, you will NOT beable to hear it unless you attach it to an object, so we need to turn off the 3d sound for this variable. Dbl Click it where it is shown in the right hand side of your screen. Uncheck the "3D Sound" box, rename the variable to "DoorOpens", and click OK.

Now to open the doors.

Name: Open Door with Key
Events: A Unit owned by Player 1 (Red) Uses an item
Condition: None
Actions:
Set ItemTypeUsed = (item-type of (item being manipulated))
Set DoorIndex = -1
For each (Integer A) from 0 to NumberOfDoors, do (if (ItemTypeUsed Equal to DoorKey[(Integer A)]) then do (Set DoorIndex = (Integer A)) else do (Do nothing)
If (DoorIndex Not equal to -1) then do (Trigger - Run Refresh Item Used (ignoring conditions)) else do (Do nothing)
If (DoorIndex Equal to -1) then do (Skip remaining actions) else do (Do nothing)
If (DoorOpen[DoorIndex] Equal to True) then do (Skip remaining actions) else do (Do nothing)
If ((Distance between (Position of Door[DoorIndex]) and (Position of (Hero manipulating item))) Greater than or equal to 256) then do (Skip remaining actions) else do (Do nothing)
Item - Remove (Item carried by (Hero manipulating item) of type ItemTypeUsed)
Destructible Doodad - Open Door[DoorIndex]
Set DoorOpen[DoorIndex] = True
Sound - Play DoorOpens

Now to test your map. First place a hero unit and a couple of each of our custom useable items (our new keys) where the hero can pick them up.

Save the map and run it.

Hopefully everything works the first time... it should if I didn't have any typeos in this tutorial and you entered everything correctly.
If it doesn't work try and de-bug it yourself. You can compare it with the map I've attached to see where you (or I) went wrong. The attached map does work.

I'm probably opening up a can of worms with this, but, I will do my best to answer questions that arise and fend off flames.
Yes, im sure there are easier ways to do things. Feel free to use this system in your maps. The item refresh trigger
can also be used to refresh other custom items called from other triggers in your map. I hope this helps.