Tools to use

Setting up the project

1. Open a command line to the JagStudio folder.
• In Windows, an easy way to do this is to use file explorer to browse to the Jagstudio folder, then in the breadcrumb at the top, click in there and type cmd and press enter.  This will open a command window straight in that folder.
  
  
2. Type in  build yourprojectname newbasic   Where yourprojectname is a unique name for your game.
3. This will create the nesessary startup project template files for you to edit for your game.
4. In file explorer, from your JagStudio folder, browse to \projects\basic\yourprojectname
5. You will see a selection of files and folders.  These are;

• assets	folder	Where you store your graphics, sound effects, fonts and music
  yourprojectname.bas	file	This is the main file for your game where you will put the majority of your code
  assets.txt	file	This is where you declare all your assets from the assets folder and how they are converted/imported into your game
  rapapp.s	file	This is the main Raptor startup file.  Generally you do not need to touch this file except for choosing your sound/input engine
  rapinit.s	file	This is where you declare all the sprite objects your game will use.  These will be sprites, backgrounds and text/particle layers
  rapu235.s	file	If you are using the U235 Sound Engine then this is where you set up your sound effects.

6. You need to decide which sound and input engine you want to use for your game.  See the relevant sections in the manual for descriptions and features of each.  We will use Zerosquares player for this guide.
7. Once decided, open rapapp.s in a text editor (we recommend Notepad++) and look at the top.  You will see the line;
• player equ 0      ;0=Zerosquare's player, 1=U-235 player
• The 0 after the equ must be set to 0 for Zerosquares player or 1 for U235.
8. As we are using Zerosquares player for this guide, leave it as 0 and save and close the file.  You are now ready to start creating your game.

Adding a sprite

To keep things straight forward, we will provide you with some assets to play with.  You can experiment with your own afterwards :)

1. From your JagStudio folder, using file explorer, browse to \docs\quickstartassets\ and copy bug1.bmp and bug2.bmp.
2. Then browse to your project folder in \JagStudio\projects\basic\yourprojectname and open the \assets\gfx\ folder.
3. Paste the two files in there.
4. For now, we will just use one of these graphics.
5. In your project root folder, open assets.txt in a text editor.
6. Type in the following line.  This tells JagStudio where in memory the sprite will be stored, what to call it, what kind of CLUT it uses and the path to the graphic file.
• ABS,SPRITE_BUG,gfx_clut16,assets\gfx\bug.bmp
7. Save your changes.
8. Now open rapinit.s in a text editor.
9. This is the file that tells the Jaguar what objects (sprites) exist in your game.  The object processor will process this list and display the relevant graphics.
10. Scroll down until you see the  ;Template  line - then paste the following code above that line.
• 
  ; Bug
      dc.l    1                                ; (REPEAT COUNTER)              ; Create this many objects of this type (or 1 for a single object)
      dc.l    is_active                        ; sprite_active                 ; sprite active flag
      dc.w    176,0                            ; sprite_x                      ; 16.16 x value to position at
      dc.w    130,0                            ; sprite_y                      ; 16.16 y value to position at
      dc.w    0,0                              ; sprite_xadd                   ; 16.16 x addition for sprite movement
      dc.w    0,0                              ; sprite_yadd                   ; 16.16 y addition for sprite movement
      dc.l    16                               ; sprite_width                  ; width of sprite (in pixels)
      dc.l    16                               ; sprite_height                 ; height of sprite (in pixels)
      dc.l    is_normal                        ; sprite_flip                   ; flag for mirroring data left<>right
      dc.l    0                                ; sprite_coffx                  ; x offset from center for collision box center
      dc.l    0                                ; sprite_coffy                  ; y offset from center for collision box center   
      dc.l    16/2                             ; sprite_hbox                   ; width of collision box
      dc.l    16/2                             ; sprite_vbox                   ; height of collision box
      dc.l    SPRITE_BUG                       ; sprite_gfxbase                ; start of bitmap data
      dc.l    16                               ; (BIT DEPTH)                   ; bitmap depth (1/2/4/8/16/24)
      dc.l    is_RGB                           ; (CRY/RGB)                     ; bitmap GFX type
      dc.l    is_trans                         ; (TRANSPARENCY)                ; bitmap TRANS flag
      dc.l    16*16*2                          ; sprite_framesz                ; size per frame in bytes of sprite data
      dc.l    16*2                             ; sprite_bytewid                ; width in bytes of one line of sprite data
      dc.l    0                                ; sprite_animspd                ; frame delay between animation changes
      dc.l    0                                ; sprite_maxframe               ; number of frames in animation chain
      dc.l    ani_rept                         ; sprite_animloop               ; repeat or play once
      dc.l    edge_wrap                        ; sprite_wrap                   ; wrap on screen exit, or remove
      dc.l    spr_inf                          ; sprite_timer                  ; frames sprite is active for (or spr_inf)
      dc.l    spr_linear                       ; sprite_track                  ; use 16.16 xadd/yadd or point to 16.16 x/y table
      dc.l    0                                ; sprite_tracktop               ; pointer to loop point in track table (if used)
      dc.l    spr_unscale                      ; sprite_scaled                 ; flag for scaleable object
      dc.l    32                               ; sprite_scale_x                ; x scale factor (if scaled)
      dc.l    32                               ; sprite_scale_y                ; y scale factor (if scaled)
      dc.l    -1                               ; sprite_was_hit                ; initially flagged as not hit
      dc.l    1                                ; sprite_CLUT                   ; no_CLUT (8/16/24 bit) or CLUT (1/2/4 bit)
      dc.l    can_hit                          ; sprite_colchk                 ; if sprite can collide with another
      dc.l    cd_keep                          ; sprite_remhit                 ; flag to remove (or keep) on collision
      dc.l    single                           ; sprite_bboxlink               ; single for normal bounding box, else pointer to table
      dc.l    1                                ; sprite_hitpoint               ; Hitpoints before death
      dc.l    2                                ; sprite_damage                 ; Hitpoints deducted from target
      dc.l    16*2                             ; sprite_gwidth                 ; GFX width (of data)
11. This can look quite daunting at first. These lines all represent an object (sprite) that is displayed on the screen.  Each of the lines describes a property to define the sprite.  You would typically be editing the properties in the 2nd column of data.  You can reference the manual to learn what all these properties do.
12. Save the rapinit.s file.
13. You can now run your project to see the sprite!
14. In the command prompt you opened in the first section (within the JagStudio folder) type in  build yourprojectname and hit enter.  You should now see the following Virtual Jaguar emulator window;
    
15. Congratulations, you have now displayed your first sprite!
16. When you have finished admiring your static sprite, close the VJ window and lets get on with moving it around the screen.

Controlling your sprite with the JoyPad

1. In your project folder, open yourprojectname.bas in a text editor.  This is the file where most of your game logic will go.  You can use more than one .bas file and $include those files into this one, but lets keep it easy for now.
2. First, we need to tell your program what number your new sprite is.  The number is its position in the rapinit.s list.  If you go back and look, the first object is the text/particle layer, your sprite should be the 2nd item in the list.
3. In your bas file, you should see this line;
• 
4. Below that line, type in     const sprBug1% = 1
5. This defines a constant value called sprBug1.  It is of type integer and you have assigned it the value of 1.  A constant is a value that will never change.  From now on in your code, you can refer to this sprite as sprBug1.
6. Below that, hit enter a couple of times to give yourself some room and then enter;   DIM pad1 AS INTEGER
7. This declares a new variable called pad1 that can hold an integer value.  We will use this to store the input that comes back from the joypad.
8. Now scroll down and find the main game loop.  It will look like this;
• 
9. Underneath that Do command type in;   pad1 = jsfGetPad(LEFT_PAD)
10. This gets the input from the left joypad and assigns it to the pad1 variable.
11. Now we need to examine that variable input and move the sprite accordingly.  Type in the following code;
•     IF pad1 BAND JAGPAD_UP THEN   
          sprite[sprBug1].y_ -= 2
      ELSEIF pad1 BAND JAGPAD_DOWN THEN   
          sprite[sprBug1].y_ += 2
      ENDIF
  
      IF pad1 BAND JAGPAD_LEFT THEN   
          sprite[sprBug1].x_ -= 2
      ELSEIF pad1 BAND JAGPAD_RIGHT THEN   
          sprite[sprBug1].x_ += 2       
      ENDIF
12. These IF statements all check the pad1 variable to see if any of the joypad directions are set.  The command sprite[sprBug1].y_ -= 2 will minus 2 pixels from the Y position of the sprite.  NOTE: the y_ has an underscore on the end.  Dont forget it.
13. Now save your bas file and go back to your command prompt and type in build yourprojectname and hit enter.
14. You should now see your same sprite again but this time you should be able to move it around the screen.  Open the VJ settings window to view the controller keyboard mappings.  They will probably either be cursor keys or A/D/S/X.
15. You can now move a sprite around the screen with your joypad.