Grid Wars User's Manual ----------------------- Introduction ------------ The object of Grid Wars is to write programs to seek out and destroy enemy programs in a battle for supremacy. Grid Wars is inspired by Core Wars, in which machine-language battle programs in a 1-dimensional memory array attempt to overwrite each others' code. In Grid Wars, the arena is a 2-dimensional grid, and programs are written in a special 2-D visual programming language called GRIP (for GRId Programming), which has the unique characteristic that the path of control flow is concretely visible as a path of symbols through the grid. Branches branch, and loops loop. The GRIP program determines the behavior of a GRIP process that can read or write symbols on the grid. The object is to make the process roam over the grid, find an enemy GRIP program, and overwrite it with symbols which will cause it to crash, before it does the same thing to your program! The Grid -------- The Grid is simply a bounded, finite 2-dimensional array of cells. Each cell may contain any symbol in a finite alphabet: currently the 95 printable ASCII characters. GRIP Programs ------------- A GRIP Program consists of a rectangular block of symbols, and a position (relative to that block) giving the "initial location" for executing that program. A program is run by loading its block of symbols somewhere in the Grid (overwriting the previous contents) and creating a GRIP Process at the initial location. GRIP Process ------------ A GRIP Process has various components of internal state, which are documented in detail in the GRIP Language Specification. Much of the internal state involves remembering the address (on the grid) of objects called HUSKS. A husk can be thought of as the 2-D analogue of a Turing machine's tape-head, or a memory address in a traditional computer architecture. In addition to its location on the grid, a husk also has an orientation (N,S,E,W), specifying what direction is "forward" for the husk. The most important husk is the PC Husk. This husk determines the location on the grid from which the process reads its instructions. The execution of the process consists of reading instructions from the PC's location and executing them. The instructions cause the process to change its internal state, which usually involves moving the PC forward to the next instruction. Processes also have data husks. (The PC is actually a special case of a data husk.) A data husk represents a location on the grid where the process can get or put symbols easily. Husks can be thought of as analoguous to the address registers in a traditional CPU architecture. However, there is no "arithmetic" on husks. A husk can only be moved one square at a time, unless it is jumping to the location of another husk. So the only way for a process to get or put symbols at a distant location is to move a husk there, one cell at a time, from the process's initial location. GridWars System --------------- The GridWars System is a X-windows application that serves as a simple programming environment for the interactive construction and execution of GRIP programs. Any number of GRIP programs can be run concurrently in a battle. User Interface -------------- The GridWars display is simple, consisting of the grid, a palette, menus, and scrollbars. The grid fills most of the GridWars display. It is where the editing and running of GRIP programs takes place. There are many key bindings available in the grid, which make use of a cursor indicating the current location for editing operations. Typing a printable ASCII character puts that symbol at the current cursor location, and moves the cursor forward. To make it easier to type programs in execution order, the cursor is also turned to move in the direction a PC Husk would move if executing that symbol. The arrow keys move the cursor without writing to the grid. Other key bindings in the grid can be found by browsing the menus. Mouse bindings in the grid are as follows: Mouse Button Action 1 (Left) Set cursor location 2 (Middle) Scroll window contents by dragging 3 (Right) Write current palette symbol The palette to the left of the main grid can be used to select symbols that can be written on the grid using mouse button 3. A symbol is selected in the palette using mouse button 1. A cursor in the palette indicates the currently-selected symbol (initially space). The scrollbars can be manipulated in order to scroll through the grid's contents. The menus can be used to perform all GridWars commands except those bound to mouse actions. They also document the equivalent key-sequences. If you have bound the Alt key on your keyboard to modifier 2, you may use it to access the menus using Alt together with the underlined letter in the menu name. Using Gridwars -------------- Gridwars starts out with an 18-point font, a 50x50 grid, and a 35x35 window (in grid units). You can change these with the Scale, Grid, and View menus. Be careful changing the grid size, because this erases the grid's contents. Manual window resizing is not currently allowed, because it messes up the display due to bugs in the Tk window toolkit. (I may try to fix this in the future.) To try out some existing GridWars programs, select one of the Load commands in the File menu. The resulting dialog box can be used to browse the filesystem for files to load. The "Directories" menu in the dialog box includes the standard Examples directory. Try loading one of the files in that directory. (Note: to be listed, a file must end in .gb# (for binary files) or .ga# (for ascii files), where # is the file format version number. (Currently only .ga2 format is defined.) You may load more than one file by loading them at random locations in the grid. Soon I will add the ability to load files at random orientations as well, and the ability to load files at the cursor, and later the ability to move them and rotate them easily after they are loaded. Once one or more files are loaded, start them running with M-r (Meta-r). They can be stopped with M-s. The running speed can be adjusted with M-[ and M-]. (Much faster maximum speeds will be available in the near future.) If a program is killed, a message to that effect will appear on standard output (this will be improved). To start writing a new Gridwars program, clear the grid with M-Delete. Then, simply move the cursor to the desired position and begin typing. When you have decided upon an initial execution location for your process, move the cursor to that location and type M-c (Create Process). If you make a mistake, the process can be deleted with M-d (Delete Process). As soon as the program looks like you want, select Save As from the menu, go to a directory you can write to, and enter an appropriate filename. You should always be careful to save your programs before running them, as the program may overwrite itself during execution. Also, you can currently only save a program if it is the only program on the grid (this will change). So always start with a fresh grid. The current GRIP file format is a very simple ASCII format. If you desire, you can edit your GRIP files using appropriate text-editors, such as Emacs in picture mode. The file format is described in ~mpf/GridWars/Format. Customization ------------- The user interface to GridWars can be customized in a very powerful, flexible, and simple way. This is because Gridwars' user interface is written largely in Tcl, the Task Control Language. The file ~mpf/GridWars/gw.tcl defines that interface. You may copy that file and modify it as desired. To run your new version, type $ ~mpf/GridWars/wish -f . "wish" stands for "windowing shell". It is the C-language part of the GridWars application. You can enter an interactive read-eval-print-loop for interactively modifying your user interface on the fly by just typing: $ ~mpf/GridWars/wish wish: source wish: Also, you can interact with a running gridwars process by simply starting a new wish process on the same X display, and sending commands to the existing process as follows: $ wish wish: send puts stdout "Hello World" wish: More details on the use of Tcl can be found in the Tcl man pages. For a list of man pages, type "tclman". To see one, type, for instance, "tclman AddErrInfo". If you know the name of a Tcl command or library function you can often just use "man", e.g., "man Tcl_AddErrorInfo". These man pages describe the Tcl language. For information on the Tk toolkit used for the user interface, use "tkman" similarly. Help on Tcl can also be found by typing "help" at any wish prompt. Source for Tcl and Tk can be found in /src/local/{tcl6.4,tk2.3,tclX6.4c}. Perhaps the simplest way to customize the user interface in gw.tcl, not requiring much knowledge, is to rearrange the key bindings. To do this, simply find the large "grid.bindings" procedure and change bindings as desired. However, Tcl is a full programming language, and indefinitely powerful programs can be written in it, using the commands supported by Tcl, Tk, and the Grid widget written for gridwars. (whose source can be found in ~mpf/GridWars/src/tkGrid.c). For example, the entire file browser is written solely in Tcl (~mpf/GridWars/file.tcl). Detailed Menu Overview ---------------------- [ not written yet ] Overview of Example Programs ---------------------------- [ not written yet ] Bugs ---- There are some known bugs and deficiencies in the user interface: * Scrolling is done incorrectly. * Cursor can be drawn over and erased. * Manual resizing doesn't work right (thus is disabled). * Processes sometimes don't disappear when deleted. * File selector sometimes doesn't come up. * Menus come up in the wrong place under the tvtwm window manager (except when you're in the upper-left corner of the virtual desktop). * Need ability to select and move programs. * Need GRIP debugging tools. * Need ability to re-load programs easily. * Need various other improvements in the user interface. * Need to be able to run programs faster. * Very large grids need to refresh more quickly. * Need to warn user not to run before saving. I will try to fix bugs and add features over the next few weeks. Please report to me (mpf) any bugs you find or helpful features you think of.