238 Hesketh Lane,
Tarleton,
Preston,
PR4 6RH.
INTRODUCTION
============
In COREWAR, "two computer programs in their native element -
the memory chips of a digital computer - stalk each other from
address to address".
Programs are written in in a specialised language called
REDCODE ( more about that later ), rather similar to assembly
language. The memory is represented by an array of 8000 addresses,
arranged cyclically (ie address 8000 is equivalent to address 0).
ABOUT THE PROGRAM
=================
This version of corewars is, to the best of my knowledge, a
complete implementation.
It has an integrated editor, compiler, and battle simulator, so
no tedious switching between programs, especially when debugging.
In brief, to use this program:
1) Enter the Alicorn editor,
2) Load some battle programs, or write and compile your own.
3) Go to the M.A.R.S. battle simulator.
4) Select which programs you want to fight.
5) Select START.
To quit the battle before it finishes, press Q.
You can then continue with the CONTINUE option.
HOW TO USE THIS PROGRAM
=======================
Put the program disc into your drive, and turn the computer on.
The program should auto boot.
When it has loaded, you will be presented with the following
menus:
INFORMATION EDITOR BATTLE QUIT
----------- ------- ---------- -------
CREDITS ALICORN M.A.R.S. BYE BYE
----------- ------- PARAMETERS -------
----------
CREDITS
=======
This just tells you who wrote the program - me, Stephen
Tavener, with graphics by UNICORN DREAM ( Matthew Webber ).
BYE BYE
=======
Quits from the program, and returns you to GEM.
ALICORN
=======
This is the text editor with which you can create corewars
programs. You must also use this option to load any programs into
memory, before selecting M.A.R.S. to run them.
The Alicorn editor supports the following:
BACKSPACE, DELETE, INSERT LINE(F1), CUT LINE(F2), PASTE LINE(F3),
HOME, and the cursor keys.
There are also the following menu options:
ALICORN PROGRAM ERRORS MAIN MENU
----------- ----------- ------------- ---------
INFORMATION [PROGRAM 1] 1. ERROR TEXT RETURN
HELP [PROGRAM .] . ---------
----------- [PROGRAM .] .
[PROGRAM N] 7. ERROR TEXT
----------- -------------
The COREWARS program stores several programs in memory at any one
time. You start off editing program 1, but can switch between
programs through the program menus.
Clicking on one of the programs will reveal a screen with the
following options:
PROGRAM NAME: Using the keypad, you can name your program.
The name will be used in all my routines, and
will be saved to disc with your program.
COMPILE Compile your program; the program status box
will show whether the program is successfully
compiled. If the compilation is unsuccessful,
returning to the editor will reveal a set of
error codes on the right hand side of the
screen, by the offending line.
PRINT Print a listing of your program.
SAVE These options allow you to load, save, or
LOAD delete your programs to/from disc. All
DELETE programs must have a ".WAR" extension. If you
don't specify ".WAR", then my routines will
chop your extension off, and put a ".WAR"
extension on anyway.
FINISH Return to the editor, editing whichever
program you selected.
The other options are straightforward enough; the error menu
gives a list of the possible error numbers, together with
explanations. ( After compilation, errors will appear in the right
column of the editor, and remain there until the program is
recompiled. )
BATTLE MENU
===========
PARAMETERS
----------
This allows you to select a number of configurable program
options:
Number of rounds in a battle.
Number of processes allowed per program.
Memory array size.
NB After altering the memory array size, you will need to
recompile all of your programs!
M.A.R.S.
--------
... Memory Array Redcode Simulator.
When you have loaded and compiled your programs, select this
option; you will be presented with the following menu options:
START COMBATANTS DEBUG RETURN
------------------- ------------- --------- ---------
LET BATTLE COMMENCE * [PROGRAM 1] ON MAIN MENU
CONTINUE THE BATTLE . OFF ---------
TOURNAMENT * [PROGRAM N] CORE DUMP
------------------- ------------- OPTIONS
---------
COMBATANTS
----------
The programs which will be competing in this battle. Selected
programs will be marked in the first column. If a program may not
be used, ie it is not compiled, or hasn't been loaded, then it
will be shaded, and non-selectable. As many programs as can be
selected may be run at any one time.
START OPTIONS
-------------
"Let battle commence" starts the battle. The battle may be
halted at any time by pressing "Q", which will return you to the
menus above.
After halting a battle, you may continue by selecting "Continue
the battle".
"Continue the battle" will continue from an interrupted battle.
"Tournament" will stage a Swiss tournament between all
programs. Each pair of programs will fight 3 battles, with 2
points for a win, 1 each for a draw.
DEBUG
=====
OPTIONS
-------
The debug options allow you to specify which programs/commands
to trace, and whether to direct output to screen or printer. You
can also specify where the programs should be placed in memory.
ON/OFF
------
Turns the debug options selected on or off. If no options are
selected, nothing will happen if you turn debug on.
CORE DUMP
---------
Allows you to browse through the memory array. You can step
through the memory, or select the address you want to examine.
A FINAL NOTE
============
Well, that's about all the tutorial you need... time for a few
final comments.
Firstly, the corny bit:
This program is public domain. Give away as many copies as
possible, but make sure that you include this text file, and the
sample battle programs.
However, neither the graphics nor the source code are public
domain. If you want a copy of the source code, send œ10 to me at
the address shown at the top of this letter. If you want any
graphics, write a grovelly letter to UNICORN DREAM, and I'll
forward it.
Secondly, if you find any bugs, let me know, so that I can
correct them. When enough alterations have been made, I'll release
the new version into public domain. If you want a corrected
version before that, send me œ2, to cover postage and the cost of
a disc, and I'll send you the new, improved version!
I'd also like to hear any suggestions for improvements, but if
you have any criticisms about the size of the display, please keep
them to yourself... it's fast, and it looks good on a colour
monitor. If I have a larger display, the program will start to
slow down...
CREDITS/THANKS
--------------
Mandarin Software, for a very powerful language, and for
sending an STE compatible compiler.
UNICORN DREAM, for the editor and graphics.
A. K. Dewdney, for the creation of COREWARS. Go buy his
book, The Armchair Universe.
- Enjoy!
APPENDIX A
==========
REDCODE
=======
Redcode consists of ten instuctions. With each instruction, the
programmer is required to specify at least one value ( argument ),
sometimes two.
INSTRUCTION | MNEMONIC | ARGUMENTS | EXPLANATION
=================================================================
Move | MOV | A B | Move contents of
| | | address A to address B
| | |
Add | ADD | A B | Add contents of
| | | address A to address B
| | |
Subtract | SUB | A B | Subtract contents of
| | | address A from address
| | | B.
| | |
Jump | JMP | A | Transfer control to
| | | address A.
| | |
Jump if zero | JMZ | A B | Transfer control to
| | | address A if contents
| | | of address B are 0.
| | |
Jump if not zero | JMN | A B | Transfer control to
| | | address A if contents
| | | of address B are not 0.
| | |
Decrement & | DJN | A B | Subtract 1 from
jump if not zero | | | contents of address B &
| | | transfer control to
| | | address A if contents
| | | of address B are not 0.
| | |
Compare | CMP | A B | Compare contents of
| | | addresses A and B. If
| | | they are equal, skip
| | | the next instruction.
| | |
Split | SPL | A | Split execution between
| | | next instruction and
| | | the instruction at A.
Addresses
---------
All addressing is relative; ie the command "JMP -7" means
"transfer control to the address 7 places before this one ( so if
the instruction is at address 1123, then control will be
transferred to address 1116 ).
Arguments
---------
Arguments can be addresses, or integers - usually the contents
of an address - depending on the context in which they are used.
For example, the command 'MOV A B' copies the value stored at
address A to address B.
Arguments can be in any of four modes;
direct ( the default ),
indirect ( prefixed by @ ),
immediate ( prefixed by # ), and
decremental ( prefixed by < ).
A "direct" argument is regarded as an address, to be acted on
immediately. Eg, 'MOV A B'.
An "indirect" argument means that the value/address used is
that specified by the contents of the address given. Eg,
'MOV A @B' copies the value stored in address A to the address
specified by the contents of address B. ( See the examples. )
An "immediate" argument means that the argument is to be
treated as an integer, not an address. Eg, 'MOV #A B' moves the
integer A to address B.
A "decremental" argument means that 1 is subtracted from the
contents of the address given, then the value/address used is that
specified by the contents of the address given.
-----------------------------------------------------------------
EG 1. MOV <4 @5
.
.
.
5. DAT 20
6. DAT 400
.
.
.
24. SPL 6
25. JMP -1
In this example, argument A, '<4', first 'looks' at address
1+4=5, 'DAT 20', and replaces it with 'DAT 19', then finds the
contents of address 5+19=24, 'SPL 6'.
Argument B, '@5', 'looks' at the contents of address 1+5=6,
to get the address, 6+400=406.
Hence, line 1 becomes 'MOVE "SPL 6" to address 406'
----------------------------------------------------------------
Most of the commands are self explanatory, but some deserve
extra attention;
DAT is not, strictly speaking, a command - just
a space containing an integer. If a program tries to execute such
a command, it will be killed.
SPL - split - effectively allows your program
to have several sub-programs (processes) running simultaneously.
This increases your chances of survival, because your program
only dies when all of the processes are dead. However, the system
allocates one move to each PROGRAM alternately, so the more
processes that you have running, the slower each will move. In
fact, the 'split bomb'; SPL 0 is a very effective weapon. If the
enemy program attempts to execute this, then the number of its
processes will increase indefinitely ( until the system maximum
is reached ).
SYNTAX
------
Program syntax is as follows:
[LABEL:] [COMMAND] [ARGUMENT A] [ARGUMENT B]
Each part must be separated from the others by at least on
space... more if you like.
Arguments have the following structure:
[QUALIFIER][VALUE]
There should be no space between the qualifier (space, #, @, <)
and the value (integer or label).
LABELS
------
Rather than specify an address, which can quickly become
confusing... especially in a long program, you can use labels:
To label a line, put the label name, followed immediately by a
colon, at the start of the line. Whenever you want to specify this
line, just use the label instead of the relative address.
Example:
LOOP: MOV #0 -1 is equivalent to MOV #0 -1
JMP LOOP JMP -1
If one of the labels is START, then program execution will
begin at that line, rather than at the first line.
Labels must be entirely alphabetic, and should not be command
names, or strange thing will happen...
COMMENTS
--------
Type a semicolon to signify a comment. The rest of the line
will be ignored.
APPENDIX B
==========
EXAMPLES
--------
All of these examples should be on the disc.
In all of the examples, ignore the line numbers... they just
make the explanations easier.
IMP
===
Imp is the simplest possible battle program. It copies itself
from one address to the next, moving all the way through the
memory, and hoping to overrun the enemy.
It is fast, virtually unstoppable, but seldom wins; most of the
time, the enemy merely becomes an imp - or imps - itself:
1. MOV 0 1
Yes, that's it! The command translates as "Copy the contents of
address 0 (this address, ie the command itself) to the next
address (current address + 1)"
When the controller next comes to execute this program, it will
execute the next line, where Imp has just placed a copy of itself!
IMP STOMPER
===========
This is not a program in itself; just a defence against the
Imp.
1. MOV #0 -1
2. JMP -1
Instruction 1 places the integer value 0 into the address
immediately below it, effectively erasing the contents of that
location.
The next time the program is executed, instruction 2 transfers
control back to instruction 1, so that the third time the program
is executed, it starts all over again.
Now, imagine an imp crawling up the memory towards the imp
stomper. The action will start when the imp arrives directly below
imp stomper. In 50% of the cases, Imp will move below Imp Stomper,
then Imp Stomper will move a zero into the Imp's address,
effectively killing it. The other 50%, Imp stomper will merely
jump back to the previous statement. In this case, Imp will copy
itself over instruction 1 of Imp Stomper. The next time Imp
Stomper is executed, it will execute the Imp, which has just been
copied over instruction 1, so that we now get two Imps chasing
each other through the memory. A draw.
MICE
====
'Mice' creates multiple copies of itself, all running
concurrently. It attempts to win by overrunning the opposition. In
fact, it won the 1st Core Wars Tournament.
1. PTR: DAT #0
2. START: MOV #12 PTR
3. LOOP: MOV @PTR <5
4. DJN LOOP PTR
5. SPL @3
6. ADD #653 2
7. JMZ -5 -6
8. DAT 833
On the first round, line 2. is executed, and PTR is given a
value of 12.
Next, lines 3 and 4 copy MICE, 'tail first', command by command
until the whole thing has been copied.
When all of MICE has been copied, a new mouse is spawned with
the SPL command. A new destination is selected for the new mouse
by adding 653 to the destination pointer (line 8), and the process
repeats.
There are many other programs on the disc. If you still aren't
sure about REDCODE, run some of the programs under DEBUG, and see
what they do...