Corewar 88 [Version 4.97] ------------------------- C88 is a corewar simulator program which can be used to assembly/simulate or debug redcode programs which is in compliance with '88 standard. The documentation here only describes the system interface. More details on '88 standard are available at FTP site soda.berkeley.edu under directory /pub/corewar/document What is on this version ----------------------- 1. Full-screen interface. (Support 80x50 mode) 2. Windowing system 3. Multiple round battles 4. Speed optimization 5. Battle replay 6. Many debugging facilities such as: core dump, debug zoom, etc 7. Support user configurable file Version update: --------------- 1. Bugs fixed: - At the assembler level where it fails to reject invalid symbol - At the simulator level where it fails to normalize CMP/SLT address after skipping - At the simulator level where it misinterprets SLT instruction - Tracing, watch-point and break-point are now set properly 2. Source redcode listing is now directed to standard output 3. User configurable file 4. Faster execution and smaller unit 5. Debugging now is not restricted to graphical battle only 6. Many others such as: core dump, evaluator, response control, core edit, process tracing, debug zoom, process/memory viewing switch etc Hardware Requirement -------------------- 1. 640K RAM (suggested) 2. CGA color or better Quick walkthrough ----------------- To start, type: program_name warrior_1 warrior_2 - Program_name is the current name of this executable file - Warrior_1 and Warrior_2 are path files containing '88 standard redcode The next events: - The program parses those two files - Unless specified with option '-L-', the program would redisplay the redcode in minimal form - The next screen is the battle view To check if a redcode follows the '88 rules, type: program_name warrior -L Additional parameter may also be specified. Just type program_name to obtain the available parameters. User configurable file is also available. More details on this are described under config file that accompanied this file. Graphic ------- The graphic interface is very simple. All processes of the first warrior would be denoted as '1' (blue) and '2' (green) otherwise. A character '.' (dot) indicates that a memory is directly changed using 'MOV' statement or indirectly changed using pre-decrement evaluation. Direct changings from 'ADD', 'SUB' and 'DJN' are represented with '-' (minus). This setting however can be redefined by using C88 config file. The graphic is scaled which means that it adjusts itself to the corewar size and the number of possible characters in one full screen. The number of possible characters is determined from the mode being used. By default, the mode could be either 80 x 25 or 80 x 50 depending on the DOS prompt mode. Specifying -25 or -50 to use 80 x 25 or 80 x 50 graphic mode respectively. Multiple round battle --------------------- The parameter '-R n' or '-Round n' specify n number of rounds. If the number of round is more than one, by default, the battle view is turned off. This speeds up the progress considerably. To have multiple round of battles with battle view turned on, specify an additional parameter '-V' or using control panel (see below). Speed Optimization ------------------ To archive the desired speed, three battle modes are available. The slowest one has all the features C88 has. The normal one has only some debugging feature enabled. The fastest one has battle view and some debugging features disabled Thus: ----------------------------------------------------- | SPEED | Graphic | Debug | How to achieve this level | ======================================================= | Fast | no | part | By default, for multiple | | | | | round battles, it goes to | | | | | this level. To enforce | | | | | this mode, specify '-V-' | | Norm | yes | part | Specify parameter '-V' & | | | | | '-F' | | Slow | yes | full | Specify parameter '-V' | ------------------------------------------------------- This default setting is also configurable in user config file. It is possible to switch between these three modes in the runtime using control panel (described under control panel section). However the change would not take place until the next round. This command is only useful in multiple round battles. Debugging level --------------- Every time C88 enters debugging mode, the screen is refreshed and the current instructions are shown. It is possible to view the memory and to view the process queue independently. The screen is splitted into two windows with each window showing the information related to each warrior depending on which state between memory viewing and process viewing is currently active. For all the time, only one of the two windows would be active and the other would be inactive. Any modification made happens only in the active window. A highlighted instruction in memory viewing state shows the current target instruction while in process viewing state shows the current target process A rectangular symbol at leftmost column of each window shows the instruction to be executed by current process. At memory viewing, all the instructions within the range of N-C and N+C are shown where N is the address of target instruction and C is a constant. At process viewing, all the instructions executed by processes within the range of N-C and N+C are shown where N is the address of target process and C is a constant. The following command characters in general serve the same function for both process and memory debugging unless specified by '(M)' for memory viewer or '(P)' for process viewer. Command character: - Left-Arrow : Switch to the first window (left) - Right-Arrow: Switch to the second window (right) { The following control keys depend on which window is currently active } - Up-Arrow : Scroll one line up (M) Goto process executed by process at previous entry (P) - Down-Arrow : Scroll one line down (M) Goto process executed by process at next entry (P) - Page-Up : Scroll one page up (M) Like above but it interprets the process list scroll up - Page-Down : Scroll one page down (M) Like above but it interprets the process list scroll down - Home : Proceed to the instruction being executed by process at previous entry - End : Proceed to the instruction being executed by process at next entry - SPACE : Return to the instruction being executed by current process - TAB : Switch between process viewing and memory viewing - 't' : Tracing. Stepping the codes n-times. The n is a decimal counter which can be specified using digit keys, ESC and backspace. This command is only available when debugging is set to FULL. - 'T' : Process Tracing. Trace only the selected process. Multiple tracing is also possible. This command is only available when debugging is set to FULL. - 'b' or 'B' : Insert a break-point on that address. A 'B' would appear on the left of the instruction. Any process executing instruction on that address would cause C88 automatically enters debugging mode. This command is only available when debugging is set to FULL. - 'w' or 'W' : Insert a watch-point on that address. A 'W' would appear on the left of the instruction. Any process modifying instruction on that address would cause C88 automatically enters debugging mode. This command is only available when debugging is set to FULL. - ESC : Reset the counter to zero or if the counter is already zero, resume the battle - Backspace : Decrement the counter by one digit - '0' .. '9' : Specifying decimal counter. Used in conjungtion with 't' or '@' - '-' : Negate the counter value - 'g' or 'G' : Goto address. Goto address shown by the counter. Can be used in conjungtion with '@'. The address is relative to the current selected address. - '@' or '.' : Pointer command. Followed by 'a'/'A' for A-field or 'b'/'B' for B-field to evaluate the new counter as the sum of old counter and chosen field value. - 'n' : Abandon this round. Assume it is a tie. - 'N' : Just like 'n'. However enter debugging mode immediately. - 'q' or 'Q' : Resume the battle - 'i' or 'I' : Invoke battle info - 'c' or 'C' : Invoke control panel (More on it under control panel section) - 'd' or 'D' : Core dump It may be specified which starting address and ending address to be written on file. - 'z' or 'Z' : Debug zoom (described more under debug zoom section) - 'e' or 'E' : On-line evaluator. Format is just like format of assembly file. Valid entries: '0'..'9', '+', '-', '*', '/', '(' and ')'. '*' and '/' have higher precedence than '+' and '-'. '-' can be used as unary operator. The result is always normalized. Note that no label or EQUs statement is accepted - ENTER : Enter core editing. The format is similar to '88 format at primitive level which means no EQUs, ENDs and labels. Debug zoom ---------- This is a feature that allows user to select instruction from screen to be debugged. Normally, debugging shows only the instruction being executed. This feature automatically performs the mapping between screen and memory before enter debugging level. Hence, this can be used to observe anything misappropriate shown in the screen. Debug zoom can be invoked by typing 'z' or 'Z' from debugging level or simulation level. A blinking cursor is where the coordinate mapping takes place. Drive the cursor using arrow keys. If the cursor went to the screen edge, it would warp around the screen. Type to map the screen to memory. Because the screen-memory is scaled, the address shown might be not accurate. But it should appears in that area. Simulation level ---------------- During battle simulation, these keys could be handy: - 'r' or 'R' : Refresh the screen - 'd' or 'D' : Enter debugging mode - 'n' or 'N' : Next round. Assume this round's result is a draw - 'c' or 'C' : Invoke control panel - : Halt the program - 'z' or 'Z' : Debug zoom (described more under debug zoom section) - Other keys : Pause and give some information about the battles All of these keys however depend on the response control set at control panel. The slower the response, the faster the simulation and vice versa. Control panel ------------- At debugging level or simulation level, typing 'c' or 'C' would invoke this panel. At this point typing (insignificant case): System control 'V': Toggle on/off battle view 'D': Toggle full/part debugging 'R': Set the response value. The higher the value, the slower the response and th faster the simulation Battle control This controls the next battle's setting 'B': Toggle between current replay, previous replay, and random play for next battle. Manual play is also available by setting any of these keys: '1', '2', 'T' '1': Set the location of first warrior at next battle '2': Set the location of second warrior at next battle 'T': Set the first turn (first/second) at next battle To resume, either press 'n'/'N' or other keys. Typing 'n'/'N' has similar effect as abandoning the round. (see above) Last Output ----------- The last output is the game result and the score. Score ----- For each warrior, the score is evaluated as 3 times number of winnings plus number of ties. '88 Format ---------- C88 accepts the following: - All identifiers must consist of letters, digits and underscore '_'. The first character of all identifiers must be a letter. The maximum identifier length is 16 (This version) - A colon after a label is always ignored. Thus: 'bomb:' is treated as 'bomb' - More than one label may refer to the same line. Example: bomb: mutate: SPL 0, EQU or