Builder Input

An input is one way of interacting directly with the player. Messages (also called message boxes) and dialog messages (which are sequences of messages) provide less general ways of interacting. In respose to an input, the player can enter an arbitrary value. In response to a message, the player can only choose between two available buttons.

Kinds of Input

You can ask for these kinds of input.

• Text. An arbitrary string of characters. On the pocket PC, the player enters a response using the virtual keyboard (or the physical keyboard if the device has one). On the Garmin Colorado, the player uses the text input function of the scroll wheel. The moral of the story is ask for short values!
• Multiple choice. You define a list of values. The player selects one.
• True/false. As of 02/25/2008, I have been unable to make this work at all in the emulator. Waiting for a response from the forums.

Using Variables to Save Input Values

You can optionally associate a variable with each input. You will usually do so since this is the only way to use the input value later.

• For a text input, you can use either a string variable or, if you expect the player to enter a number, a number variable. In the latter case, if the player enters something which is not a number, the variable value will be nil. Presently, this does not appear to be a useful behavior because the builder provides no way to test for this condition. (You can only compare a number variable to literal values between 0 and 100.)
• For a multiple choice input, you can use either a string variable or a number variable. If the values in your list are all numbers, you can use either a string or a number variable, according to what you intend to do with the value. If the values are not all numbers, you should use a string variable. (When you use a number variable and the selection is non-numeric, the variable will be set to nil, just as it is for a text input. See above.)
• For a true/false input, we have no clue.

Gotchas (or Why the Input Event Is Your Friend)

In order to use inputs correctly, you must understand that the script which displays the input continues to execute immediately. In particular, it does not wait for the player to provide the input. Usually, you will want to do something when the player answers your question. In order to accommodate that, there is an event associated with completion of the input. The script attached to that event is where you will put anything you want to do when the player answers.

There are other ramifications to this situation.

• The entered value will not be saved in the variable associated with input unless you attach a script to the event. If all you want to do is save the value in the variable, the script may be empty -- but it must exist.
• Obviously, the variable will not be set until the user completes the input action. You cannot depend on the value in other places (for example, subsequent events triggered by player motion, such as zone entry events) unless you know that the input event has already fired. In particular, the value will not be set in the next statement in the script in which you requested the input!
• Once you have requested input, you must not do anything which alters the display until the input event fires. For example, you must not request a different input, display a message box, display a screen, or display a detail screen. If you do so, the player will never be able to complete the input. And you run the risk of crashing the engine. If you are displaying a series of screens, this usually means that you will display the next one in the script attached to the input event.

Inputs in the Builder

To create or edit an input, choose Inputs in the main sidebar. You will see a list of existing inputs.

• To add an input, choose the Add button beneath the list. Provide the requested information.
• To edit an existing input, choose the Edit button beneath the list. Provide or change the requested information.
• To delete an existing input, choose the Delete button beneath the list. Confirm your intention to delete the input.
• To edit the script associated with the input event for a particular input, select the input in the list. Select the (one and only) event in the list to the right. If there is no script attached, choose New Script and create your script. If there is a script attached, choose Edit Script to change it. To delete an existing script, choose Delete Script and confirm your intention to delete it.

If you plan to use a variable to hold the answer, you should create the variable first. The builder gives you the option of creating a variable here, but this feature does not work correctly as of this writing (02/25/2008).

When you create or edit an input, you will be asked to provide the following information.

• A short name. Required. Must be different from all other variables.
• A brief description. Optional.
• Text to be shown to the player. Prompt the player with a question.
• Choose the type (Text, MultipleChoice, TrueFalse).
• Choose a variable to hold the answer. Choose the object type (currently limited to ZVariable) and the object (variable).
• You can optionally select a piece of media (picture) to be displayed with the input request. This picture will appear above your text.
• You can optionally select an icon as well. Not sure where this is used, if it is.

You can maintain the associated event script on the Events tab. First, select the event in the list.

• If no script exists, choose New, then create the script.
• To edit the existing script, choose Edit and make your changes.
• To delete the existing script, choose Delete and confirm your intention to delete the script.