The UBG Terminal system is a self-contained system that can be activated and controlled through dedicated function calls without ever having to directly manage variables or objects.
There are two primary elements that you need to set up when using the terminal system:
For both of these options defaults have been provided to get things going quickly without needing to set up every property every time you want to use the terminal. It is worth noting that you cannot modify properties until the visual terminal has been created even though they are global.
To create the visual terminal you must make a call to ubg_terminal_init. This will define all the graphical defaults, scan the game for resource names, and finally create the terminal object. After this function has been called you can open the terminal by pressing 'Tab' (see ubg_terminal_set_key_activate). As you will notice, however, there are no valid commands for you to type in! To set up the default commands included with the terminal you should then call ubg_terminal_define_commands_quick, you can alternatively define them yourself (explained below). This makes a series of calls to ubg_terminal_define_command and adds a number of commands to the system. It also adds a 'help' command that can be typed into the terminal to view the available default commands.
When all is said and done you should have something like this:
In order to define a custom command you'll need at least a GameMaker script to reference and a call to ubg_terminal_define_command. Optionally, you will want to add a hint for your command with ubg_terminal_define_hint.
In our example we are going to make the command "destroy" that takes one argument, an instance, and destroys it. In order to actually destroy the instance we will need a GameMaker script which we will call command_scr. While we are at it we can also define a hint so it shows us all the available instances in the room. All this in mind, our first call should be to define the command:
The first argument in that script is the name of the command that the terminal should recognize while the second argument is the id of the script that the command will trigger when it is called; this is the script we will define shortly. Our third argument is how many arguments the command should expect which, in our case, is just the one. You can overload commands with various numbers of arguents if needed later on. The last argument in that function has to do with our hint. It is always treated as false unless we have a proper hint defined where we are then given a choice to set it to true. When set to true the command will attempt to use the hint to determine which datatype the arguments passed are. It will then automatically convert them for you when they are passed into your script command_scr. If this is set to false, or no hint is defined, then all arguments will be passed as strings.
Next up let's define our hint. Hints are defined by passing an array of strings. The first value in the array will be the command name to match the hint with while every following value in the array will be an argument. By default argument hints are like GameMaker argument hints. They just suggest something about what the argument should be. If you want to suggest multiple options for one argument then you can separate each option with a space. Multi-word options can be enclosed in quotes.
Now, of course there are times when you need to have a specific kind of hint; for example a number or resource name. In this case you can place a special flag at the start of the argument to specify what you need. You can read about the available flags in the function description for ubg_terminal_define_hint. With all this in mind, defining our hint should look something like this:
In our case we are using the flag [instance] to specify that we want the hint to contain the instances in the room. Other flags can also include words but not all of them need it. For example, if we type [string] instance1 instance2 instead of [instance] then the argument would suggest the user type either "instance1" or "instance2" exactly. This kind of thing is good for setting specific properties to limited values, such as "true" and "false".
Now that we have all the terminal stuff out of the way all that is left is to write our script. We told the command to execute comand_scr when it is called, so how to we handle this? Well, when your script is called it will be passed two arguments. argument0 will be the name of the command that was executed. In our case it will always be "destroy". argument1 will be a 1D array containing all the arguments typed for the command. Since we specified that we wanted all the values to be converted for us in our ubg_terminal_define_command call, our argument will come through as an instance id or object index (depending on what was typed in). In the case that an invalid id or name is typed the system will recognize it and change the value to undefined. Knowing all this, our script should look like this:
That's all there is to it! Everything else is just changing how things look and feel which you can do through the numerous Setters
and Getters provided.
If you have any questions or issues that can't be found in this manual please feel free to contact us!
If you like this extension take a look at some of our other offerings!