Start and end: TITLE

       Name: TITLE                                                   [Show more]
       Type: Subroutine
   Category: Start and end
    Summary: Display a title screen with a rotating ship and prompt
    Context: See this subroutine in context in the source code
 References: This subroutine is called as follows:
             * BR1 (Part 1 of 2) calls TITLE
             * BR1 (Part 2 of 2) calls TITLE


 Display the title screen, with a rotating ship and a text token at the bottom
 of the screen.


 Arguments:

   A                    The number of the extended token to show below the
                        rotating ship (see variable TKN1 for details of
                        recursive tokens)

   X                    The type of the ship to show (see variable XX21 for a
                        list of ship types)

   Y                    The distance to show the ship rotating, once it has
                        finished moving towards us


 Returns:

   X                    If a key is being pressed, X contains the ASCII code
                        of the key pressed


.TITLE

 STY distaway           ; Store the ship distance in distaway

 PHA                    ; Store the token number on the stack for later

 STX TYPE               ; Store the ship type in location TYPE

IF _GMA_RELEASE

 LDA #$FF               ; Set MULIE to $FF to indicate that the RESET routine is
 STA MULIE              ; in-progress, so we don't try to stop any music that
                        ; may be playing (as RESET updates the music variables,
                        ; so trying to update the music variables will lead to
                        ; unpredictable behaviour)

ENDIF

 JSR RESET              ; Reset our ship so we can use it for the rotating
                        ; title ship

IF _GMA_RELEASE

 LDA #0                 ; Set MULIE to 0 to indicate that the RESET routine is
 STA MULIE              ; no longer being run, so the stopbd routine can work
                        ; again

ENDIF

 JSR ZEKTRAN            ; Call ZEKTRAN to clear the key logger

 LDA #32                ; Switch to the palette for the title view, though this
 JSR DOVDU19            ; doesn't actually do anything in this version of Elite

 LDA #13                ; Clear the top part of the screen, draw a border box,
 JSR TT66               ; and set the current view type in QQ11 to 13 (rotating
                        ; ship view)

;LDA #RED               ; These instructions are commented out in the original
;JSR DOCOL              ; source

 LDA #0                 ; Set QQ11 to 0, so from here on we are using a space
 STA QQ11               ; view

 LDA #96                ; Set nosev_z hi = 96 (96 is the value of unity in the
 STA INWK+14            ; rotation vector)

 LDA #96                ; Set A = 96 as the distance that the ship starts at

 STA INWK+7             ; Set z_hi, the high byte of the ship's z-coordinate,
                        ; to 96, which is the distance at which the rotating
                        ; ship starts out before coming towards us

 LDX #127               ; Set roll counter = 127, so don't dampen the roll and
 STX INWK+29            ; make the roll direction clockwise

 STX INWK+30            ; Set pitch counter = 127, so don't dampen the pitch and
                        ; set the pitch direction to dive

 INX                    ; Set QQ17 to 128 (so bit 7 is set) to switch to
 STX QQ17               ; Sentence Case, with the next letter printing in upper
                        ; case

 LDA TYPE               ; Set up a new ship, using the ship type in TYPE
 JSR NWSHP

 LDA #6                 ; Move the text cursor to column 6
 JSR DOXC

 LDA #30                ; Print recursive token 144 ("---- E L I T E ----")
 JSR plf                ; followed by a newline

 LDA #10                ; Print a line feed to move the text cursor down a line
 JSR TT26

 LDA #6                 ; Move the text cursor to column 6 again
 JSR DOXC

 LDA PATG               ; If PATG = 0, skip the following two lines, which
 BEQ awe                ; print the author credits (PATG can be toggled by
                        ; pausing the game and pressing "X")

 LDA #13                ; Print extended token 13 ("BY D.BRABEN & I.BELL")
 JSR DETOK

.awe

 LDA brkd               ; If brkd = 0, jump to BRBR2 to skip the following, as
 BEQ BRBR2              ; we do not have a system error message to display

 INC brkd               ; Increment the brkd counter

 LDA #7                 ; Move the text cursor to column 7
 JSR DOXC

 LDA #10                ; Move the text cursor to row 10
 JSR DOYC

                        ; The following loop prints out the null-terminated
                        ; message pointed to by ($FD $FE), which is the OS
                        ; error message pointer - so this prints the error
                        ; message on the next line

 LDY #0                 ; Set Y = 0 to act as a character counter

 JSR CHPR               ; Print the character in A (which contains a line feed
                        ; on the first loop iteration), and then any non-zero
                        ; characters we fetch from the error message

 INY                    ; Increment the loop counter

 LDA ($FD),Y            ; Fetch the Y-th byte of the block pointed to by
                        ; ($FD $FE), so that's the Y-th character of the message
                        ; pointed to by the OS error message pointer

 BNE P%-6               ; If the fetched character is non-zero, loop back to the
                        ; JSR CHPR above to print it, and keep looping until
                        ; we fetch a zero (which marks the end of the message)

.BRBR2

 LDY #0                 ; Set DELTA = 0 (i.e. ship speed = 0)
 STY DELTA

 STY JSTK               ; Set JSTK = 0 (i.e. keyboard, not joystick)

 LDA #15                ; Move the text cursor to row 15
 STA YC

 LDA #1                 ; Move the text cursor to column 1
 STA XC

 PLA                    ; Restore the recursive token number we stored on the
                        ; stack at the start of this subroutine

;JSR ex                 ; This instruction is commented out in the original
                        ; source (it would print the recursive token in A)

 JSR DETOK              ; Print the extended token in A

 LDA #3                 ; Move the text cursor to column 3
 JSR DOXC

 LDA #12                ; Print extended token 12 ("{single cap}C) {single
 JSR DETOK              ; cap}D.{single cap}BRABEN & {single cap}I.{single
                        ; cap}BELL 1985")

 LDA #12                ; Set CNT2 = 12 as the outer loop counter for the loop
 STA CNT2               ; starting at TLL2

 LDA #5                 ; Set the main loop counter in MCNT to 5, to act as the
 STA MCNT               ; inner loop counter for the loop starting at TLL2

 LDA #$FF               ; Set JSTK = $FF (i.e. joystick, not keyboard), which
 STA JSTK               ; we will change later if joysticks are not chosen

.TLL2

 LDA INWK+7             ; If z_hi (the ship's distance) is 1, jump to TL1 to
 CMP #1                 ; skip the following decrement
 BEQ TL1

 DEC INWK+7             ; Decrement the ship's distance, to bring the ship
                        ; a bit closer to us

.TL1

 JSR MVEIT              ; Move the ship in space according to the orientation
                        ; vectors and the new value in z_hi

 LDX distaway           ; Set z_lo to the distance value we passed to the
 STX INWK+6             ; routine, so this is the closest the ship gets to us

 LDA MCNT               ; This has no effect - it is presumably left over from
 AND #3                 ; the other versions of Elite which only scan the
                        ; keyboard once every four loops, but that isn't the
                        ; case here as the result is not acted upon

 LDA #0                 ; Set x_lo = 0, so the ship remains in the screen centre
 STA INWK

 STA INWK+3             ; Set y_lo = 0, so the ship remains in the screen centre

 JSR LL9                ; Call LL9 to display the ship

 JSR RDKEY              ; Scan the keyboard for a key press and return the
                        ; key in X (or 0 for no key press)
                        ;
                        ; This also clears the C flag if no keys are being
                        ; pressed

 DEC MCNT               ; Decrement the main loop counter

 BIT KY7                ; If the joystick's fire button is being pressed, jump
 BMI TL3                ; to TL3 to leave joysticks configured (i.e. JSTK = $FF)

 BCC TLL2               ; If no key is being pressed then the C flag will be
                        ; clear from the call to RDKEY, so loop back up to
                        ; move/rotate the ship and check again for a key press

 INC JSTK               ; The joystick fire button was not pressed, so set JSTK
                        ; to 0 (it was set to $FF above), to enable keyboard and
                        ; disable joysticks

.TL3

 RTS                    ; Return from the subroutine