Scripting Help - Creating Hotkeys - Destruct Target

Hotkeys are fairly simple to create, they just need to be registered in the game and attached to a script. These allow you to assign keys to scripts, which allows easy running of scripts without having to use a command slot or manually run the script via the command console.

For this example it will be a very simple script caled Destruct Target, which will destroy the currently targetted object.


Stage 1 - Creating Hotkey Script

The first thing to do is create a script, this script will be the script called when the hotkey is activated.

Hotkey scripts are always run as global scripts, so the [THIS] pointer will not work as its not run on an object, if you wish to use it on the current players ship, then use the [PLAYERSHIP] pointer.

The first command is to get the targetted object, the command is <RetVar/IF> get player tracking aim, this is found in the Fly command menu.

Tracking Aim

It doesn't have any arguments, just a return value, set the return value as a varible of your choise, like target.


Next we need to test if the target is valid, we do this by checking if the object $target exists. If the player has no target it will return null. Use the command "exists" found in the General Object Commands Menu.


Set the first value to "Skip If" so it will skip the next statement if the object exists.

Skip If

Finally, set the Argument to the target object, $target. This will then check if the returned object exists, if it doesn't it will perform the command below the statement, this is where we leave the script.

Skip Target

In the Script Calls commands submenu in the General Commands menu you will find a command to return.


Then select the argument as "null" as we dont need to return anything.


This command will leave the script, so any more commands below will not be executed. If you called this script from another, the return varible from the call script command will be what ever value you set here, in this case it will equal "null".

Null Command

Now we can carry on with the rest of the script. The current script will check if the players aim is valid otherwise it will exit. Next we use the destruct target command, this is found in the General Object Commands menu.

Destruct Target

And the first argument is the object to run the command on, in this case we want to use the object in the varible $target.

Destruct Target

The final argument is for the Explosion, this is a True or False value. Setting it to [TRUE] will mean no explosion is played when the command is run, the object will just disappear. Setting it to [FALSE] will show the explosion if you are close. It runs quicker without any explosion as it doesn't have to compute and render the explosion frames. True and False are found in the constants menu.


Select which one you prefer, for this example, im choosing TRUE.


Stage 2 - Registering a Hotkey

To use a hotkey in game, you need to first tell the game that you want to create a new hotkey and assign a script that should be run when the user press the hotkey. This is very simple and can be done in a single command.

For this example, its just going to be another script that you manually run to register the hotkey to keep things simple. For automatic hotkey registering check later stages of this guide.

So, first of all create a new script, this first and only command to add is the register hotkey command, which is found in the General Commands menu.

Register Hotkey

This command has a return value, and this is the ID the key has been registered in. This will be explained in later stages, for now jsut choose a varible name for it like key.


The next value is the text string that will be displayed in the controls options to identify what the hotkey does, set this to a string and enter something like "Destruct Targetted Object"

Call Script

The final command is the call script, this is the script you want to run when the hotkey is triggered. This is the script you made previously in Stage 1. When selecting you will get a display of all available scripts.


Thats the only command you need for this basic script, when you manually run it you will then be able to use the hotkey.


Note, that when you register a hotkey it will be stored in your save game, if you register it again then you will get multiple entries of the same key showing up. This makes this method not sutible for using in a setup script that will be run each time you load a game. For this, check later stages.


Stage 3 - Using the Hotkey

Once you have ran the script to register the hotkey, it should be available to be asssigned a key. To assign a key, you need to go into the standard control options for the game.


All the hotkeys created by scripts are found under the "Interface" tab right at the bottom in the "Extensions" section.


Then you need to find the one that you added, it will be the same text that you added in the register command.

Destruct Hotkey

Just assign it like any other control in the game. Then when you want to use it, all you have todo is press that key when in flight. If you have a target selected it will be destroyed, otherwise nothing will happen.


Stage 4 - Automatic Registering of Hotkey

The current system is far from user friendly and means users have to manually run the register script once in each save game they use the script in. A better way would be to use a setup script, these scripts are run automatically when you load a game. The problem with this, is that each time you load the game, another instant of the hotkey will be added. To prevent this you need to detect if the hotkey has already been registered.

To do this, we need to store the key in the saved game, then if the key exists, you dont bother registering the hotkey. This can be done with global varibles. Global varibles are not like other varibles, and allow you to assign values and objects to a string that are stored in saved games. These are accessable in any script and at any time.

So, the first thing we need to do is create a setup script, this is easy and is created the same way as normal scripts, the only difference is the file name, if you prefix the script name with setup. then it will be a setup script. ie setup.register.hotkey.

First thing we need to go is check for the existence of the hotkey from our varible. Use the command to get a global varible, found in the General Object Commands.

Get Varible

The return value is the value that is currently being stored by that varible, set it to key.


Then next argument is the varible name itself, this is a string name, you can have as many varibles as you like. Its command practice to prefix the name with the name of the script, ie destruct.key.


Now you need to check if the key is valid, if its not been set then it will return "null". You can use a conditional expression "if block" to test the varible key. If its not valid, then you can use the register command.

If Block

Now add the same command you did previously remembering to set the return value from the register command.

Register Key

Now we need to store that key in the varible so next time its run it can detect that its been used. For these, we use the set global varible command from the General Commands menu.

Set Varible

The first argument is the varible name, this should be the same as the one you used for get global varible, destruct.key.

Set Varible

The final argument is the value you want to assign, this is what is returned when using the get global varible command. So we want to assign the value stored in the $key varible.

Set Varible

finally we just need to finish the script by closing the if block. Then next time you load your game, this script will be run and the hotkey will be registered. The varible can also be used if you wish to unregister a key.



Stage 5 - Varible text for different languages

How the script currently stands now, the name displayed in the controls menu will be fixed, and cant easily be changed if you wish the script to be multi language. To solve this problem, we can create a text file to control the string we wish the control to be called.

We then read the string from the text file and use that instead of the hardcoded version.

First thing you need to do is insert the load text command at the top, and load the text id. View previous guides for information on creating text files.

Load Text

Now, before we register the hotkey, we need to get the text from the file, use the read text command and set the correct page and id for the command and set the return value to a varible.

Read Text

Finially change the string for the hotkey to the varible you used to read the text to.


Once the hotkey has been registered any changes made to the text wont take effect, as they only work when you first register the hotkey. If you wish to change the text, you will need to unregister it first then re register with the next text.


Stage 6 - Unregistering Hotkeys

To unregister a hotkey you need to know the keys id, this is what you stored in the global varible. So first you need to do what you need and get the key, but this time check if its true, using "if", instead of "if not".


Next you need to add the command for Unregister hotkey, this is found in the General Commands menu.


The only argument is the ID for the key, this is what is stored in the varible $key.


Now you need to unassign the varible as the key is no longer valid. Use the set global varible, but set the value to "null" instead, this will unassign the varible.


Now when you run this script, it will remove the hotkey from the list and allow it to be registered again if needed. This can also be used to clean up a script if its no longer used.

<< Prev (Creating Wares)
Next (Creating an AL Plugin) >>