@DATABASE "Default" @AUTHOR "Paul Manias" @(c) "Copyright 1996-1997 DreamWorld Productions." @$VER: 0.7 Beta (5 July 1997) @NODE "MAIN" "The Games Master System V0.7B" @{b} T H E G A M E S M A S T E R S Y S T E M BY PAUL MANIAS VERSION 0.7B GENERAL DOCUMENTATION @{ub} Welcome to the latest version of GMS! This version signals the first step towards cleaning things up in preparation for V1.0. Now that most of the general functionality is in place, it is just a matter of finalising the structures and the functions. I am also in the process of converting many of the functions (the ones where speed isn't important) to C. This will make it easier to port GMS to PPC and other platforms. The full version of GMS should be available before the end of this year. Remember, if you make any GMS programs then I would like to see them, just mail them to me at my e-mail address so I can see what you are doing. Tell me if you are having any problems, or if a new feature could help your program. There is also a questionnaire in this archive and I would like you to fill it out and return it to me. This is quite important as it guides the future of GMS in many areas. I have questionnaires from the following people: Dag Agren, Daniel Rost, Fabio Rotondo, Julian Boibessot, Mark Papadakis, Miguel Ramos, Midael Drugge, Porter Woodward, Robbie Bankston. Pathetic! So if your name isn't there, start writing :-) @{" Introduction " LINK "Introduction"} @{" General Overview " LINK "Overview"} @{" Features " LINK "Features"} @{" Languages " LINK "Languages"} @{" Hints and Tips " LINK "HintsnTips"} @{" Structures and Lists " LINK "StructList"} @{" Questions and Answers " LINK "Questions"} @{" Compatibility Problems " LINK "Compatibility"} @{" Resource Tracking " LINK "ResourceTracking"} @{" Writing a GPI " LINK "WritingGPIs"} @{" Screens Overview " LINK "ScreensDesc"} @{" Sound Overview " LINK "SoundDesc"} @{" Blitter Overview " LINK "BlitterDesc"} @{" The Authors " LINK "TheAuthors"} @{" Copyright " LINK "Copyright"} @EndNode --------------------------------------------------------------------------- @NODE "Introduction" "Introduction to the Games Master System" This introductory text is taken directly from the web pages: http://gms.ethos.co.nz/gms/ @{b} WHAT IS THE GAMES MASTER SYSTEM? @{ub} The Games Master System is a solution to one of the biggest problems the Amiga community has ever faced. What problem? Games support in the OS! Windows has it, the Apple has it, and the poor old Amiga has none. This lack of support has brought up some quite serious problems when it comes to hardware compatibility in games. Every Amiga owner encounters them at some time, if not often. There have been efforts made towards libraries specifically tailored to handling graphics cards, but these are missing the big picture. @{b} THE BIG PICTURE @{ub} Hardware bashing is fast, sometimes many times as fast as an equivalent system legal routine. However hardware bashing is not very compatible with other hardware types, resulting in unpredictable results on other systems. No programmer can be expected to support dozens of obscure hardware configurations... just look at what it did to the PC, you can't install a game without going through and setting IRQs for sound cards. Let's face it, if the problem isn't dealt with directly, then the situation is just going to get worse as new hardware is released. So how are we going to deal with this ever increasing problem? No-one has ever come up with an acceptable solution for our little Amiga. Maybe we are getting close to retargettable graphics, but what about retargettable sound? What about user support? What about networking? Where's our support for all those different joysticks? Where's the real support for writing games in an OS? What about all the other stuff people keep moaning about? Well after a lot of design and investigation into this, a solution is already on its way. It's a clever little system that everyone will come to know as... @{b} THE GAMES MASTER SYSTEM @{ub} The "Games Master System" solves all the problems developers have faced in the past, and are still facing today. Project GMS encompasses not only the games library but also all the GPI's, documentation, developer information, and most importantly the user prefences program (GMS Prefs). All these things have been designed to work together and will achieve the following: * Erradication of the need to bash the hardware from within games. * Make it easier to migrate from the current Amigas to the new Power (or whatever) Amigas. * Make games programming, easier, faster, and more productive. * Give users the ability to modify any game to suit their requirements. @{b} HOW DOES IT WORK? @{ub} First lets look at the way games are written on the Amiga today. A lot of experienced coders would tell you that a lot of their source is automated, put into macros, drawing routines, sound routines, and so it goes on. Rather interestingly, this is usually the same stuff that is doing all the hardware hacking. By taking these commonly used routines and putting them into a library we remove the hardware compatibility problem immediately. Unfortunately for us, although it works this method is just not fast enough for the speed that games require. Enter the use of GPI's! A GPI (short for "Games Programming Interface") is a collection of library functions specifically designed to perform a task for just one hardware device. Each GPI can therefore be built to do whatever it wants without having to worry about compatibility problems. New versions of an existing GPI can be written for different hardware devices, so graphics cards, sound cards, 3D chips etc can be supported. The benefit of this is that the user gets the best possible speed, while the programmer can simply utilise the built-in routines and know that not only will their game be fast, but also be compatible with Amigas everywhere. @{b} USER SUPPORT @{ub} If you're a games player then there have probably been a number of times where you've thought "Why can't I use my Sega Joypad?", "I want to run in a DBLPAL screen!", "I want multi-tasking!", "I want to turn the music off!", "I want, I want, I want!". Unfortunately, that's what it sounds like to developers who don't have time to support all these things! Luckily an important feature of the Games Master System is the level of support given to the user. The GMSPrefs program allows the user to select levels of mode promotion, type of joystick used, vector detail, networking, C2P routines, music re-direction, task priorities, and much much more. This solves a lot of the moans and gripes that users have had in the past, and since this is all transparent to the programmer, user support is easily achieved. Hopefully this news will make you all very happy! @{b} ANYTHING ELSE? @{ub} Look around the rest of the site to get more detail on the things mentioned here, and other things that we haven't gone into yet. The GMS binaries and documents are available on Aminet, in dev/misc/gms_dev.lha. Remember to ask us if you have any questions about the project! @EndNode ---------------------------------------------------------------------------- @NODE "Overview" "OverView" @{b} OVERVIEW OF THE GAMES MASTER SYSTEM @{ub} Project GMS started in the beginning of April 1996, in an effort to provide games support in the Amiga OS. The overall aim is to write the best games interface we possibly can, which should eventuate into a system that everyone can enjoy. Although the development of GMS is largely controlled by me (Paul Manias) I would like people to see it as a project of the Amiga community and I am completely open to ideas and comments. The prime objectives of GMS are: 1. To erradicate the need to bash the hardware from within games. 2. To make it easier to migrate from the current Amigas to the new Power Amigas. 3. To make games programming easier, faster, and more productive. GMS has been designed to be fully extendible in ways that will make future improvements very easy to implement. The system is split into a number of sub-sections: The master GPI, the slave GPI's, the debugger, and the preferences program. This is further enhanced by identifiable data structures, which allow us to write new structures in future, without overhauling the functions. GMS has no problems with future compatibility, since hard-coded structure definitions are outlawed and tag-lists are very well supported. @{u}Games Programming Interfaces (GPI's)@{uu} The Master GPI contains some code, but also serves as a "skeleton" of function calls, rather than having all the code residing within the GPI itself. The Master GPI is "filled out" on opening by smaller slave GPI's (Games Programming Interface's). A GPI consists of a group of function calls pertaining to one particular area of games programming. For example, the Screens.GPI contains routines for opening and closing a screen, altering the screen's palette, and placing sprites onto a screen. Other GPI's are purely optional, and must be initialised before use. This saves a lot of memory as you only have to load in what you need. GPI's can be written and re-written for any hardware setup imaginable. It is possible to split them up into even smaller files if desirable. An example of this is the Screens.GPI's Chunky 2 Planar routines, which can give the user a variety of options for his system. To see how everything links together, view the @{"Communication" LINK "GMS:docs/Communication.iff/Main"} file to see a graphic representation of the links and connections now. @{u}Looking to the Future@{uu} There will of course be a version of GMS for the new Amiga's, so an AGA game written now could still work on these new machines! The great thing is that this library really closes the gap between differences in machine architecture. Even games written on a PPC could work on an Amiga with CyberGfx card, granted that you compiled a 680x0 conversion. In the future I hope to have available: * Support for graphics cards. * Support for sound cards. * Vector and 3D functions. * Support for all the new hardware capabilities in PPC Amigas. This is looking quite some time into the future of course, but GMS is already designed for these things so it's all possible. @EndNode ---------------------------------------------------------------------------- @NODE "Questions" "Questions and Answers" @{b}QUESTIONS AND ANSWERS@{ub} I often get mail from people asking me questions about what you can and can't do in GMS. Here I will answer some of these questions, and hopefully this way everyone can benefit in learning more about how GMS works. If you have any questions you can mail them to me and they may appear here. @{u}@{b}GENERAL@{uu}@{ub} Q. Will you support new machines such as those from PIOS and the upcoming OS's like pOS? A. When I get a PPC machine (at the moment I couldn't afford one), unless someone else volunteers to do a PPC version. The 680x0 versions will still be developed first though, as they will remain as a foundation for all other GMS conversions. I expect that the PPC version will be written in C/C++ to get it done as quickly as possible. If you really want a PPC version though, give me your support and buy the full 680x0 version as soon as it is available. Q. Is it possible to free structures that have not been initialised? [The idea being that it makes it easier to write the initialisation code] A. Yes, a standard feature of GMS is to recognise structures that have not been initialised. The function will just ignore the structure and exit. Functions also recognise if you have passed them wrong or invalid structures, so the security in this area is very solid. @{u}@{b}BLITTING@{uu}@{ub} Q. If I want to have 5 bobs with the same graphics, may I initialise the first with NULL in bob.maskdata and GENMASK set, then copy the pointer created to the @{i}other structures@{ui} and init them with GENMASK cleared? Otherwise the masks would be created again several times and waste memory. A. Yes, it is legal to copy masks generated in one bob over to another bob. Just remember when you free the "master" bob, all bob's containing pointers to its masks will become invalid. For this reason make sure that you free the master bob last. Note: If your framelist contains graphics which have identical masks, this will be detected when your masks are generated. Any mask which is discovered to be identical to another mask in the framelist is automatically discarded and will be replaced with a pointer to the existing mask. This will save you memory without effort on your part. Q. How does CPU assisted blitting work when parallel drawing means that there could be an instance of data overlap (CPU and blitter draw to the same area at the same point in time)? A. It's a clever trick... What you do is start the blitter drawing the first 5 lines or so of the bob. While it does that you use the CPU to start drawing 5 lines from the bottom of the bob. When the CPU finishes with its section it checks on the blitter. If the blitter has finished then the CPU sets it blitting the next 5 lines and the CPU continues on. This keeps going until the blit is finished. Q. I have successfully initialised a bob with a picture attachment. But when I draw it the dimensions are correct but the graphic is corrupt. A. If you have a machine with fast ram installed then first make sure that you have specified the VIDEOMEM or BLITMEM flag in the PIC_Options field. If you forget to set one of these flags then the blitter will probably be attempting to blit from fast memory, resulting in corrupt graphics. Q. How do I initialise a Bob using a Bitmap as the graphic source? A. The simple answer is to use a Picture as the source, and not a Bitmap in the first place. If this is not possible, call GetPicture() and then CopyStructure() the Bitmap details over to your empty Picture. Place the Picture structure in Bob->Picture, and you're done. Remember to free your Picture after you've finished. @EndNode ---------------------------------------------------------------------------- @NODE "WritingGPIs" "I want to write a really awesome-cool-funky-thingofa GPI." @{b} WRITING NEW GMS INTERFACES @{ub} Anyone can write a GPI, but the first thing you must do is email me about your idea and describe what it will do. I will then consider wether or not a whole new GPI should be created, or if your idea should be added to an existing GPI. It may turn out that someone else has the same idea as you, in which case I will put you in contact with that person. If in the event a whole new GPI needs to be created, I will first ask you to list all the possible functions you think will be needed. Once that is figured out we will design the structures that will be required - usually there will only be one of these, so it's important that we get it right. You will then be sent a GPI development kit which details how to integrate your GPI with the Master GPI. GPI's are based on normal system libraries, but have the addition of some code supporting function remapping. Later when you have written the GPI you have to send it to me and I will suggest any changes to the functions etc. Once everything is okay, then it's an official GPI. The only other condition that you must adhere to is that your GPI is written in assembler, or very good C. Also, it helps to send me the souuce at some point so that if you lost interest later on, I could still update the GPI when necessary. Remember there may be a lot of people using your GPI so I must ensure that it's 100% OK and can be upgraded for future Amigas. @EndNode ---------------------------------------------------------------------------- @NODE "Features" "Really cool features!" @{b} CURRENT FEATURES OF THE GAMES MASTER SYSTEM @{ub} This is just a summary of the major features that have so far been implemented. Not all new features and changes have been documented here. For the complete low-down on all features of GMS check the developer information files. * Multiple platform capabilities. A GMS program compiled on a 680x0 Amiga could also be run on a 680x0 Atari or Mac, all you would need is the necesary drivers. All PPC compilations will have the same feature and can also be 680x0 compatible through emulation. * Resource tracking is fully implemented, a task can now exit and all its resources will be completely freed. A SelfDestruct() function allows a task to abort itself at any time and the system will free its resources - extremely useful for debugging purposes. A user may force a task to abort simply by pressing L-AMIGA and DELETE, 100% safe. * Debugging support implemented into all initialisation functions, no need for unnecessary patches to get debug information or track system calls. A debugger utility exists for receiving and displaying this data. * Transparent Chunky-To-Planar, which means it won't bother wasting time with conversions or copying if chunky mode is already available in the hardware. * Fast blitter functions for drawing bob's, copying for screen buffers, 3 different screen clears, auto background saving and clearing for bob's. Also includes Pixel and Line drawing functions, and support for list's for very fast mass-drawing operations. CPU assisted blitting means that drawing speed is no longer limited to blitter throughput. * Full sprite support, and that is: All available sprite dimensions, colour table offsets, 16 colour sprites, width-doubled sprites, full animation support, lo-res, hi-res, and superhi-res support, * Sound support includes: Support for sound priorities, intelligent dynamic channel play-back, channel modulation for special effects, IFF support. * Proportional colour fading, functions are: PaletteMorph, ColourMorph, PaletteToColour and ColourToPalette. Support for setting speed and colour ranges. * Full support for raster/copperlists, with effects such as: ColourLists, Mirror, Flood, Screen and Sprite Splitting, and Palette Changes. * Structure and object pre-processing, allows data to be changed separately from the main program. This makes GMS the first system to support up to 100% user editing of game data. * Allows you to support all different kinds of input devices (joysticks, joypads, mouse etc) through just one simple function call. This enables you to support devices that don't even exist yet. * User preferences program to allow full configuration of a game's functionality. This includes configuration for: Game/Task Priorities, Choice of networking, Mode Promotion, Joystick Config, Music Redirection, and more. * Stable memory allocation and a freemem routine that will not crash your machine if you have written over your memory boundaries. Internal resource tracking ensures that GMS programs will not chew up your memory. * Smart Saving and Loading of files, with automatic packing and depacking. Packer support covers files crunched with XPK (external), PowerPacker (internal), and RNC methods 1&2 (internal). * 230k of assembler, E and C sources, demonstrating all uses of the library. * All GMS programs can multi-task with no significant drop in speed or performance. @EndNode --------------------------------------------------------------------------- @NODE "Languages" "What language to use with GMS?" @{b}GMS LANGUAGES@{ub} As GMS is no more than an extension to the OS, it can work with any language that you want it to. Currently supported languages in this archive are: Assembler C/C++ E You could also use Blitz Basic, Pascal, Oberon and others if you know how, but I currently don't have any source demos or special include files to help you with those. If you're new to programming then I would recommend starting out with C or E. In my opinion E is a little easier on the beginner, but C is more common place in other areas and you might find that useful. If you don't know which one to choose, try learning E first, and then C as they are quite similar languages. If you want to write really fast games, you will have to learn assembler. With GMS learning assembler is quite easy, as you don't have to think about programming the hardware registers. Look at the demo sources and make up your own mind if you want to learn it or not. Using GMS you could become a fairly adequate assembly programmer in as little as 2 months if you have come from something like C. @{b}WHAT COMPILER?@{ub} If you know what language you want to use, you will have to think about what compilers you should get. You can't program without a compiler! Here is my opinion on the most common and best compilers available: @{u}Assemblers@{uu} The best assemblers are AsmOne, DevPac and PhxAss. I have all three of these and use each one of them for different situations. You don't need that many, but two of these are free, so it won't cost you anything. AsmOne has an excellent source-level debugger and I recommend it to beginners, as you can observe how the 680x0 instructions work. I don't use it that much today, but it is useful and has some features that make it very easy to use. It also has the fastest compiler speeds that you could imagine. I got the latest AsmOne from the WWW, go to one of the Amiga Web searches and look for "AsmOne" to find it. DevPac is a good, robust compiler with many options, but it's a little slow and hasn't been updated in a while. I recently moved to using PhxAss for these reasons. You can get DevPac from HiSoft and other software dealers, it's a commercial product so you will have to pay for it. I have been using PhxAss for a few months now and have found it to be a very impressive asm compiler. It is compatible with DevPac sources and has very good compiling times. The package is regularly upgraded and it's freeware. Good work Frank Wille! You can get PhxAss from Aminet, just download it as dev/asm/Phx*.lha. You will also need a text editor if you're using DevPac or PhxAss, I recommend CygnusEd as it's small and you can alter the TAB stops. This feature is important as it keeps your sources easier to write and manage. You will notice that all my assembler sources look strange unless you view them with CED or AsmOne. CygnusEd hasn't been updated for a while, but until I find another good text editor with this feature, I'm sticking with it. @{u}C Compilers@{uu} SAS C/C++ is what I use most often, it's very reliable and I've never had a problem with it. The documentation is very extensive, so you'll be able to get help for all your problems. This product is commercial but I don't think it is receiving updates at the moment. You may be able to get it from various software dealers. DICE C is a nice package but it doesn't support C++. You have to register the compiler to get all the features, but you get to play with it first which is good for beginners. You can get this one from Aminet, in dev/c/ I believe. Again, you will need a good text editor for efficient programming. CygnusEd is ideal here, and I believe GoldEd is a popular choice as well. @{u}E Compilers@{uu} There is only one E compiler available (EC) which you can get as part of the E package. You can get this from Aminet, along with everything else that you will need. You will probably have to register, although this program was put on a coverdisk some time ago. @EndNode --------------------------------------------------------------------------- @NODE "StructList" "About Structures and Lists" @{b}STRUCTURES AND LISTS@{ub} One of the things you will notice about the GMS structure format is the version header in the first longword (eg GSV1 for GameScreens). In the past, header fields have only ever been used for easily identifying files. If we didn't have them, we'd never know what sort of data we were dealing with. Now the idea of these headers has now been taken and is being used in GMS structures. Why? Well for debugging, support for the growth of structures, and identifying exactly what any structure is used for. Also, it allows the functions to do different things according to what sort of structures you give them. An example of this identification is for lists. What's a list? Well in the case of GMS a list is intended for processing 2 or more structures inside a function. This is the fastest way that you can process a whole lot of structures without having to make heaps of function calls. Lets say you wanted to load in 10 sounds from your hard-drive using InitSound(). Normally InitSound() takes a Sound Structure, but it can also identify a List by checking the header ID. To illustrate, a typical list for initialising/loading sounds looks like this: SoundList: dc.l LIST ;List identification header. dc.l SND_Boom ;Pointers to each sound to load and dc.l SND_Crash ; initialise. dc.l SND_Bang dc.l SND_Ping dc.l SND_Zoom dc.l SND_Zig dc.l SND_Zag dc.l SND_Wang dc.l SND_Whump dc.l SND_Bong dc.l LISTEND ;Indicate an end to the list. When you want to load all your sounds in, just use this piece of code: move.l GMS_Base(pc),a6 lea SoundList(pc),a0 ;a0 = Pointer to the soundlist. CALL InitSound tst.l d0 bne.s .error Pretty easy right? Of course, there are lots of other functions that sup- port lists. The not-so obvious ones are: InitBob() InitSprite() InitSound() FreeSound() Some functions are specially written to be given lists only, eg DrawBobList(). This is mainly for speed reasons, as we don't want to waste time checking if a structure is a list or not in time critical situations. That's basically the summary on lists. You may be interested to know that the GMS package is the only programmers aid that supports structures in this way. You will learn more about lists and how ID fields will help you in other areas of this doc. @EndNode --------------------------------------------------------------------------- @NODE "HintsnTips" "Hints and Tips" @{b}GAMES MASTER SYSTEM@{ub} @{b}HINTS AND TIPS@{ub} This section is written to offer some friendly advice and tips on how to get full use from the Games Master System, and what tricks you can use to make sure your game runs at the highest speed possible. I'm still writing this section, but if you have a trick of your own that should be here, please write to me at paul@ethos.co.nz. @{b}1.1 GENERAL CODING TIPS@{ub} Less... equals More! Never call the same routine twice in your main loop unless absolutely necessary. For example, look at this routine that calls ReadKey() twice: ---- Loop: lea KeyStruct(pc),a1 CALL ReadKey cmp.b #K_ESC,d0 beq Game_Over ... Rest of main loop ... lea KeyStruct(pc),a1 CALL ReadKey cmp.b #" ",d0 beq .Exit lea GameScreen(pc),a0 CALL WaitVBL bra.s Loop KeyStruct: ds.b KP_SIZEOF ---- Do this instead... Loop: lea KeyStruct(pc),a1 CALL ReadKey cmp.b #K_ESC,d0 beq Game_Over ... Rest of main loop ... lea KeyStruct(pc),a1 cmp.b #" ",KP_Key1(a1) beq .Exit lea GameScreen(pc),a0 CALL WaitVBL bra.s Loop KeyStruct: ds.b KP_SIZEOF As you can see the second version is faster because it doesn't make an extra call to ReadKey(). Simple really, and this common sense applies to many situations. @{b}1.2 MULTI-TASKING UNDER THE GAMES MASTER SYSTEM.@{ub} It is up to you wether you want to multi-task or not, I can only encourage you to do so. GMS offers some special features to allow your game to multi-task effectively without disabling the OS entirely. Four functions are specifically related to multi-tasking, and they are: SetUserPrefs() Switch() AutoSwitch() WaitVBL() Firstly, SetUserPrefs() is a compulsory function that you must call immediately after opening GMS. Apart from the fact that it can load in the user settings for you program, it will also set your task priority to the preferred user level. This is usually set to a default of 4, enough to give your program all CPU time. The highest setting is 8 which locks out just about everything except for standard system procedures (input device etc), while a setting of 0 is on equal footing with all other tasks. There is absolutely no need to completely lock out the system with Forbid()/Permit()! Switch() is a very important function to use for multi-tasking. Lets say you've opened the screen and now the view is taken over. But, what if the user wants to return to the OS momentarily without quitting the game? By calling Switch() the screen will leave the display and either a) drop out to a window on workbench or b) drop out to a standard OS screen. What will happen exactly is up to the user setting in GMSPrefs. The OS will now be available to the user until he signals GMS to return to your task. The Switch() function is further supported by the AutoSwitch() function. This is very similar to Switch(), but checks the Amiga-M key combination for you and if found, switches the screen automatically. It's a lot easier to incorporate this in your main routine but some may prefer the Switch() function for full task control. Finally is WaitVBL(), which is probably the function you will use most often. This will perform an Amiga-M check before the vertical blank occurs, which can be very convenient in all circumstances. If you use this function in loops or whenever you need a VBL wait, your game should be 100% supportive of screen-switching without you needing to think much about it. As a final note, whenever the OS is returned your game will be paused until the user enables you again. This is quite convenient, since we don't want the player to die when he can't see the action. @{b}1.3 CONTINUATION OF TASK PROCESSING WHILE PAUSED@{ub} There are times when pausing of your main task (through Switch()) will be inconvenient if it is necessary to continually process information. For example lets say you are writing a game that can connect via the serial port for 2 player communications. If one machine was to stop its processing, the serial buffer will continue to receive information and could go into overflow, potentially causing you some problems when your task is reactivated. The easy solution to this is to activate a secondary task that will continue to process when the main task is switched. This is a simple procedure and only requires that you put all your communication handling into this separate task. Another method is to use an interrupt, which can be ideal. An option that may be more convenient for the user in a TCP environment, would be to send out a message saying "This machine is temporarily paused" so that all other machines know that they must not send information to you. This will give any other TCP tasks running on the paused machine more time to send/receive data, eg for FTP. @{b}1.4 SUPPORTING HIGHER RESOLUTIONS@{ub} Drawing high resolution graphics and supporting them as an option in your game is a worthwhile exercise, and will make the owners of more powerful computers happy. But it can be annoying to support - most developers make two copies of each picture file, one in lo-res and one in hi-res and then program the game to support both files. This can get in the way of programming the game itself and results in wasted time. In GMS there is a way to solve this problem. Draw all the graphics in high resolution and use them as you normally would in your game. Use screen tag lists that accept the default screen dimensions from the user (do not set GSA_ScrWidth, GSA_ScrHeight or GSA_ScrMode). Set the RESIZE flag when loading in the pictures and set PIC_Width and PIC_Height in accordance to the user's resolution in the screen that you opened. Example: If the game graphics were drawn on a 640x512 screen and the user has asked for a LORES screen, then drop the picture dimension to 320x256 and load it in. The picture will be resized to fit the new dimensions and you now have the lo-res equivalent of your hi-res screen. The next step is to proportionalise your bobs to the new settings. There are two fields to help you do this - PropWidth and PropHeight. These fields must contain the original dimensions of the Bob's source picture, which in the example above was 640x512. Now, when you call InitBob(), the function will detect that the Width of the source Picture does not match the PropWidth setting (same thing for the height). It will then use a formula to alter your Bob's Width, Height and coordinates to reflect the new dimensions. Bob->Width = (Picture->Width) / (Bob->PropWidth / Bob->Width) That's it. There are some proportional demos in this archive, check those to see how easy the procedure is (note how there is no extra coding needed, just the addition of a few tags and the RESIZE attribute). @EndNode --------------------------------------------------------------------------- @NODE "SoundGPIDesc" "Sound Overview" @{b} SOUND SUPPORT OVERVIEW @{ub} The GPI for sound support is one of the best Amiga interfaces for the support of Amiga sound effects. It features full sound prioritisation, intelligent channel selection on playback, and will eventually support special sound formats such as the common PC WAVE. To illustrate the power of the Sound.GPI, here is an example. Lets say you develop your game on your A1200 to make dynamic use for all 4 sound channels. This is simply done by specifying CHANNEL_ALL in the SAM_Channel field. What that does is play the sound through whatever channel is currently available. Used in conjunction with the PlaySoundPri() function, you can make maximum use of all 4 channels, rather than just one channel with no prioritisation. Clever right? Sure, but if your game was to be run on an Amiga with say... 12 channels... then all those 12 channels will suddenly be supported by your game! This is because the Games Master System has been designed to allow your game to improve as the hardware gets better. Our aim is to get games written in 1997 to still have up-to-date sound support in 2007. (Yes, really). As a further example, if you were to use IFF sounds loaded in from disk, you could support 16 bit sound, if the user was to update the sound files. (The hardware would have to support 16 bit sound of course). Packed sounds are also supported by the GPI so there are no problems in that department. If you have any ideas for further improvements to the Sound.GPI, send them on in... @EndNode --------------------------------------------------------------------------- @NODE "ScreensDesc" "Screens Overview" @{b} SCREEN SUPPORT OVERVIEW @{ub} The Screens.GPI was the first GPI to be designed, and speed was a major factor while it was being programmed. To keep it fast, the GameScreen structure has been kept highly simplified while not giving away any powerful features. One example of this power is that you can move the screen around by changing its coordinates, and even dynamically alter its width and height without any adverse affect on the picture display (see the Redimension demo). There exists a wide range of functions, including special effects such as proportional fading, which allows you to add some very smooth and impressive touches to your programs. Sprite support can give you some extra speed increases where you need it. Features from AGA sprites are also fully supported if you need extra wide sprites or access to colours in different areas of the palette. Finally is the rasterlist support, which provides an easy to use gateway to the copper chip. Using the available commands you can acheive affects like mirrors and smooth gradients of colour. The Screens.GPI is further supported in GMSPrefs, allowing the user to select his preferred screen modes. A powerful feature is being able to select the screen type, so you can change the display type from ILBM to Chunky for example. This can give you a great speed up if your hardware allows you to use such modes and if the game would benefit from such a change (eg 3D vectors). It is even possible to do things such as upgrading a game to hi-res interlaced, or running in different video modes such as DBLPAL. @EndNode --------------------------------------------------------------------------- @NODE "BlitterDesc" "Blitter Overview" @{b} BLITTER SUPPORT OVERVIEW @{ub} The blitter support is designed so that it can perform the task of drawing images to screen as quickly and efficiently as possible. The best way of doing this is to provide you with a large amount of drawing options, so that you can specify exactly how you want an image to be drawn. For experienced programmers this level of functionality is extremely useful in providing fast and optimised drawing speeds. If you're a beginner it may take some time before you learn what methods to use in each situation, but with a little practice you will know how to use the available options to your advantage. Currently, options include blitting in lists, clipping on/off, restore and clear modes, masking on/off, mask generation, multiple BOBs, setting clip areas, and others. To make the Blitter.GPI as effective as possible, special rules are in place that are ideal for games applications only. If you have come from OS programming then the ideas may sound a little unusual, but for games programming they make sense. The nature of any game is not to multi-task with other games, as it is impossible for a player to play two different games on the same screen at once. If two different games try to share resources, the result can be a catastrophe. Since GMS only allows one game to be using the display at any given time (ie no windows or screen dragging), it made sense that the only task allowed to use the drawing functions is the one at the front. This means that at any time when your task is active, you know that you have 100% available blitter time. Your drawing cycles will not be stolen by hidden tasks! It was suggested to me in the past that I could use QBlit() or similar interrupt driven blitting. The advantage of this is that it is easier for the processor to do things while the blitter is active, and there is no blitter waiting involved. This sounded like a good idea at the time, but after trying it I found the results to be disappointing, so I dropped it. Why? Because this method did not recognise the fact that the blitter is so SLOW! Using the blitter only, you would be lucky to get 7 32x32x32 BOBs on a 50fps screen with clear modes on. It doesn't matter how fast your routines are, the blitter will not move data any faster. This a sorry speed for any arcade game to be using. Instead I am now in the process of implementing high-speed CPU assisted blitter drawing routines. These work extremely well in mass drawing operations with about 20-30% speed up on my '020 A1200+Fast in comparison to blitter-only drawing. On a '030 I would expect at least 40% faster operations, while on '040 and '060 we are probably looking at the CPU drawing 2 bobs while the blitter draws 1. I think Amiga owners with fast CPU's will appreciate this feature, while '000 users will not suffer because the blitter will take most of the load for slow CPU's. Enjoy the fast drawing, and if you have any good ideas for advancements then send them all in. @EndNode --------------------------------------------------------------------------- @NODE "UserInputDesc" "User Input Support" @{b} USER INPUT OVERVIEW @{ub} @EndNode --------------------------------------------------------------------------- @NODE "Compatibility" "Compatibility Problems" @{b} COMPATIBILITY PROBLEMS @{ub} One of the most important decisions I made in the design of GMS, was to get the absolute most out of what the Amiga hardware is capable of. The fact is, if I wrote GMS with respect to other gfx cards, there would be no: Sprites Hardware Scrolling Overscan Double Playfields Split Screens and Rasterlists Strangely enough, isn't this what makes the Amiga unique? Also if the new Amiga's came out with quadruple 256 colour playfields and 512 colour sprites, should I support that if other gfx boards don't? Why should I not support it? Well one of the goals of GMS, is to always be as up to date as the hardware that is available at the time. Now, this is at the cost of compabitility. How compatible you want your game to be on other systems is entirely your own choice. Generally, the more hardware-specific features you use, the more you risk your games failure on different hardware. If you use less, your game has an excellent chance of successfully working on all systems. Whatever happens, you will have to make your own decisions on the compatibility issue. What I will do in the future of this section is try and help you face these problems, and hopefully overcome them. With some intelligent programming, you can still use features like sprites, rasterlists and hardware scrolling, and still keep your game running on other systems. It takes a little work but the least it will do is make a lot of people very happy. Good luck! @EndNode --------------------------------------------------------------------------- @{b}1. PLANAR AND CHUNKY CONVERSIONS@{ub} @{b}2. COMPATIBLE HARDWARE SCROLLING@{ub} @{b}3. SPRITE HANDLING@{ub} @{b}4. USING RASTERLISTS@{ub} @{b}5. SUPPORTING MULTIPLE PLAYFIELDS@{ub} @{b}6. TESTING GFX BOARDS@{ub} Although this feature isn't available just yet, in future you will be able to select a gfx board from GMSPrefs and test your program as if it is running on that board. Eg, if sprites are not supported they will not appear on screen etc. This will enable you to test your game on every board without having to buy them all :-) ---------------------------------------------------------------------------- @NODE "TheAuthors" "The Authors" @{b}THE AUTHORS@{ub} The Games Master System is written in assembler by Paul Manias (that's me!). Paul has 5 years 68000 and games programming experience, and another 1.5 years in other languages like C and Pascal. Paul's favourite past-times are chewing the heads off dolls, staring at the ceiling, and lurking in basements. So far he has written two games of his own and contributed graphics to two other commercial ones. None of those games have beeen released (yet?), for all sorts of various reasons. Luckily this is not the case with GMS. GMSPrefs is written in E, by Richard Clark. Richard's favourite past-times are standing, sending morse code via blinking, and talking to suspicious items of furniture. Thanks to Jyrki Saarinen and Fabio Bizzetti for their donations to the project. Some of the C demos were converted by Adam Dawes, good job Adam! Gerardo Iula has come up with some good ideas while using GMS, thanks Gerardo. To the people that send in the useful bug reports, thank you. Also to the many people that sent in ideas when the project first started (but we still need more!). Many thanks to Graeme Chiu, who hosted the GMS pages from April 1996 - May 1997. To see the newly moved pages, visit: http://gms.ethos.co.nz/gms/ @EndNode ---------------------------------------------------------------------------- @NODE "ResourceTracking" "Resource Tracking" @{b} RESOURCE TRACKING @{ub} GMS is fully supportive of internal resource tracking, which means that it tracks resources without any effort from the programmer. Resource tracking is great for programming as it warns you if you have forgotten to free important system allocations when your program exits. This is not just memory, but also things like sound, blitter, video display, files and device allocations. This becomes a life saver in situations such as forgetting to free a hardware allocation like the blitter, as this would normally cause a system deadlock and you would have to reset your machine. Fortunately resource tracking will rescue a situation like this and you can get the system back with everything intact. @{b} TASK DESTRUCTION @{ub} Resource tracking also gives us the opportunity to use an even greater feature, which is task destruction. Task destruction is the ability to stop and destroy a task while it is performing its normal processes, and still leave the system intact. You can stop a GMS program immediately by holding LEFT AMIGA and DELETE - even in the middle of a video game! This powerful feature uses resource tracking to return your system to the same state that it was in before the program was active. This is quite handy for users and programmers that want to get back to their system as quckly as possible, and obviously is very useful for debugging purposes. @EndNode --------------------------------------------------------------------------- @NODE "Copyright" "Copyright Notice" @{b}COPYRIGHT@{ub} The Games Master System archive may be re-distributed on the condition that its original content is unchanged. Files found in the archive are not available for separate distribution, unless specified otherwise. DreamWorld Productions reserves the right to change any of the material within the Games Master System at any time and without notice. Reverse engineering of the Games Master System software or the release of unauthorised programs using or emulating the Games Master System is strictly prohibited. DreamWorld Productions will not be held responsible for any smoke, explosions, volcanic activity, illness, acts of God, or any other harmful incidents caused by using this product. The Games Master System is a trademark of DreamWorld Productions, © 1996- 1997. All rights reserved. @EndNode ---------------------------------------------------------------------------