The MADgic Core Core War for the Amiga ©1992 Mark A. Durham Table of Contents Introduction 3 A Brief History 4 Description 6 Quick Start 8 Redcode 12 ASR 26 MARS 29 Menus 32 2 Introduction Welcome to The MADgic Core, Core War for the Amiga. Core War, dubbed "the Programmer's Game of Choice", is an exciting dual of survival between programs within your computer. The MADgic Core brings you all of the tools necessary to do combat. This manual will provide you with a basic understanding (or reminder) of Redcode assembly language programming as well as a complete description and explanation of the use of the Redcode assembler, MARS executive program, and tournament manager. 3 A Brief History Core War was first defined by D. G. Jones and A. K. Dewdney of the Department of Computer Science at the University of Western Ontario in March of 1984 in their "Core War Guidelines". Core War was introduced to a larger public via Dewdney's regular columns in Scientific American, "Computer Recreations", starting in May of 1984, and a collection of those columns (and others) in Dewdney's book - The Armchair Universe. 4 Since that time, Core War has been in the hands of The International Core War Society. The ICWS has produced two standards over the years: ICWS'86 and ICWS'88. Neither varies too far from the original document, nor are they much different from each other. This is a partial testament to the soundness of the careful initial thought and effort that went into the project as well as the difficulties of agreeing on new ideas. 5 Description Core War is a game which combines programming skills and strategic thinking. The object is very simple: devise and implement a program more capable of surviving and more capable of killing than your opponent's. It is much like deciding on an opening game, middle game, and end game in chess and irrevocably committing robots to play the game that way for you. The robots won't make any mistakes, but if your strategy was wrong, you lose. Note that although Core War encompasses much of Artificial Life and computer virus theory, there is absolutely no 6 danger to your computer or anyone else's computer from Core War. The MADgic Core is a completely contained, stable environment. You quit, and it is gone. Core War consists of two parts: the language and the simulator. The language is known as Redcode. It is an assembly language and is described in full in the following section. The simulator is known as MARS (for Memory Array Redcode Simulator). The MADgic Core consists of ASR, a symbolic Redcode assembler, MARS and other simulators, and a collection of Redcode programs from previous ICWS tournaments. Also included is a tournament manager program. 7 Quick Start This section describes the basics of how to write, assemble, and run Redcode programs. Insert your copy of The MADgic Core disk into a disk drive. Assuming you still have the Notepad utility on your Workbench disk, double-click on the IMP.s icon. This will open up a Notepad note. If you do not have the Notepad utility on your Workbench disk, you can view the contents of the file with any standard text editor or word processor. 8 The note is actually a Redcode source file for a program called IMP. The appendix ".s" is necessary on all source files, hence this note is named "IMP.s". You do not need to make any changes to this file, so just close the Notepad window for now. Select the IMP.s icon. While the IMP.s icon is selected, shift double-click on the ASR icon. A window will open up and a question will be displayed. Answer the question by typing a 'Y' followed by . A listing of the file will be displayed in the window followed by a symbol table. 9 A request to hit the key is the last thing in the window. When you have finished looking at the window, hit . The window disappears. Double-click on the MARS icon. A blank and borderless window will open in a new screen. A requester will appear. Select "OK" and the requester will disappear. Select "Load" from the "CORE" menu. A requester will appear. Select the left uppermost text gadget and type "IMP". Select the left lowermost text gadget and type "IMP". Select "OK" and the requester disappears and the programs are loaded. 10 Select "Go" from the "Control" menu. You should see an advancing white square lead by a light blue square on the top half of the screen and an advancing black square lead by a dark blue square on the bottom half of the screen. After a while, select "Stop" from the "Control" menu. Next, select "Close" from the "Core" menu. Congratulations! You have successfully assembled and run a Core War program! 11 Redcode Redcode is the language of Core War. Redcode is an assembly language. This means that each single statement in Redcode will be assembled into a single machine language instruction. Because there is no Core War machine as of yet, we use a simulator to run the machine code instead. There are eleven types of machine instruction. Each of these types has a corresponding three-letter opcode in Redcode. These opcodes are: DAT, MOV, ADD, SUB, CMP, JMP, JMZ, JMN, DJN, SLT, and SPL. These opcodes are meant to be indicative of what the instruction will do. DAT is storage 12 for data, MOV moves data, ADD and SUB add and subtract data, etc. These opcodes will be explored further below. Each opcode can be followed by one operand or two operands seperated by a comma. Operands are merely that part of an instruction which holds the data operated on by the opcode, or tells the opcode where to find the data. We usually indicate generic operands as A and B. Operands can be divided up into two seperate parts: the mode indicator and the address. The mode indicators are for immediate, the # (octothorpe), for direct, _ (space) or $ (dollar sign), for indirect, @ (commercial 'at'), and lastly 13 for pre-decrement indirect, < (left angle bracket). The mode indicator tells the opcode whether the address is data (immediate), an offset to the data (direct), an offset to an offset to the data (indirect), or an offset to one more than the offset to the data (pre-decrement indirect). The address of a Redcode instruction is special. All addresses in Core War are relative to the currently executing instruction and modulo the memory size of our Core War machine. This means that if the memory size of our machine is 8000, an address of -2 is really 7998; an address of 9256 is really 1256. 14 Fortunately, ASR is a symbolic assembler. What this means is that most of the time you will not have to bother writing addresses as numbers. Each statement of interest to you may be proceeded with a label. A label may be any word other than the opcodes and any other labels. Lastly, there are things you can write in Redcode which do not have a direct relationship to the machine instructions. These include comments and pseudo-ops, opcodes which instruct the assembler to do something rather than produce a machine instruction. 15 In order to better understand Redcode, it is best to look first at a few Redcode programs. The smallest useful program is Imp. Here we have an expanded version to demonstrate all of the important aspects of Redcode. ; Imp.s ; by A. K. Dewdney ; Imp MOV Imp, Imp+1 ; That's all! END 16 The lines which begin with a semicolon are comment lines. These lines mean nothing to the Redcode assembler, so they are ignored. You can use comments to keep track of who wrote a program, when it was written, what kind of algorithm it implements, etc. There is only one real instruction line in the program. It starts with the label Imp. The opcode is MOV. Both the A and B operands are of direct mode. You will note that this instruction is followed by a semicolon and another comment. 17 Of interest is the fact that in the A address is the Imp label again. The Imp label is also in the B address along with a plus sign and a one. Because the offset from this instruction to this instruction is zero, the statement could have been written much more simply as MOV 0, 1. Finally, the pseudo-op END instructs the assembler that we are at the logical end of this file and it may stop assembling now. The only other pseudo-op of interest is EQU. These pseudo-ops, as well as the opcodes, are discussed in greater detail below. 18 DAT A B This instruction is used for storing data. However, upon trying to execute a DAT instruction, the current task is stopped and removed from the queue. When all of one player's tasks have been stopped and removed from the queue, that player has lost. MOV A B If the A-mode is immediate, the A-value is placed in the B- operand of the memory location specified by the B-operand. Otherwise, the entire statement referred to by the A-operand is moved to the address specified by the B-operand. 19 ADD A B If the A-mode is immediate, the A-value is added to the B- operand of the memory location specified by the B-operand. Otherwise, both operands are added: the A-operand is added to the A-operand of the memory location specified by the B- operand and the B-operand is added to the B-operand of the same memory location. SUB A B SUB is just like ADD except the operands are subtracted instead of added. 20 JMP A B This task will continue processing at the memory address specified by the A-operand, instead of the next statement as usual. JMZ A B If the B-operand evaluates to zero, a jump will occur just as in JMP A B, otherwise the task will continue with the next statement as usual. 21 JMN A B If the B-operand does not evaluate to zero, a jump will occur just as in JMP A B, otherwise the task will continue with the next statement as usual. CMP A B If the A-mode is immediate, the A-value is compared to the evaluation of the B-operand. Otherwise, the entire statement referenced by the A-operand is compared to the entire statement referenced by the B-operand. If the comparison is equivalent, the next statement is skipped. 22 SLT A B If the A-mode is immediate, the A-value is compared to the B-operand specified by the B-operand. Otherwise, the B- operand specified by the A-operand is compared to the B- operand specified by the B-operand. If the comparison is less than, the next instruction is skipped. Note that nothing is less than zero. DJN A B The value referenced by the B-operand is decremented and compared to zero. If it is not zero, a jump is taken just as in JMP A B. 23 SPL A B The task starting at the address specified by the A-operand is added to the task queue. Note that this new task is placed between the current task and the next task. Also note that all other tasks will execute once before this task will execute for the first time. EQU A EQU is a pseudo-op which associates everything to the right of itself with the label of the left of itself. So the result of the statement X EQU A is the same as replacing every occurence of X with the text A. 24 END A END is a pseudo-op which indicates the last logical line of Redcode. Additionally, if there is an operand it indicates which statement is the first to be executed. If there is no operand, execution will start with the first statement. 25 ASR ASR, the assembler, can be started from either the CLI or the Workbench. The assembler accepts as a source file any plain ASCII text file such as that produced by the Notepad (with Global Fonts), a text editor, or a word processor (again, when saved as plain ASCII). The name of the source file must end with a ".s" in order for ASR to recognize it. There are many example source files presented on the disk. To invoke ASR from the CLI, type "ASR" followed by the name of the source file. The name you type after "ASR" need not have the ".s" appended to it, as in "ASR IMP", but ASR will 26 still look for a filename ending in ".s"; "IMP.s" in this example. If you want to list the assembler output from the CLI, place a " -l " (a minus sign followed by a lowercase L) between "ASR" and the name of your source file. If you want to send the listing to the printer, type " >prt: " just after "ASR" and before " -l ". If you want to send the listing to another file, replace "prt:" with the name of your list file in the example above. 27 To invoke ASR from the Workbench, select the icon of the source file you want to assemble and shift double-click on the ASR icon while the source file icon is still selected. If you want to list the assembler output to the window, type "Y" followed by the key. If you want to list the assembler output to the printer, type "P" followed by the key. If you do not want to list the file, type "N" followed by the key. In any case, you will need to hit the key after the assembly is complete in order for the window to close. 28 MARS MARS can be started from either the CLI or the Workbench. To start MARS from the CLI, type "MARS". Any parameters will be ignored. To start MARS from the Workbench, double-click on the MARS icon. Alternatively, select one or two files, and shift double-click on the MARS icon while the file(s) are still selected. Any selected files will still need to be loaded, but the file name(s) will be already in the load requester text gadget(s). 29 Default core size, maximum number of tasks, maximum number of cycles, colors, and version can all be set from the Workbench. Select the MARS icon and select Get Info from the Workbench menu. In the Tool Types, you will see these options. Add or change Core Size= to any of the menu choices. Tasks= can be any number, as well as Cycles=. Version= should be either 86 or 88. 30 Color= sets all the colors. They are listed as eight sets of three hexidecimal numbers (0-F) seperated by vertical bars (|). Each number represents one fifteenth of a percent of red, green, or blue in that order. The order is background, MOV A, MOV B, executing A, executing B, DAT A, DAT B, and SPL. 31 Menus This is a reference section for the menu items you will find in MARS. Core The Core menu is available whenever there are no requesters open in the MARS window and there are no battles currently running. Size The Size item has subitems of 2000, 4000, 8000, 8192, 16000, 32000, 64000, and 128000. Each of 32 these subitems selects a core size. Not all core sizes may be available to you. The more memory you have, the larger the core size you can accomodate. The arrow indicates which core size you have selected. Just because you are able to select a core size does not mean that you can actually run programs in a core of that size. In the event you do not have enough memory for a core of your selected size, a requester will appear with "Not Enough Memory" when you try to load your programs. 33 Load The Load item brings up a requester with two text gadgets on the left and two integer gadgets on the right. Type the names of the programs you want to load into the text gadgets on the left and type the locations to load the programs to in the adjacent integer gadgets on the right. Then select "OK". If you did not intend to bring up the load requester, then select "Cancel". 34 Alternatively, you can specify which file to load by clicking on the "A" or "B" gadget for Player A or Player B respectively. Clicking on either of these gadgets brings up a file requester. You can specify what volume by volume name, assigned name, or device. You can then enter directories by clicking on the appropriate name. "Parent" will take you up to the parent directory. You can change the extension filter by double- clicking on "Filter", or just turn it on/off with a single click. The default extension filter is 35 ".o" since MARS can load only those files which end in ".o". The load requester can be brought up at any time by holding down the right Amiga key and the L key at the same time. You must load in programs before you can access the "Control", "Trace", or "Memory" menus. 36 Max Cycles The Max Cycles item brings up a requester with an integer gadget. Select the integer gadget and type in the maximum number of cycles you want executed per side before declaring a draw, then select "OK". If you do not want to change the maximum number of cycles from that originally displayed in the requester, select "Cancel". Max Tasks The Max Tasks item brings up a requester with an integer gadget. Select the integer gadget and type in the maximum number of tasks you want to 37 allow per side, then select "OK". If you do not want to change the maximum number of tasks from that displayed in the requester, select "Cancel". Color The Color item brings up a requester with several gadgets in it. Select the item for which you wish to change the color, either player A, player B, MOV A, MOV B, DAT A, DAT B, or SPL. Then adjust the level of red in that color by sliding the knob in the gadget next to the "R". Similarly, you can adjust the level of blue or green by sliding the knob in the gadget next to the "B" or the "G". 38 When you are finished with any item, select any other item and adjust its colors in a like manner. When you are finished adjusting colors, select "OK" if you want to use your new colors, or select "Cancel" if you want to use the colors that were in the requester when you first selected "Color". Version You can select from running the ICWS'86 standard version of Core War and the ICWS'88 version of Core War. Only ICWS'88 is described in this document. 39 Quit The Quit item ceases any battles, closes all open windows, and closes the screen. You can also quit at any time by holding down the right Amiga key and typing "Q" at the same time. You must restart MARS in order to use any of the other items after selecting "Quit". 40 Control The Control menu is only available if programs have been successfully loaded into the core and no requesters are in the MARS window. Stop The Stop item is only available if there are programs currently battling in the core. Stop ceases the current battle and enables the Core menu. Stop is also invoked whenever the right Amiga key is held down along with the S key. 41 Step The Step item is only available if there are no programs currently battling in core. Step executes the next instruction from each warrior. Step is also invoked whenever the right Amiga key is held down along with the T key. 42 Continue The Continue item is only available if there are no programs currently battling in core. Continue starts execution of all warriors in core from the next instruction of each warrior. Continue is also invoked whenever the right Amiga key is held down along with the C key. Go Go is just like Continue except it is more psychologically satisfactory for starting battles. 43 Trace The Trace menu is only available if programs have been successfully loaded into the core and no requesters are in the MARS window. Open The Open item has three subitems, "A", "B", and "Both". If you select "A", only program A will be traced. If you select "B", only program B will be traced. If you select "Both", then both program A and program B will be traced. 44 Upon selection, a window with the title "Trace Window" appears. The trace window can be moved about, to the front and back, and sized. As instructions are executed by MARS, they appear in the trace window. Player A instructions appear in white (assuming default colors) and Player B instructions appear in black. The absolute address, the opcode, and the two operands are each displayed. Close The Close item closes the trace window. 45 Address The Address item has three subitems, "Relative", "Negative", and "Absolute". If Relative is selected, addresses in operand fields will be relative to the current instruction. If Negative is selected, addresses in operand fields will be relative to the current instruction, but addresses larger than half of the core size are displayed as negative addresses. If Absolute is selected, addresses in operand fields are displayed as absolute addresses. 46 Memory The Memory menu is only available if programs have been successfully loaded into the core and no requesters are in the MARS window. Open The Open item opens the memory window. The memory window can be moved and sized. It will display as many lines as will fit completely in the window. The portion of memory currently displayed in the memory window can be changed by sliding the knob 47 in the right hand gadget. Sliding the knob up moves toward memory location zero. Sliding the knob down moves toward memory location (Core Size - 1). The up-arrow gadget will move one memory location closer to zero. The down-arrow gadget will move one memory location closer to (Core Size - 1). Pointing at any point in the MARS window and clicking the left mouse button will start the memory display at that location. The memory window is not dynamically updated. If you want to be sure that what is displayed in the memory 48 window is what is currently in memory, make sure that the current battle is stopped and then select the sizing gadget of the memory window. It is unneccessary to actually change the size of the memory window. Close The Close item closes the memory window. Address The Address item behaves exactly as the Address item under the Trace menu does. 49 Window The Window Menu is available whenever there are no requesters open in the MARS window. To Front The To Front item moves the MARS window to the front of the MARS screen. Any window which is also open in the MARS screen, such as the trace window and/or the memory window, will temporarily disappear behind the MARS window. 50 To Back The To Back item moves the MARS window to the back of the MARS screen. Any window which is also open in the MARS screen, such as the trace window and/or the memory window, will reappear from behind the MARS window. 51 Screen The Screen menu is available whenever there are no requesters open in the MARS window. To Front The To Front item moves the MARS screen to the front of the display. To Back The To Back item moves the MARS screen to the back of the display. 52