PANDORA version 1.01 - Addendum to User's Manual 2-11-89 -------------------------------------------------------- Pandora is an evolving language, and here are the revisions to the latest version. 1. Change to usage of CHAR command ---------------------------------- CHAR now only accepts one parameter, so to generate the sequence CHR$(10)+CHR$(13), use: CHAR 10:CHAR 13 2. Notes on collision detection ------------------------------- To check for a collision between any non-driver sprite and active driver sprites, you must first attach the X and Y coords of the non- driver sprite to an unused driver sprite. Example: To check for non-driver sprite 47 colliding, where its coordinates are in variables x and y, and assuming that driver sprite 31 (the last available) is unused, use the following code: XPOS 31,x: REM Attach X coord of our sprite to Driver Sprite 31. YPOS 31,y: REM Attach Y coord of our sprite to Driver Sprite 31. CHECK 31,i: REM Now check for collision and put result in "i". IF i<255: REM 255 signals no collision. GOTO collided REM Jump to ".collided" if less than 255. ENDIF REM End of condition test. .collided REM take appropriate action. 3. Revised Memory Map --------------------- &0172 - &1FFF : Ascii source code storage area &2000 - &2FFF : Compiled Pandora program &3000 - &47FF : Run-time supervisor &4800 - &49FF : Screen address lookup table &4A00 - &5AFF : Current sprite bank &5B00 - &62FF : Enhanced character set &6300 - &74FF : Source code compiler &7500 - &7533 : Variable storage area a - z &7D00 - &82FF : Array storage area a# - m# &8A00 - &8CFF : 32 driver sprite attribute blocks &8D00 - &8D6F : Blank sprite definition &8D70 - &8D60 : General workspace &8F00 - &8FFF : Animation attribute blocks &9A00 - &9BFF : Envelope storage area 4. Notes for Protext users -------------------------- PANDORA works best in Protext's PROG mode, which generates pure Ascii files and is designed for this type of work - DOC mode should be avoided, as your program may end up containing invisible text- formatting control characters, which could confuse the compiler. 5. Using Pandora without a wordprocessor ---------------------------------------- The last sentence of the first paragraph on page 33 of the manual should read: The final DATA statement should be STOP. A revised version of the program (COMPILE.BAS) appears on this disc. PLEASE NOTE: A COMPREHENSIVE TEXT EDITOR IS NOW SUPPLIED WITH PANDORA SEE SECTION 15 IN THIS FILE FOR MORE DETAILS. 6. Additions to Appendix I - Page 29 ------------------------------------ Please note: commands prefaced by a '*' are new additions which have been included for speed and flexibility. The others are documented elsewhere in the manual. * BANK "filename.ext" : Load in a new sprite bank BORDER b : Set border colour DRAWR x,y : Draw a line relative to the current position DRIVE : Drive sprites * ESAVE "filename.ext": Save all ENV and ENT definitions * ELOAD "filename.ext": Load a bank of ENV and ENT definitions * LOOP s,e,v : Initiate a loop, setting variable V to S. Each time a NEXT is encountered, V is incremented until it reaches the value for E (Similar to a FOR-NEXT loop with no STEP parameter) LSCROLL x,x1,y,y1 : Scroll area of screen memory left MASK m : Set graphics write mode * MAX : Set maximum number of sprites to use. See below (Set this to the highest number sprite you will be using - it is essential that you do this!) * NEXT : Forces the next iteration of the current LOOP * POKES x,y,n : Write byte n to screen location x,y * PEEKS x,y,v : Read byte from screen location x,y into v * POKEM l,b : Poke byte b into location l * PEEKM l,v : Read byte from location l into variable v * PUTS n,x,y : Place a small sprite on the screen manually * PUSH v : Store a variable's contents on the stack * POP v : Retrieve a variable's contents from the stack REM : REMark statement RSCROLL x,x1,y,y1 : Scroll area of screen memory right * USER addr,A,BC,DE,HL: Call machine code routine at addr, passing the following parameters into registers A,BC,DE,HL * USRV addr,A,BC,DE,HL: Call machine code routine at addr, passing the following parameters into registers A,BC,DE,HL On exit, these registers are passed to Pandora variables of the same name (a,b,c,d,e,f,h,l). * WIPES : Erase a small sprite manually 7. The MAX command ------------------ Syntax: MAX n Where "n" is a number between 0 and 31 inclusive. MAX is used to tell Pandora how many sprites are to be processed when the next DRIVE comand is issued, thus speeding up the execution of some games where only a few sprites are used. Normally, every time a DRIVE is executed, Pandora checks all 32 sprites to see which are ON and which are OFF. However, this takes time, and so the MAX command can be used to limit the number of sprites checked in this way. Every Pandora program using sprites must have a MAX command at the start, as the default value assigned to MAX is 0, allowing only sprite 0 to be moved with the DRIVE command. So set "n" to the number of the highest driver sprite you will be using, or the Driver will ignore all sprites higher than 0, regardless of whether ON has been used to activate them. 8. The ANIMATE command ---------------------- Syntax: ANIMATE s,i,t,f,r The manual states on page 21 that parameter "f" must lie between 0 and the value given for parameter "t". This is not so; "f" must be between 0 and t-1, as it states the relative frame number (within the defined sequence) at which animation is to commence. Parameter "t" gives the total number of frames in the sequence, numbered from 1 upwards. However, the frame numbers are referred to from 0 upwards in parameter "f". Therefore the example given on page 21, which reads: ANIMATE 20,0,6,3,0 should read: ANIMATE 20,0,6,2,0 9. The PUTS and WIPES commands ------------------------------ Syntax: PUTS n,x,y WIPES n,x,y These commands are the same as PUT and WIPE respectively, but allow the placing and erasing of small sprites on the screen. A small sprite is one defined using only the pixels which lie within the small blue inner box on the Sprite Editor's editing grid. The WIPES command simply places a small-size blank sprite on-screen at the given coordinates. 10. The Sprite Designer ----------------------- The sentence on page 27 under the heading "CLEARING THE GRID", starting: "To clear the grid..." should state that the CLR key is used to clear the grid, and not the à key. 11. Usage of hexadecimal numbers -------------------------------- Version 1.01 of Pandora now allows constants to be expressed as hexadecimal numbers, which may be mixed freely with denary. This is especially useful when used with the USR, POKEM and PEEKM commands. For example, you may now use: PRINT &00fc:POKEM &0e27,&0002:USR &bb5a,65,0,0,0 POKEM 16384,32:POKEM &ffff,255:USR 32768,&00ff,3,&ffaa,47 Note that if the length of a hex number is less than four digits, it must be padded out to four using zeros. Furthermore, any alphabetic parts of a hex number must be in lower case. 12. Logical operations ---------------------- Version 1.00 made no provision for logical operations on Pandora variables. This has been remedied with version 1.01 - the following operations may now be included in assignments as well as the usual +, -, * and /: a = b A c Logical AND the variables B & C, placing result in A a = b O c Logical OR the variables B & C, placing result in A a = b X c Logical XOR the varialbes B & C, placing result in A Note that the operator must be an upper-case A, O or X. As usual, spaces between the seperate parts of the expression are ignored, so you could also use a=bXc to XOR B & C and place the result in A. Also note that the operations are fully 16 bit - that is, they work on all 16 bits of the variables or numbers given, and the result is also 16 bits long. However, as variables are printed in signed decimal, the following program would print the result -1: a = &00ff:REM Set lower 8 bits of variable a b = &ff00:REM Set upper 8 bits of variable b c = a O b:REM Set variable C to A XOR B print c:REM Result is &ffff, but is printed out in signed decimal as -1 13. Storing variables on the stack ---------------------------------- There are two commands now available with version 1.01 which allow you to temporarily store the contents of any variable(s), allowing the variables to be re-used for a different purpose. The original values may be retrieved later on. This is extremely useful in routines where you need to use more variables than there are available. The two commands are: PUSH v Store the contents of any named variable on the stack POP v Retrieve the contents of a variable from the stack Users unfamiliar with machine code will need to understand the principle of a "stack". Imagine a pile of papers on a table. Each time you want to save a variable's contents, imagine writing the value on a new piece of paper and adding it to the "stack" on the table. When you want to retrieve a variable's contents, imagine taking off the top- most sheet and reading the value. This introduces a new concept: LIFO. This stands for "Last In, First Out", and means that when you use the POP command, the value read into the variable specified will be from the top of the stack, and not from somewhere in the middle. Therefore, if you are PUSHing more than one variable at once, you must POP them in reverse order if you want the correct values to be returned to the right variables: PUSH a:PUSH b:PUSH c:CALL fire:POP c:POP b:POP a There is no harm in POPping variables from the stack in the same order as they were PUSHED; the values will simply end up in the wrong variables. However, this is a useful way of swapping two variable's contents: PUSH a:PUSH b:POP a:POP b will effectively exchange the contents of variables A and B, without the need to use an intermediary variable as temporary storage. There is only one rule to follow when using PUSH and POP: You are restricted to a maximum of 64 entries on the stack at once - any attempt to PUSH more than this will result in the error: "Stack full". Likewise, attempting to POP more items than actually exist on the stack will result in "Stack empty". Experience machine code users will be interested to note that the PUSH/POP stack is entirely seperate from the CALL/RETURN stack, and so program flow cannot be corrupted by careless nesting of PUSHes and POPs. 14. FOR - NEXT loops -------------------- A new loop structure has been written into version 1.01. Similar to Basic's FOR - NEXT loop, the Pandora LOOP command allows continous incrementing of a named variable, in a positive direction, until the variable reaches the "target" value: LOOP start,end,variable:NEXT Where "start" is the starting value (constant or variable), "end" is the target value (which must be greater than "start"), and "variable" is any of the 26 Pandora variables. Array elements MAY NOT be specified - any attempt to do so will be disallowed. The NEXT command is identical to Basic's version, forcing the program to loop back to the LOOP command until the named variable reaches the target value. Nesting of LOOP commands is allowed, up to a depth of 8. Beyond this, you will receive the error "Stack full". An attempt to use a NEXT for which there is no corresponding LOOP command will generate "Stack empty". Note that the Pandora LOOP - NEXT structure is many times faster than Locomotive Basic's FOR - NEXT loop, and should be used in time- critical sections of a program. Here are some timing comparisons which will give you a good idea of Pandora's superior capabilities: Test 1 ------ Basic: FOR a%=1 TO 10000:FOR b%=1 TO 10:NEXT:NEXT Execution time: 85.5 seconds Pandora: LOOP 1,10000,a:LOOP 1,10,b:NEXT:NEXT Execution time: 18.8 seconds Test 2 ------ Basic: FOR a%=1 TO 10000:NEXT Execution time: 4.8 seconds Pandora: LOOP 1,10000,a:NEXT Execution time: 1.5 seconds 15. SWIFT TEXT EDITOR --------------------- In response to enquiries from a number of users we have created the Swift Text Editor. It allows up to 500 lines with up to 79 characters in each, which should be sufficient for most applications. The editor offers "Protext-Style" commands, making it very easy to use, and you can get help from within edit mode at any time by pressing CONTROL-H. The program is saved under the name SWEDIT.BAS. Just type RUN "SWEDIT to start using it. Tape users will find the program on side B of the cassette. 16. FREE COMPETITION -------------------- If you write a game with Pandora that you think could be a best seller, send it to us and if we like it we'll publish it on a forthcoming compilation of Pandora programs, PLUS we'll pay you a generous royalty for every copy sold! So enjoy yourself and get coding. We look forward to seeing the results. 17. VERSION 2 ------------- Look out for version 2 - due for release in January 1990. It will include a sprite editor for all screen modes, a music designer and sequencer, an envelope and sound effects creator, several new sprites and sound effects to add to your own programs, even faster flicker free sprites that can go under or over other sprites and much, much more (including your suggestions if we like them). And the cost? All upgrades to the latest version of Pandora are just £4.95 to cover post. packing and handling. If you want to know if there's a newer version check the national CPC computer magazines or give us a phone call on 01 738 4889. When sending for an upgrade remember to enclose your old master disc or tape as proof of purchase. Swift Software 2-11-89