View source for B-ASIC

'''B-Asic''' is a set of RSX commands allowing to use the Amstrad CPC Plus features from [[BASIC]]. It was written by [[Longshot]] of [[Logon System]].

== Introduction ==
'''B-ASIC''' is a set of RSX instructions to manage the extra features of the '''CPC +'''

RSX instruction signify that each instruction is prefixed by a special char : | on english keyboard and "ù" on french azerty keyboard

Since release 3.0 B-ASIC runs only on CPC range with 128 Kb memory 

Main instructions can manage colours and sprites, providing an extra bank of '''128 sprites''' for a total of '''144 sprites''' (since version 3.4)

'''B-ASIC doesn't take any byte of the CPC locomotive Basic memory.''' 
(The RSX definition and code for locomative basic are not declared in main memory )
The whole interruption system and RSX managment is modified when B-Asic start. 

From a technical point of view, the code of the program BASIC using B-ASIC is copied in a bank, because one bank is always open for the system to store the BASIC code. 
So, there are two video pages availables for the user. 

A set of new powerful instructions will come in future versions.



== Games developed using B-ASIC ==

* [[Call &BD10'n'oeuf]]


== Historics ==
* V1.1 ??/04/1991 Published in Amstrad Cent pour Cent (A100%) magazine N°38 (may/june 1991) New instructions INKF, INKS, BORDERP, INKFRVB, INKSRVB, BORDERRVB
* V1.2 ??/05/1991 Published in A100% N°39 (july/aug 1991)New instructions  SPRON,SPROFF,SPRZOOM,SPRXY,SPRTDEF,SPRTON,SPRTOFF, SPRSWAP,SPRPLOT,SPRCOPY,SPRTURNX,SPRTURNY,SPRFILL
* V1.3 ??/08/1991 Published in A100% N°40 (sept/oct 1991)- Corrected bug with  MODE instruction with some roms- Corrected bug on prg  > 16k- Update instructions SPRTDEF, SPRTON, SPRTOFF- New instructions SPRTORAM, RAMTOSPR, SPRSAVE, SPRLOAD- New instructions RETARDX, RETARDY, MASQUE, SPLIT
* V1.4 ??/??/1992 Published in A100% N°42 ()- B-Asic runs in banks (without RSX managment).
* V2.1 ??/??/1992 - New temporary version with RSX system deviation
* V3.1 ??/??/1992 - 2nd vidéo page. Corrected little bugs.- New instructions POKEASIC, POKEVR, DEFORGXY, DEFORGSPR - New instructions SPRCATCH, INKCOPY,SPRLINK, SPRUNLINK, ERALINK
* V3.2 25/02/2006 - Corrected a bug in table calculation (interrupt function)- Corrected a bug in locomotive firmware (ei before real end interrupt)
* V3.3 27/02/2006 - Corrected bug : Basic code copied in banque 5 at B-Asic boot (it was a problem for progr bigger than 16 kb) since 3.1- New instruction SPRWHERE
* V3.4 24/05/2007 - Corrected bug in SPRWHERE (variable setting between 4000 and 7FFF)- Update instruction SPRCOPY (now accepting sprites number from 0 to 143). Sprites 0 to 15 are real sprites. Now there are 128 sprites instead of 64 in previous version :  64 sprites FAST and 64 sprites SLOW (sprites access for sprites 80 to 143 are slowest than FAST sprites access). These additionnal sprites does not take more space than with 64 in the previous release.- New instruction DOKE,address, 16bitsvalue- Removing instructions RAMTOSPR and SPRTORAM, which are now unuseful. (replaced by SPRCOPY)- New instruction SPRTSTEP,n1,…,nx to play the sprite-way step by step (user action).- New instruction DEFKBDSPR to link one or two super-sprites with keyboard (or joystick) keys (automatic or user activable).- Update instruction CATCH : New name SPRCATCH- New instruction SPRCOLL to manage (automatically or user-activable) collisions for up to 8 super-sprites.- Some optimisations

== Starting B-Asic ==
To use B-Asic, it's very easy. You need only two things :
Get the file named '''B-ASIC.BIN'''
Insert as first line in your basic program the following line :

'''10 IF PEEK(&BC0E)<>&CD THEN OUT &7F00,&C1 :LOAD "B-ASIC.BIN ",&C000 :CALL &C000'''

== Instructions ==
----
=== Colours Instructions Set ===
----
'''INKF,pen,colour'''
* pen=[0..15] colour=[0..4095]
* Modify colour of a pen
* Example : INKF,0,2303
----
'''INKFRVB,pen,red,green,blue'''
* pen=[0..15] red=[0..15] green=[0..15] blue=[0..15]
* Modify colour for a pen using colour elementaries components
* Example : FOR I=0 TO 15:INKFRVB,0,I,0,0:NEXT I
----
'''BORDERP,colour'''
* colour=[0..4095]
* Modify border's colour.
* Example : BORDERP,543
----
'''BORDERRVB,red,green,blue'''
* red=[0..15] green=[0..15] blue=[0..15]
* Modify border colour using colour elementaries components
* Example : FOR I=0 TO 15:BORDERRVB,0,0,0,I:NEXT I
----
'''INKS,pen,colour'''
* pen=[1..15] colour=[0..4095]
* Modify colour of an hardware sprite pen
* Note : The pen 0 cannot be modified. It's the transparent colour.
* Example : INKS,1,3456
----
'''INKSRVB,pen,red,green,blue'''
* pen=[1..15] red=[0..15] green=[0..15] blue=[0..15]
* Modify colour for an hardware sprite pen using colour elementaries components
* Note : The pen 0 cannot be modified. It's the transparent colour.
* Example : FOR I=0 TO 15:INKFRVB,0,I,0,0:NEXT I
----
'''INKCOPY'''
* Copy the whole colour screen palette to sprite palette.
----
=== Sprites Instructions Set ===
----
'''SPROFF,SpriteNumber'''
* SpriteNumber=[0..15]
* Sprite display is disactivated for specified sprite.
* Example : SPROFF,3  
----
'''SPRON,SpriteNumber'''
* SpriteNumber=[0..15]
* Sprite display is activated for specified sprite.
* Example : SPRON,3  
----
'''SPRZOOM,SpriteNumber,XZoom,YZoom'''
* SpriteNumber=[0..15] XZoom=[0..3] YZoom=[0..3]
* Define sprite zoom for specified sprite.
* If XZoom or YZoom is zeroed, sprite is not displayed
* Zoom value of 1 is no magnify.
* Note : Sprite must be activated by SPRON instruction to be displayed on screen
* Example : SPRZOOM,2,2,1 define the sprite 2 magnification to 2x horiz. and 1x vertically
----
'''SPRXY,SpriteNumber,XPos,YPos'''
* SpriteNumber=[0..15] XPos=[-256..767] YZoom=[-256..255]
* Define sprite position on screen according a mode 2 definition
* Note : Sprite must be activated by SPRON instruction to be displayed on screen
* Example : SPRXY,2,100,80 define sprite 2 position at 100,80 coordinates
----
'''SPRTDEF,SpriteNumber,Address,DurationPer,WaitingPer'''
* SpriteNumber=[0..15] Address=[0..65535] DurationPer=[0..65535] WaitingPer=[0..65535]
* Periods are defined by period of 0,02 second (e.g. 50 = 1 second) 
* Define a path for the specified sprite.
* The path is defined by screen positions, given by a set of x,y coordinates defined in memory.
* Each coordinate is defined on 2 bytes (4 bytes for a screen position) in the memory
* The coordinate must be stored on a little endian method, e.g. the less significant byte in first and the most significant byte in second position in memory. 
* You can use the instruction DOKE to do that easily (example : |DOKE address, x : |DOKE address+2,y : address=address+4)
* The last x coordinate must take the value F0F0 (hexa) to indicate the path end definition (|DOKE address,&F0F0)
* DurationPer indicates the time while the sprite will run on the path (at the last position the path start again at the fist position). 
* If DurationPer is zeroed, so the duration is infinite.
* WaitingPer indicate the start period which occurs when the path will be activated (see SPRTON and SPRTOFF instructions). Note : A same path can be used by one or more sprites. Example : SPRTDEF,3,&3000,0,100 to define for sprite 3 a path defined in &3000 with an infinite loop of the path after 2 seconds of start delay after SPRTON,3 instruction.
----
'''SPRTON,SprNb1,SprNb2,...,SprNbx'''
* SprNbx=[O..15]
* Start the path simultanously for the specified sprites.
* Note : An undefined path for the sprite may occur an erratic behaviour of the sprite started.
* Example : SPRTON,1,5,7  start the path for sprites 1, 5 and 7 simultaneously
----
'''SPRTOFF,SprNb1,SprNb2,...,SprNbx'''
* SprNbx=[0..15]
* Stop the path simultaneously for the specified sprites 
* Example : SPRTOFF,1,7 stop the path for sprites 1 and 7 simultanously
----
'''SPRTSTEP,SprNb1,SprNb2,...,SprNbx'''
* SprNbx=[0..15] 
* Execute the path step by step for the specified sprites. 
* Note : An undefined path for the sprite may occur an erratic behaviour of the sprite started. 
* Example : SPRTSTEP,1,5,7 plays one path step (defined with SPRTDEF) for sprites 1, 5 and 7 simultaneously 
----
'''SPRSWAP,SpriteNumber1,SpriteNumber2'''
* SpriteNumberx=[0..15]
* Exchange the sprite content of two sprites.
* Note : If SpriteNumber1=SpriteNumber2 it results just a waste of time.
* Example : SPRSWAP,1,5 exchange the graphics data of sprites 1 and 5
----
'''SPRPLOT,SpriteNumber,XPos,YPos,SpritePen'''
* SpriteNumber=[0..15] XPos=[0..15] YPos=[0..15] SpritePen=[0..15]
* Plot a pixel in the specified sprite at specified coordinates
* Note : SpritePen=0 means the transparent pen for sprite
* Example : SPRPLOT,3,10,9,4 plot a pixel pen 4 at coordinates 10,9 of sprite 3
----
'''SPRCOPY,SpriteOrg,SpriteDst'''
* SpriteOrg=[0..143], SpriteDst=[0..143] 
* Copy the content of SpriteOrg to SpriteDst. 
	Sprites number	Definition
	0 to 15		Real sprites
	16 to 79	Ram Fast sprites
	80 to 143	Ram Slow sprites
* Example : SPRCOPY,1,81 copy the content of sprite 1 (asic) to sprite 81 (ram slow)
----
'''SPRTURNX,SpriteNumber'''
* SpriteNumber=[0..15]
* Flip the sprite specified on horizontal axis
* Example : SPRTURNX,1
----
'''SPRTURNY,SpriteNumber'''
* SpriteNumber=[0..15]
* Flip the sprite specified on vertical axis
* Example : SPRTURNY,1
----
'''SPRFILL,SpriteNumber,SpritePen'''
* SpriteNumber=[0..15] SpritePen=[0..15]
* Fill the specified sprite with the specified pen
* Note : SpritePen=0 means the transparent pen for sprite
* Example : SPRFILL,1,12 fill the sprite 1 with pen 12
----
'''SPRCATCH,SpriteNumber,XPos,YPos'''
* SpriteNumber=[0..15] XPos=[0..143] YPos=[0..183]
* Get a sprite from mode 0 screen at specified coordinates (coordinates top/left).
* Note : This instruction runs only in graphic mode 0
* Example : CATCH,3,120,100 catch the pixels from 120,100 to 135,115 in sprite 3
----
'''SPRWHERE,SpriteNumber,@varx%,@vary%'''
* SpriteNumber=[0..15] varx=Name of x variable vary=Name of y variable
* Get the x,y coordinates of the specified sprite
* Important note : varx and vary must be defined first like integer (declaration in basic with '%') and
* they must be given to the instruction "by address" ('@' before the variable name). The * declaration must
* be respected to avoid unpredictibles results.
* Example : 10 VARX%=0: VARY%=0 : SPRWHERE,1,@VARX%,@VARY%: PRINT VARX%,VARY%
----
'''SPRSAVE,[SpriteNumber,] BlocNumber, Filename'''
* SpriteNumber=[0..15] BlocNumber=[0..4] Filename=Name of file in Amsdos standard 
* Save a sprite or a set of 32 sprites (defined as one Block) to disk 
* B-Asic can store 128 sprites definitions more than the usal sprites contained in asic ram. 
* These 128 sprites are organised as 4 sets of 32 sprites named "Block".  Each block contains 16 fast sprites and 16 slow sprites 
Block & sprites number	Fast Sprites	Slow Sprites
1 - 0 to 15		16 to 31	80 to 95
2 - 0 to 15		32 to 47	96 to 111
3 - 0 to 15		48 to 63	112 to 127
4 - 0 to 15		64 to 79	128 to 143
* Bloc 0 is used for the 16 "real" asic sprites. 
* If  SpriteNumber is not precised in the instruction, so a complete block is saved 
* If  SpriteNumber is precised, only two sprites (fast and the slow sprite associated) for the block is saved 
* Example : SPRSAVE,3,2,"SPR3BLK1.BIN" save the sprite fast and slow number 3 of the Bloc 2 (e.g. sprite 35 and sprite 99) in the file named "SPR3BLK1.BIN" 
* Example : SPRSAVE,0,"SPRASIC.BIN" save the content of block 0 (e.g. 16 asic sprites) 
----
'''SPRLOAD,[SpriteNumber,] BlocNumber, Filename'''
* SpriteNumber=[0..15] BlocNumber=[0..4] Filename=Name of file in Amsdos standard 
* Load a sprite or a set of 32 sprites (defined as one Block) from disk 
* B-Asic can store 128 sprites definitions more than the usal sprite contained in asic ram. 
* These 128 sprites are organised as 4 sets of 32 sprites named "Block". 
Block & sprites number	Fast Sprites	Slow Sprites
1 - 0 to 15		16 to 31	80 to 95
2 - 0 to 15		32 to 47	96 to 111
3 - 0 to 15		48 to 63	112 to 127
4 - 0 to 15		64 to 79	128 to 143
* Bloc 0 is used for the 16 "real" asic sprites. 
* If  SpriteNumber is not precised in the instruction, so a complete block is loaded 
* If  SpriteNumber is precised, only the specified sprite of the block is loaded 
* Note : If the file specified has an invalid size, an error is displayed 
* Example : SPRLOAD,3,2,"SPR3BLK1.BIN" load the fast and slow sprites 3 of the Bloc 2 (e.g. sprites 35 and 99) from the file "SPR3BLK1.BIN" 
* Example : SPRLOAD,3,"RAAHHHHH.SPR" load the block 3 (e.g. sprites 48 to 63 and sprites 112 to 127) from file "RAAHHHHH.SPR" 
----
'''SPRLINK,SpriteNumber1,SpriteNumber2,Xrel,Yrel'''
* SpriteNumberx=[0..15] XRel=[-256..767] YRel=[-256..255]
* Link a sprite (2) to another sprite (1) with a relative position.
* That means if sprite (1) is moved, then sprite (2) is moved too.
* So if sprite 1 is moved in X1,Y1 then the sprite 2 will be moved automatically in X1+Xrel,Y1+Yrel
* It's possible to link all the sprites in all combinations to create one or more "super sprites"
* Note : A sprite cannot be linked to itself.
* Example : SPRLINK,1,2,16,0 link sprite 2 to sprite 1 with a relative x position of 16 pixels
* Example : SPRLINK,2,5,0,16 link sprite 5 to sprite 2 with a relative y position of 16 pixels
* [ so move the sprite 1 signify to move sprite 2 and 5 ]
----
'''SPRUNLINK,SpriteNumber1,SpriteNumber2'''
* SpriteNumberx=[0..15]
* Unlink a sprite from anoter sprite.
* Example : SPRUNLINK,2,5 erase the link between sprite 2 and 5
----
'''ERALINK'''
* Erase all link
----
'''SPRCOLL,NumDef,SpriteNum1,DeltaX1,DeltaY1,SpriteNum2,DeltaX2,DeltaY2,@collision%, PixelPerfect'''
'''SPRCOLL, NoDef, 255'''
'''SPRCOLL'''
* Process the collision test between two sprites automatically or manually
* NumDef = [0..7] (8 collisions can be processed simultaneously) SpriteNum1=[0..15] 
* DeltaXn=[0..255], DeltaYn=[0..255] : Number of pixels in mode 2 definition from sprite coordinate defining the zone to test collision. This method is useful to extend the collision to a super sprite or to restrict collision to only a part of a sprite or supersprite. 
* PixelPerfect is not used actually
* @collision% : This variable take the value 1 when a collision is detected between 2 sprites. The user must set the value to 0 to reset the collision detection.

'''VERY IMPORTANT''' : The variable collision must be defined like an integer (déclaration by initialisation with %), and the variable must be given to function by address (e.g. @ ou à (on french keyboard) before the variable name).
Example : collision%=0  used in function like @collision%
When SPRCOLL is used with all parameters, the collision process is automatic, and so independant of locomotive basic program. But it's possible to control manually each collision test using the instruction without parameters (at this time, the automatic mode is disactivated). If the user wants to cancel a collision process, he must use the instruction with 2 parameters  : SPRCOLL,NumDef,255 (This will help the cpu ;-)) 
 
'''WARNING about SPRCOLL:'''
SPRCOLL use a locomotive basic variable given by address. And this address is stored by B-Asic when SPRCOLL is called with all parameters. So the user needs ABSOLUTLY keep in mind the two following situation :
* When SPRCOLL is used in automatic mode (e.g B-Asic store automatically the collision test result at each frame), you  must absolutly replace the instruction in manual mode (by using SPRCOLL without parameter) before to modify your basic program because the variable is stored and moved in the basic area.
* When you have just stopped your basic program, NEVER modify the program and do a GOTO through a SPRCOLL instruction used without parameters. (the SPRCOLL must be called before with all parameters to give to B-Asic the new address of the variable)
'''You must respect ABSOLUTLY these 2 rules to avoid a destruction of some part of your basic program. (I will solve the problem of first case later.''' I need to know when the locomotive basic interpreter is not running. Help appreciate)
----
'''DEFORGXY,SpriteNumber,XPos,YPos'''
* SpriteNumber=[0..15] XPos=[-256..767] YPos=[-256..255]
* Define absolute origin position of the specified sprite
* That means that real sprite position take care of this defined coordinates.
* Example : DEFORGXY,1,10,20:SPRXY,1,5,3 display sprite at 15,23
* Note : It's possible to define an origin position for a sprite following a path (see SPRTDEF)
* The default of origin at B-Asic reset is 0,0
----
'''DEFORGSPR,SpriteSlave,SpriteMaster'''
* SpriteSlave=[0..15] SpriteMaster=[0..15]
* Define the origin position of SpriteSlave with the position of SpriteMaster.
* Note : It's possible to define a sprite relative position for a sprite following a path (see SPRTDEF)
* It's possible to generate complex definitions of sprites movments.
* If a sprite 1 use a path 1 and a sprite 2 use a path 2, if the sprite 2 is the slave of sprite 1, then
* the path 2 will be relative to path 1.
* To erase the slavery of a sprite, use DEFORGXY instruction
----
'''DEFKBDSPR, NumDef, SpriteNumber, KeyUp, StepUp, KeyDown, StepDown, KeyLeft, StepLeft, KeyRight, StepRight'''
'''DEFKBDSPR,NumDef,255'''
'''DEFKBDSPR'''
* Associate the sprite coordinates to keyboard keys
* NumDef =[0..1] It's possible to define keys for 2 sprites /  SpriteNumber=[0..15] Sprite number / Keyxxxxx=[Key number] (see table), Stepxxxx=value 0..255 : Step in mode 2 pixel to add or substract associated value to corresponding key.
* A key 0 indicate to do not test the key. When DEFKBDSPR is defined with all parameters, the sprite process is automatic, and so independent from basic program. It is possible to control manually the sprite movment by using the instruction without parameters (the automatic mode is disactivated). 
* Note : If the user wants to cancel a definition, it's better to disactivate the sprite with DEFKBDSPR,NumDef,255 instead of defining all keys with 0 (The B-Asic will gain cpu-speed).
---
=== Others Instructions Set ===
----
'''POKEASIC,Address,val1,...,valx'''
* Address=[&4000..&7FFF] Valx=[&00..&FF]
* Poke one or more bytes in Asic I/O page
* Instruction reserved to experimented users.
----
'''POKEVR,Address,val1,...,valn'''
* Address=[&4000..&7FFF] Valx=[&00..&FF]
* Poke one or more bytes in second video page
* Instruction reserved to experimented users.
----
'''DOKE,Address,value16bits'''
* Address=[&4000..&7FFF] value16bits=[&0000..&FFFF] 
* Double Poke in user memory 
---- 
'''SCREENCOPY,direction '''
* direction=[0..1] 
* 0 : Copy the main videoram  to videoram 2
* 1 : Copy the videoram2 to main videoram

== Error Messages ==
'''Bad arguments number'''
* Bad number of arguments used in the instruction

'''Invalid Argument'''
* An invalid value is used in one or more arguments of the instruction

'''Invalid Filename'''
* A bad filename was used in a SPRSAVE or SPRLOAD instruction

'''Disc Error'''
* An I/O error has occured in a SPRSAVE or SPRLOAD instruction.
* Disc is missing, or the disk has a wrong or damaged format.

'''Not a Sprite file'''
* The size of the file specified in SPRLOAD is not correct.
* See if you do no use the SPRLOAD with a block instead of a single sprite (or the opposite)

'''Same Sprites Numbers'''
* An instruction SPRLINK or SPRUNLINK is attempted with 2 identical sprite numbers.

'''Bad Graphic Mode'''
* Instruction CATCH is not used in MODE 0

'''Invalid Moving List'''
* An invalid table is created for SPRTDEF 
* (e.g. the first coordinate is the path end)

'''Link Table Full'''
* The link table is full.
* Normally this error cannot occur in a well built program.

'''Sprites not Linked'''
* Instruction SPRUNLINK is used with sprites not linked.

== Links ==
[http://logon.system.free.fr/html/downloadlogon.htm Download B-Asic]

[[Category:Programming software]]
[[Category:CPC Plus]]