COREWARS README FILE
last change: 23 March 2000 by Walter Hofmann <walterh@gmx.de>
- What is Core Wars
Core Wars is a simulation game. A number of programs are loaded into a virtual machine and executed. The programs can to crash each other, manipulate other programs, overwrite as much memory as they can, etc... The "best" program is selected according to a scoring mechanism which involves the number of memory cells the program has overwritten, the number of other programs it has crashed and whether/when it crashed.
Two different languages are supported. The one called "Corewars" is easy to learn and described in this document. The second language, called "Redcode", is harder to learn but also more powerful.
2) Compiling Core Wars
You do not need to compile Corewars if you download the precompiled RPM package. It should work on any Linux/glibc2.1 system (like Red Hat 6.1, SuSE 6.3). You can download it from the Corewars homepage at http://corewars.sourceforge.net/
If you want to compile Corewars yourself, then you need Glib 1.2.x and Gtk 1.2.x. Get them from
and install them first.
Then untar the distribution file (you probably did this already), enter
cd corewars-x.y.z
./configure
make
To try the program without installing it:
cd programs
../src/corewars
From 0.9.6 on there is a spec file. You can use it to generate a RPM package from the tar file:
rpm -tb corewars-x.x.x.tar.gz
3) Installing Core Wars
If you downloaded the RPM package or created it yourself install it with
rpm -i /path/to/rpm/corewars-x.x.x-x.rpm
or
rpm -U /path/to/rpm/corewars-x.x.x-x.rpm
if you have a previous version installed.
If you compiled the source package enter
make install
to install the Core Wars executable in /usr/local/bin and the sample corewars programs in /usr/local/share/corewars (unless changed with configure).
4) Using Core Wars
File/Load Directory...
Loads all *.cw and *.red programs in the selected
directory. Double-click on the directory name to load a
directory without closing the window.
File/Select Programs...
Selects the number of copies (processes) to load from each
program. Syntax errors in the programs are displayed in this
window as well. The program title is prefixed with the
language the program is written in. You can only load programs
in the currently active language; use the options dialog to
change this. You can start your editor from the select window
to make changes to the programs; just click on "Edit". By
default nedit is used; this can be changed in the options dialog.
File/Start, Pause, Continue, Single Step, Stop, Quit
do the obvious things
View/Statistic...
opens a statistic window. You can see the loaded programs
sorted by their score. Threads is the number of independent
threads of execution for each running process or "dead" if
the program has crashed. Cells gives the number of memory cells
the program currently owns. Kills is the number of other
programs that have been crashed by this program.
Select "selection follows process" to make the selection bar
follow the selected process when its rank has changed.
You can click on a line in the statistic to mark all the cells
the process owns.
View/Options:
Some options in the dialog can only be changed if the program
is not running.
The "General" page:
You can select the language here. The other options apply to
both languages. If a process tries to create more than the
maximum threads it is killed if written in Corewars or no new
threads are created if written in Redcode.
The "Corewars" page:
Options on this page apply to Corewars only.
By disabling "Allow self move" you can forbid one particular
"move" instruction. This is explained in detail in the section
about "move" further down in this file. This instruction is
enabled by default.
The "Display" page:
You can use the settings on this page to adjust the executions
speed. To make the virtual machine faster increase the "Number
of steps in each execution block" setting. Don't change the
delay time. Make sure to use reasonable numbers or the program
will react slowly and display updates will be delayed.
"Statistic update delay" gives the delay between two updates of
the statistic window.
The "Game Score" page:
"Alive points" is the number of points the program gets per
instruction executed.
"Cell points" is the number of points a program gets per cell
owned.
"Kill points" is the number of points a program gets when it
crashed another program.
The "Program Score" page:
This page describes how the program score (eg. for a
tournament) is made up from the game scores.
The "Editor" tab:
Enter the name of you editor here. It is called with the file
name as its only argument.
5) Writing Your Own Programs
Use one of the supplied programs as a starting point. Make sure you save the program with the extension .cw. If you have changed you program while Core Wars is running you only need to reopen the "Select Programs" dialog box to reload your program.
Please send me you programs! I will include them in the distribution. My mail address is walterh@gmx.de .
6) Virtual machine
The memory consists of SIZE cells. All address arithmetic is done modulo
SIZE Each cell can contain a signed 32-bit integer or an instruction.
Every process running on the virtual machine gets the same share of
cpu time. The programs are run with a round-robin scheduler, one
instruction per process and time-slice.
Every process can consist of many threads. They are executed
independently. The threads are executed with a round-robin scheduler as
above, but they can only use the time-slice of their process.
The number of threads is limited. If a process creates too many threads,
the whole process crashes (for Corewars, in Redcode no new threads can
be created).
Each time a process writes to a memory cell, it gets the "ownership" of
the cell. However, a process can read and execute cells owned by other
processes without any difference.
When the processes are loaded into the memory, they are placed at a
random position. A minimum distance between every two processes is
guaranteed.
Execution is started at the first non-data cell (for Corewars, in
Redcode you can set the starting point using "ORG" or "END").
Instructions which access a memory cell are stored in a way that when
they are copied to a different location, they access the memory cell
which is moved by the same number of cells, i.e. all addresses are
stored relative to the instruction.
Only instructions can be executed. Attempts to execute data cells will
crash the task doing so.
7) Programming language
This section applies to the Corewars language only.
The general form of an instruction is
<label>: <keyword> <operand1> [ , <operand2> ] #comment
<label> is an alphanumeric identifier for this instruction cell.
<keyword> is one of the instruction names listed below.
<operand1,2> can be one of:
<integer> just a plain integer (signed)
&<address> gives the address of a labelled instruction
<address> gives the content of a labelled instruction
[<address>] takes the content of <address> and uses it to
address another memory cell and gives its
content.
Make sure that the last instruction in a program is terminated by a newline. The instructions are:
title <String>
Gives the title of the program. Must not have a label. Does not
use a memory cell. Must only be used once.
data <integer>
data &<address>
Stores the integer or address in a memory cell.
move <operand1>, <address>
move <operand1>, [<address>]
Copies <operand1> to <address> or [<address>]. Can copy data and
instructions. By disabling the "Allow self move" option moving
a move instruction with two <address> operands is forbidden if the
instruction used to do this is a move instruction and <address>
operands are used in this instruction.
add <operand1>, <address>
add <operand1>, [<address>]
Adds <operand1> to <address> or [<address>]. Memory cells must
contain integers.
neg <operand1>, <address>
neg <operand1>, [<address>]
Copies - <operand1> to <address> or [<address>]. Memory cells
must contain integers.
mul <operand1>, <address>
mul <operand1>, [<address>]
Multiplies <address> or [<address>] by <operand>. Memory cells must
contain integers.
div <operand1>, <address>
div <operand1>, [<address>]
Divides <address> or [<address>] by <operand>. Memory cells must
contain integers. Division by zero terminates the thread.
mod <operand1>, <address>
mod <operand1>, [<address>]
Divides <address> or [<address>] by <operand>. The remainder of the
division is stored. Memory cells must contain integers. Division
by zero terminates the thread.
and <operand1>, <operand2>
Calculates (<operand1> AND <operand2>) and stores the result in
<operand2>. Memory cells must contain integers.
not <operand1>, <operand2>
Calculates (NOT <operand1>) and stores the result in
<operand2>. Memory cells must contain integers.
equal <operand1>, <operand2>
Compares <operand1> and <operand2>. The next instruction is
skipped if they are not equal. Can compare both integers and
instructions. Instructions are only equal if they are copies
from each other.
less <operand1>, <operand2>
Compares <operand1> and <operand2>. The next instruction is
skipped if the first is not (strictly) less than the second.
Must be integers.
jump <address>
jump [<address>]
Jumps to <address> or [<address>]
fork <address>
fork [<address>]
Starts a new thread at <address> or [<address>]. Execution
also continues at the next instruction.
info <index>, <address>
info <index>, [<address>]
Reads a system-dependent value. All available values are
indexed from 0 on. Possible indices are:
0: gives the size of the memory
1: gives the square root of the size of the memory
(if the size is not a square then the integer part of the
square root is returned)
2: gives a random number 0...size of memory-1
3: gives a random number 0...sqrt(size of memory)-1
4: gives the number of threads of this process
5: gives the number of elapsed cycles
6: gives the maximal number of threads a program may have
All other values are not allowed.
system <operand1>, <index>
Changes a system-dependent value. No values are defined. This
instruction is very useless right now.
own <address>
own [<address>]
Skips the next instruction if <address> of [<address>] does
not belong to the process.
loop <address1>, <address2>
loop <address1>, [<address2>]
loop [<address1>], <address2>
loop [<address1>], [<address2>]
Decrements the first operand by 1. If the result is not zero,
jump to the second operand.
movei <address1>, <address2>
This command does the same as
move [<address1>], [<address2>]
add 1, <address1>
add 1, <address2>
in one step.
9) Web page, online warrior tournaments
The Corewars web page is at http://corewars.sourceforge.net You can find there:
- Latest version of Corewars, both .tar.gz and .rpm. If you have a sourceforge account you can get notifications of new versions.
- The bug tracking system (don't bother with it if you don't want it -- just mail me your bug reports).
- Online tournaments ("Hills"). You can submit your warriors and they will automatically be run against all others currently in the high score list. Different configurations with different parameters are available.
8) Bugs, patches, feedback
If you found a bug or if you want a change included in the program then mail me. My email address is walterh@gmx.de . Please tell me if you like Corewars.
Have fun!
March 2000,
Walter Hofmann