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

Reference Manual - Updated: Feb 4th, 2021 - v1.0

Reference Manual

Please refer to the Quickstart Guide for a brief walkthrough on setting up a BASIC project.


JagStudio supports BASIC, C and Assember languages.  This reference manual is written aiming towards BASIC, however, the same functions are available to C and ASM too.  The syntax for those will be different when calling JagStudio functions.


This is not designed to be a comprehensive guide - it only covers the commands, functions and variables introduced in JagStudio.

It does not cover BCX functions, commands and syntax. For that you are kindly referred to read the bcx help file, "BCXHelp.chm" or browse the example projects.

For further information please visit the official site at jagstudio.reboot-games.com or the forums over at AtariAge.


Index

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.

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 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

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 conversion tool will recognise these and convert them to the format required.

 

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

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'.
Faster Multiply and Divide helpersThese 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

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.


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 futher 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

Map module

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
Creating Tile Maps 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

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: bin2asc(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 concatination.

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

Highscores and data persistence

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

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, like above, is 8 characters.
Example;
if rapHiscoreCheck(432,name$,0) > 0 then    'check for highscore and inject score + name
    call rapHiscoreSort(0)                                    'if we have a highscore, then sort the first table (0)
endif
rapHiscoreSort(tableNumber) 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 project scoresadvanced.
EEPROM (Cart persistent memory support)
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
raptor_user_savedata 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.
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!!
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

Universal PAD Input - These commands can be used with both U235 and Zerosquare

Command Description
value = jsfGetPad(padID)

The value returned from this command will repeat when the buttons are held down.  This is ideal for general gameplay movement where the player would be holding a direction or firebutton.

Returns values from either pad 1 or 2. padID can be LEFT_PAD or RIGHT_PAD

Example:

pad1 = jsfGetPad(LEFT_PAD)

Check dpad up: "if pad1 BAND JAGPAD_UP then"

Check button A is held down: "if pad1 BAND JAGPAD_A then"

value = jsfGetPadPressed(padID) The value returned from this command will be a single press (debounced).  Therefore, it will always just return the last button pressed down.  This is ideal for menus where you might not want the player to hold down the button to move something, but rather have to keep pressing a button.

Returns values from either pad 1 or 2. padID can be LEFT_PAD or RIGHT_PAD

Example:

pad1 = jsfGetPadPressed(LEFT_PAD)

Check dpad up: "if pad1 BAND JAGPAD_UP then"

Check button A was pressed: "if pad1 BAND JAGPAD_A then"

Direction pad masks

JAGPAD_UP, JAGPAD_DOWN, JAGPAD_LEFT, JAGPAD_RIGHT, JAGPAD_A, JAGPAD_B, JAGPAD_C, JAGPAD_PAUSE, JAGPAD_OPTION, JAGPAD_0, JAGPAD_1, JAGPAD_2, JAGPAD_3, JAGPAD_4, JAGPAD_5, JAGPAD_6, JAGPAD_7, JAGPAD_8, JAGPAD_9, JAGPAD_STAR,JAGPAD_HASH

U-235

Command Description
u235PlayModule(mod_address,format)

plays a .mod file at address "mod_address" in either mono or stereo.

"format" can be MOD_STEREO or MOD_MONO

Example: u235PlayModule((int)strptr(Module1),MOD_STEREO)

where Module1 is an asset in abs.

Example project: u235_Test
u235StopModule() stops .mod playing
u235GetPad(padID)

This is the specific U235 pad input. It returns values from either pad 1 or 2. padID can be LEFT_PAD or RIGHT_PAD

For standard pad input you should just use the universal function jsfGetPad(padID).
u235PlaySample(int channel,int sfxnum) triggers sampleno on channel
u235PlaySampleFreq(channel,sampleno,frequency) triggers sampleno on channel at frequency in Hz
u235ModuleVol(x) sets mod music volume (x in range 0 - 63)
u235SampleVol(x) sets global sfx volume (x in range 0 - 63)
u235KillChannel(x) stops playing sample at channel number x
u235ChannelVol(channel,volume) set or adjust the volume on channel to volume (0 to 63)
u235ChannelFreq(channel,frequency) sets frequency of channel (0 to 65535)
rotary_mode1 +1 = rotary, - 1 = jagpad (Port 1) (.l)
rotary_mode2 +1 = rotary, - 1 = jagpad (Port 2) (.l)
turn_direction1 rotary value (bigger is faster) - +=left / 0=nothing / - =right (Port 1) (.l)
turn_direction2 rotary value (bigger is faster) - +=left / 0=nothing / - =right (Port 2) (.l)
rotary_interval1 trim value for rotary (Port 1) (.l)
rotary_interval2 trim value for rotary (Port 2) (.l)
spin_delta1 value to add to turn_direction per increment (Port 1) (.l)
spin_delta2 value to add to turn_direction per increment (Port 2) (.l)
value = u235Rnd Return a random number from U235SE.  NOTE: A random number will only be generated if U235 is running.  For example, playing a mod or sfx.
Direction pad masks

PAD_UP, PAD_U, PAD_DOWN, PAD_D, PAD_LEFT, PAD_L, PAD_RIGHT, PAD_R, PAD_HASH, PAD_9,
PAD_6, PAD_3, PAD_PAUSE, PAD_A, PAD_OPTION, PAD_STAR, PAD_7, PAD_4, PAD_1, PAD_0, PAD_8, PAD_5, PAD_2, PAD_B, PAD_C
u235Restart(int rate,int period) Stop and restart U235 at the desired rate and period.  See tables below for values.
NOTE: changing to a higher frequency can impact performance.
eg. u235Restart(U235SE_16KHZ,U235SE_16KHZ_PERIOD)
u235Init(int rate,int period) Start U235 at the desired rate and period.  See tables below for values.
NOTE: changing to a higher frequency can impact performance.
eg. u235Init(U235SE_16KHZ,U235SE_16KHZ_PERIOD)
u235StopDSP() Stop U235 from running. 


Rate Values

Command Description
U235SE_8KHZ Set playback rate  (8.1kHz)
U235SE_12KHZ Set playback rate  (12.060kHz)
U235SE_16KHZ Set playback rate  (16.446kHz)
U235SE_24KHZ Set playback rate  (24.67kHz)
U235SE_32KHZ Set playback rate  (31.925kHz)


Period Values

Command Description
U235SE_8KHZ_PERIOD 8kHz period
U235SE_12KHZ_PERIOD 12kHz period
U235SE_16KHZ_PERIOD 16kHz period
U235SE_24KHZ_PERIOD 24kHz period
U235SE_32KHZ_PERIOD 32kHz period




Zerosquare Player

Command Description
zeroGetPad(padID)

reads both pad ports and sends results back to variables zero_left_pad, zero_right_pad, zero_mousex_delta, zero_mousey_delta and zero_rotary_delta. padID can be LEFT_PAD or RIGHT_PAD. By default the engine is configured to assume 2 joypads connected.

For standard pad input you should just use the universal function jsfGetPad(padID).

example projects: zero_Test, chessboard, print
zeroSetNormalPadMode() sets up the engine to read two pads (enabled by default).
zeroSetJoyPort1() enables joypad port 1 to be used for rotary/mouse input. This doesn't enable rotary/mouse mode. zero_rotary_delta will give the number of rotary ticks since the last read command.
zeroSetJoyPort2() enables joypad port 2 to be used for rotary/mouse input. This doesn't enable rotary/mouse mode. zero_rotary_delta will give the number of rotary ticks since the last read command.
zeroSetRotaryMode() enables rotary mode.
zeroSetAtariMouseMode enables Atari mouse mode. Input_Mouse_Left and Input_Mouse_Right are the masks to check for button presses zero_mousex_delta, zero_mousey_delta are the number of mouse ticks in x and y axis since the last read command.
zeroSetAmigaMouseMode enables Amiga mouse mode. Input_Mouse_Left and Input_Mouse_Right are the masks to check for button presses zero_mousex_delta, zero_mousey_delta are the number of mouse ticks in x and y axis since the last read command.
zeroPlay(channel,start_address, end_address, frequency, params) plays a sample starting from start_address and ending at end_address on channel with speed frequency and with flags params.
Channel should be from 1 to 4.
Frequency should be an integer that divides the base frequency of 46168Hz. So for example if it's set to 1, it'll play a sample at 46168Hz, a 2 will play a sample at 23084Hz etc.

Example: zeroPlay(1, strptr(explode_sam), strptr(explode_sam_end), (46168/8000), Zero_Audio_8bit_Signed)

Example: zeroPlay(1, strptr(music), strptr(music_end), (46168/22050), Zero_Audio_Looping|Zero_Audio_8bit_muLaw)

Example project: zero_Test
zeroPlaySample(channel,start_address, len, frequency, params)

plays a sample starting from start_address with length len to channel chan with speed frequency and with flags params. Channel should be from 1 to 4. start_address should be aligned to 4 bytes. len should be a multiple of 4. frequency should be an integer that divides the base frequency of 46168Hz. So for example if it's set to 1, it'll play a sample at 46168Hz, a 2 will play a sample at 23084Hz etc.

Example: zeroPlaySample(1, strptr(explode_sam), (strptr(explode_sam_end)-strptr(explode_sam)+3) and 0xfffffffc, (46168/8000), Zero_Audio_8bit_Signed)

Example project: zero_Test

Available flags are:
  • Zero_Audio_8bit_Signed (plays an 8-bit signed sample)
  • Zero_Audio_8bit_Unsigned (plays an 8 - bit unsigned sample)
  • Zero_Audio_8bit_muLaw (plays a 8 - bit compressed ?w sample)
  • Zero_Audio_Looping (enables sample loop).
zeroClearChannel(channel) Stops all audio on channel
Channel should be from 1 to 4.
Direction pad masks Input_Pad_Pause, Input_Pad_A, Input_Pad_Up, Input_Pad_Down, Input_Pad_Left, Input_Pad_Right, Input_Pad_C1, Input_Pad_B, Input_Pad_Star, Input_Pad_7, Input_Pad_4, Input_Pad_1, Input_Pad_C2, Input_Pad_C, Input_Pad_0, Input_Pad_8, Input_Pad_5, Input_Pad_2, Input_Pad_C3, Input_Pad_Option, Input_Pad_Sharp, Input_Pad_9, Input_Pad_6, Input_Pad_3

Pro Controller Support

The Pro Controller buttons all map to the existing standard Jag Pad controller.  This was by design of the original hardware and cannot be changed in JagStudio.
Therefore, see the table below to know which buttons to check to support the Pro Controller.
We have supplied helper names for the additional buttons, but keep in mind they map to the existing number pad buttons.

Command Description Helper Names
Shoulder Button Left Number Pad 4 JAGPAD_TL
Shoulder Button Right Number Pad 6
 JAGPAD_TR
X Number Pad 9 JAGPAD_X
Y Number Pad 8 JAGPAD_Y
Z Number Pad 7 JAGPAD_Z

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);
include "RAPTOR235.INC"
- Directly above the line jsr     RAPTOR_U235init    Add these two;
move.l    #U235SE_16KHZ,d0
move.l    #U235SE_16KHZ_PERIOD,d1
- Directly under the line RAPTOR_user_vbi:     Add these lines;
if player=1
jsr        RAPTOR_U235playqueue
endif
- Replace this single line     .uvbi_out:    rts     to the multiple lines;
.uvbi_out:
if player=1
jsr        RAPTOR_U235resetqueue
endif
rts
- Rename the two occurances of RUPDALL_FLAG to jsfVsyncFlag
- Directly above the section;    ;; Graphics   add in;
if player=0
include "jagstudio_pad_zero.inc"
else
include "jagstudio_pad_u235.inc"
endif

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

List of OLD commands and their NEW names

RB+ Command JagStudio Command (rename to)
RSETOBJ(objnum,property,value) Removed - use sprite[objnum].property = value   instead
value = RGETOBJ(objnum,property) Removed - use value = sprite[objnum].property instead
SNDPLAY(int sampleno,int channel) u235PlaySample(int channel,int sfxnum)
ZEROPAD() jsfGetPad(pad) - Global pad reader for u235 and Zero. Where pad is LEFT_PAD or RIGHT_PAD
zero_left_pad / zero_right_pad These are no longer needed as the pad values are populated by jsfGetPad(pad)
GETPAD(padnum) jsfGetPad(pad) - Global pad reader for u235 and Zero. Where pad is LEFT_PAD or RIGHT_PAD
powaset
 jsfSprlistFieldSet
powadiff jsfSprlistFieldMod
powazap jsfSprlistFieldSetval
powabset jsfSprlistFieldSetOffset
powabdiff jsfSprlistFieldModOffset
powabzap jsfSprlistFieldSetvalOffset
powaunpack jsfUnpack (you can also use jsfUnpack68k)
powablitlist REMOVED - Use rapBlitList which is now the full version.
fullpowablitlist rapBlitlist
powaeeprom jsfEEPROM
powaeepromword jsfEEPROMWord
powaeepromboard jsfEEPROMBoard
SNDZEROPLAY zeroPlaySample
RAPTOR_particle_clear rapParticleClear
RLOCATE rapLocate
RPRINT rapPrint
RPRINTINT jsfPrintInt
loadclut jsfLoadClut
colour jsfColour
DELAY jsfDelay
RBSORT jsfSort
RSETLIST rapSetActiveList
FADEPAL rapFadeClut
RHIT rapCollide
RPARTI rapParticleInject
RSETMAP rapSetMapLoc
fadesingle rapFadeSingle
hiscore_sort rapHiscoreSort
hiscore_check rapHiscoreCheck
bin2asc rapNumToStr
MODPLAY u235PlayModule(int module,short stereo) - 'stereo' input can be;  MOD_MONO or MOD_STEREO
RUPDALL jsfVsync - The normal VSYNC command should still generally be used and maps to jsfVsync(0)
basic_r_indx = index jsfSetFontIndx(index)
basic_r_size = index jsfSetFontSize(index)
SNDKILL u235KillChannel
SNDDELTA u235ChannelVol
raptor_fade_delay rapFadeDelay
raptor_ntsc_flag rapNTSCFlag
MODVOL u235ModuleVol
SNDVOL u235SampleVol
SNDFREQ u235ChannelFreq - Not required if using u235PlaySampleFreq
Input_SetJoyPort1 zeroSetJoyPort1()
Input_SetJoyPort2 zeroSetJoyPort2()
Input_SetNormalPadMode zeroSetNormalPadMode()
Input_SetRotaryMode zeroSetRotaryMode()
Input_SetAtariMouseMode zeroSetAtariMouseMode()
Input_SetAmigaMouseMode zeroSetAmigaMouseMode()
rlist[] sprite[]
RAPTOR_mt_init rapMTInit
raptor_mt_present rapMTPresent
RAPTOR_mt_save rapMTSave
U235SE_rng u235Rnd
raptor_highscores_hex rapHighscoresScore
raptor_highscores_nam rapHighscoresName
raptor_highscores1_hex rapHighscores1Score
raptor_highscores1_nam rapHighscores1Name
raptor_highscores2_hex rapHighscores2Score
raptor_highscores2_nam rapHighscores2Name
raptor_highscores3_hex rapHighscores3Score
raptor_highscores3_nam rapHighscores3Name
raptor_highscores4_hex rapHighscores4Score
raptor_highscores4_nam rapHighscores4Name
raptor_highscores5_hex rapHighscores5Score
raptor_highscores5_nam rapHighscores5Name
raptor_vbl_time_remain rapVBLTimeRemain
raptor_ticks rapTicks

Old and new Joypad constants.

Old Zero Player Value Old U235 Value New (Universal) JagPad Constant (will work for either sound/input engine)



Input_Pad_Up PAD_UP JAGPAD_UP
Input_Pad_Down PAD_DOWN JAGPAD_DOWN
Input_Pad_Left PAD_LEFT JAGPAD_LEFT
Input_Pad_Right PAD_RIGHT JAGPAD_RIGHT
Input_Pad_A PAD_A JAGPAD_A
Input_Pad_B PAD_B JAGPAD_B
Input_Pad_C PAD_C JAGPAD_C
Input_Pad_Pause PAD_PAUSE JAGPAD_PAUSE
Input_Pad_Option PAD_OPTION JAGPAD_OPTION
Input_Pad_0 PAD_0 JAGPAD_0
Input_Pad_1 PAD_1 JAGPAD_1
Input_Pad_2 PAD_2 JAGPAD_2
Input_Pad_3 PAD_3 JAGPAD_3
Input_Pad_4 PAD_4 JAGPAD_4
Input_Pad_5 PAD_5 JAGPAD_5
Input_Pad_6 PAD_6 JAGPAD_6
Input_Pad_7 PAD_7 JAGPAD_7
Input_Pad_8 PAD_8 JAGPAD_8
Input_Pad_9 PAD_9 JAGPAD_9
Input_Pad_Star PAD_STAR JAGPAD_STAR
Input_Pad_Hash PAD_HASH JAGPAD_HASH