A complete Assembler, BASIC and 'C' Development Suite for the Atari Jaguar

Reference Manual - Updated: Feb 10th, 2023 - v1.11

Building

To create a new project and get going, open a command prompt in the JagStudio folder and type either 'build projectname newbasic' , 'build projectname newc' or 'build projectname newasm' (without quotes) where projectname is a unique name for your project.

The project files will be created in the relevant \projects\language\ folder ready for editing.  To run your project from that same command prompt type 'build projectname' and it'll run in VJ.

Linux users; see below.

General notes about build.bat:

• Automatically switches to ROM building if there is even one ROM asset in assets.txt. You can still use build BUILD PROJECT ROM though.
• Will abort build to RAM if the resulting binary is too large.
• When building a ROM, it will be padded up to 1, 2, 4 or 6mb depending on size.  Regardless of size, the Skunk will be forced into 6mb mode so only bank 1 can be used.

Command	Description
build (no parameters)	Lists all projects in the "projects" folder
build projectname newbasic	Creates a new BASIC language project in the \projects\basic\ folder.
build projectname newc	Creates a new C language project in the \projects\c\ folder.
build projectname newasm	Creates a new ASM language project in the \projects\asm\ folder.
build projectname	Builds project and runs it in the Virtual Jaguar emulator (VJ)
build projectname bigp	Builds project and runs it in the BigP Jaguar Emulator (best used for when testing EEPROM)
build projectname skunk	Builds project and uploads it to a Skunkboard
build projectname skunkabs	Builds and performs a quick upload of the ABS portion of the build while leaving the previous ROM on the Skunk. Beware: only run this if you haven't changed any ROM assets. Useful and faster to upload to the Skunk if you are using a ROM file but have not changed any assets within it.  This will just upload the code and any ABS assets.
build projectname jaggd	Builds project and uploads it to JagGD
build projectname ROM	Builds project as a ROM file. Assets in RAM are packed with the program code and depacked into RAM during boot. Assets in ROM simply are mapped inside ROM space.
build projectname ROM skunk	Builds project as a ROM file and uploads it to skunkboard. NOTE: THIS WILL OVERWRITE ANY ROM YOU HAVE ON BANK 1 OF YOUR SKUNKBOARD WITHOUT WARNING!
build projectname ROM jaggd	Builds project as a ROM file and uploads it to JagGD.
build projectname skunk bjl	Uploads built binary using bjl transfer (note: you might need to edit the upload settings). Will not work for ROM builds.
build projectname mrq Developername PublisherName Year	Create a JagGD MRQ file.  This uses the screen and box images from \projectname\assets\jaggd\ Example: build projectname mrq Devname Pubname 2021
build projectname ROM split	Build the ROM and split the output to HI and LO files

Building on Linux

We have included a bash script for Linux users called build.sh.  Please see the steps below to set up your environment.

1. Install Wine (distro-specific, on debian/ubuntu sudo apt install wine).
2. Make the bash script, jaggd, and jcp executable (chmod +x build.sh ; chmod +x buildfiles/bin/jaggd/jaggd-x64 ; chmod +x buildfiles/bin/jcp).
3. ./build.sh PROJECTNAME and enjoy!

NOTE: jcp may depend on libusb, most distributions have a libusb package.

assets.txt

This is the file where you declare all the main assets to be loaded for your project. Items such as graphics, sounds and music.
See the instructions in the assets.txt file on formatting those commands.  Please also refer to example projects.

For graphics, you typically want to create BMP images.  The JS build process will recognise these and convert them to the format required on the Jaguar.

 

Command	Description
Assets can be packed. Suffix field C with "_pack" in assets.txt	See file assets.txt Example project: pack
Examples
ABS,SPRITE_PLAYER,gfx_clut16,assets\gfx\sprite.bmp	In memory (ABS) create a new asset called SPRITE_PLAYER.  It is a 16 bit graphic and the path to the asset is assets\gfx\sprite.bmp
ROM,SPRITE_PLAYER,gfx_clut16,assets\gfx\sprite.bmp	On cart (ROM) create a new asset called SPRITE_PLAYER.  It is a 16 bit graphic and the path to the asset is assets\gfx\sprite.bmp
ABS,SPRITE_ENEMY,gfx_clut,assets\gfx\sprite2.bmp	In memory (ABS) create a new asset called SPRITE_ENEMY.  It is a CLUT (indexed) based graphic and the path to the asset is assets\gfx\sprite2.bmp

Asset Addressing

In some cases where you load or reference Assets, you need to address them differently depending if they are loaded from RAM (abs) or ROM.

 

Command	Description
RAM  (abs)	strptr(explode_sam)
ROM	(void *)(explode_sam)
Examples;
Play a sample from RAM (using Zero Player)	zeroPlay(1, strptr(explode_sam), strptr(explode_sam_end), (46168/8000), Zero_Audio_8bit_Signed)
Play a sample from ROM (using Zero Player)	zeroPlay(4, (void *)(gamemusic0), (void *)(gamemusic0_end), (46168/23084), Zero_Audio_Looping|Zero_Audio_8bit_muLaw)
Load a CLUT from a RAM Asset	jsfLoadClut(strptr(back1_clut),0,16)
Load a CLUT from a ROM Asset	jsfLoadClut((void *)(back1_clut),0,16)

General

Command	Description
Binary bitfields in basic	Just use B8(binary byte) for bytes, B16(binary byte,binary byte) words and B32(binary byte,binary byte,binary byte,binary byte) for longwords. Example: B8(11110000) is 240 in decimal.
rapNTSCFlag	is > 0 if machine is ntsc, otherwise it is PAL.
jsfSort(table,no_of_indices)	sorts an array of longwords from smallest to largest. Only longwords (4 byte integers) for now.
value = rapRND()	Get a random 24bit number.  This is more efficient than the BCX Basic RND. However, if used in critical code points it could impact performance. Examples: rapRND() & 255   (get a number between 0 and 255) rapRND() & 63   (get a number between 0 and 63) rapRND() & 1   (get a 0 or 1) See example project 'rndtest'.
jsfClearBuffer(int sizeInBytes, char *bufferAddress)	Clear a buffer in memory.  Not designed for performance, just function. Example: DIM gfxBuffer[352*240*2] AS CHAR jsfClearBuffer(352*240*2, strptr(gfxBuffer)) See example project 'jaguargd'
value = rapFlashCheck()	This will query the type of flash cart the game is running on.  value will contain FLASH_NONE, FLASH_SKUNK or FLASH_JAGGD.  You can then run specific code depending on the type returned. NOTE: This will only work for a ROM  (not abs). See example: flashcheck
Faster Multiply and Divide helpers	These are typically faster than the built in BCX commands, providing you are dealing with the appropriate size numbers.   NOTE: Some inputs must be shorts.
short = xdivs(int divid, short divis)	Divide divid by divis and return the answer as a short.
unsigned short = xdivu(unsigned int divid, unsigned short divis)	Divide unsigned divid by divis and return the answer as an unsigned short.
int = xmuls(int multid, short mults)	Multiply multid by mults and return an integer.
unsigned int = xmulu(unsigned int multid, unsigned short mults)	Multiply unsigned multid by mults and return an unsigned integer.

Sprites

See the section Colours / Fading if you are using sprites with a CLUT (graphics have less than 16 bit colours).

Command	Description
sprite[spr_index].property = value	Sets the property of object spr_index to value . See Table A for properties, their descriptions and user friendly names. Example: sprite[1].x = 10<<16
value = sprite[spr_index].property	Gets the property of object spr_index and saves it to value. See Table A for properties, their descriptions and user friendly names. Example: xposition = sprite[1].x
sprite[spr_index].x_ = 50	Set the X position of the sprite to 50 pixels from the left.  (NOTE: The x_ property means you don't need to <<16 shift the values)
sprite[spr_index].y_ = 30	Set the Y position of the sprite to 30 pixels from the top.  (NOTE: The y_ property means you don't need to <<16 shift the values)
sprite[spr_index].x = 50<<16	Set the X position of the sprite to 50 pixels from the left. Note: The X and Y position are actually stored as 16.16 fixed point numbers.  Therefore you can specify subpixel accuracy if required.
sprite[spr_index].xadd_ = 2	Automatically move 2 pixels to the right every refresh.  Also available as yadd_
sprite[spr_index].xadd = 2<<16	Automatically move 2 pixels to the right every refresh.  Also available as yadd.  Note: The X and Y ADD properties are actually stored as 16.16 fixed point numbers.  Therefore you can specify subpixel accuracy if required.
Other sprite properties are available.  Please see the list below.

Sprite manipulation

Command	Description
rapSetActiveList(listnum)	Set the active object list as defined in rapinit.s where listnum is zero based.  You only need to use this command if working with more than one list.  NOTE: If you use multiple lists, the sprites in the 2nd list will not have 0 based indexes.  The indexes continue from the previous lists.
address = rapSpriteTableStarts[16]	If using multiple lists, this array will contain the start address of each list.
jsfSprlistFieldSet(spr_index, property, no_of_times, array_of_values)	Will write integer values from address array_of_values, no_of_times times in raptor table property, starting with index spr_index.
jsfSprlistFieldMod(spr_index, property, no_of_times, array_of_values)	Will add integer values from address array_of_values, no_of_times times in raptor table property, starting with index spr_index.
jsfSprlistFieldSetval(spr_index, property, no_of_times, value)	Will write integer value no_of_times times in raptor table property, starting with index spr_index.
jsfSprlistFieldSetOffset(spr_index, property, no_of_times, array_of_values, skip_offset)	Exactly the same as jsfSprlistFieldSet but you can specify the number of sprites to skip between each.
jsfSprlistFieldModOffset(spr_index, property, no_of_times, array_of_values, skip_offset)	Exactly the same as jsfSprlistFieldMod but you can specify the number of sprites to skip between each.
jsfSprlistFieldSetvalOffset(spr_index, property, no_of_times, value, skip_offset)	Exactly the same as jsfSprlistFieldSetval but you can specify the number of sprites to skip between each.
rapSpriteShift(xshift, yshift, sprBug1, numOfSprites)	Move a consecutive list of sprites by xshift and yshift pixel amounts.    An efficient way to move multiple sprites at once (by the same amount). Starting from sprite named 'sprBug'.  numOfSprites is the total number of sprites you want to update including the first one (sprBug1). See example project 'spriteshift'
rapSortSprites(spriteIndex, sortProperty, totalSprites, sortDirection)	Sort a list of sprites for z ordering.  The sprites must be consecutive in the object list and MUST always have an active sprite before and after them. This must be called every frame and could have a minor impact on performance with a large sort list. Start sorting from sprite spriteIndex using the property sortProperty.  There are totalSprites to sort and we want to sort in sortDirection. Possible sort directions are; SPRSORT_HIGH       -       (highest values at the back) SPRSORT_LOW       -       (lowest values at the back) Example:  rapSortSprites(sprite1,R_sprite_y,8,SPRSORT_HIGH) This will start from sprite1, use the sprite Y positions to sort on. There are 8 sprites to sort and the highest Y values will be further back in the z-order. Please see the BASIC example project zsort.

Sprite Collision

Command	Description
value = rapCollide (startSprite, endSprite. startOtherSprite, endOtherSprite)	Check collision between two lists of sprites. 1st list:  startSprite , endSprite 2nd list: startOtherSprite , endOtherSprite Value will be greater than -1 if anything within the specified range has collided. This is only a general indication of a collision and further interrogation is required. You can either do this by looping all sprites and checking the 'was_hit' flag or by checking the collision list.  The collision list is generally more efficient for larger numbers of sprites. NOTE: When collision happens, the values of damage variables of the source sprites are deducted from the target sprites automatically. Raptor can be set to automatically kill an object when its hitpoint variable reaches -1 (dead) by setting the sprite variable 'remhit' to 'cd_remove'. The collision check will only work on sprites that have their 'colchk' variable set to 'can_hit', sprites that are set to 'cant_hit' will be skipped. See BASIC example projects 'collisionlist', 'shootbang' or 'doger'
Checking the was_hit flag	After calling rapCollide, you can loop over all sprites in the collision range and check if their was_hit flag is greater than -1.  If so, that sprite was hit. If you want this sprite to keep colliding, remember to reset the was_hit flag back to -1. See BASIC projects 'shootbang' or 'doger' as examples.
Collision List	Alternatively after calling rapCollide, the collision list will be populated with all sprites that collided.  The list contains the object addresses of the sprite that was hit and the sprite that hit it. This is generally more efficient than using the was_hit logic because you only need to loop over the collided sprites (not all of them). The collision list is accessed via the colliders array.  You can iterate over this list to get the sprite addresses; spriteWasHit = colliders[i].objectHitAddr spriteThatHit = colliders[i].objectSourceHitAddr You can then use the helper function to look up the sprite index from the address so that you can manipulate the sprite as needed. See BASIC example project 'collisionlist'
spriteIndex = jsfGetSpriteIndex(collisionSprAddr)	Get the list index of the sprite from its collision address (for use with the Collision List function). Example: collisionSprIndex = jsfGetSpriteIndex(colliders[i].objectHitAddr) sprite[collisionSprIndex].active = R_is_inactive See BASIC example project 'collisionlist'

Angle Calculations and direction lookup

The built in angle calculation and direction vector lookups can be used to look up a 0-511 'angle' between two points.  If required, you can then pass that angle into the helper function to retrieve the direction vector for that angle.

Command	Description
rapInitCalcAngle(calcAngleBuffer)	If you wish to use the angle lookup, you MUST call this function to initialise it.  You should only do this once. You must pass it a buffer of suitable size (65540 bytes) that it can populate with the relevant values. Eg.   DIM calcAngleBuffer[65540] as char rapInitCalcAngle(calcAngleBuffer) See example project 'calcangle'
angle = rapCalcAngle(x1, y1, x2, y2)	Look up the 0-511 'angle' between the pair of coordinates. 0 = East 128 = South 256 = West 384 = North NOTE: You must pass the integer portions of the positions such as 50 or 120.   NOT the sprite 16.16 x or y positions. See example project 'calcangle'
rapAngleVector(angle)	If you wish to know the direction vector for the angle result from the previous rapCalcAngle, pass the angle into this function. It will populate the two variables; rapAngle_xAdd and rapAngle_yAdd with the direction vector in 16.16 format. You can then scale these values as required for your purposes. Example: sprite[sprBug2].xadd = rapAngle_xAdd sprite[sprBug2].yadd = rapAngle_yAdd See example project 'calcangle'.

Pixel

Command	Description
jsfColour x	Set plot colour (0 - 15)
jsfPlot(x,y)	Plot pixel in coordinates x,y with the colour set using "jsfColour"
cls	Clears the pixel/print text buffer.  It calls the Raptor function rapParticleClear()

Sync

Command	Description
vsync	Waits till the next vertical blank (This is a BASIC convenience command for jsfVsync(0) )
jsfVsync(0)	Waits till the next vertical blank
jsfDelay(x)	Waits for x vertical blanks.

Memory

Command	Description
poke x,y	writes byte y to address x
peek(x)	returns byte from address x
dpoke x,y	writes word y to address x
dpeek(x)	returns word from address x
lpoke x,y	writes longword y to address x
lpeek(x)	returns longword from address x

Packing

Command	Description
rapUnpack(source_address,destination_address)	Unpacks data using the GPU from source_address to destination_address. Note that it's your responsibility to reserve enough RAM for unpacking. Also, no checking to see if a packed asset exists at the source address - again it's your responsibility! This is the default and fastest unpack routine. If any assets have issues, use jsfUnpack68k instead. Example: dim buffer[352*250*2/4] as integer ' Define a buffer in memory to hold a 352x250 16bit image. rapUnpack((int)strptr(source_image),(int)(int *)buffer) ' Unpack the packed image into the buffer.
jsfUnpack68k(source_address,destination_address)	Unpacks data using the 68000 from source_address to destination_address. Note that it's your responsibility to reserve enough RAM for unpacking. Also, no checking to see if a packed asset exists at the source address - again it's your responsibility! This is slower than the default unpacker but in some edge cases can be more compatible. Example: dim buffer[352*250*2/4] as integer ' Define a buffer in memory to hold a 352x250 16bit image. jsfUnpack68k((int)strptr(source_image),(int)(int *)buffer) ' Unpack the packed image into the buffer.

Clock / Timer  (See project 'clocktest' for an example)

Command	Description
rapSetClock(x)	Set the clock value to x seconds. Example: rapSetClock(0)
rapClockMode = mode	Set the current clock mode.  Values can be;  Clock_Freeze, Clock_Countdown, Clock_Countup Example: rapClockMode = Clock_Countdown
rapAddClock(value)	Add value seconds to the clock value. Example: rapAddClock(10)
rapSubClock(value)	Subtract value seconds from the clock value.
rapClockValue	The text representation of the current clock value; Example: rapPrint rapClockValue
rapClockHex	The numerical value of the current seconds. Example: jsfPrintInt rapClockHex
rapTicks	Number of ticks passed. Can also be set to a value or back to 0.

Blitter

Command	Description
rapBlitlist(pointer_to_blitlist).	Passes a list of blitting commands to raptor so they can be processed fast. pointer_to_blitlist contains an array of ints that have A1_BASE, A1_FLAGS, A1_CLIP, A1_PIXEL, A1_STEP_INT, A1_STEP_FRAC, A1_PIXEL_POINTER, A1_INC_INT, A1_INC_FRACT, A2_BASE, A2_FLAGS, B_PATD, A2_PIXEL, A2_STEP, B_COUNT, B_CMD. End the list with -1. Example project: blitline

Particles

Command	Description
rapParticleInject(address_of_particle_struct)	address_of_particle_struct points to a 6 column by user definable rows table of longwords. First row must have (0,0,0,x,y,no_particles) and the other the particle definitions (angle, speed, angular speed, initial colour, colour decay (per frame), pixel life (in frames)) See example projects: particles, spiral, starfield, starfield2

Tile Map module

NOTE: rapapp.s contains a group of equates that must be set up for Tile Maps to work correctly.   Look in rapapp.s for the section titled 'MAP MODULE SETUP EQUATES'.

See example project 'tilemap'

Command	Description
rapSetMapLoc(x,y)	Set map position to x,y. Where x and y are x<<16 and y<<16 Eg. rapSetMapLoc(10<<16,200<<16) See example project: tilemap
raptor_maptop_obj	Pointer to the first object in the map define
raptor_gmap_startx	32 bit screen position (in pixels) for where the left edge of the map will be drawn
raptor_gmap_starty	32 bit screen position (in pixels) for where the top edge of the map will be drawn
raptor_map_position_x	16.16 map co-ordinate (x).   NOTE: When using rapSetMapLoc(x,y), you don't need to set this variable directly.
raptor_map_position_y	16.16 map co-ordinate (y)   NOTE: When using rapSetMapLoc(x,y), you don't need to set this variable directly.
raptor_map_bitdepth	The bit depth of the tileset.  (Can be 1,2,4,8,16).  The default is 4 bit.  This is set in rapapp.s.
Creating Tile Maps for use in JagStudio.	We recommend Mappy

Colours / Fading

Command	Description
jsfLoadClut(palette_address,target_clut,number_of_indices)	Takes the palette values at address "palette_address" and copies them to CLUT "target_clut_number" (0 to 15). clut_number_of_indices tells the routine how many to copy. This routine can be used to set up anything from 2 to 256 palette indices at once. Eg. jsfLoadClut(strptr(STARS_clut),10,16) ' Loads the palette from the STARS asset into CLUT 10 where there are 16 colours. See example project: shootbang
rapFadeClut(int clut_no,int fade_cols,int *palette)	Fades CLUT clut_no (0-15) to CLUT values address palette . fade_cols is the number of CLUT entries to process. Note that fade_cols is 0 based, so to fade 16 cols pass 15. See example BASIC project fader.
rapFadeSingle(index_to_fade,desired_colour_in_16_bit_BBG)	Fades CLUT index index_to_fade to desired_colour_in_16_bit_BBG .
rapFadeDelay = x	Where x is the delay (in function calls) between steps
Font and Particle Palette Loading	See example project fontpalettes
rapUseParticlePalette(clutToPopulate)	Tell Raptor to load the 4 bit palette from the assets/partipal.bmp file into CLUT number clutToPopulate.
rapUse8x8fontPalette(clutToPopulate)	Tell Raptor to load the 4 bit palette from the assets/fonts/f_8x8.bmp file into CLUT number clutToPopulate. Example: rapUse8x8fontPalette(15)  -  This will load the 8x8 font palette into CLUT 15.
rapUse8x16fontPalette(clutToPopulate)	Tell Raptor to load the 4 bit palette from the assets/fonts/f_8x16.bmp file into CLUT number clutToPopulate.
rapUse16x16fontPalette(clutToPopulate)	Tell Raptor to load the 4 bit palette from the assets/fonts/f_16x16.bmp file into CLUT number clutToPopulate.

Strings

Command	Description
rapPrint "text here"	prints a static string to screen at coordinates set by rapLocate. No fancy formatting allowed (i.e. it'll only work with something like rapPrint "hello". rapPrint "hello"&"world" will fail). Font is set via jsfFontIndx and size from jsfFontSize.
rapPrintCont "more text here"	Continues printing from where previous rapPrint command ended. You can use font commands before this to change text style or colour mid sentence. No need to use rapLocate before this.
jsfPrintInt 64	Print an integer value.
rapNumToStr(number, digits, string$)	converts number with (digits+1) digits very fast and render it to string$. Note that the number has to be an integer. Example: rapNumToStr(987,2,out$) will convert number 987 to string using 3 digits and place it into out$. If we used 3 instead of 2 we'd get "0987"
print "text here"	Print text at location rapLocate and allow concatenation. Example: print "hiya! ",variablename," hello ",123.237462376
rapLocate x,y	Locates the cursor at coordinates x,y. Notice that those are pixel coordinates, not cursor coordinates.
jsfFontSize(index)	Changes Font Size - This is a zero based index that tells Raptor which font file to use from the Assets/Fonts folder.
jsfFontIndx(index)	Changes Font Color - This is a zero based index that tells Raptor which font to use from within the relevant font.bmp as picked by jsfFontSize.   NOTE: See the section above "Font and Particle Palette Loading" to see how to load different font palettes.

Highscores and data persistence

JagStudio can store up to 5 scoreboards and additional adhoc user data.  For Carts (ROMS) only a 2K eeprom will be supported - not any smaller.   See example projects eeprom, scores and scoresadvanced.

BigP Emulator supports 2K EEPROM saves - so we recommend using BigP instead of VJ when testing EEPROM.
To run your project in BigP use the command;   build projectname bigp
To set up BigP to use EEPROM in development mode;  1. When BigP Opens from the JagStudio command line, press ESC to access the main options menu.  2. Scroll down to "Developer" and then Enable "Local EEPROM".  This will ensure the .bigpeep EEPROM file is created alongside your .ROM / .ABS and also that the eeprom will work between different builds of your game (the ROM HASH will be ignored).

Command	Description
rapHighscoresScore	Points to the first highscore table (10 entries, one integer each)
rapHighscoresName	Points to the first highscore names table (10 entries, 8 characters each, not null terminated)
rapHiscoreCheck(score,name)	Checks if score is a high score. (name is 8 characters) Example; if rapHiscoreCheck(432,name$,0) > 0 then    'check for highscore in board 0 and inject score + name     call rapHiscoreSort(0,name$)                       'if we have a highscore, then sort the score table 0 endif
rapHiscoreSort(tableNumber,name)	Re-sorts the highscores as well as the names.  Will only sort tableNumber.
rapHighscores1Score & rapHighscores1Name	Point to individual highscore tables.  5 are available.  rapHighscores1Score to rapHighscores5Score and rapHighscores1Name to rapHighscores5Name See example projects EEPROM and scoresadvanced.
EEPROM (Cart persistent memory support)
eeprom_result = jsfEEPROMFullRead()	Read ALL 5 of the highscore tables from EEPROM into memory.  Stores the values in the rapHighscores1Score & rapHighscores1Name tables (all 5 tables).  This will read a checksum at the end of the scoreboards in the EEPROM, eeprom_result will be greater than 0 if the checksum failed. NOTE: If you also use the separate single scoreboard writes then this checksum is NOT updated and would be incorrect.
eeprom_result = jsfEEPROMFullWrite()	Save ALL 5 of the highscore tables to EEPROM. This will write a checksum at the end of the scoreboards in the EEPROM, eeprom_result will be greater than 0 if the checksum failed. NOTE: If you also use the separate single scoreboard writes then this checksum is NOT updated and will not be correct when you next perform a jsfEEPROMFullRead()
jsfEEPROMBoardRead(boardnumber)	Read a single scoreboard stored in position boardNumber. boardnumber should be between 0 to 4
jsfEEPROMBoardWrite(boardnumber)	Save a single scoreboard. boardnumber should be between 0 to 4
jsfEEPROMWordRead(eepromAddress)	We recommend using rapUserSaveData instead of this function for general use. Read a single WORD (short int) value from EEPROM.  The value is stored at eepromAddress on the EEPROM. Example:  value = jsfEEPROMWordRead(512)   . Value would contain the value stored at position 512.
jsfEEPROMWordWrite(eepromAddress, value)	Advanced (be careful!) - We recommend using rapUserSaveData instead of this function for general use. Save a single value  WORD (short int) to EEPROM at address eepromAddress.  eepromAddress should be between 511 and 1023. Example: jsfEEPROMWordWrite(512,123) - This will save the value 123 in the EEPROM (after the 5 scoreboards).  512 onwards should be free. NOTE:rapUserSaveData also stores values at 512 onwards.
jsfEEPROMUserDataRead()	Reads all 128 entries into the rapUserSaveData[] array.
jsfEEPROMUserDataWrite()	Writes all 128 entries contained in the rapUserSaveData[] array to EEPROM.
rapUserSaveData[128]	Array that points to 128 integers (long words) for storing user data.  These can be used to save game options, game progress or any other values you might want to persist between game boots. Example: See project eeprom
Original EEPROM Functions (left in for compatability).  Use the above functions instead of these.
jsfEEPROM(1,rapHighscoresScore)	Read ALL the highscore tables from EEPROM into memory.  Stores the values in the rapHighscores1Score & rapHighscores1Name tables (all 5 tables)
jsfEEPROM(0,rapHighscoresScore)	Save ALL the highscore tables to EEPROM.
eeprom_result = jsfEEPROMBoard(0,highscoreBoard,boardNumber)	Save a single scoreboard stored in the array highscoreBoard in scoreboard position boardNumber.  eeprom_result will be 0 is scores saved successfully.
eeprom_result = jsfEEPROMBoard(1,highscoreBoard,boardNumber)	Read a single scoreboard stored in position boardNumber and store the values in memory in array highscoreBoard.
jsfEEPROMWord(0,eepromAddress,value)	Advanced (be careful!) - Save a single value to EEPROM as address eepromAddress. Example: jsfEEPROMWord(0,560,123) - This will save the value 123 in the EEPROM after the 5 scoreboards.  560 onwards should be free.
value = jsfEEPROMWord(1,eepromAddress,0)	Read a single value from EEPROM.  The value is stored at eepromAddress. Example:  value = jsfEEPROMWord(1,560,0)   . Value would contain 123 if the above write had occurred.
Memory Track (CD persistent memory cart support)
rapMTInit	If you are using Memory Track, you must put this command at the beginning of your code. Example: CALL rapMTInit See example projects: scores and scoresAdvanced
value = rapMTPresent	Value is negative if no Memory Track is present. If you are using memory track, make sure you have used rapMTInit
rapUserSaveData[]	Points to 512 bytes for user data which will be appended to the MT save
rapMTSave	Saves the highscore table. Use it in combination with rapMTPresent and rapMTInit.

Debugging

This will display a debug window detailing the main 68K registers and 16 user defined watch variables.  It will also show a user defined string.

All values shown are in HEX.

By default, the 7-15 watch variables will point to; Ticks and NTSC flag, VBL Time remaining, last collision result, current active list, tilemap x, tilemap y, end of program data (BSS), Free RAM.

 

Command	Description
rapDebugSetXY(x,y)	Set the position of the Raptor debug window in pixels.
rapDebugPrint "This is some debug text"	Print some text in the debug window.  Maximum of 77 chars.
rapDebugSetVisible(DEBUG_SHOW)	Show or hide the debug window.  Valid options to pass in are DEBUG_SHOW or DEBUG_HIDE
rapDebugUpdate()	Tell Raptor that you want the debug values to update.
rapDebugInverse()	Switches between White background with black text and black background with white text.
jsfDebugMessage "Quick debug message"	Will automatically show the debug window with your text string.  Your program will keep running. NOTE: Call rapDebugSetXY(x,y) before using this.
jsfDebugMessageHalt "We have halted the application"	Will automatically show the debug window with your text string and also HALT your program from continuing.  NOTE: The background will intentionally strobe colours!! Also; Call rapDebugSetXY(x,y) before using this.
rapDebugSetMonitor(watchnumber, strptr(variabletowatch))	This will set up a watch over a variable of your choice.  You pass in the address of the variable, whenever a rapDebugUpdate() is called, Raptor will get the value at the variable and update it's debug values.  There are 16 watch numbers that you can set up (0-15). Example: rapDebugSetMonitor(0, strptr(sprite[sprBugIndex].x))   ' This will set up the first watch to peek at that sprites x position.
	See example project: debugview

Sound/input engines

Two sound and input engines are available.  Your project can only use one or the other; U-235 or Zerosquare.

To choose which engine to use, open your projects rapapp.s file and look at the very top for the line   player equ 0

Set that value to either;   0=Zerosquare's player, 1=U-235 player

JagGD

If you want to use the JaguarGD or GameDrive Cart from RetroHQ either for development or specific game features then see below;
See BASIC example project 'jaguargd'.

These features were added to the GD Cart firmware; v1.11, ASIC 1.08, Menu 1.08, Stub 1.04.
You must be using at least this version for all these functions to work.

EEPROM Saves when developing using JagStudio.  NOTE: EEPROM SAVES ARE CURRENTLY DISABLED AS THERE ARE BUGS IN THE GD FIRMWARE.  

If you use the jaggd command when building, JagStudio will now automatically add the -e switch to the command line.  This will create an e2p file on your SD Card and use that for your development build.

This gives you the ability to properly test EEPROM saves on your GD Cart between power cycles.

 

Command	Description
x = rapGDDetect	If x is set to 1 then the GD Cart has been detected. Eg. if rapGDDetect = 1 THEN Print "GD Detected"
x = rapGDCardInserted()	Detect if an SD Card is inserted.  If x = 1 then an SD Card is inserted.
rapGDSetLEDOn()	Turn the GD LED On.
rapGDSetLEDOff()	Turn the GD LED Off.
rapGDReset(resetcommand)	Reset the console using one of the following resetcommands; GD_RESET_NORMAL GD_RESET_MENU GD_RESET_DEBUG Example; rapGDReset(GD_RESET_MENU)
rapGDDebugPrint "string to print here"	Send this string message to the COM port for external debugging.  You can use something like "putty" to listen to the COM port and view the string messages sent from your Jaguar.
rapGDLoadFile(void *fullPathAddr, void *buffer)	Load the file and populate its contents into the buffer. Example; DIM gfxBuffer[352*240*2] AS CHAR DIM fullpath$ DIM success AS INTEGER fullpath$ = "\LOGO.JAG" success = rapGDLoadFile(strptr(fullpath$),strptr(gfxBuffer)) sprite[sprBackground].gfxbase = (int)gfxBuffer success=0 if the load worked.  If it's -1 then it failed. See example BASIC project 'jaguargd'
rapGDSaveFile(void *fullPathAddr, void *buffer, int size)	Save the contents of gfxBuffer to a file with the full path suppled Example; fullpath$ = "\LOGO.SAV" success = rapGDSaveFile(strptr(fullpath$),strptr(gfxBuffer),352*240*2)
Serial Numbers. rapGDGetCartSerial()	If you want to retreive the serial number of the users Cart then first call rapGDGetCartSerial() This will populate the internal variables with the relevant details.
rapGDASERIAL$	The internal variable used to store the ASCII GD serial.
rapGDSERIAL	The HEX GD serial number.
rapGDGetCardSerial()	Look up the SD Card Serial number.
rapGDSDSERIAL	SD Card serial number

Table A (sprite object properties)

These are the properties you can use to access a sprite from code. In the following example substitute 'property' with one of the values below (from 1st column); sprite[spr_index].property = value,
Eg.  Where spr_index is the number of the sprite to update (the position of the object in the rapinit.s file)
sprite[spr_index].active = R_is_active
sprite[spr_index].x = 100<<16
sprite[spr_index].y_ = 50
sprite[spr_index].wrap = R_edge_wrap

Offset's friendly name	Offset	Description	Possible Values (From code)
			If using in rapinit.s then exclude the R_ from the setting.
active	4	Show or hide the sprite	R_is_active R_is_inactive
x	8	x position in 16.16	100<<16     (would be 100 pixels from the left)
x_	10	x position (does not require 16.16 conversion)	100     (would be 100 pixels from the left)
y	12	y position in 16.16	100<<16     (would be 100 pixels from the top)
y_	14	y position (does not require 16.16 conversion)	100     (would be 100 pixels from the top)
xadd	16	x velocity to add in 16.16  (auto-move the sprite)	2<<16     (automatically move the sprite 2 pixels on X every frame)
xadd_	18	x velocity to add (does not require 16.16 conversion)  (auto-move the sprite)	2     (automatically move the sprite 2 pixels on X every frame)
yadd	20	y velocity to add in 16.16  (auto-move the sprite)	2<<16     (automatically move the sprite 2 pixels on Y every frame)
yadd_	22	y velocity to add (does not require 16.16 conversion)  (auto-move the sprite)	2     (automatically move the sprite 2 pixels on Y every frame)
flip	24	if set, add _width to X and set mirror	R_is_normal R_is_flipped
width	28	Width of sprite	In pixels
height	32	Height of sprite	In pixels
vbox	36	Height of collision box from centre in pixels	In pixels (does not change when scaling used)
hbox	40	Width of collision box from centre in pixels	In pixels (does not change when scaling used)
gfxbase	44	Pointer to phrase aligned sprite bitmap data
framesz	48	Size of sprite frame in bytes (offset to next frame)
framedel	52	Counter until the next anim frame advances
curframe	56	Current frame number (or 0 for no frames)
maxframe	60	Additional number of animation frames after the first
animloop	64	R_ani_rept = loop animation R_ani_once=terminate on loop	R_ani_rept R_ani_once
wrap	68	What the sprite will do when exiting the bounds of the screen.  R_edge_wrap = wrap round to the opposite side. R_edge_ignore = Ignore the edge and don't wrap (won't be visible when off screen but will be active). R_edge_kill = Automatically set the sprite as inactive when it leaves the screen.	R_edge_wrap R_edge_ignore R_edge_kill
timer	72	integer number of frames to stay alive, or R_spr_inf for infinite	R_spr_inf
track	76	R_spr_linear = use fract update, else pointer to x.y co-ords	R_spr_linear
colchk	80	R_cant_hit = no collision detection	R_can_hit R_cant_hit
scaled	84	R_spr_unscale = sprite is not scaled R_spr_scale = sprite will or can be scaled	R_spr_scale R_spr_unscale
scale_x	88	32 is 1:1. 0-31 are scaled down, 33-255 are scaled up.	32
scale_y	92	32 is 1:1. 0-31 are scaled down, 33-255 are scaled up.	32
CLUT	96	R_no_CLUT for no change, else use an integer of 0-15 if the sprite is less than 16bit colour.	R_no_CLUT or 0-15
animspd	100	Number of screen updates (VB) before the animation advances	Integer
bytewid	104	Width of one scanline of sprite in bytes
tracktop	108	Loop point for tracking, or -1 for exit	0
was_hit	112	Set to +ve if by the collision routine if sprite hit
coffx	116	Collision box x offset - pixel distance from centre of sprite
coffy	120	Collision box y offset - pixel distance from centre of sprite
remhit	124	R_cd_remove = Set the sprite as inactive if hit. R_cd_keep =  Leave the sprite active.	R_cd_remove R_cd_keep
bboxlink	128	R_single, or pointer to bounding box link data	R_single
hitpoint	132	Hitpoints of damage to take before removal
damage	136	Damage to deal
flash	140	Make sprite blink
gwidth	144	Graphics width
Rrmotion	148	Pointer to RMotion animation
rmcurfrm	152	RMotion internal
rmfrm	156	RMotion internal
bdepth	160	Bit Depth of sprite - Sprite graphics type: 1,2,4,8,16 or 24 bit	1,  2,  4,  8,  16,  24
cryrgb	164	If CRY colour space	R_is_RGB R_is_cry
trans	168	Trans for see-through background, opaque for solid background.  If <16bit then colour index 0 is used.  Otherwise black is used.	R_is_trans R_is_opaque
userdat1	172	Reserved for future expansion - Can be used to store extra information about the sprite.
userdat2	176	Reserved for future expansion - Can be used to store extra information about the sprite.
userdat3	180	Reserved for future expansion - Can be used to store extra information about the sprite.
userdat4	184	Reserved for future expansion - Can be used to store extra information about the sprite.

RB+ to JagStudio Manual Migration Guide    

1. COPY your entire game project folder over to Projects\Basic\ inside the JagStudio folder.

2.
a) If you haven't edited rapapp.s - Just copy over the latest version from JagStudio\buildfiles\template\ into your project folder.
b) If you have made changes that you cannot remember then do the following;

- Add the following line in the list of includes at the top (around line 18);

- Directly above the line jsr     RAPTOR_U235init    Add these two;

- Directly under the line RAPTOR_user_vbi:     Add these lines;

- Replace this single line     .uvbi_out:    rts     to the multiple lines;

- Rename the two occurrences of RUPDALL_FLAG to jsfVsyncFlag

- Directly above the section;    ;; Graphics   add in;

3. In all your .bas files, delete this line if you have it;      rlist=(RAPTOR_LIST *)strptr(RAPTOR_sprite_table)
4. In all your .bas files; Find and replace all the old commands to replace with new JagStudio versions.  See list below of old and new commands. NOTE: There are some syntax changes.
5. In all your .bas files; Change all RSETOBJ(objnum,prop,value) to sprite[objnum].prop = value
6. In all your .bas files; Change all value = RGETOBJ(objnum,prop) to value = sprite[objnum].prop
7. If you have any lines containing rlist[].property then rename to sprite[].property