PMARS(6) GAMES AND DEMOS PMARS(6) NAME pmars - portable corewar system with ICWS'94 extensions SYNOPSIS pmars [ option ... ] file1 [ file(s) ] DESCRIPTION pMARS (portable Memory Array Redcode Simulator) is a corewar interpreter with multi-platform support. pMARS currently runs on UNIX systems, PC/DOS, VMS, Amiga (AmigaDOS command line), and the Mac. pMARS implements the ICWS'94 draft standard, but can also be used in ICWS'88 mode. The base system includes a graphical core display for UNIX (curses), PC/linux (svgalib), PC/DOS and the Mac (see APPENDIX). A line-oriented debugger is included to help in writing warri- ors for the ICWS'94 draft standard. pMARS runs one or more warriors written in Redcode that are provided as file(s) on the command line. Running a single warrior is supported for debugging. Two warriors are pitted against each other for standard play, but up to 36 warriors can be named for "multi-warrior" core war. If the warrior(s) assemble without error they are loaded into the core array and executed in round-robin mode starting with the first warrior. Warrior 1 is loaded starting at core position 0, warrior 2, 3, etc., at either a random or fixed position. For fairness the starting order is rotated after each round. SCORE The score is reported after all rounds have been played. A round ends when either a single surviving warrior remains or when a maximum number of cycles has elapsed. For each round, every surviving warrior is awarded points calculated from a score formula (F). By default, this is (W*W-1)/S, where W is the total number of warriors participating, S is the number of of survivors, and "/" is integer division. Alternative score formulas can be specified with the = option (see below). When two warriors battle, the results are reported as wins1, wins2, and ties, where wins1 and wins2 are the numbers of rounds that each warrior won, and ties are the number of rounds in which both warriors lasted until time-out. The score is then: warrior 1: points = wins1 * F + ties * F warrior 2: points = wins2 * F + ties * F F is a score formula containing the W and S parameters. When more than two warriors (W) participate in a game, results are reported as wins[1], wins[2], .., wins[W], losses for each warrior, where the index indicates the PMARS PROJECT Last change: August 5, 1995 1 PMARS(6) GAMES AND DEMOS PMARS(6) number of warriors that survived until the end (S parameter in the score formula). The total number of points for each warrior is then calculated as: points = sum (S=1..W) (wins[S] * F) A few alternative score formulas: 10 (W+1)/S (x=W-S+1)*(x+1)/2 (S==3)*5 + (S==2)*3 + (S==1) (S == 1)*W + (S != 1) OPTIONS Command line options may occur anywhere on the command line. Single-letter options without a parameter can be combined as in -fbe. The special argument - (dash) stands for standard input (stdin). It can be combined with the -@ option (see below) to signify reading options from stdin, or the - can take the place of a warrior filename, in which case warrior code starting with a ;redcode line and ending with an END statement is extracted from stdin. The END statement can be omitted if the next ;redcode line immediately follows the last instruction. Several warriors, each specified by a separate dash on the command line and bracketed by ;redcode/END can be piped into pMARS. #- (where # is a posi- tive number) is a shorthand for writing this number of dashes on the command line. -r # This options sets the number of rounds to play. The default is 1. -r 0 produces assembly output (unless -b is specified), but does not execute the warrior(s). A maximum of 32787 rounds can be specified. -s # The -s option specifies the size of core memory in number of instructions. It defaults to 8000. Maximum core size is platform-dependent, but usually at least 65535. -c # -c sets the maximum number of cycles per round. A cycle consists of one execution of each warrior. A round ends when either a single warrior remains execut- ing or when the maximum number of cycles has elapsed. -p # This option sets the maximum number of processes a war- rior can run. The default is 8000. -l # This sets the maximum length of a warrior source file in instructions. It defaults to 100 and can be up to 500. PMARS PROJECT Last change: August 5, 1995 2 PMARS(6) GAMES AND DEMOS PMARS(6) -d # This option specifies the minimum distance between the first instruction of each warrior. It cannot be smaller than the maximum length (-l option) and defaults to 100 instructions. -S # The -S option sets the size of the P-space to # cells. The default is 1/16th of core size if core size is evenly divisible by sixteen, or the next larger divisi- ble fraction. See also the P-SPACE section below. -F # This option tells the loader to install warrior 2 at a fixed address # for round 1. This number is then used to seed the pseudo random number generator for all sub- sequent warriors and subsequent rounds. This option is useful for testing different versions of a warrior with constant initial placement. Warrior 1 is always installed at address 0. -f The -f option instructs the loader to use a fixed series of addresses for positioning warriors. This is done by initializing the pseudo random number generator with a checksum value derived from the source of both warriors. Thus, initial placements will still be "ran- dom" from round to round, but will be the same if the same warriors are run again. As a consequence, the result of battles run with the -f option will show no statistical fluctuations. This options is useful for validating ports of pMARS to new platforms and for pro- viding an absolute, albeit arbitrary performance meas- ure for warriors. The -F and -f option are mutually exclusive. If neither option is specified, the pseudo random number generator is initialized with the system time. -e If this option is specified, the cdb debugger is entered immediately after loading warriors into core. -b This options runs pMARS in brief output mode. -b suppresses warrior listings after assembly. -k With the -k option, pMARS uses the same output format as the KotH program. This option enables pMARS to work with scripts written for the KotH server. -8 This options enforces strict compliance with the ICWS'88 standard and disables all ICWS'94 language extensions, which are flagged as syntax errors by the assembler. Since ICWS'94 is a superset of ICWS'88, this options is not necessary to run ICWS'88 warriors. -o When this option is given, pMARS reports scores in decreasing order rather than in the order warriors were PMARS PROJECT Last change: August 5, 1995 3 PMARS(6) GAMES AND DEMOS PMARS(6) named on the command line. This is mostly useful for multi-warrior play. -V The assembler generates verbose output with this option. This is only useful for debugging. -v This option sets the display mode for UNIX and DOS display versions (see APPENDIX). -@ pMARS continues reading options and filenames from the parameter file . If is a - (dash) standard input is parsed. Comments in the parameter file start with a semicolon. -= The = (equal) option allows you to specify a custom score formula (see SCORE). The formula may contain the standard arithmetic and logical operators (as in the C language), as well as the parameters W (number of war- riors participating) and S (number of warriors surviv- ing this round). You need to enclose the formula string with quotes if it contains spaces or characters inter- preted by the operating system. -Q # The "query" option is intended for use in scripts that run pMARS in batch mode. Depending on the number code following -Q, the program returns an informative number as the exit status. "pmars -Q 1000" e.g. will cause pMARS to exit with a code that spells out the program version. More on -Q arguments and exit codes can be found in the ADDENDUM. $ The $ (dollar) parameter is not preceded by a dash and cannot be grouped with other options. It terminates reading command line parameters and is used in parame- ter files or input streams (-@ fn). The $ is necessary if you want to combine two or more of command line parameters, warrior code and cdb commands in the same input stream or file. Below an example of such a com- bined input file: ;Below the command line parameters: -r 10 -beF 1000 2- $ ;redcode ;name Imp 1 ;assert 1 mov 0,1 end ;redcode ;name Imp 2 ;assert 1 PMARS PROJECT Last change: August 5, 1995 4 PMARS(6) GAMES AND DEMOS PMARS(6) mov 0,2 mov 0,2 end !! cdb commands follow: sk 1000 reg quit X-WINDOWS OPTIONS The X-Windows display version of pMARS has these additional command line options: -display Expects a string specifying the display where the win- dow should appear. Following X standards, this display specification has a format of hostname.domain:display.screen where the part before the colon is the standard internet host specification and display and screen are integers. The screen specification can be omitted. For an example, consider you are working at an X terminal named ncd13.complang.tuwien.ac.at and remotely logged in at host stud1.tuwien.ac.at where the binary of pmars lies, you can use the following command line stud1$ pmars -display ncd13.complang.tuwien.ac.at:0 -b aeka.red aeka.red and the window will appear at you local screen. -geometry Lets you specify the initial size and position of the window. The format is widthxheight+x+y where width, height, x, y are integers and + may be replaced by -. Either of the two parts (widthxheight or +x+y) may be omitted. This overrides the -v switch concerning the window geometry. As an example, pmars -geometry 600x400+30+100 .... will open a window of 600 by 400 pixels at the screen position (30,100). pmars -geometry 1024x768 ... creates a window of 1024x768 pixels and pmars -geometry -20+300 ... creates a window with standard size with its left upper corner at posi- tion (-20,300), i.e. out of the left side of the screen. -fn The string following this argument specifies the X font to use. By default, a terminal font is used. If this font can't be found, "fixed" is used for a font ("fixed" should be present at every X installation). Use the command 'xlsfonts' to get a listing of fonts that can be used at your X server. 'xfontsel' provides a comfortable way to select a font. "fixed" is the PMARS PROJECT Last change: August 5, 1995 5 PMARS(6) GAMES AND DEMOS PMARS(6) fallback if the specified font can't be found. It is strongly recommended to use a fixed pitch font. REDCODE pMARS implements an extension of the proposed ICWS'94 stan- dard. The new instruction modifiers .A,.B,.AB,.F,.X, and .I, the arithmetic instructions MUL, DIV and MOD, as well as post-increment indirect (>) are supported. pMARS currently does not implement read/write ranges, although they may be added in future versions. Version 0.5 of pMARS adds support for three experimental opcodes that are currently not included in the ICWS'94 draft: SEQ (Skip if EQual): this is a synonym for CMP and is included mainly for clarity (future versions of pMARS may implement SEQ as a "predefined EQU" rather than a true opcode). SNE (Skip if Not Equal): the opposite of SEQ. NOP (No OPerations): do nothing. Version 0.6 adds three new indirect addressing modes that use the A-field instead of the B-field as the pointer for indirection: * - indirect using A-field { - predrecement indirect using A-field } - postincrement indirect using A-field The new P-space instructions of version 0.8 are discussed under separate heading below. The assembler also supports multi-line EQU statements, a feature not included in the current ICWS'94 draft. The for- mat for multi-line EQUates is