COREWARS README FILE


last change: 23 March 2000 by Walter Hofmann <walterh@gmx.de>

_______________________________________________________________________

 1) 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

	http://www.gtk.org/

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