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