pre-release 0.2 Edited By Dr Phibes
STOS Manual 4: SPRITE COMMANDS
The Sprite Definer
SCREEN BREAKDOWN:
1 THE SYSTEM MENU:
The system menu contains nine Icons which control the main features of
the designer. Typical options available from this section are load/save,
change size, and a clever facility to allow you to design an animation
sequence. These commands can be accessed directly from the screen by moving
the mouse pointer over the appropriate icon and pressing the left button.
2 THE DRAWING AREA:
This is the area of the screen in which your sprite will be drawn. Points
can be plotted at the current cursor position by pressing either the left
or the right mouse buttons. As a default the right key is set to the background,
and the left key to the colour white. You can change these colours whenever
you like using a special colour window.
3 THE SCROLL ZONE:
The scroll zone allows you to see the relative size of your sprite, and
scroll it in all four directions. This scrolling can be activated at any
time by clicking on one of four different icons which border the zone.
4 THE COLOUR WINDOW:
This is divided up into two sets of 16 colours. One set of these colours
is for the left mouse button, and the other is for the right. To select
a new colour for the mouse, you simply move the mouse pointer over the
new colour and press the left button. Your current choice will now be highlighted
on the screen.
5 THE TOOLS SECTION:
The tools area contains 18 different drawing icons. These include facilities
to create circles, ellipses and bars as easily as a single point. There's
also an extremely useful undo feature which immediately reverses the effects
of your last command. You can choose one of these functions by simply clicking
on the appropriate icon. The shape of the mouse pointer will now be changed
accordingly to indicate the option you have selected. Most functions require
you to first set the dimensions of an object before it can be drawn on
the screen. You normally specify the size of an item by keeping the left
button pressed while moving the mouse. When you release the button, the
object can be moved about with the mouse. You can now draw as many copies
of the design on the screen as you wish by pressing the left button at
any point in the drawing area. Incidentally, if you want to draw another
object you can immediately reset the size back to zero with the right mouse
button.
6 THE SELECTION WINDOW:
The selection window is used to display all the sprites which are currently
held in the ST's memory. Several of the system options use this window
to allow you to choose one of a number of images which are currently held
in the ST's memory. You can scroll through these sprites using the following
Icons single arrow smoothly moves the list back or forward one place. double
arrow quickly moves the sprites back or forward treble arrow left moves
to the first sprite in the list. treble arrow right moves to the last sprite
in the list.
Creating An Animation Sequence
In order to to create your animation sequence, you first need to select
the number of frames to be animated. This can be done by simply clicking
on the appropriate sprite in the selection window with the left mouse button.
Your sprite will now be added to the current progression, and the string
associated with it will be displayed on the screen. As a default the animation
takes place at the centre of the drawing area. You can however move this
display anywhere else you like on the screen using the mouse.
Controlling The Animation
The effect of the animation is controlled from a special dialogue box positioned
to the immediate right of the selection window. At the top of the box is
a line comprising of four arrows and a number. The number in the centre
indicates the delay in 50th's of a second between the last image in the
sequence and the next one you select. You can change this number up or
down by clicking on the inner arrows. You can also highlight any single
animation string using the mouse cursor. The speed setting of this string
will now be altered whenever you press the inner arrows, allowing you total
control over the speed of each individual animation step. The second set
of arrows on the control panel change the speed of the animation as a whole.
They do this by adding or subtracting one unit of time from all the animation
strings you have defined. It is important to note that this option retains
any differences between each of the separate stages.
Changing The Direction
The second line of the dialogue box lets you change the direction of the
animation, and also provides you with the ability to step through your
animation a single frame at a time. There are three different options available
from this section.
FORWARD ANIMATION: Executes the animation string from left to right.
REVERSE ANIMATION: Executes the animation string from right to left.
STEP BY STEP ANIMATION: When this is set to ON, clicking on the mouse
(if pointer outside control panel) executes a single animation step.
Displaying A Background Screen
The final set of options enable you to load a screen in either Degas or
Neo format into the background. This can now be displayed along with your
animation using the background Icon. WARNING These screens overwrite any
pictures you have loaded with the GRAB IMAGE option.
Grabbing Sprites From The
Disc
This command enables you to grab sprites directly from a file in either
Degas or Neo format. There are seven icons:
-
Return to main menu
-
Grab image (see note)
-
When this toggle is ON the grab can only start on word boundaries. This
helps when grabbing sprites that are snapped onto a boundary.
-
If this option is ON the grabbed sprite will be transferred directly into
the store.
-
Reads a NEO file off the disc. If the GET PALETTE option is ON then the
pictures palette is also loaded.
-
As for 5, but with a DEGAS file.
-
Loads the current palette of colours with the settings used by the new
picture.
Note: Grab Image
Displays the current picture on the ST's screen. In order to grab a
sprite from this picture you always need to follow thsee steps :
Define the size of your sprite by enclosing it in a rectangle. As you
move the mouse with the left button held down, the dimensions of the rectangle
will expand and contract. When you release the button the dimensions of
the sprite are set to the current size.
Move the box over the part of the image you wish to grab.
Grab the contents of this box into the sprite bank by pressing the
left button.
Grabbing A Sprite From A
Program
This enables you to grab a sprite out of a program stored in a disc file.
Unlike GRAB IMAGE, this file doesn't have to be in any particular screen
format at all. It can in fact, be anything from your favourite commercial
game to a sprite file generated by a different editor. This command has
two icons:
-
GRAB IMAGE Select this to grab a sprite from a file already loaded.
-
SELECT AND GRAB This erases the current screen and loads part of the file
into the ST's memory.
The contents of this file is now displayed in the form of a screen image.AT
the bottom of the screen lies the main control panel. As you can see, two
numbers are displayed directly underneath the name of your file. P: This
number indicates your position in the file. The designer loads the file
in 16k chunks so there is no real limit to the size of the file you can
inspect with this function.
W: Denotes the current screen width, and can vary from 1 to 20>
The width can easily be changed by clicking on the icons situated just
beneath the W. On the right of the screen lies two sets of direction arrows
which enable you to scroll through the file in search of some useful images.
Once you've found something interesting, you can save the entire screen
using the SAVE NEO or SAVE DEGAS options in the menu box. You can also
grab any individual sprite from this image. First press the right button
to remove the control panel. Now select the sprite with the left button
in the same way as with the grab image command.
The File Menu
This is the menu which is used to save and load your sprites to the disc.
These sprites are always stored in memory bank 1. See RESERVE This menu
has the following seven icons:
-
USE PALETTE When this option is ON all files saved will have the current
colour palette saved with them. Files loaded into the editor will change
the current palette.
-
LOAD A SPRITE FILE This loads a set of sprites from the disc. These are
placed in bank 1 and replace any other sprites previously in this bank.
-
MERGE A SPRITE FILE This command merges a sprite bank held on disc to one
which is stored in memory. WARNING LOW RES ONLY !
-
SAVE Saves the current contents of sprite bank 1 to the disc. WARNING Any
sprites you wish to save must first be placed in the sprite bank with the
PUT SPRITE option before this function is called - otherwise your data
will be LOST.
-
SAVE AS Save your sprites under a new name.
-
QUIT Leaves the sprite designer, losing any sprites you have defined.
-
QUIT & GRAB This option only makes sense if the designer has been executed
as an accessory. Quit & Grab then leaves the definer and copies the
sprites you have defined straight into the current program.
Changing The Hot Spot
Each sprite is manipulated on the screen using a special point called the
hot spot. This can be changed to anywhere inside the sprite using the hot
spot menu. To see the current setting, move the mouse into the drawing
area. The hot spot will now flash continually on the screen. In order to
make life easier for you, a number of commonly-used settings have been
assigned to the icons: Upper left, Upper middle, Upper right, Bottom left,
Bottom middle, Bottom right, Center Click on the icon which represents
the hot spot you want.
Changing The Palette
This can be achieved with the RGB option which allows you to specify one
of 512 shades of the 16 available colours.
Changing The Size Of The
Sprite
Set X and Y menu: Stos basic allows you to use sprites ranging from 16X2
to 64X64 pixels in size.
As a default the size is set to 32X32 but this can be changed at any
time from the set X and Y menu. Note that the width can only be altered
in 16 pixel steps and that the HOT SPOT will be set to the top left Squeeze
sprite: If you press on this selection the sprite in the edit window will
be moved to the top left corner. This frees the surrounding space and allows
you to shrink the sprite, thus achieving the smallest size possible.
Placing A Sprite Into The
Bank
After you have created a sprite you must place it into the sprite bank.
This can be done using the store sprite menu which supports five options:
ERASE BANK:
very dangerous. This deletes an entire bank.
DELETE SPRITE:
Deletes the sprite from the selection window.PERMANENT INSERT SPRITE: Inserts
the sprite at the current slot by shifting all the other sprites one place
to the right.
PUT SPRITE:
This copies the sprite you are currently editing into the sprite displayed
in the centre of the selection window. In order to avoid overwriting your
existing sprites, you should position the first empty slot at the middle
of the window before use. WARNING erases destination sprite. GET SPRITE:
Edits the sprite you have chosen with the selection window.
Some shortcuts: When editing a sprite you can place it into the
store by pressing the down arrow key twice. This is the same as using the
put sprite menu option. To get a sprite from the store just press the up
arrow key twice. For real speed you can put the sprite in the editor and
then get the next sprite from the store just by pressing the right arrow
key. If you press the left arrow key then the edit sprite will be stored
and the previous sprite will be loaded into the drawing area.
The Multiple Mode Sprite
Definer
This can be found in the file SPRITE2.ACB on the accessory disc.
On startup the screen is split into six separate windows as follows:
-
THE INFORMATION LINE: This is placed at the top of the screen and
displays the colour of the current pen or the size of the sprite.
-
THE RGB WINDOW: Used to select a colour for drawing operations.
-
THE SCROLL WINDOW: This is utilised by the scroll option to scroll
the sprite in all four directions.
-
THE PATTERN WINDOW: Holds a copy of the current fill pattern.
-
THE SPRITE DISPLAY: This displays a full sized copy of the edited
sprite.
-
THE DRAWING WINDOW: Draw your sprite here. The left mouse button
plots a point and the right button deletes a point.
Here is a breakdown of the menu options available from this program:
-
STOS-SPRITES: Displays title screen.
-
STOS-QUIT: Exits from the accessory, losing all current sprites.
-
STOS-QUIT&GRAB: Exits from the accessory, transfers sprites
to current program
-
FILE-LOAD SPRITE BANK: Loads a file of sprites into bank 1 for editing.
-
FILE-SAVE SPRITE BANK: Saves all the sprites defined into a new
file on disc
-
FILE-SAVE AS: As above but with a new filename.
-
BANK-GRAB FROM PROGRAM: Grabs any sprites from current program.
-
SPRITE-PUT SPRITE: Puts the current sprite into a particular slot
and replaces any of the original contents.
-
SPRITE-INSERT SPRITE: Inserts the currently edited sprite into bank
1 without overwriting existing images.
-
SPRITE-GET SPRITE: Gets a sprite out of the memory bank to be edited.
-
SPRITE-ERASE SPRITE: Erases on of the sprites from the bank. Select
the sprite used by these functions by clicking on it with the mouse.
-
SPRITE-MOVE SPRITE: This allows you to assign one of the sprites
to the mouse and see how it looks when you move it around.
-
SPRITE-CINEMA: To choose the sprites for an animation sequence simply
click on the appropriate images in the drawing area. Click the left mouse
button anywhere outside the window to start animation. Control the speed
of animation with the + & - keys.
-
SPRITE-PREVIOUS CINEMA: Restarts the last animation sequence you
defined from the point you left off.
-
SPRITE-GET FROM: Grab a sprite from a screen stored on the disc
in Degas or Neo format. After you have chosen a file with the file selector,
you are then presented with a list of the currently defined sprites in
the bank. Select the one you wish to load using the left mouse button.
Note that the dimensions of this sprite determine the final size of the
image which will be grabbed. The new screen is now displayed and you can
grab the image which is underneath the mouse cursor by clicking the left
button. After you have finished you can return to the editor by clicking
the right button.
-
SPRITE-FIX MASK: This allows you to select the mask colour used
as the transparent index.
-
SPRITE-FIX HOT SPOT: Click the mouse on the point wanted as the
hot spot.
-
SPRITE-FIX X & Y SIZE: Change the size of the sprite using the
scroll arrows.
-
TOOLS-ERASE: Erases the currently edited sprite. Does not affect
any sprites stored in the bank.
-
TOOLS-MIRROR: Reverses the sprite from left to right.
-
TOOLS-FLIP: Reverses the sprite from top to bottom.
-
TOOLS-SCROLL: Scrolls the sprite.
-
TOOLS-PAINT: Whenever you click the mouse in an enclosed area it
willbe filled with the current colour. Click on DRAW to revert the editor
back to normal.
-
TOOLS-PALETTE: Click on the colour required for subsequent drawing.
The Sprite Command
SPRITE n,x,y,p
Displays the sprite number n on the screen at coordinates x,y n can range
from 1 to 15. It is this number which identifies the sprite.x and y, unlike
normal screen coordinates can take negative values. The x coordinate can
range from -640 to 1280, and the y coordinate from -400 to 800. p specifies
which of the images in bank 1 is to be used for a particular sprite. The
only limit to the number of images is the amount of memory.
Moving A Sprite
MOVE X n,m$
This defines a list of horizontal movements which will be performed by
sprite n. m$ contains a sequence of commands which determine the speed
and direction of the sprite as follows:
SPEED: Stipulates the delay in 50ths of a second between each
sprite movement. 1 (very fast) to 32767 (incredibly slow)
STEP: Specifies how many pixels the sprite will move in each
operation. If the step is +ve the sprite will move right and a -ve value
will move it left.
COUNT: Designates the number of steps which will be completes
in a single movement. Values range from 0 to 32767. If you use a COUNT
of 0 the motion will repeat indefinitely.
These three elements are placed in the movement string using the following
format: (speed,step,count): Syntax:
MOVE X 1,"(SPEED,STEP,COUNT)"
To move the sprite use the command MOVE ON
To combine a number of individual movements use the following format:
MOVE X 1"(SPEED,STEP,COUNT)(SPEED,STEP,COUNT)"
Some extra directives are L and E used as follows:
MOVE X 1"(SPEED,STEP,COUNT)L"
Will cause the sprite to jump back to the start of the list and rerun the
whole sequence again.
MOVE X 1"(SPEED,STEP,COUNT)E100"
Will stop the sprite when it reaches a point on the screen, in this case
at an x coordinate of EXACTLY 100.
MOVE Y n,m$
This command complements the move x one described above and is used in
exactly the same way, except that +ve displacements now result in the sprite
moving down the screen and -ve ones result in an upward movement.
MOVE ON/OFF[n]
Switches a sprite movement on or off, n refers to the sprite number, if
it is omitted then all sprite nmovement sequences will be affected.
MOVE FREEZE[n]
This command temporarily suspends a numbered sprites movement, if n is
omitted the all sprites will be frozen. Resume movement with MOVE ON.
=MOVEON(n)
Returns a non 0 number if sprite n is currently moving else 0. =X SPRITE(n)
Returns the x coordinate of sprite n.
=Y SPRITE(n)
Returns the y coordinate of sprite n.
LIMIT SPRITE x,y to x2,y2
When a sprite moves outside this area, it will disappear from the screen.
All x coordinates are rounded to a multiple of 16 In order to return the
sprites to normal use LIMIT SPRITE with no parameters.
Animation
ANIM n,a$
n refers to the number of the sprite to animate and a$ to a list of animation
commands to be carried out and is split into two separate component enclosed
between brackets as follows:
IMAGE: This is the image number of the sprite to be displayed
during each step of the animation.
DELAY: Specifies the amount of time the image will be held on
the screen before the next image is displayed in 50ths of a second. (70ths
on a mono system)
Typical example:
anim 1,"(1,10)(2,10)"
This would display image 1 for 10/50 or 1/5 of a second, and then flick
to image 2. As with the MOVE instruction there is also an L directive to
display a sequence continually:anim 1"(1,10)(2,10)L". ANIM ON/OFF[n] Start
or stop a series of animations of sprite n. If n is omitted then all animation
sequences will be affected.
ANIM FREEZE[n]
Temporarily freeze the animation of sprite n. If n is omitted then all
animation sequences will be frozen.Restart with ANIM ON.
CONTROLLING THE SPRITE USING THE MOUSE CHANGE MOUSE m
This allows complete redesign of the mouse pointer. Three forms are already
present m=1>arrow:m=2>pointing hand:m=3>clock: If a value greater than
3 then this is assumed to refer to an image stored in the sprite bank.
The number of the image used is determined by subtracting 3 from m. So
image number 1 would be selected by a value for m of 4.
The default definitions for the mouse stored on the disc can be changed
using the following procedure:
-
Define 3 sets of sprites, for EACH resolution. If you only want to affect
one resolution, it's best to modify the sprites in SPRDEMO.MBK, as this
already contains a bank of sprites in the correct format.
-
Load these sprites into bank 1 using either LOAD or QUIT & GRAB options
from the sprite definer accessory.
-
Place a copy of the STOS basic system disc into the drive.DO NOT USE THE
ORIGINAL SYSTEM DISC FOR THIS PURPOSE !
-
now type: bsave "\stos\mouse.spr",start(1) to start(1)+length(1)
Whenever you subsequently load STOS basic from this disc, the new mouse
pointers will be automatically utilized by the system.
=X MOUSE
Get the x coordinate of the mouse pointer.
=Y MOUSE
Get the y coordinate of the mouse pointer.
=MOUSE KEY
Returns the state of the mouse buttons as follows:
| 0 |
no buttons pressed |
| 1 |
left button pressed |
| 2 |
right button pressed |
| 3 |
both buttons pressed |
LIMIT MOUSE x,y to x2,y2
Restricts the mouse movement to the area defined and causes the pointer
to go to the middle of the defined area.
HIDE
Removes the mouse pointer from the screen. It is still active and all the
other mouse functions can still be used, ie.a=x mouse. To redisplay the
mouse, the command SHOW is used. One important point to note is that the
system keeps a count of how many HIDEs and SHOWs have been used and only
displays or removes the mouse if they are even when the function is called.
To get around this and ensure that the mouse is always hidden or revealed
on demand the alternative commands HIDE ON and SHOW ON can be used as these
functions will always result in action being taken, irrespective of the
count.
Reading The Joystick
=JOY
Read the right joystick. The five LSB's of the returned value indicate
the status of the joystick as follows, a 1 signifies a positive:
| bit number |
significance |
| 0 |
joystick moved up |
| 1 |
joystick moved down |
| 2 |
joystick moved left |
| 3 |
joystick moved right |
| 4 |
fire button pressed |
=JLEFT
Test joysticks left movement bit. true=-1 False=0
=JRIGHT
Test joysticks right movement bit. true=-1 false=0
=JUP
Test joysticks up movement bit. true=-1 false=0
=JDOWN
Test joysticks down movement bit. true=-1 false=0
=FIRE
Test if fire button pressed. true=-1
Detecting Collisions With
A Sprite
t=COLLIDE(n,w,h)
This provides an easy way of detecting whether two or more sprites have
collided on the screen. n refers to the sprite you wish to check and can
range from 0 to 15. w and h determine the sensitivity of the test and refer
to a rectangular area around the hot spot of the sprite. Whenever another
sprite enters this box, a collision will be detected.
t is a number in binary format which holds a list of sprites which
have collided with sprite n. Each bit in this number represents the status
of the equivalent sprite. You can test for these bits using the btst function.
Detecting Collisions
With Rectangular Blocks
SET ZONE z,x,y to x2,y2
Defines 1 of 128 rectangular zones which can then be tested using the ZONE
command for the presence of either the mouse or a sprite. z specifies a
number from 1-128 which represents the zone to be created, the x &
y coordinates refer to the top left corner of the rectangle and x2 &
y2 refer to the bottom right of the rectangle.
t=ZONE(n)
This searches for the sprite n in the list of the zones defined using SET
ZONE. n can range from 0 to 15, with the mouse being indicated by sprite
number 0. After the function has been called, t will hold either the number
of the zone where the sprite was detected or 0. Note that ZONE only returns
the FIRST zone in which the sprite was found. If two or more zones overlap,
it is not possible to determine any other zones the sprite is also in
RESET ZONE[z]
This command erases any of the zones created with SET ZONE, if the optional
z is included, then only this zone will be affected.
Detecting Collisions
With An Irregular Shape
c=DETECT(n)
This function returns the pixel colour under sprite n's hot spot
Exceeding The 15 Sprite Limit
PUT SPRITE n
Simply places a copy of sprite n at it's current position on the screen.
Note that the sprite you have copied is completely unaffected by this instruction.
GET SPRITE x,y,i[,mask]
This enables you to grab any images off the screen and turn them into sprites.
The x and y refer to the start of the rectangular area to be captured.
i denotes the number of the image to be loaded, and MUST refer to an image
which already exists in the sprite bank. The size of the new image is taken
from the original dimensions specified when using the sprite editor.
Also note that the HOT SPOT of the sprite is set to the point x,y.WARNING
this command only works if the rectangle you are trying to grab is completely
inside the borders of the screen.
The optional mask specifies which colour in the new sprite is to be
treated as transparent. If this mask is omitted, it will be set to 0. In
MONO systems the mask has a different action. All monochrome sprites are
given a special border on the screen. The thickness of this outline is
usually set to a width of 1 pixel, but you can increase it by including
a higher value as part of the mask.
Sprite Priority
PRIORITY ON/OFF
The priority determines how sprites are displayed when they overlap on
the screen. Sprites with a higher priority always appear to have been placed
in front of sprites with a lower one. Normally the priority of the sprites
is assumed to be in REVERSE order to the sprite numbers. There is however
a different priority system which can be activated with the PRIORITY ON
command. This gives the highest priority to the sprites with the largest
y coordinate. The coordinates of the HOT SPOT are used to determine the
sprites current y position on the screen.
PRIORITY OFF
returns the priority system to normal.
The Background
Whenever a sprite is moved across the screen, it obscures some sections
of the graphics and reveals others. In order to prevent corruption of this
data, Stos has a default condition which automatically backs up the screen
in another area of memory, it is this back up area which is used to redraw
parts of the screen vacated by a sprite. You can change this state of affairs
by switching this backup mode off.
AUTOBACK ON/OFF
Use of this command speeds up graphics commands substantially when OFF
is selected.
Miscellaneous Sprite Commands
UPDATE
Usually any sprites drawn on the screen are automatically redisplayed whenever
they are animated or moved. This feature can be temporarily halted which
results in the sprites appearing not to move.
This is not the case as the sprite positions are still being changed
but nor displayed. The command has three variations.
UPDATE OFF
Turns off the automatic updating of sprites.
UPDATE
Redraws any sprites which have changed at their new positions. This command
can occasionally be substituted for the normal WAIT VBL after a PUT SPRITE
instruction as it is much faster.
UPDATE ON
Returns sprite updating to normal.
REDRAW
Redraws all sprites at their current location irrespective of movement
OFF Turns off all sprite movements and animations and removes them from
the screen. As a default it is assigned to function key f10.
FREEZE
Temporarily halts the actions of all the sprite commands and stops any
music which is currently being played.
UNFREEZE
Restarts sprite movement and music halted with the FREEZE command.