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