Human Interface

The Human Interface system routines handle input from the keypad and control handles, scoring, system pausing and blackout, and menu display.

Human Interface System Routines

Undocumented routines are marked with an asterisk (*)

Name Description
DOIT Responds to input transition (and branches to transition handler)
DOITB* Like DOIT, but uses B instead of A
GETNUM Get a number from the user
GETPAR Get game parameter from user (“Enter <prompt string>”)
INCSCR Increment 3-byte score and compare to end score (ENDSCR)
KCTASC Converts Bally keypad code to ASCII
MENU Display menu and branch on choice
MSKTD Mask joystick in B to Deltas
PAWS Pause for specified number of interrupts
PIZBRK Black out screen and wait for key/trigger/joystick input
QUIT* Quit cartridge execution
SENTRY Wait for change of program status in ports/timers/counters

Human Interface System Routine Descriptions

DOIT

RESPOND TO INPUT TRANSITION

Calling Sequence:
SYSTEM    DOIT

or

SYSSUK    DOIT
DW        (DOIT table)
Arguments: A = Return code from SENTRY routine
B = Extended return code
HL = DOIT table address
Description: This routine is used with SENTRY for dispatching to a state transition routine. The return code from SENTRY is used to search the DOIT table. If a match is found, control is transferred to the associated handling routine. If no match is found, the routine repeats.

The handling routine may be macro or machine instructions. The routine receives registers as they are on DOIT entry. If no transition is found, execution continues at the first instruction following call.

The DOIT table is a linear list composed of 3-byte entries, with one entry per SENTRY return code.

Transfer type (byte 0, bits 6–7) designates how the handler address is to be transferred to. The codes are:

  • 00 = JMP to machine language routine and pop context
  • 01 = RCALL machine language routine in current context
  • 10 = MCALL interpreter routine in current context

Mode 01 and 10 expect the returned-to point to be interpretive; mode 00 expect it to be machine instructions.

Return code (byte 0, bit 0–5) from SENTRY routine (e.g., ST0, SJ1, SCT7, etc.)

Handler address (bytes 1 and 2) contains the address of the handling routine.

End of list is indicated by a terminator byte that is greater than or equal to $C0.


Example: Football DOIT Table

;**********
;*
;*   Player Input Transition Table
;*
;
DOTABLE:  RC    SCT7,DOCT7,0   ; CT7
          RC    ST0,DOTRIG0,0  ; TRIGGER 0
          RC    ST1,DOTRIG1,0  ; TRIGGER 1
          RC    SP0,DOKNOB0,0  ; Pot. 0
          RC    SP1,DOKNOB1,0  ; Pot. 1
          RC    SJ0,DOJOY0,0   ; Joystick 0
          RC    SJ2,DOJOY2,0   ; Joystick 2
          RC    SJ3,DOJOY3,0   ; Joystick 3
          RC    SJ1,DOJOY1,ENDx  ; Joystick 1

Also see the Keyboard Input Example below for example SENTRY and DOIT usage.

DOITB

RESPOND TO INPUT TRANSITION (USING B)

Calling Sequence:
SYSTEM    DOITB

or

SYSSUK    DOITB
DW        (DOIT table)
Notes: Identical to DOIT, but uses B instead of A

GETNUM

GET NUMBER

Calling Sequence:
SYSTEM    GETNUM

or

SYSSUK    GETNUM
DB        (x-coordinate)
DB        (y-coordinate)
DB        (CHRDIS options)
DB        (DISNUM options)
DW        (number address)
Arguments: B = DISNUM display options
C = CHRDIS display options
D = Y-coordinate for feedback display
X-coordinate for feedback display
HL = Address to store entered number
Description: This routine captures number input from either the keypad or the player one control handle pot. Keypad entry has priority. The routine exits when the specified number of digits are entered or = is pressed on the keypad.

Pot entry is enabled by pressing the trigger. The current pot value is then shown. Twist the pot until the number you want is shown, then press the trigger again to complete entry.
Restrictions: The pot can only enter 1 or 2 digits. If a group of numbers is being entered, the user must enable entry for each new number.

GETPAR

GET GAME PARAMETER

Calling Sequence:
SYSTEM    GETPAR

or

SYSSUK    GETPAR
DW        (prompt)
DB        (digits)
DW        (parameter)
Arguments: A = number of digits to get
BC = address of prompt string
DE = title string address (not loaded)
HL = address of parameter to get
Description: A menu frame is created displaying the title passed in DE. The message “ENTER” is displayed in the center of the screen, followed by the prompt string. GETNUM is entered with feedback specified in 2X enlarged characters. After entry is complete, GETPAR pauses for ¼ second to allow the user to see their entry, then returns.
Notes: See entry conditions and resource requirements for MENU.

Prompt string example: “# OF PLAYERS”

The title string address (DE) is usually the title returned from MENU.

The parameter address (HL) points at the low-order byte of the BCD number in RAM.

Example

A sample 2-digit GETPAR prompt from Gunfight.

INCSCR

INCREMENT SCORE AND COMPARE TO END SCORE

Calling Sequence:
SYSTEM    INCSCR

or

SYSSUK    INCSCR
DW        (address of score)
Arguments: HL = Address of score (must be 3 bytes long)
Output: Score incremented and optionally game over bit set
Description: The 3-byte score pointed at by HL (BCD with low-order byte at lowest address) is incremented by 1 and compared to the end score (ENDSCR). If the end score bit (GSBSCR) was set in the game status byte (GAMSTB) and end score has been reached, then the game over bit (GSBEND) is set in the game status byte.

KCTASC

KEY CODE TO ASCII

Calling Sequence:
SYSTEM    KCTASC
Arguments: B = key code (not loaded)
Output: A = ASCII equivalent of key code
Description: This routine uses a lookup table (listed below) to return the proper ASCII code.
Key Code Name Graphic Hex Value
1 Clear C 43
2 Up Arrow 5E
3 Down Arrow 5C
4 Percent % 25
5 Recall MR 52
6 Store MS 53
7 Change Sign CH 3B
8 Divide ÷ 2F
9 7 7 37
10 8 8 38
11 9 9 39
12 Multiply × 2A
13 4 4 34
14 5 5 35
15 6 6 36
16 Minus 2D
17 1 1 31
18 2 2 32
19 3 3 33
20 Plus + 2B
21 Clear Entry CE 26
22 0 0 30
23 Decimal Point . 2E
24 Equals = 3D

DISPLAY MENU AND BRANCH ON SELECTION

Calling Sequence:
SYSTEM    MENU

or

SYSSUK    MENU
DW        (menu title string address)
DW        (menu list address
Arguments: DE = Address of menu title string
HL = Address of menu list
Output: DE = String address of selection mode
Description: The title is displayed at the top of the screen. Each entry in the menu list is then displayed with a preceding number supplied by MENU. GETNUM is called to get the selection number. The menu list is searched for the selected node and it is jumped to.
Notes: A maximum of eight entries may appear.

On entry, MENU expects interrupts to be enabled and colors and boundaries to be initialized. MENU uses 96 lines of screen, creams the alternate set, and requires three levels of context. MENU calls SENTRY and thus 'eats' all irrelevant transitions.

MSKTD

CONVERT JOYSTICK MASK TO DELTAS

Calling Sequence:
SYSTEM    MSKTD

or

LD        B,(joystick mask)
SYSSUK    MSKTD
DW        (x-delta)
DB        (flop flag)
DW        (y-delta)
Arguments: B = Joystick mask (not loaded)
C = Flop flag
DE = X positive delta
HL = Y positive delta
Output: DE = X-Delta
HL = Y-Delta
Description: This routine uses the joystick mask and flop flag to conditionally modify the passed deltas. If negative direction is indicated, the delta is 2's complemented; if no direction is indicated, 0 is returned.

MSKTD uses the value returned by a joystick and returns positive, negative, or zero values depending on the delta values provided. Delta values entered are what we would like to use if the joystick is held right (left if flopped) or down. Negative values will be returned if the joystick is left (right if flopped) or up.

If we give it an x-delta of 1.0 for single pixel motion, we will get -1.0 for left, 0.0 for middle, and 1.0 for right. Dropping these values directly into the x-delta bytes of the vector block, then calling VECT and VWRITR, will move the pattern appropriately for direct motion control. Passing a delta of 0.25 and adding the resulting values to the vector block deltas would simulate, for example, the inertial motion of a spaceship.
Notes: B is not loaded by SYSSUK.

The joystick mask (B) is the byte value returned by the joystick port, either as a result of reading the appropriate port for a joystick (e.g., $10 for joystick 0) or calling SENTRY and picking up the joystick changes through DOIT (which stores the mask in B).

PAWS

PAUSE

Calling Sequence:
SYSTEM    PAWS

or

SYSSUK    PAWS
DB        (number of interrupts)
Arguments: B = number of interrupts to wait
Description: This routine pauses for a specified number of interrupts. If used with ACTINT, a value of 60 = 1 second. This routine does an EI (enable interrupt) upon entry and assumes interrupts will occur.

PIZBRK

BLACK OUT SCREEN AND WAIT FOR KEY

Calling Sequence:
SYSTEM    PIZBRK

or

SYSSUK    PIZBRK
DB        (number of interrupts)
Arguments: none
Description: This routine blacks out the screen and waits for either a key press, trigger, or joystick change. This function should be called whenever a “hold until further notice” is needed.

All keys on the keypad are enabled. Interrupts are disabled on entry and enabled on exit. It is recommended to reset any 60th of a second timers on exiting PIZBRK.
Note: Often referred to as a 'coffee break' throughout the NM and other documentation.

QUIT

QUIT CARTRIDGE EXECUTION

Calling Sequence:
SYSTEM    QUIT
Arguments: None
Description: Displays the text 'GAME OVER' and holds the present game score until the system detects a key press or player 1 trigger pull.

SENTRY

SENSE TRANSITION

Calling Sequence:
SYSTEM    SENTRY

or

SYSSUK    SENTRY
DW        (Key mask address)
Arguments: DE = Keypad mask table
Output: A = Return code
B = Extended code (see output chart below)
Description: SENTRY checks for changes in the potentiometers (pots), control handles, triggers, keypad, semaphores (i.e., flags), and counters/timers. It also takes care of blackout, the automatic blacking-out of the screen after 255 seconds without a change. If SENTRY isn't called, then the game will not black out.

SENTRY checks if TIMOUT equals zero on entry, and if zero, it goes to PIZBRK. If a key has gone down or a control handle changed, then TIMOUT is set to $FF.

HL should point at a keypad mask. The keypad consists of 6 rows by 4 columns.

Example mask of 0–9 only:
DB      011100B
DB      111100B
DB      011100B
DB      000000B

Keypad Mask Layout

SENTRY Output Chart

Priority A = Meaning B =
SNUL Return NULL (i.e., nothing happened)
1 SCTn Counter/timer n decremented to 0 (n = 0–7)
2 SFn SEMI4S (i.e., flag) bit n was 1 (n = 0–7)
3 SPn Pot n changed (n = 0–3) new value
4 SSEC 1 second has elapsed since the last SSEC
5 SKYU Keypad went from down to up 0
5 SKYD Key is down key number
6 SJn Joystick n changed (n = 0–3) new value
6 STn Trigger n changed (n = 0–3) new value

Notes:

  • The potentiometers (pots) are debounced.
  • New trigger value = trigger off ($0) or trigger on ($10).
  • When switches are actuated simultaneously, the order of return is: SCT7 to SCT0, SF7 to SF0, SP0 to SP3, SSEC, SKYU, SKYD, SJ0, ST0, SJ1, ST1, SJ2, ST2, SJ3, ST3.

Keyboard Input Example

This routine echoes number keys and takes a coffee break (i.e., PIZBRK) on trigger 0 being pulled. Assumes SP is set and screen erases.

          SYSTEM     INTPC
LOOP:     DO         SENTRY
          DW         NUMBAS
          DO         DOIT
          DW         DTAB
          DO         MJUMP
          DW         LOOP
 
NUMBAS:   DB         011100B          ;NUMBER KEYS ONLY
          DB         111100B 
          DB         011100B
          DB         0
 
DTAB:     MC         SKYD,SHOW        ;ON KEY DOWN MACRO CALL
          MC         ST0,PBREAK+END   ;ON TO MACRO CALL
 
SHOW:     DO         KCTASC           ;CONVERT TO ASCII
          DO         SUCK
          DB         00000111B        ;X,Y=0=DE
          DB         11001100B        ;OPTIONS=C
          DONT       CHRDIS           ;DISPLAY CHAR
          MRET                        ;BACK TO LOOP
 
PBREAK:   DO         PIZBRK           ;COFFEE BREAK
          DO         MRET             ;BACK TO LOOP

[NM:55]