Documentation - amaurycarvalho/msxbas2rom GitHub Wiki
Use -c parameter to compile your BASIC code into ROM.
Source code must be in plain text (ASCII) format.
Statements supported:
DEFDBL, DEFINT, DEFSNG, DEFSTR, DIM,
REM, END, CLS, BEEP, PRINT, INPUT, LINE INPUT,
GOTO, GOSUB, RETURN, SOUND, PLAY,
RANDOMIZE, LET, FOR/NEXT, DATA, READ, RESTORE,
IF/THEN/ELSE, IF/GOTO/ELSE, IF/GOSUB/ELSE,
LOCATE, COLOR, SCREEN, WIDTH, PSET, PRESET,
LINE, CIRCLE, PAINT, DRAW, OUT, POKE, VPOKE
SPRITE$, PUT SPRITE, ON...GOSUB, ON...GOTO,
SWAP, WAIT, ON INTERVAL GOSUB, INTERVAL ON/OFF,
ON KEY GOSUB, KEY ON/OFF, KEY() ON/OFF,
ON STRIG GOSUB, STRIG() ON/OFF,
ON SPRITE GOSUB, SPRITE ON/OFF,
STOP, STOP ON/OFF, ON STOP GOSUB, CMD,
SET SCROLL, SET PAGE, COPY, PUT TILE,
SET TILE COLOR, SET TILE PATTERN,
OPEN, CLOSE, MAXFILES, DEF USR, BLOAD,
PRINT USING, SET VIDEO, COPY SCREEN
[RUN]
Functions supported:
INT, FIX, RND, SIN, COS, TAN, ATN, EXP,
LOG, SQR, VAL, TIME, SGN, ABS, ASC, INKEY,
LEN, CSNG, CDBL, CINT, CHR$, INKEY$, INPUT$,
SPACE$, SPC, TAB, STRING$, STR$, LEFT$, RIGHT$, MID$,
INSTR, OCT$, HEX$, BIN$, PEEK, VPEEK, INP, POS, LPOS,
CSRLIN, STRIG, STICK, PDL, PAD, BASE, VARPTR,
PLAY, VDP, POINT, COLLISION, FRE, HEAP, TILE,
RESOURCE, USR, PSG, MSX, NTSC, TURBO, MAKER,
USING$, PLYSTATUS
TIME and MID$ assignments
VDP assignment
Data types, operators and operations supported:
Integer, Float, String, Fixed Bidimensional Arrays
Math expressions and basic operators (+-*/^)
OR, AND, XOR, EQV, IMP, NOT, MOD, SHL, SHR
&h0000, &o0000, &b00000000
Limitations and differences:
- Minimum hardware requirements for compiled programs:
* MSX1 machine (with ROM BIOS and ROM BASIC);
* 16kb of RAM for running as Cartridge without resources;
* 32kb of RAM for running as Cartridge with resources;
* 64kb of RAM for running with ExecROM (for 32kb ROMs) or ODO
(for 48kb ROMs) via disk driver or Caslink3/CASDuino/MSX2CAS
via cassete;
* 64kb Memory Mapper and/or MegaRAM for running with SofaRun;
* MegaROM compiled mode needs a Memory Mapper and/or MegaRAM with
at least the same size as the final ROM for running it in memory
with ExecROM (note: not required for running as Konami SCC
Cartridge in emulators);
- Partial file support (OPEN "GRP:", PRINT #...);
- No dynamic arrays (REDIM);
- No variant data type (only string, integer and single);
- All variables has an unique data type (dont change in runtime);
- Variables are not initialized at startup (do it yourself);
- Default data type is single (use DEFINT A-Z to modify it to integer);
- Singles cannot be used with boolean operations;
- Printing numerical decimal values above 9999 will result in
scientific notation;
- Printing will not wrap the full numeric data on the next line,
instead it will just wrap the characters that don't fit.
- CIRCLE tracing and aspect parameters not supported;
- STOP works like END;
- CMD WRTSCR/CMD WRTCHR activate the tiled mode in screen 2, forcing text
mode coords;
- LOCATE/PRINT works in graphical mode (screen 2+) without use of
OPEN 'GRP:'. When in screen 2 tiled mode, it works similar as text
mode coords (faster output);
- PUT TILE <char>, (x,y) - for tiled mode used with screens 0-2;
- COPY works only with graphical parameters (no files support) just
like: COPY (x0,y0)-(x1,y1) TO (x2,y2);
COPY ... TO <ram address> / COPY <ram address> TO ... is accepted
instead of COPY <array>... (try HEAP() as <ram address>);
When in screen 2 tiled mode, it works with text mode coords;
- IDATA (integer data) and IREAD (integer read) works similar as DATA/READ
but use less ROM memory and its faster. Use IRESTORE <position> to
change the pointer position on binary files resources;
- BLOAD works only to load standard screen files (.SCn) and TinySprite
compatible files (.SPR). You need to inform a file name as literal (no
via variables) because it will be loaded into ROM (it will activate
MegaROM mode). Ex: BLOAD "file.sc5", S;
- RANDOMIZE statement (without parameters) works like a RND(-TIME)
function;
- FRE() return free RAM size only (doesnt accept parameters);
- HEAP() return first free RAM address;
- TILE(x,y) return character from position (screens mode 0-2);
- MSX() return current machine version (0: MSX1, 1: MSX2,
2: MSX2+, 3: MSXturboR);
- NTSC() return true to a NTSC (or PAL-M) machine and false to a PAL one;
- TURBO() return true to cpu turbo mode (R800 or 5.37mhz) or false
to standard mode (Z80/3.57mhz). Use with CMD TURBO...
- VDP() without parameters return VDP version (0: TMS9918A, 1: V9938,
2: V9958, x: VDP ID);
- MAKER() return the manufacturer ID [1:ASCII/Microsoft, 2:Canon, 3:Casio,
4:Fujitsu, 5:General, 6:Hitachi, 7:Kyocera, 8:Matsushita (Panasonic),
9:Mitsubishi, 10:NEC, 11:Nippon Gakki (Yamaha), 12:JVC, 13:Philips,
14:Pioneer, 15:Sanyo, 16:Sharp, 17:SONY, 18:Spectravideo, 19:Toshiba,
20:Mitsumi, 21:Telematica, 22:Gradiente, 23:Sharp Brazil,
24:GoldStar(LG), 25:Daewoo, 26:Samsung,
212:1chipMSX/Zemmix Neo(KdL firmware)];
Works only in some MSX2 machines;
- RESOURCE(number) return resource start address (use with COPY);
- COLLISION() return if any sprite collided with another sprite, else
return -1;
- COLLISION(<n>) return if a sprite <n> collided with another sprite,
else return -1;
- COLLISION(<n1>,<n2>) return n2 if sprite n1 collided with n2, else
return -1;
- INKEY() is an alternative to INKEY$, but returning an integer instead;
- IPEEK()/IPOKE is similar to PEEK()/POKE, but applied for integer data;
- DATA statements allocate space in resources page and will be compiled to
a 48kb ROM;
- PRINT USING support only numerical formatting symbols (#+-.*$,^0) and
works the same way as USING$() function. For exponential display,
include more # in the format string until the correct value is
displayed. Use 0 char symbol to fill the value with left zeros;
- USING$(format$, number) works just like PRINT USING statement;
- SET/GET DATE and SET/GET TIME adopts a customized syntax;
- F1..F10 function keys return ASCII codes 246 to 255 respectively;
- Spaces on your line code, REMs and blank lines not affect compiled code
size, but if your include it on your program it can help the compilation
process (not need for strip spaces from your code anymore);
- Resources total size are limited to 16kb (for FILE directive), and
when compiled generates 48kb ROMs thats can run as cartridge or in RAM
with SofaRUN or ODO loaders (ExecROM do not support this ROM size);
- Arkos Tracker 2 player use the minimalist binary file (AKM and AKX),
with songs composed to play at 50hz, exported at 0100 address, and must
be included as the first resource in the list (AKM as 1st and AKX as 2nd);
- PT3 player support is now deprecated, dont use it. Also, it cannot be
used in concurrence with Arkos Tracker 2 player too.
Statements not supported:
AUTO, BLOAD, BSAVE, CALL, CLOAD,
CONT, CSAVE, DEF FN, DELETE, EOF, ERASE,
ERL, ERR, ERROR, FILES, FN, FPOS, FIELD,
GET, GET DATE, GET TIME, IPL, LIST, LLIST,
LOAD, LOC, LSET, LPRINT, MERGE, RSET,
MOTOR, NEW, PUT, PUT KANJI, RENUM, RUN, SAVE,
SET ADJUST, SET BEEP, SET DATE, SET PASSWORD,
SET PROMPT, SET SCREEN, SET TIME,
SET TITLE, TROFF, TRON,
RESUME, ON ERROR GOTO, CLEAR
TEXT <text>
FILE <file name>
INCLUDE <file name>
Play a text resource with Basic (xbasic compatible, channel C disabled to use with SOUND command)
CMD PLAY <rsn>[, <channel C: 0=off|1=on>]
Mute the PSG (for PLAY use)
CMD MUTE
Draw a text resource with Basic (xbasic compatible)
CMD DRAW <rsn>
Exec a binary uncompressed resource as an assembly code
CMD RUNASM <rsn>
- There is a limit of 256k for the Assembly code;
- All jumping instructions must be relative (JRs instead of JPs);
- No CALLs to addresses inside the program are allowed.
Exec a text resource as a plain text basic code (must start with ':')
CMD RUNBAS <rsn>
Write a compressed resource (pletter) to VRAM address
CMD WRTVRAM <rsn>, <VRAM address>
Write a compressed .ALF resource (pletter) to VRAM font pattern table
CMD WRTFNT <rsn>
Write a compressed resource (pletter) to VRAM tile pattern table
CMD WRTCHR <rsn>
Write a compressed resource (pletter) to VRAM tile color table
CMD WRTCLR <rsn>
Write a compressed resource (pletter) to VRAM screen table
CMD WRTSCR <rsn>
Write a TinySprite (msx.jannone.org) compatible resource (.SPR) to VRAM sprite pattern and color tables
CMD WRTSPR <rsn>
- Export your sprites as a Backup and save it as .SPR text file;
- Use with sprite parameter size 2 or 3 on SCREEN statement;
- You can use, alternativally: BLOAD "file.spr",S
Write a compressed resource (pletter) to VRAM sprite pattern table
CMD WRTSPRPAT <rsn>
Write a compressed resource (pletter) to VRAM sprite color table
CMD WRTSPRCLR <rsn>
Write a compressed resource (pletter) to VRAM sprite attribute table
CMD WRTSPRATR <rsn>
Write RAM to VRAM address
CMD RAMTOVRAM <RAM address>, <VRAM address>, <size>
Write VRAM to RAM address
CMD VRAMTORAM <VRAM address>, <RAM address>, <size>
Write RAM to RAM address
CMD RAMTORAM <RAM source address>, <RAM dest address>, <size>
Write RESOURCE to RAM address
CMD RSCTORAM <resource>, <dest address> [, <pletter? 0=no, 1=yes>]
Inhibits the screen display
CMD DISSCR
Display the screen
CMD ENASCR
Turn off keyboard clicks (for xbasic use)
CMD KEYCLKOFF
Clear keyboard buffer and reset joysticks ports
CMD CLRKEY
Fill screen 2 with spaces to use with SETFNT/PRINT
CMD CLRSCR
Load internal FONTs to VRAM font pattern table (screen mode >= 1)
CMD SETFNT <style number>[, <bank:0-2|empty=all>]
0 = BIOS default font
1 = Compile Zanac Style
2 = Konami Gradius Style 1
3 = Konami Gradius Style 2
Update tiled font color with current fore/background COLOR
CMD UPDFNTCLR
Set clipping on and off (screen modes 5 through 8, and same as '#C of xbasic)
CMD CLIP <0=off | 1=on>
Activate cpu turbo mode (R800 or 5.37mhz)
CMD TURBO <0=off | 1=on>
Set READ statement to get lines from a text resource file (.TXT or.CSV) informed on FILE directive
CMD RESTORE <resource number>
- Use normal RESTORE <line number> and READ statements to read any specific line from the resource text;
--- Line number zero is the first line on the resource text;
--- Each line on TXT files will be treated like an unique string;
--- Each line on CSV files will be treated like a DATA content;
- Use IRESTORE <byte number> and IREAD to read binary resources.
Enable/disable a page alternating effect on screen mode 5 and above via VDP R#1 (Cadari Bit) and R#13. Pass 0 to stop the effect.
CMD PAGE <mode: 0=swap, 1=wave>, <delay #1: 0-15, 0=stop> [, <delay #2: 0-15, default=same as delay #1>]
Put a tile character into screen position (for tiled mode, screens 0-2)
PUT TILE <n>, (<x>,<y>)
Set tile color (for tiled mode, screens 1, 2 and 4)
SET TILE COLOR <n>, <forecolor>, <backcolor> [, <bank:0-2, default=3=all>]
SET TILE COLOR <n>, (<fc0>,...,<fc7>), (<bc0>,...,<bc7>) [, <bank:0-2, default=3=all>]
Set tile pattern (for tiled mode, screens 0, 1, 2 and 4)
SET TILE PATTERN <n>, (<l0>,...,<l7>) [, <bank:0-2, default=3=all>]
Enable/Disable tiled mode (screens 2 and 4, for use with PRINT)
SET TILE <ON|OFF>
Set sprite color (msx2)
SET SPRITE COLOR <n>, (<fc0>,...,<fc15>)
Set sprite pattern for a quadrant
SET SPRITE PATTERN <n>, <q:0-3>, (<l0>,...,<l7>)
Flip a sprite pattern
SET SPRITE FLIP <n>, <dir: 0=horizontal, 1=vertical, 2=both>
Rotate a sprite pattern
SET SPRITE ROTATE <n>, <dir: 0=left, 1=right, 2=180 degrees>
Copy screen to array (only for modes 1, 2 and 4)
SCREEN COPY TO <array> [SCROLL <direction>]
*direction = same as STRIG
Copy array to screen (only for modes 1, 2, and 4)
SCREEN PASTE FROM <array>
Do a screen scroll (only for modes 1, 2 and 4)
SCREEN SCROLL <direction>
*direction = same as STRIG
Load a screen resource
SCREEN LOAD <resource>
Load a sprite resource
SPRITE LOAD <resource>
Load internal FONTs to VRAM font pattern table (screen mode >= 1)
SET FONT <style number>[, <bank:0-2|empty=all>]
0 = BIOS default font
1 = Compile Zanac Style
2 = Konami Gradius Style 1
3 = Konami Gradius Style 2
SET/GET DATE/TIME customized syntax
SET DATE iYear%, iMonth%, iDay%
SET TIME iHour%, iMinute%, iSecond%
GET DATE iYear%, iMonth%, iDay% [, iWeekDay% [, iDateFormat%]]
GET TIME iHour%, iMinute%, iSecond%
Code Date Format
0 YY/MM/DD
1 MM/DD/YY
2 DD/MM/YY
Week day: 0=Sunday
Get resource data address
<address> = RESOURCE(<rsn>)
tokenized mode: <address> = USR0(<rsn>)
Get resource data size
<size> = RESOURCESIZE(<rsn>)
tokenized mode: <size> = USR1(<rsn>)
Multifunction alternatives
PLAY() function alternative (for tokenized mode)
<0=false> = USR2(0)
INKEY$ function alternative (for tokenized mode)
<ASC> = USR2(1)
INPUT$(1) function alternative (for tokenized mode)
<ASC> = USR2(2)
AKM PLAYER STATUS (bit 7 = end of song reached, bit 0 = loop status)
<STATUS> = PLYSTATUS()
tokenized mode: <STATUS> = USR2(3)
Read PSG register
n = PSG( <register number> )
Sprite Collision Detection
<-1=no collision|collided sprite number> = COLLISION( <-1=any sprite | sprite1> [, <sprite2> ] )
tokenized mode: <-1=no collision|collided sprite number> = USR3( <-1=any sprite | sprite1 | &h1122> )
Examples
Beep if any sprite collided with each other:
SN# = COLLISION(-1)
IF SN# >= 0 THEN BEEP
Beep if any sprite collided with sprite 2:
SN# = COLLISION(2)
IF SN# >= 0 THEN BEEP
Beep if sprite 4 collided with sprite 5:
SN# = COLLISION(5)
IF SN# = 4 THEN BEEP
Beep if sprite 5 collided with sprite 4 (direct test):
SN# = COLLISION( 5, 4 )
IF SN# >= 0 THEN BEEP
Beep if sprite 0 collided with sprite 1 (direct test):
SN# = COLLISION( 0, 1 )
IF SN# >= 0 THEN BEEP
Notes
Sprites with same X and Y position are considered the same object, thus there's no collision in this case.
Load an AKM (songs) and AKX (effects) uncompressed files resources in memory setting up the first song to play
CMD PLYLOAD <AKM resource number:0-n> [, <AKX resource number:0-n>]
Initialize a song from the previous AKM resource loaded
CMD PLYSONG [<subsong number:0-n>]
Play/continue a song in memory
CMD PLYPLAY
Mute/pause a song in memory
CMD PLYMUTE
Play a sound effect from the previous AKX resource loaded
CMD PLYSOUND <sound effect number:1-n> [, <channel number:0-2> [, <volume:0-16>] ]
Set the song loop status
CMD PLYLOOP <0=off | 1=on>
Restart a song in memory (after stopped by loop turned off)
CMD PLYREPLAY
Click on here to get the presentation.