Writing Games for RISC OS

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) Acorn Computers Limited 1992

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.

Appendices

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.

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.

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.

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.

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.

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.

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.

It is recommended that a game which makes any change to the host machine's
memory allocation (via manipulation of the RMA),should end its execution by
instructing the user to perform a hard reset,
e.g.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

2

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
a standard WIMP error box.

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

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:

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.

This application was converted into HTML format by Gareth Moore, 29/1/95. It
was the first HTML document I ever wrote!