COLLISION interruptType [ , lineNumber ]

 

 

 

Program flow control; set a subroutine to be called when a video event occurs in a program.

 

COLLISION without a lineNumber disables calling of a subroutine when interruptType occurs.  If lineNumber is given, it is saved as a Secret Variable and enables a special subroutine, called an interrupt routine (described below), that is called when the given interruptType occurs. 

 

All interruptTypes are video events, but unfortunately you can't set a routine to be called based on the raster interrupt (even though most video chips support this).  Type 1, collision of two sprites, is hopefully obvious: when any of the "visible" (non-transparent) pixels of a sprite occupy the same screen location (coordinate) as any "visible" pixels of another sprite.  Note however that sprite-sprite collisions may occur off-screen ("under" the border).  Type 2 is also pretty obvious in text mode: whenever a "visible" sprite pixel appears at a screen location that has a non-background (foreground) pixel (any of the "lit" pixels that make a character).  In high-res bitmap mode, any pixel with a 1 bit value is considered foreground and will trigger an interrupt (a pixel wih a 0 bit value will be ignored); this is pretty obvious if you use the same colors on the whole bitmap, but if you switch foreground and background colors it might be hard to tell by looking if a pixel is 1 or 0; you can use the RDOT function if you need to check a pixel at a specific location.  In multi-color bitmap mode, the background is pretty obvious because it is shared over the full screen.  However, of the other 3 bitmap color sources, only source 2 and 3 are considered foreground; color source 1 in multi-color bitmap is considered background by sprites; thus pixels set to 0 or 1 are ignored, and pixels set to 2 or 3 will trigger a collision with a sprite (again, you can use RDOT if you want to check a pixel).  Type 3 occurs when a new coordinate has been latched by a light pen/gun.

 

A specified lineNumber should exist, however BASIC does not check when you use COLLISION.  Later, when (if) the specified interruptType occurs, BASIC will attempt to GOSUB to the appropriate lineNumber.  At that time, UNDEF'D STATEMENT ERROR occurs if the lineNumber is not in the program.  Unlike GOSUB, the lineNumber does not need to be a literal value; it can be any numeric expression.  However, using a non-literal value will usually cause a silent error with RENUMBER which only updates line numbers written as a literal number.  The GOSUB action requires 5 bytes of the BASIC stack; if this is not available when the interrupt routine needs to be called, OUT OF MEMORY ERROR occurs.  Calling the interrupt routine also uses 2 bytes of the CPU stack; however this is not checked until an expression is evaluated in BASIC.

 

If interruptType is ommited, SYNTAX ERROR occurs immediately.  If interruptType or lineNumber (if present) is not numeric, a TYPE MISMATCH ERROR happens immediately.  If a numeric expression is used but is not valid, SYNTAX ERROR occurs immediately.  If interruptType or lineNumber is not a legal value (see table above), an ILLEGAL QUANTITY ERROR occurs immediately.

 

The video chip, while drawing the screen, will note the appropriate condition; once each frame(field) the BASIC IRQ checks for any/all interruptTypes.  The BASIC IRQ will set a flag in the secret variable (really a 3-byte array) called "interrupt trip flag" if a corresponding lineNumber has been specified and the appropriate condition is satisfied.  Note the BASIC IRQ runs "in the background".  That is, it appears to run (periodically) at the same time as the normal BASIC language.  It is a primitive form of multi-tasking (or better, multi-threading).

 

Assuming BASIC is not already processing an interrupt routine, before every BASIC statement is executed in a program the secret array "interrupt trip flag" is checked.  If a byte in the array is set (non-zero), BASIC will clear that byte (so hopefully the routine won't be called again...), BASIC will set bit 7 of another secret variable "interrupt val" (temporarily disables all interrupt routines), and GOSUB the interrupt routine corresponding to the interruptType.  This action interrupts whatever BASIC code was formerly executing, hence the name of the called subroutine is "interrupt routine".

 

The interrupt routine is only called when a program is running.  It is never called in direct mode.

 

The interrupt routine should do any tasks needed in the situation, and end with RETURN so that the formerly executing code may resume execution.  Details of Interrupt Type 1 (sprite-sprite) can be tested with BUMP(1) and Type 2 (sprite-foreground) with BUMP(2).  Type 3 can be tested with PEN.  If other interrupt events occur during the proccessing of an interrupt routine, they will be saved (i.e., the secret array "interrupt trip flag" is updated) but the corresponding routine will not be called until the current routine executes RETURN.  In other words, interrupt routines can not be nested.  After the interrupt routine ends, BASIC clears bit 7 of the secret variable "interrupt val" to re-enable calling of interrupt routine(s).  Note the clearing of "interrupt val" is done by a special part of BASIC, not the actual RETURN statement.  This means your interrupt routine can use GOSUB/RETURN without "accidentally" re-enabling interrupts.

 

The BASIC IRQ only runs once per frame (this is true even when split-screen is enabled).  In other words, 60 or 50 times per second, or once every 16.6.6ms or 20ms (NTSC or PAL video standard, respectively).  Thus unless the condition which triggered the interruptType is somehow negated, the interrupt routine will be called again, in theory, 60 or 50 times per second.  I said "in theory" because the BASIC Interpreter is not very fast, so depending on the total size of the program and the length of a particular interrupt routine, it can happen less frequently.  This is important if your program attempts to negate the condition that caused the interruptType.  Well, you don't have any control over the light-pen/gun, because it is triggered by the user; but you do have control of sprites.  There are only four possible actions to negate a sprite interrupt:

The important thing to note is that interruptTypes 1 and 2 (the sprites) can be re-triggered while your interrupt routine runs.  As stated above, these triggers will not immediately call your interrupt routine when BASIC is processing the code of an interrupt routine; in other words the trigger is "remembered" for later.  But once your interrupt routine does its RETURN, the "remembered" values will be acted upon.  Thus, even if you negate the condition which triggered the interruptType, your interrupt routine(s) may immediately be called again (i.e., right after RETURN) because of the "remembered" value(s)... see the Example.  Another important point with sprites is that their position is only updated once per frame, so any sprite statements that move or disable the sprite will not happen immediately, thus allowing another frame of video where your interrupt routine may be called again.

Besides the 4 options listed above, another option to deal with delayed/multiple interrupts is to use the COLLISION statement without a lineNumber (or a different lineNumber) inside the interrupt routine.  This works with the light-pen(gun) too.  If you use this method, your interrupt routine will probably want to set some flag so that the main program will know to restore the original lineNumber of COLLISION at an appropriate time.

 

In short, a program using COLLISION must be robust enough to handle the case where an interrupt routine is called multiple times, sometimes "wrongly"... that is where the condition which caused the interrupt was negated by the program but the routine was called again anyway because an interruptType was "remembered" or there was a delay until the next frame to update a sprite's position.

 

In summary, the COLLISION command itself is very simple, it just sets a program line to be GOSUB'ed (or not) when a particular video event occurs.  But the results are rather complex; this is due to multiple levels of indirection and several secret variables.  It is a very useful/powerful statement when used appropriately, but it requires programming skill to be used effectively.  If you can write a useful program involving COLLISION, you can consider yourself a master of CBM BASIC :)

 

Example:

NEW

READY.
0 REM setup -- create sprite 1
10 GRAPHIC 1,1           : REM clear hi-res bitmap
20 CHAR 1,0,0,"*"        : REM draw a * at the top-left of screen
30 SSHAPE S$,0,0,23,50   : REM save sprite-sized area of bitmap (includes *)
40 SPRSAV S$,1           : REM copy the shape (S$) into sprite #1
45 REM -- main program
50 GRAPHIC 0,1: PRINT"!" : REM clear text screen, write character at top-left
60 MOVSPR 1,24,50        : REM position sprite over character
70 SPRITE 1,1            : REM display sprite 1
80 COLLISION 2,100       : REM set interrupt routine for sprite-foreground
90 DO: SLEEP 1: LOOP     : REM wait forever...
95 REM sprite-foreground interrupt routine
100 PRINT "COLLISION"    : REM verify interrupt routine was called
110 MOVSPR 1,200,50      : REM re-position sprite to negate future interrupts
120 RETURN               : REM resume main program

RUN                      note a delay of 1 second
COLLISION                note a delay of 1 second
COLLISION                note a delay of 1 second
COLLISION                the program now waits forever...

 

 

ENVELOPE, GOSUB, TRAP

 

CONT, DISPOSE, EXIT, LOOP, NEXT, RESUME, RETURN
 

BUMP, COLOR, GRAPHIC, MOVSPR, PEN, RDOT, RENUMBER, RSPPOS, SPRITE