== Introduction ==
'''B-ASIC''' is a set of RSX instructions to manage the extra features of the '''CPC PLUS+'''
Since release 3.0 B-ASIC runs only RSX instruction signify that each instruction is prefixed by a special char : | on CPC range with 128 Kb memoryenglish keyboard and "ù" on french azerty keyboard
Main instructions can manage colour and sprites, providing an extra bank of '''64 sprites''' for a total of '''80 sprites'''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 '''B-ASIC doesn128 sprites't take any byte '' for a total of the CPC Basic memory'''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.
By the wayFrom a technical point of view, the whole interruption system and RSX managment is modified when code of the program BASIC using B-Asic startASIC 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.
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.
By the way, there are two video pages available for the user.
Some instructions are not explained because they will disappear from next version.
(SPLIT, RETARDX, RETARDY, MASQUE)
A set of new powerful instructions will come in future versions.
== Historics ==
* V3V1.1 xx??/xx04/1993 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 doesn't use any byte of BASIC main memoryAsic 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 Bug fix on - Corrected a bug in table calculation for path in (interrupt / Correct function)- Corrected a firmware bug in locomotive firmware (ei before real interrupt handler endinterrupt)* V3.3 27/02/2006 Forgotten to copy BASIC - Corrected bug : Basic code from bank 2 to 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 : SPRWHERENew 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 ==
* 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 ===
* 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.
* 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'''
* Example : SPRPLOT,3,10,9,4 plot a pixel pen 4 at coordinates 10,9 of sprite 3
----
'''SPRCOPY,SpriteOrg,SpriteDst'''* SpriteOrg=[0..15143], SpriteDst=[0..15143]* 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,2 81 copy the content of sprite 1 (asic) to sprite 281 (ram slow)
----
'''SPRTURNX,SpriteNumber'''
* Example : SPRFILL,1,12 fill the sprite 1 with pen 12
----
'''SPRSAVE,[SpriteNumber,] BlocNumber, Filename'''* SpriteNumber=[0..15] BlocNumber=[0..4] Filename=Name of file in Amsdos standard* Save a sprite or a set of 16 sprites (defined as one Block) to disk* B-Asic can store 64 sprites definitions more than the usal sprite contained in asic ram.* These 64 sprites are organised as 4 sets of 16 sprites named "Block".* Bloc 1 : sprites 0 to 15, Bloc 2 : sprites 16 to 31, Bloc 3 : sprites 32 to 47 and* Bloc 4 : sprites 48 to 63* 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 the specified sprite of the block is saved* Note : Sprites are not optimised (e.g. 1 pixel=1 byte)* Example : SPRSAVE,3,2,"SPR3BLK1.BIN" save the sprite 3 of the Bloc 2 (e.g. sprite 18/63)* 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 16 sprites (defined as one Block) from disk* B-Asic can store 64 sprites definitions more than the usal sprite contained in asic ram.* These 64 sprites are organised as 4 sets of 16 sprites named "Block".* Bloc 1 : sprites 0 to 15, Bloc 2 : sprites 16 to 31, Bloc 3 : sprites 32 to 47 and* Bloc 4 : sprites 48 to 63* 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 : Sprites are not optimised (e.g. 1 pixel=1 byte)* Note : If the file specified has an invalid size, an error is displayed* Example : SPRLOAD,3,2,"SPR3BLK1.BIN" load the sprite 3 of the Bloc 2 (e.g. sprite 18/63)from the file "SPR3BLK1.BIN"* Example : SPRLOAD,3,"RAAHHHHH.SPR" load the block 3 (e.g. sprites 32 to 47) from file "RAAHHHHH.SPR"----'''SPRTORAM,SpriteAsic,SpriteRam* SpriteAsic=[0..15] SpriteRam=[0..63]* Copy the content of the current asic sprite in the sprite ram specified* See SPRLOAD/SPRSAVE instruction for block oragnisation.* Example : SPRTORAM,1,17 copy sprite asic 1 to sprite 17 of ram (e.g.in Block 2)----'''RAMTOSPR,SpriteRam,SpriteAsic* SpriteRam=[0..63] SpriteAsic=[0..15]* Copy the content of the sprite in ram in the current asic sprite specified* See SPRLOAD/SPRSAVE instruction for block oragnisation.* Example : RAMTOSPR,17,1 copy sprite sprite 17 of ram (2nd of bloc 2) in sprite asic 1----'''CATCHSPRCATCH,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).
* Example : CATCH,3,120,100 catch the pixels from 120,100 to 135,115 in sprite 3
----
'''INKCOPYSPRWHERE,SpriteNumber,@varx%,@vary%'''* Copy SpriteNumber=[0..15] varx=Name of x variable vary=Name of y variable* Get the whole colour screen palette 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 paletteor 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 Sprites1 - 0 to 15 16 to 31 80 to 952 - 0 to 15 32 to 47 96 to 1113 - 0 to 15 48 to 63 112 to 1274 - 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 Sprites1 - 0 to 15 16 to 31 80 to 952 - 0 to 15 32 to 47 96 to 1113 - 0 to 15 48 to 63 112 to 1274 - 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'''
'''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'''
* To erase the slavery of a sprite, use DEFORGXY instruction
----
'''SPRWHEREDEFKBDSPR, NumDef,SpriteNumber,@varx%KeyUp,@vary%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] varxSprite number / Keyxxxxx=Name of x variable vary[Key number] (see table), Stepxxxx=Name of y variablevalue 0..255 : Step in mode 2 pixel to add or substract associated value to corresponding key.* Get A key 0 indicate to do not test the xkey. When DEFKBDSPR is defined with all parameters,y coordinates of the specified sprite* Important note : varx process is automatic, and vary must be defined first like integer (declaration in so independent from basic with '%') and* they must be given program. It is possible to control manually the sprite movment by using the instruction "by address" without parameters ('@' before the variable nameautomatic mode is disactivated). The * declaration must* be respected to avoid unpredictibles results.* Example Note : 10 VARX%=0: VARY%=0 : SPRWHEREIf the user wants to cancel a definition,1it's better to disactivate the sprite with DEFKBDSPR,@VARX%NumDef,@VARY%: PRINT VARX%,VARY%255 instead of defining all keys with 0 (The B-Asic will gain cpu-speed).---
=== Others Instructions Set ===
----
* 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 ==