#### #### #### #### ####----#### ####----#### ####----#### ####----#### ####5555----############----5555#### ####5555----############----5555#### ####++++++++++++++++++++++++++++#### ####++++++++++++++++++++++++++++#### ####++++--------++++++++++++--------++++#### ####++++--------++++++++++++--------++++#### ####5555####--------++++--------####5555#### ####5555####--------++++--------####5555#### ####5555 ####------------#### 5555#### ####5555____####------------####____5555#### ####5555++++ ####----#### ++++5555#### ####5555++++____####----####____++++5555#### ####++++++++++++----++++++++++++#### ####++++++++++++----++++++++++++#### ####5555++++----####----++++5555#### ####5555++++----####----++++5555#### ####5555####5555####5555#### ####5555####5555####5555#### ####++++++++++++#### ####++++++++++++#### ############ ############ ---- http://BitJag.com/ ---- contact@bitjag.com -------------------------------------------------------- | TABLE OF CONTENTS | -------------------------------------------------------- (T1)Introduction (T2)Why Jagbuntu? (T3)What is Included? (T4)Installing Jagbuntu (T5)Build/Run Your First Jaguar Program (T6)Preparing Jag Graphics -------------------------------------------------------- | INTRODUCTION | -------------------------------------------------------- (T1) This read me is designed to give you a basic introduction to how the Jagbuntu development environment is setup, and help you build and run an included "blank_slate" program. This read me will not teach you how to program Jaguar games. That is something your will have to learn on your own. Here are a few suggested topics to study to help you get started: -PROGRAMMING -Programming in Motorola 68000 (M68000) assembly -Going through the Atari Jaguar SDK documentation -Programming in C (for the Remover's library) -Writing Makefiles -Navigating in a linux terminal -GRAPHICS -Learn a photo-manipulation program for 2D assests (Gimp, Photoshop, or Paint Shop Pro) -Learn how to model, texture, animate, and render in a 3D program(Blender) for 3D and pre-rendered 3D assets. -AUDIO -Learn to use an audio program like Audacity -Learn to use a tracker like MilkyTracker These topics just scratch the surface of what you will need to learn to make Jaguar games. Here at BitJag we don't even know a fraction of these things. But the idea is that we are always learning, and wanting to learn. -------------------------------------------------------- | WHY JAGBUNTU? | -------------------------------------------------------- (T2) First we would like to thank the Remover's, Reboot, Michael Hill, Matthias Domin, and anyone else who has worked to make Jag programming more accessible for us beginners. And that is the main reason why we put this distribution together and allow others to download it. We were previously working off of Jag Station, by the Removers, and Micheal Hills KDE distribution. But, like most programmers, we weren't quite comfortable working in those custom environments. For three reasons, no easy access to other Linux software (i.e. Ubuntu repositories and apt-get), having to work in a virtual machine, and being required to use older hardware to run the OS. We found, because of these reasons, we were spending more time just setting up our environment,instead of programming games. Of course, some will think the same of this distribution, and thats okay. Jagbuntu is designed to allow you to begin programming and building your Jag programs, right after you install the OS. You can still make changes to the OS if need to, or, if you are using your computer for things other than programming, you have access to the Ubuntu repositories and whatever other software you may need. Jagbuntu is built on top of the Kubuntu distribution, and is still a fully functional Ubuntu distribution. -------------------------------------------------------- | WHAT IS INCLUDED? | -------------------------------------------------------- (T3) --------------------------------- NOTICE: We have the essentials for programming for the Jaguar, with the Removers library, but we have also included an assortment of programs to fill in the gap of other aspects of game making Listed below. Like making graphics or audio for your game, something lacking in previous distrobutions. --------------------------------- PROGRAMMING ---The GCC/M68K Cross Compiler--- Copied directly from the Jag Station (http://removers.free.fr/) by the Removerrs. We are still learning how to build it ourselves, tricky. We will have our own build in the next release. ---Mac Assembler--- This is the magical program that converts your Assembly code into programs the Jaguar can read. LOCATION: /home/guest/Jaguar/bin ---ALN linker--- Used to link all the separate files in your program so the Mac Assembler knows how to assemble them. LOCATION: /home/guest/Jaguar/bin ---The Standard Jaguar C Library 0.5.9--- Gives allot of standard C functions to work with. LOCATION: /home/guest/Jaguar/src/jlibc-0.5.9 ---Removers C Library 1.3.4--- An amazing library, that will allow you to make graphically based Jag Games, using C Code. (http://removers.free.fr/) LOCATION: /home/guest/Jaguar/src/rmvlib-1.3.4 ---RMVJCP--- The removers version of JCP. A program used to push built Jaguar programs out the SkunkBoard. (http://removers.free.fr/) LOCATION: /usr/local/src/rmvjcp ---Virtual Jaguar--- The best Jaguar Emualtor emulator out there (Thank you Shamus!) Run you programs through this baby if you don't have access to BJL or a SkunkBoard. (http://icculus.org/virtualjaguar/) LOCATION: /usr/local/src/virtualjaguar GRAPHICS ---Converter 0.1.7--- Command line Program by the Removers, used to convert your images into a format that will compile and work with the Jaguar. ---Gimp--- Comparable to Photoshop for many of it's basic functions, can be used to create 2D assets for your games. (http://gimp.org) ---Krita--- Another raster graphics editing program. Trailered more for the artist, but can also be used to build 2D assets for your games. (http://krita.org/) ---Blender--- Awesome 3D modeling, Texturing,Animation, and Rendering package. Great for building pre-rendered assets, or export OBJ's for your programs. (http://blender.org/) ---Inkscape--- A vector graphics editor. Maybe more useful, in some instances, over Gimp or Krita. (http://www.inkscape.org/) AUDIO ---Audacity--- A versatile audio editor. It can import/export and edit most audio formats. (http://audacity.sourceforge.net/) ---MilkyTracker--- multi-platform music application for creating .MOD and .XM module files. (http://www.milkytracker.org/) OTHER ---Chromium--- Open source version of Chrome. You can easily download and install Chrome through Google officially. Or run with the included Firefox installer if thats your cup of tea. ---VLC--- Really nice video player, for convenience sake. -------------------------------------------------------- | INSTALLING JAGBUNTU | -------------------------------------------------------- (T4) Download the iso from; http://jagcorner.bitjag.com/jagbuntu.html Then burn it to a DVD or get it onto a USB drive. Then start your compurter from whichever device. The installer should start automatically. Jagbuntu installs like most other Ubuntu distributions, with one exception. Your user name must be "guest" (without the quotes, all lower case). This is because the GCC/M68K cross compiler was built in such a way that it needs the file structure /home/guest and until we can figure out how to build this ourselves, this is required to build your jaguar programs correctly. Ounce we figure out how to build the crosscompiler ourselves, we are unable to change this requirement. When you login the first time you will notice that there are two 'guest' accounts. This is because Kubuntu has a guest account ativated already. Login to the first guest account and you can disable the other guest account from the "Login Screen(LighDM)" located in "System Settings" from the K-Launcher (bottom-left corner of the screen). Once you are in the Login Screen settings click on the general tab. There will be a check-box for the guest account. Un-check it. System Settings>Login Screen(LightDM)>General> -------------------------------------------------------- | BUILD/RUN YOUR FIRST JAGUAR PROGRAM | -------------------------------------------------------- (T5) --------------------------------- NOTICE: These instructions are specifically for the example blank_slate program located in the home; /guestJaguar/src/blank_slate directory. And may or may not work with your programs. --------------------------------- With the dolphin file manager, navigate to the blank_slate program or by running in a terminal; cd /home/guest/Jaguar/src/blank_slate (This is blank example program, that can be used to start a new project). The makefile is already setup to make this program. So, hit f4 on the keyboard to bring up the terminal in the dolphin file manager. Then, in the terminal, run; sudo make Then enter your user password. If the distribution is setup directory (i.e. your chosen username is 'guest'), it should build the program correctly. If it built correctly you will have a two files, a 'blank_slate.cof' and a 'blank_slate.bin'. Your program is now ready to be pushed out to the SkunkBoard or ran in Virtual Jaguar. NOTE: The blank_slate project has some README files included, explaining some various parts of a basic Removers API based project. ---RUN ON SKUNKBOARD--- To run on the SkunkBoard, run; sudo jcp blank_slate.cof This will download the program to the RAM of the Jaguar and run it. If you make changes to your program again, dont forget to run; sudo jcp -r to restart the Skunkboard. For additional commands for JCP, run; jcp ---RUN IN VIRTUAL JAGUAR--- To run your program in Virtual Jaguar, run; sudo virtualjaguar blank_slate.cof -g This will run the Virtual Jaguar emulator in GPU mode enabled (aka the '-g' option), with your program. NOTE: You could setup your own bash script, or modify the programs make file to automatically perform these steps commands to speed up your work flow. But if all else fails, these commands should work. OTHER NOTE: Because Virtual Jaguar doesn't use an editable config file, we can change the default directory for the roms. (You may have noticed that there is a 'roms' directory locating in your Home folder). You will have to manually change where Virtual Jaguar looks for roms through the GUI. Either to /home/guest/roms/ or some other directory of your choosing. -------------------------------------------------------- | MAKING JAG GRAPHICS | -------------------------------------------------------- (T6) --------------------------------- NOTICE: This is one way to prepare your graphics for the Jaguar, and is certianly not the only way to do it. The is a sure fire way to get something to show up on the screen with the blank_slate project included. --------------------------------- The key to making graphics is to know that mode and bit depth the final image will be presented in. Do you want a 16-bit RGB image or are you looking to make a CRY texture for a 3D object your builing? Do you need to do some pallete shifting with a 8-bit image or do you need a solid 24-bit depth image on the screen? These questions are really important because they effect how we prepare the graphics for the Jaguar. In this example we will be building a 256 color palleted image with a 16-bit color depth. We won't explain how to make an image from scrap, Gimp is included in this distribution, and there are tons of tutorials to refer from. But we will show you how to convert that image with the included image converter program. If you don't want to worry about bit-depth right now, exporting your image as .gif image should give you something that we will be able to prep for the image converter. In a Terminal, if you type; jag-convert -h You will get a list of commands for converting your images to files that will work in your Jaguar program. Notice, right after the verions number, there is a list of options that are turned on by default. Most of these defaults won't cause any problems. So if you navigate to the folder with your image in it. Then just run; jag-convert myimage.png This will dump a new file in the same directory as your original image file with the same name, but with a different file exstension called 'myimage.s'. We are sure this a usable image format for the Jaguar, simbly because it is an assembler file, but we if you add the --binary flag before your image file name, it will convert it into a binary file. So, run; jag-convert --binary myimage.png This will give your a file with a .RGB exstension and it will be in binary. This file is ready to load into the graphics folder for your project.