Controllers
Controllers can be assigned to keyboard shortcuts, joystick buttons, and menu items. Controllers are used by AGI to take specific actions based on keyboard input or menu selections or joystick input.
Controller Assignment Table
AGI allocates two different but related a tables in memory to manage controllers. A controller assignment table is allocated to hold up to 50 different keyboard and joystick controller assignments. The controller assignment table is not indexed; i.e. the first controller assignment does not have to be for controller 0. Each assignment in the table includes its associated controller number, regardless of its position in the assignment table, as well as the key press/joystick information that will trigger the controller.
Controller Evaluation Table
A separate 50 byte evaluation table is allocated for tracking when controllers are activated. When a particular controller is triggered, this table is updated so the controller test command can identify it. The evaluation table IS indexed; i.e., the first byte corresponds to controller 0, second byte to controller 1, and so on.
Keyboard Controllers
Keyboard combinations, i.e. shortcut keys, are assigned to controllers using the set.key command. Note that even though there is room for 50 controller assignments in the controller assignment table, if you attempt to assign more than 39 controllers, AGI ignores additional calls to set.key. (It's not clear why this limitation exists; Sierra may have had a reason, or it could be a bug. In AGI Version 3.002.149, the limit changed to 49, still one short of the maximum of 50 available slots in the controller assignment table.)
When a key combination is assigned to a controller with set.key, AGI stores the assignment in the next available space in the controller assignment table, storing both the controller number and the key-press assignment. The controller number should be less than or equal to 49 or the controller will not work correctly when evaluated with the controller command due to a buffer overflow. Key-press information is stored in the same format that key-presses are added to the input queue, i.e. as either an ASCII value or a keyboard scan code.
Whenever a key-press is detected, AGI checks all the entries in the controller assignment table. If a match for the key-press is found, the input is converted to the assigned controller activation, which gets added to the input queue in place of the key-press.
Note that the check for ego direction keys occurs before the controller check, so it is not possible to assign a controller to the ego direction keys.
Joystick Controllers
Joystick buttons]] can also be assigned to controllers using set.key command. When joystick buttons are pressed, AGI will search the controller assignment table and add controller input in the same manner as with key presses.
Menu Controllers
Controllers are assigned to menu items in a different manner. Instead of storing the controller information in the controller assignment table where key-press controller information is stored, menu controller information is stored along with other menu item information. When the set.menu.item command is called, AGI stores the menu item information - caption text, parent menu, pointers to next and previous menu item and controller value - in a 14 byte menu item header that gets added to the memory heap. When a menu item is selected, AGI adds the corresponding controller to the input queue.
Responding to Controllers
When a controller input entry is read from the input queue, a one byte flag in the 50 byte controller evaluation table is set to true for the current [[interpreter cycle</A> (at the beginning of each cycle, the entire controller evaluation table is cleared).
To determine if a particular controller has been activated, use the controller test command. The controller test returns TRUE if the corresponding controller evaluation table entry is set.
Note that if the controller was assigned with a value greater than 49, the input queue will overwrite memory past the end of the controller evaluation table. The area of memory that will be overwritten includes space used by sounds, pictures and messages, so if it gets overwritten it can cause unpredictable behavior. The other problem with using a controller greater than 49 is that after the controller gets set by input queue, there is nothing to reset it (only the 50 bytes in the controller evaluation table get cleared each cycle), so once the invalid controller is set, it will stay set, which will certainly result in unexpected behavior.
In the first version 2 interpreter (2.089), there was room for only 40 controller assignments. But due to a bug, the controller evaluation table only provided space to hold 30 controllers. Assigning controller values above 30 will not work as expected, and will probably crash AGI. This bug was not fixed until version 2.411.
Assigning Duplicate Controllers to Multiple Inputs
Note that it is possible to assign more than one key combination or menu to the same controller. For example, you can assign a function key, a CTRL+key combination and a menu item to one controller so they all trigger the same action. Additional information on how controllers are used in logics, including details on useful ASCII values and keyboard scan codes can be found in the Programming Menus and Keyboard Shortcuts topic.
Assigning the same key press combination to more than one controller is allowed, but just wastes a controller entry. As soon as AGI finds a valid match in the controller assignment table, it stops checking, so only the first assignment will trigger a controller event.
