-----------------------------------------------------------------------------
05/04/1994
-----------------------------------------------------------------------------
Support Group Application Note
Number: 202
Issue: 1.04
Author: James Bye
-----------------------------------------------------------------------------

Writing Games for RISC OS

-----------------------------------------------------------------------------
Notes: 

This application note outlines what is required by a game running under RISC 
OS and the considerations that need to be taken into account by the games 
writer.  RISC OS computers, unlike Acorn's previous computers such as the BBC 
Model B and Master 128, run in a desktop environment where other applications 
are running and processing data.  The games writer needs to take this into 
account and hence enable the user to start the game without the loss of any 
data or other disruption to the computer of any  kind.                         
-----------------------------------------------------------------------------
Applicable Hardware: 

All Acorn RISC OS based computers

Related Application Notes: 

None

-----------------------------------------------------------------------------
Copyright (C) 1994 Acorn Computers Limited 

Every effort has been made to ensure that the information in this leaflet is 
true and correct at the time of printing. However, the products described in
this leaflet are subject to continuous development and improvements and
Acorn Computers Limited reserves the right to change its specifications at
any time. Acorn Computers Limited cannot accept liability for any loss or
damage arising from the use of any information or particulars in this
leaflet. ACORN, ECONET and ARCHIMEDES are trademarks of Acorn Computers
Limited.
-----------------------------------------------------------------------------
Support Group
Acorn Computers Limited
Acorn House
Vision Park
Histon
Cambridge
CB4 4AE                                                  
-----------------------------------------------------------------------------

1. Background

RISC OS is a multi-tasking environment, where many applications may be running 
at the same time.  Any one or more of these applications may be actively 
editing data and it is important that the subsequent execution of a game does 
not result in the user losing valuable data.

On certain systems, other than those provided and manufactured by Acorn, the 
booting of such games  is totally different.  There are, for example, games 
for other machines where the manual actually states  that to load the game you 
must first remove the system disc from the floppy drive, power down the 
machine, insert the game disc and then power up the machine to re-start the 
game.  As you can see, doing such a thing in a RISC OS world could have 
adverse effects on the user which can result in the loss of data.  In an 
environment such as RISC OS, more care and consideration needs to be used in 
the interests of  the user.



2. The structure of a game application

Any application written for RISC OS should follow the structure that has been 
described in the RISC OS Style Guide and it is important that games follow the 
same structure.  The  game will be contained in an application directory and, 
for this example, we shall use the  directory name !Game.  The structure of 
the game application directory could be as follows :-

!Boot 
often found in the application directory but might well be unnecessary.
The filer will automatically load !Sprites if the !boot is not present.  You
should only include the !Boot file if you wish to set run or load actions.

!Sprites  
spritefile passed to *iconsprites by the filer (or the !boot file).  This 
should contain the sprite to represent the application icon in the directory 
display.

!Run 
*Run by the filer when the application is double clicked on in the directory 
display.  This should set environment variables as required and
*iconsprites the !Sprites file.

!Help  
the game application's documentation

!RunImage  
the main executable part of the game

Modules  
a directory containing any modules loaded by the game application
(any Acorn modules should be inside !System and not inside the game)

Sprites  
a directory containing the Game's own personal sprites used during
the running of the game.  Game's may have many different sprite files
so it is useful to keep them in one place within the !Game.

Code  
a directory containing other bits of code that are loaded and run by the
!Game.

Resources  
a directory containing assorted resources needed by the !Game 
(such as data files etc...)

Of course, it is up to the games writer to decide on the structure of the 
!Game directory but it always a good idea to have a tidy and maintainable 
structure.  The !Game directory must contain the !Sprites, !Help and !Run file 
but we recommend that the other items listed above are also included if they 
are necessary.  It is up to games writers to decide whether they wish to add 
extra directories or files.


3. Providing help for the game

A game application is the same as a normal RISC OS application and help should 
be provided in the standard way.  The standard RISC OS way is to have a text 
file inside the application directory called !Help.  This provides the user 
with information about the application from the directory display menu.  
However, the game itself is not restricted to providing this as the only help 
available.  Many games provide help when the !Game has been run, which is 
optional by user selection.  Another common method under RISC OS is to provide 
a second application directory on the disc that, once run, provides the user 
with the documentation and information that he/she requires.  This application 
is commonly called !ReadMe or !GameInfo (or similar).

It is worth noting that the use of a !Help file is the most common way a RISC 
OS application provides help to the user.  Hence, using this method provides 
the user with a standard environment.


4. The execution and termination of a game

Any game should be in the form of a standard RISC OS application, as described 
earlier in this document.  Hence, the user should be able to start the game as 
if it was any other application.  This is carried out by double clicking on 
the !Game application in a directory display.  The next steps that are taken 
are really up to the game entirely.  It is most common for the game to start 
right away and take over the whole screen (if it needs to do so).  Another 
method, that is currently being used by some games, is to install an icon on 
the iconbar like a normal application.  The user can then set any 
configuration options, such as redefining keys or loading saved data, in the 
desktop environment.  The game can then be started by selecting a menu option 
or clicking on the icon  on the iconbar.  The latter approach is preferred as 
it provides a similar environment to other applications.

Quite a few games in the RISC OS world still rely on Shift-Break to start 
them.  This is a legacy from the  BBC Model B world and this approach should 
no longer be taken.  The user should start the game as if it were any other 
RISC OS application.

At any point in the game, the user should be able to terminate it and return 
to the desktop.  A recommended method for this is the use of the Escape key 
whilst the game is running, or by selecting an option when the user is at the 
'start-up' screen.  Users should be able to return to a desktop that is in the 
state that they left it, if possible.  Many users have plenty of free memory 
and in many cases no memory grabbing techniques are required.  On no account 
should running the game result in the unexpected loss of data.  The CMOS RAM 
settings must be in the same state as before the game was started.  The CMOS 
RAM settings should not be touched under any circumstances.  It is permissible 
to change the font cache, system sprite area or other transient data areas as 
long as the user is informed.   In this case the only return to the desktop 
should be via a reset.


5. Ensuring there is enough space for execution

It is important that all games written for Archimedes computers work on the 
base machines.  The base machine is currently a 1 Megabyte machine with a 
single floppy disc drive.  On a base machine, the user will have about 720K 
(default) of free space for the game to use.  The maximum amount of free 
memory for 
a default machine can be changed by shrinking the font cache and system sprite 
area to zero, and this can 
increase the amount of free memory to approximately 752K.  This extra memory 
can be grabbed by the game under the consent of the user.  Of course, a more 
complicated game may need a higher specification to run (e.g. a 2 Megabyte 
machine).  If this is the case then the game should clearly state this to the 
purchaser.  Please note that RISC OS 3 version 3.10 provides 24k less free RAM 
in a machine in its default state compared to that of an equivalent RISC OS 2 
machine (696k compared to 720k).

In the absence of a suitable operating system interface in early Archimedes 
computer systems, some games developers used a variety of highly undesirable 
techniques for ensuring that host machines had sufficient free memory to run 
their games. As stressed elsewhere in this application note, actions such as 
changing CMOS RAM configuration or altering memory allocation are totally 
unacceptable in an application running in the RISC OS multi-tasking 
environment.  However, since the  majority of games run as single tasks a 
degree of configuration management is acceptable provided that it is :-

- necessary
- initiated with the user's consent
- transient in effect 

As with any application, a game ought to be able to determine the amount of 
free memory it requires to start up in; if sufficient memory is available the 
game should  start immediately.

If free memory is currently insufficient, the game should alert the user to 
the problem with a suitable dialogue box :-

<Insert DrawFiles.Figure1 here>

If the user chooses to continue with execution, the game should first close 
the  desktop (thereby offering the user the opportunity to save unsaved data); 
it is  then at liberty to make any necessary changes to the machine's memory 
allocation.  The author of the game application should use the Desktop 
Closedown protocol to ensure that any applications that have unsaved data give 
the user the chance to object.  Example code on how to do this can be supplied 
on request via Developer Support.


It is possible for game applications to retrieve memory from the Relocatable 
Memory Area (RMA) by RMKilling selected modules. It has to be said, however, 
that this technique is not totally reliable as its effect cannot be guaranteed 
across all variants of RISC OS. For a list of modules that can be RMKilled, 
then please see Appendix C.  The RMA does suffer from fragmentation, so the 
killing of modules does not always ensure that the free memory will be 
returned for general use.  To retrieve the memory after killing modules, you 
will have to issue the command *RMTidy.  However, under RISC OS 3.50 (and 
greater) the RMTidy command will no longer work (it is now a dummy command).  
Hence there is no way of retrieving space from RMKilling modules, rendering 
this memory retreival method as being useless.

It is recommended that a game which makes any change to the host machine's 
memory allocation should end its execution by instructing the user to perform 
a hard reset, e.g.
                                                                         
  Execution of !Game required some changes to your machine's internal
  memory allocation. Reset your computer to restore your machine's 
  normal configuration.


6. Saving the game state

It is quite often desirable, especially with tactical or adventure games, to 
allow the user to save the state of play at a particular point in the game.  
With RISC OS being a 'multi-disc' environment (i.e. having hard discs of 
different varieties - SCSI, IDE, ST506), it is important that the games writer 
does not rely on saving the game to a specific filing system or disc (e.g. 
save state to the root directory of the floppy disc).  As explained earlier in 
this document, it is a good idea to have your game inside an application 
directory.  In the !Run file you should set up the system variable 'Game$Dir' 
which will give you a pointer to your application directory (so that you do 
not have to be filing system specific).  The game state can then be saved 
inside the application directory using a filename such as 
'<Game$Dir>.SavedState'.  An alternative method of saving would be to use the 
!GameStore application, which is detailed in Appendix G.

However, a better method of saving the game state is to use the RISC OS 
filetype reserved for the purpose and allow the user to drag the file to any 
filing system that he feels fit.  This method is only really possible when the 
game installs itself on the iconbar (explained earlier in this document).  
When the user terminates the game and returns to  the desktop the game's icon 
should still be on the iconbar.  The iconbar icon will have a menu from which 
the user can drag a standard RISC OS save box to save the state of the game 
when it returned to the desktop.  

Acorn has a simple generic "saved-game" filetype that can be used by any game 
that is registered to use it.  The format consists of a 16 byte header, which 
identifies the game with a name and unique number.  This can then be dragged 
to the game icon on the iconbar and the game would enter at the stage that it 
left off.

Note that it is important that, when saving files, the game is never reliant 
on specific filing systems or filing system names.

If you do wish to use the saved game filetype, then please get in contact with 
Acorn Developer Support regarding its current status.

A full explanation of the saved game filetype can be found in Appendix A.


7. Interfacing to Joysticks

RISC OS 3 version 3.10 contains a module which allows third party software to 
interface to the built-in Joystick hardware (this is available on certain 
machines).  Full information on the interface to this module can be found in 
Appendix B.


8. Software protection

It is important for the games writer to take into account that many users now 
have hard discs in their machines.  Many owners of Acorn Computers have hard 
discs.  Hence, for a game to insist on only running from a floppy drive due to 
software protection is not a route that most  users would  find acceptable.  
Of course, we do not mean that games writers should release un-protected 
software, but there are possible alternatives.

A common approach used by other application writers, as well as games writers, 
is to use an approach called 'KEY-DISCING'.  This method permits the user to 
install the game onto the hard disc and then execute it from there.  The 
protection comes when the game asks the user to insert the floppy disc 
supplied with the game to read a protected sector or track.  If you do decide 
to use the 'KEY-DISCING' approach then it is important that you still allow 
the user to install the game onto his hard disc.  Subsequent running of the 
game from the hard disc would ask the user to insert the original disc to read 
the protected sector or the like.  This gives the user the benefit of speed by 
loading from the hard disc but also allows protection of the software.

Other methods that are worth considering are limiting the number of times they 
can install on his hard disc.  Another possible method is to have a 
'registration' scheme where, when the user purchases a copy, it will be 
protected and will run from floppy only.  The user would then be able to send 
his disc back to the software house and have the disc un-protected and 
registered.   The user would now be free to install the game on his hard disc, 
but every time he runs the software his registration name and number will 
appear on the screen.  Hence, if the software is distributed without prior 
permission of the author, the tracing of the illegal distribution is made 
easier.

9. Screen mode independence

There is increasing diversity of monitor types being used with Acorn 
computers.  VGA and Multiscan monitors have become more common.  It is 
important that no assumptions should be made on the field refresh rate as 
monitors will vary and VSync may change.  All timing should be derived from a 
stable base e.g. Timer1 or 100hz tick.

A special VGA compatible mode has been developed specifically for game style 
applications that take over the whole screen.  Details of these modes can be 
found in appendix E.


10. Processor dependencies

With the increasing range of ARM processors being used, together with varying 
cache and bus clock speeds, it is important that a Game does not make any 
assumptions on processor performance to time the game. For example, timing 
through the use of software loops should not be used. The appropriate 
operating system calls should be used for timing purposes.

As many developers are already aware, there are some machine code sequences 
that should not be used with the ARM processor as they cause unstable states. 
An ARM Code check program with further information can be provided by 
Developer Support to enable developers to test their applications for the
presence of these code sequences.

11. Direct addressing of the Video Controller (VIDC)

It is known that many games style applications need to poke the Video 
Controller (VIDC) directly to achieve certain special effects.  These special 
effects include some of the following :-

- Palette Switching
- Hardware Scrolling
- Setting Video parameters

Although addressing the hardware for VIDC1 Video Controller works, the code 
used to address the controller directly will not work on new Video 
Controllers, such as VIDC20.

It has been recognised that it is necessary for games to achieve special 
effects, so a module has been developed to provide a SWI veneer to addressing 
the Video Controller.  The module is called Screen Tricks and details of this 
can be found in Appendix F.

12. RISC OS

It is important for all software houses, including games software houses, to 
ensure that their software will work effectively of all versions of RISC OS.  
Hence, it is important that developers check that their software runs on all 
versions. 


13. Pitfalls to avoid when writing games for RISC OS

Ever since the Archimedes range of Computer was first released, software 
houses have been writing innovative games for the machine.  The aim of this 
section is to learn from previous mistakes that have either left the user's 
machine in an unuseable state or conflicted with desktop operation.



Altering CMOS RAM -In the past, some games have re-configured the CMOS RAM to 
enable the application to run.  Altering the CMOS RAM, even though it may be 
temporary, is very bad practice and should never be carried out.


Faking a reset -This approach SHOULD NEVER BE TAKEN.  If the game has been run 
in a low memory condition then it is up to the user to reset the machine and 
not the game application


Hardware addressing - There are now many different hardware platforms in the 
Archimedes range of computers.  Hence, we advise that games writers avoid 
addressing the hardware wherever possible and that they follow the standard 
operating system routes. In 1991, Acorn released the A5000, which has 
dramatically different hardware to previous machines.

Specific system reliance -In the past, many games have relied on the user 
having a specific system (e.g.  a 1 Megabyte A3000 with a single floppy drive) 
and then have designed their game taking into account this environment only.  
Many users now have machines with larger memory capacity, multiple floppy 
drives, hard discs in many flavours (the list is endless) and it is important 
that the game will run on any hardware platform in the Archimedes range, no 
matter how it has been configured. 

Shift-Break -Using Shift-Break to start the game should no longer be used.  
This method of starting a game is a legacy from the BBC Model B days and with 
the introduction of RISC OS and the desktop environment is no longer necessary.
The games writer should follow the guidelines provided earlier  in this 
document to find out how the game should start-up.

14. Summary

If the points in this document are taken into account then the games writer 
should be able to produce a RISC OS compatible item of software.

The basic rule when writing a game for RISC OS is :-

"Take the user into account - allow the user to start the game from the 
desktop, without the loss of any data, and then allow an easy return on 
termination of the game to a machine that is in the same state."

If you are unsure about anything that has been described in this document then 
please get in contact with Acorn Developer Support (if you are a Registered 
Developer) otherwise you should contact Customer Services.  It is important 
from Acorn's and all third parties points of view that only RISC OS Compatible 
or Compliant software is released for the Archimedes range of machines.

Appendix A:
the "Saved Game" filetype

A generic filetype exists for data saved from a  game (e.g.  an adventure 
game).  Hence,  the loading of the saved game file will cause  your game to 
re-start at the place that you left off.


FileType specification

The filetype is &AE8 and has the name 'SaveGame'.  To allow this filetype to 
be used by many different games then the file must have a specific header so 
that the required game can recognise its own saved data.  The file header will 
be as follows :-

 Size     Description

  4       A single word Identifier
  12      Name of application that created it (null terminated)

This gives the file a 16 byte header followed by the data written by the 
application/game.  The data will be at byte offset 16 in the file.

As with any generic filetype, you  may encounter the case where this filetype 
will be loaded into your application and its data is for another.  In this 
case, you should explain this to the user in an error box similar to the 
following :-

<Insert DrawFiles.Figure2 here>

Allocations of this filetype

If an application or game wishes to use this filetype then it will obviously 
need two items reserved for its own use.  These are as follows :-

A single word identifier (starting from &0000)
A 12 character name

These will be allocated by Acorn on request.


Appendix B:
SWI Interface for Joystick Devices

The Joystick module provides a SWI interface for reading the state of a 
joystick.  When the module initialises, it tests for the existence of built-in 
joystick hardware and if it does not find any then it will not initialise.  
Third parties can replace this module to provide support for different 
hardware.  It is recommended that any such modules have version numbers 
greater than 2.00 so that Acorn can upgrade its own module without preventing 
its replacement.

SWI  Joystick_Read (SWI &43F40)

Returns the state of a joystick.

On entry: R0 = joystick number

On exit:  R0 = joystick state

Interrupts:  Interrupt status is not altered

Processor mode: Processor is in SVC mode

Re-entrancy: Not defined

Use:            This SWI is used to obtain the state of the requested
                joystick.  The state is returned in the following
                format:

                        Byte 0: signed Y value (range -127 to 127)
                                -64, 0 or 64 for single switch joystick
                                (corresponds to Down, Rest, Up).

                        Byte 1: signed X value (range -127 to 127)
                                -64, 0 or 64 for single switch joystick
                                (corresponds to Left, Rest, Right).

                        Byte 2: Switches (e.g. fire buttons) starting in
                                bit 0, unimplemented switches return 0.

                        Byte 3: Reserved.

Note that this format allows both digital and analogue devices to be supported.
Applications which are only interested in state (up, down, left, right) should 
not simply test the bytes for positive, negative or zero.  It is recommended 
that the 'at rest' state should span a middle range, say from -32 to 32 since 
analogue joysticks cannot be relied upon to produce 0 when at rest.

Appendix C:
Retrieving modules from the RMA

As discussed earlier in this document, in low memory conditions it is 
permissible for the game application to kill certain modules that are not used 
by the game itself, to be able to free as much memory in the machine as 
possible.  This should, of course, ONLY be carried out in conjunction with the 
warning sequences, desktop closedown and non-return to the desktop as 
explained earlier in this document.

The list differs between machines running RISC OS 2 and RISC OS 3.  When you 
are RMKilling modules in low memory conditions, you should ensure that none of 
the modules are needed by your application.  Please note, that you should only 
RMKill modules and never UNPlug them.

The list of the modules is as follows.  You should ensure that you *RMTidy the 
module area after you have killed the modules to truly free the space.

RISC OS 2

Desktop  SystemDevices  FileCore%RAM Econet
NetFS  NetPrint  BBCEconet  International
InternationalKeyboard Debugger  IIC  SoundScheduler
StringLib  Percussion  SpriteExtend  Draw
FontManager  WindowManager TaskManager  PaletteUtil
Filer  ADFSFiler  RAMFSFiler  NetFiler
ShellCLI  Hourglass  NetStatus  SpriteUtils
Podule  SharedCLibrary ARMBasicEditor RamFS
MIDI  ColourTrans

RISC OS 3

DOSFS  !Edit  !Paint  !Draw
!Configure  StringLib  Filer_Action  SharedCLibrary
Percussion  FilterManager  WindowUtils WindowManager
TaskWindow  SystemDevices SysInfo  SuperSample
Squash  SpriteUtils  SpriteExtend  SoundScheduler
ShellCLI  ScreenBlanker  RTCAdjust  ROMFonts
ResourceFiler  RAMFSFiler  PipeFS  Pinboard
PDumperDM  PDriverDP  PDriver  PaletteUtil
NetStatus  NetPrint  NetFiler  BroadcastLoader
NetFS  InternationalKeyboar  International  IIC
Hourglass  Free  FontManager  FilerSWIs
Filer  BBCEconet  Econet  Draw
DragASprite  Debugger  ColourTrans  BASICTrans
BASIC  ADFSFiler  Printers  !Help
!Chars  !Calc  !Alarm  TaskManager
Desktop  Podule


Appendix E:
The Games Modes module

The games modes module is a module that has been specifically developed for 
the use of game style applications which take over the whole screen.  This 
module is intended to support the use of VGA monitors, but with lower demands 
on processor power and screen memory than the standard VGA mode 27 and 28.  
The games modes module provides two modes and these are as follows :-

Mode No. Dimensions BPP (no. Colours) Screen Memory Vertical Refresh

  48       320 * 480        4 (16)         96k            60 Hz
  49       320 * 480        8 (256)        160k           60 Hz

This module is available from developer support on request.


Appendix H:
Other relevent documentation

This application note does not cover all the aspects of writing games 
applications for RISC OS and other technical documentation maybe relevant.  
Other relevant documentation includes the following :-

Title:       The RISC OS 3 Programmer's Reference Manual
Publisher:   Acorn Computers Limited
ISBN:        1 85250 110 3

Title:       Acorn Assember Release 2 Users Guide
Publisher:   Acorn Computers Limited
ISBN:        1 85250 096 4
Available:   Documentation supplied as part of Desktop Assembler Pack

Title:       Acorn C Release 4 User Guide
Publisher:   Acorn Computers Limited
ISBN:        1 85250 095 6
Available:   Documentation supplied as part of the Desktop C pack

Title:       BBC BASIC Reference Manual VI
Publisher:   Acorn Computers Limited
ISBN:        1 85250 103 0

Title:       Acorn RISC Machine Family Data Manual
Publisher:   Prentice Hall, Inc.
ISBN:        0 13 781618 9
Available:   VLSI Sales Office
             486-488 Midsummer Blvd
             Saxon Gate West, Central Milton Keynes
             MK9 2EQ
             United Kingdom
             Phone: 0908 667595
             Fax:   0908 670027

Some of the titles mentioned above depend on the language used in programming.
