Instructions for using the Mars Core Wars Automaton
by Cristian Ghezzi and Sergio Monesi


INTRODUCTION
------------

ABOUT THE PROGRAM

Mars is a Core Wars multi-tasking integrated environment. It includes a
Redcode compiler, the Memory Array Redcode Simulator (MARS) and a Redcode
Debugger. It installs itself on the icon bar, can interact with
multi-tasking text editors like Edit, and has a special facility to send
data to Pipedream 3 (see below). It has been entirely developed on the
Archimedes using the Acorn ANSI C Compiler Release 3 and Release 4.

THE ORIGINS

Mars allows you to play the game called "Core Wars". In this game two 
programs written in a special language fight each other until one "kills" 
the other. The aim is to write the program that defeats the highest number 
of enemies.

This game was invented by A.K.Dewdney of Ontario University nearly ten
years ago, and was published in "Scientific American" in the column called
"Computer (Re)Creations". It was such a great success that a bit later the
"International Core Wars Society" (ICWS) was created. ICWS defined the
standard rules to which all the programmers had to conform and organized an
annual tournament to proclaim the strongest warrior of the world.

GAME DESCRIPTION

This is a game that you can't play: your programs do it for you. But we 
don't think you can call fighting for life and death a game. It is a war, 
a war inside the computer memory, a "Core War" between digital warriors. 
They can't spread over the memory but must stay in a restricted area, the 
"core", from which they can't escape but where they can move without 
restrictions. The programs are written in a special language called 
"Redcode" and run under supervision of the "Memory Array Redcode 
Simulator" (MARS). Mars must interpret one instruction at a time and take 
appropriate action until it understands that one warrior has been killed 
by the other, or until it has executed 50000 instructions per warrior 
(cycles) in which case there is no winner. But one battle is not enough to 
decide who is stronger because the result could have been down to luck, so
two warriors must fight many battles (e.g. 20-100). A war is fought between
only two warriors, so if you want to find the best from a lot of programs
you have to make them fight each other two by two in a tournament.

HOW TO USE THE PROGRAM
----------------------

STARTING

When you run the program it installs itself on the icon bar. Clicking
Select on the icon opens two windows, the "Tournament Control" window and
the "Warriors" window. To begin the fight you can either load some warriors
or load a previously saved tournament file, dragging them respectively to
the former or to the latter window. You can also drag them to the icon bar
icon (note that you can select many warrior files and drag them together).
When a warrior has been loaded and compiled its name appears in the warrior
window; the name is taken from the first line of the warrior file, or from
the filename if there is no name.

THE COMPILER STEP

When a warrior is dragged into Mars it has to be translated from a text
program into code that Mars can understand. This is done by the Compiler.
If the warrior program is correctly written you only notice a very short
delay, but if it contains some mistakes the Compiler opens a window to show
you the error list and the faulty program is not loaded.

THE TOURNAMENT CONTROL WINDOW

This window allows you to run and monitor the whole tournament. There are
many icons you can interact with:

- Start, Pause, Stop: Once you have loaded the warriors, clicking on Start
begins the fight. Then you can Pause or Stop it as you wish. A paused
tournament can be continued by clicking on the Pause icon again. If you
start a tournament without clearing the results of a previous one (see
below) the new values are added to the old ones. This allows you to extend
a tournament if you think that a bigger number of rounds is needed to be
sure of the reliability of the result. For example if you have just made a
tournament with sixty rounds per match you can restart it, setting the
rounds per match to forty; the final result is the same as if you had typed
one hundred rounds per match from the beginning.

- Graphics: Initially you have no graphics. Clicking on this icon with
Select or Adjust allows you to change type of display: it will cycle
through "No", "Small", "Medium" and "Big". With no graphics Mars runs
considerably faster. Small and Medium graphics are shown in a movable
window so that you can set it in the position you like (even outside the
screen area). The Big window is shown in the background of the Desktop and
you can't move or resize it.

- Full Screen: Leaves the Desktop and takes you to the "Mars Full Screen
Mode", described later.

- Fast: Mars will take over the processor, eventually switching the screen
off, to achieve the best time performance (with an ARM2 processor 50000
cycles in less than 4 seconds). If you move the mouse the screen will be
switched on for a few seconds to let you control what is going on without
leaving fast mode. To leave fast mode simply click a mouse button.

- Wait: This icon toggles the wait flag on and off; when it is on Mars
pauses after each round and shows the result of the last match,
highlighting the winner or, if a draw, highlighting both fighters.

- Cycles/Poll: The number in this icon represents how many cycles (couples
of instructions) Mars executes every time the Task Manager passes control
to it. With a high value Mars runs faster but the Desktop and the other
applications run slower. If you use too high a value you will notice that
everything in the Desktop becomes slow and sometimes quite impossible to
use. Even Mars could seem to be slower but it is only the Desktop interface
that is slow; Mars itself runs faster. On the other hand, when using a
lower number the Desktop runs without delay but Mars takes more time to do
its job. When you change graphic type the cycles per poll number changes to
a more appropriate value. This has been tested on an ARM2 processor and
without other applications running in the Desktop. You may have to change
it to a suitable value.

- Rounds/Match: In this icon you can type the number of rounds (battles)
the two warriors have to fight to determine who is the best between them.
The bigger the number, the more reliable the result. For a very reliable
tournament you must type at least 100.

The remaining icons give various information: which warriors are fighting,
the total number of matches, the matches and the rounds played so far, the
cycles executed in this round, the total elapsed time from the start of the
tournament and the average time taken for one round. Note that the "Actual
Cycle" and the "Elapsed Time" icons show you the speed of the Desktop: if
they are updated after long intervals you may need to decrease the value of
cycles/poll described above (or buy an ARM3 if you don't have one!).

Clicking Menu pops up the Tournament Menu. Some of the items are a copy of
the icons in the window and do the same job. There are also some extra
items:

-Type: Before starting a tournament you can choose its type. Suppose you
have loaded three warriors named A, B and C, and you want them to fight two
rounds per match. If you choose "type by match" the battle sequence would
be A vs B, A vs C, B vs C for the first round and the same again for the
second one; with "type by round" the sequence would be A vs B, A vs B for
the first match, A vs C, A vs C for the second one and B vs C, B vs C for
the last match.

- Fast: This allows you to enter Fast Mode; by default the screen blanks
but you can switch this option off if you detect some problem with your
computer.

- Save: This leads you to a submenu where you can choose to save the
tournament, the statistics or the result.

- Save Tournament: Allows you to save the tournament so that you can resume
it when you want.

- Save Statistics, Save Result: Creates a table with the result of every
single match or a copy of the Warriors Window. You can choose the "Edit"
format or the "PipeDream" format and save to disc or directly to an
application.

THE WARRIORS WINDOW

This window lists the name of all the warriors loaded with the number of
rounds that have been won, drawn and lost, the score realized by each one
and the efficiency. This last parameter is obtained by dividing the score
by the total number of available points. The higher it is, the better the
warrior behaves. The menu allows you to delete all the warriors or clear
all the results. If you click Menu while over a warrior icon you can take
the same actions on the only warrior selected. Furthermore you can sort the
warriors by score, by the number of rounds won, drawn or lost, by
efficiency, by name or by loading order. The auto sort option will sort the
warriors after each match or round, depending on the tournament type. As
stated above, to load a warrior you can drag it to this window; if you drag
it exactly on a warrior name icon and the dragged warrior has the same name
of the old one, this one is replaced with the new one. You can use this
facility when debugging a program so that you can modify a warrior in Edit
and then immediately load it into Mars and test it without having to delete
the old version by hand.

THE GRAPHIC WINDOWS

The first two graphic windows differ only in size. The window is divided in
two parts: the bottom displays an image of the "core" where the battle is
proceeding, the top lets you control the display of additional information.

- The core: The area of the computer memory where the warriors fight is
called the "core". It is divided into a number of cells. Each cell is
represented in the window by a little square. At the beginning of a round
the core is cleared and the two fighters are placed in it at a random
location. The cells occupied by them are set to red or blue respectively.
All empty cells are black. During the battle the locations executed by the
two programs are set to red or blue, while the cells modified are set to
orange and light blue.

- Box: If this option is on, a white box surrounding a cell will show the
location that is actually executed.

- Debug: If debug is set, text appears near the name of the warrior telling
you the number of the task in execution, the total number of tasks, the
location of the instruction and the instruction itself. Note that the
location printed after the task number refers absolutely to the start of
the core but the numbers printed after the instruction refer relatively to
that location. Note also that a negative address in the source file is made
positive by adding the core size (8192) so that -1 is printed as 8191. If
you move the pointer over a cell of the core you will have the instruction
in it displayed in the correct icon.

- Delay: If you want you can slow down the execution. If you set the
maximum delay (200) you enter single step mode: after every instruction the
execution is suspended, waiting for a mouse click in the window.

The "Big" window is similar to the others but it always stays on the
background, can't be moved or resized and to turn it off you have to click
on the "Quit" icon.

If you set "Wait" in the Tournament Window the winner is highlighted after
each round and you can continue execution clicking on the window
background.

THE FULL SCREEN MODE

When you select this mode you leave the Desktop and all the tasks are
suspended. The screen is redrawn showing the core in the main area, some
icons at the top and a dummy icon bar on the bottom. The aim of this option
is to look at the graphics at an astounding speed and also take some of the
already explained actions such as debugging etc. Note that the "win",
"draw" and "lost" values represent the result of the rounds between the two
warriors and not the total as in the Warrior Window. The icon bar shows
three "strange" icons: the palette-like icon lets you change colours
cycling over five palettes, the last of which can be randomly set up
clicking over the taskmanager-like icon, and the disc drive icon takes you
back to the Desktop.

THE ICWS STANDARD
-----------------

This version of Mars conforms to the International Core Wars Society
standards defined in 1988:

- Maximum number of instructions in a program: 512 (Note that equs are not
instructions)

- Maximum number of parallel tasks: 64

- Minimum initial distance between two warriors in the core: 2048

- Number of cycles for draw: 50000

- Size of the core: 8192 cells

- Score: 3 points to the winner, 0 to the loser and 1 both if draw.

KNOWN BUG
---------

Sometimes, while the "Redcode Compiler" window is open (the one reporting
errors generated by the compiler), Mars seems to refuse to start. To solve
the problem simply close the window. This could be a bug in the RISC_OSLib
of Desktop C: when you drag the vertical scroll bar or play around with the
caret, the txt module changes the idle event claimer and masks out NULL
events. Any ideas about this problem are most welcome.

CONTACT THE AUTHORS
-------------------

We have done everything possible to sweep all the bugs out of this program,
but some of them may still remain. If you find one please contact us. Send
in any warrior you want to share with us: we will try to manage a big
tournament with all the programs people send in. Also please do send any
suggestions for improving the game, such as new Redcode instructions or
other ideas.

Write to:

Cristian Ghezzi                          Sergio Monesi
Via Bramante da Urbino 2                 Via Trento e Trieste 30
20035 Lissone (MI)                       20046 Biassono (MI)
ITALY                                    ITALY

Email: ser638@cdc835.cdc.polimi.it

 RISC User 1992
