Builder Commands

Commands provide a way for the player to act in the virtual world. You can attach commands to characters or items. For example, you might have a command to talk to a character, or a command to open an item like a box or an envelope. You can (and usually will) attach a script to each command. The engine executes the script when the player chooses to perform the command. Use the script to communicate with the player and to do other things to change the virtual environment.

You can also have commands with affect characters, items or zones other than the one with which the command is directly associated. For example, a character might have an associated "ride" command which can be applied to several different items such as a bicycle or a horse. In this case, we call the bicycle or the horse the target of the ride command.

Different Kinds of Commands

There are different kinds of commands which are distinguished by the set of allowable target objects.

• A regular (non-custom) command is not intended to be used with any particular target object. Our command to talk to a character is an example of this type. When the player chooses to perform a command like this, no additional input is required. The script associated with this type of command has no parameters.
• A custom command which is intended to work with any (visible) item or character. For example, a "tricorder" might have a "scan" command which can be applied to any visible object. When the player chooses to perform this command, the player must also select the target object from a list of all visible objects. The script associated with this type of command has a single parameter which is the selected target object.
• A custom command which is intended to work with a restricted set of items, characters, or zones. Our command to ride is an example of this type. We can restrict the ride command to work with the bicycle or horse, but not with an envelope or a box. When the player chooses to perform this command, the player must also select the target object from a list of the applicable objects which are visible. The script associated with this type of command has a single parameter which is the selected target object.

Commands in the User Interface

Commands appear on the item and character detail screens. Which commands appear where depends on the kind of command.

• A regular (non-custom) command appears only on the detail screen of the item or character with which it is directly associated.
• A custom command which works with any object appears only on the detail screen of the item or character with which it is directly associated.
• A custom command which works with a restricted set of items, characters or zones is different. It appears on the detail screen of the item or character with which it is directly associated. In addition, it appears on the detail screen of any visible target item or character (not zone). This allows the player to perform the command from either side. For example, the player can cause a character to ride from the character's detail screen, or from the bicycle or horse detail screen.

Commands which require a target can only be applied to visible objects. No other restrictions apply. For example, if you choose to allow it, the player can perform commands associated with an item which is visible but distant, or visible but not in the player's inventory.

Commands can be enabled or disabled dynamically from script. For example, you can choose to enable the "unlock" command on a box only when the player has the correct key in his or her inventory.

Commands in the Builder

You can add commands to items and characters, either when you create them or when you later edit them. The procedures are virtually identical for both. In each case, the editing screen has a box (somewhere) containing a list of existing commands. Several buttons appear near the list.

• To add a new command, choose the New button and provide the requested information.
• To edit an existing command, select a command in the list, choose the Edit button, and change or provide the requested information.
• To delete a command, select the command in the list, choose the Delete button, and confirm your desire to delete the command when asked.
• To view the list of commands as a menu, choose the View button. I have never seen the commands presented this way to the player, so I have no idea why this is here. The menu only includes enabled commands. For some reason, View is only available when you are editing an item.
• To enable the command initially, be sure that the box next to the command in the list is checked. To disable it initially, make sure this box is not checked.

You must provide the same basic information for every command, regardless of type:

• Text which appears in the "menu". When the command can be performed, this is the text which identifies the command for the player.
• Text to be displayed when no applicable targets exist. This only applies to those command types which accept a target object, but the builder asks for text for every command. The engine displays this text if the user chooses to perform the command when no targets are visible. For example, the player might try to perform the ride command for a character even though neither the bicycle nor the horse is visible.
• An indication (check box) of whether or not this is a custom command intended to be used with other items or characters. Leave this unchecked to create a regular command which does not require a target. Check it to create a custom command which does require a target.

If you choose to create a custom command, you must further choose (via radio buttons) whether this command works with all items and characters, or only with a selected list of items, characters and zones. If you choose the latter option, you will be presented with a list of existing items, characters and zones. To make the command applicable to a particular object, check the box next to that object in the list. To make it non-applicable, make sure the box is not checked.

Command Scripts

Each command has an associated event which fires when the player chooses to perform the command. In most cases, you will need to supply a script to be executed when the event fires. You can use this script to communicate with the player. For example, if the player chooses to "talk to" a character, you can present a message box whose contents depend on the current state of the game. You can also use the script to make changes in the state of the game. For example, if the player applies the "open" command to a box, you might move the contents of the box to the player's inventory.

You can define the script directly from the Items or Characters list screen (the one which appears when you select Items or Characters in the main sidebar). You can also define them from the Events tab in the editing screen for an individual item or character.

For commands which have a target, the script has a single parameter which identifies the target which the user selected. In the script, you can test the target object using the "If the target object is item or character" condition. (There seems to be a minor disconnect here. In the case of a command with a list of applicable targets, the target can be a zone. There does not appear to be any way to test for a particular zone.)