Advanced T-Robots (AT-Robots) version 2 (ATR2) Copyright (C) 1997, Ed T. Toton III All Rights Reserved. http://www.necrobones.com/atrobots/ ---------------------------------------------------------------------------- For current CONTACT INFORMATION see: NBONES.DOC ---------------------------------------------------------------------------- CONTENTS: Introduction Credits Trademarks & Copyrights Things you should have Running AT-Robots - Settings - During the Simulation Locking Robots Acronyms, Abbreviations, and Definitions What's new to ATR2 Basics and General Info Hexidecimal Programming Robots - Statements - Compiler Directives - Robot Configurations - Registers - Instructions - Ports - Interrupt Calls - Memory Map - Constants - Writing the code - Errors - Designing the perfect robot The Physics of AT-Robots Staging a Competition Trouble-Shooting & Speed-Control Legal Shtuffs - License & Disclaimer - Registration Revision History Final note ---------------------------------------------------------------------------- INTRODUCTION: Welcome to Advanced T-Robots, a game in which players write programs to control robots which will battle to the death in a simulated arena, using a programming language similar in design and concept to PC assembly language. This particular game is ATR2, or rather, the second AT-Robots. Unfortunately, though much remains the same, some fundamental changes made downward compatablility impossible. If you used AT-Robots 1.x, you will either need to make new robots from scratch or convert your old ones by hand. Further down, I will explain what has changed and what is the same. AT-Robots stands for "Advanced T-Robots", though "AT" can also refer to AT-class PC's, since it will run on 286's and higher. T-Robots was the predecessor program to this, written originally in November of 1991. It was inspired by P-Robots (written by David Malmberg), which was in turn inspired by C-robots (written by Tom Poindexter). T-Robots and AT-Robots are designed with the idea of programming robots, without going to the lengths of learning to program in high-level languages, but to still allow fairly simple program design. In the case of AT-Robots, the language is based on PC assembly. Basically, T-Robots allowed you to use T-Robot-Basic to program the robots, and now in AT-Robots you use T-Robot assembly. Instead of having complex commands for complex tasks, you have simple commands to do simple tasks. You will have to design subroutines to access the specific devices/ports/memory areas of the robot specifically in your program. The language has a small amount of available commands, thus making it easy to learn, while offering experienced programmers an interesting challenge. Though it is not a real programming language of sorts, it can still teach the basic concepts of programming and logical thinking. The first incarnation of AT-Robots was in February of 1992, only 3 months after the initial T-Robots program. After that, AT-Robots remained dormant from a development standpoint, but continued to be used occasionally by people around the world for fun and for educational purposes. The original versions were primarily distributed through my own personal BBS, and through a very large BBS that I often used for launching my shareware programs (The Programmer's Corner), and then eventually through AOL. Then in March of 1997, AT-Robots version 2 came on the scene, which coincided with my obtaining my own domain name on the World Wide Web. I made announcements on several usenet newsgroups, and ran a contest. Since then the game has slowly trickled out into the world. ----------------------------------------------------------------------------- CREDITS: Concept, Design, Programming - Bones (Ed T. Toton III) Debugger - FiFi LaRoo ----------------------------------------------------------------------------- TRADEMARKS & COPYRIGHTS: AT-Robots v2 (c) 1997 Ed T. Toton III AT-Robots (c) 1992 Ed T. Toton III T-Robots (c) 1991 Ed T. Toton III P-Robots (c) 1988 David Malmberg C-Robots (c) 1985 Tom Poindexter Turbo Pascal is a registered trademark of Borland International. All robots are under copyright of their respective authors. ---------------------------------------------------------------------------- THINGS YOU SHOULD HAVE: First of all, you need DOS 3.3 or higher (or Win95's DOS), some free hard drive space, a VGA or SVGA, and at least a 286 PC processor. That covers the hardware. You will also need a text editor. DOS (starting with 5.0) comes with a built-in text editor called EDIT. Whatever you use doesn't matter specifically, as long as you save your robot programs in "DOS Text" or "ASCII format" (must be the DOS standard of CR,LF ending each line). Files: ATR2.EXE - The main program. ATR2.DOC - This document. NBONES.DOC - Contact information. READ.EXE - A text viewer. ATRLOCK.EXE - Encrypts robots for distribution. demo.bat - Demo batch file demo.ats - Demo config file. file_id.diz - BBS auto-description file *.at2 - These are robot programs, all ending in .AT2 *.pas,*.tpu,*.obj -Source code files for AT-Robots. ---------------------------------------------------------------------------- RUNNING AT-ROBOTS: Before we get into the language, let me first explain how to run the game. If you try running AT-Robots just by typing ATR2, this is what you will see: Error #5: Robot names and settings must be specified. Well, here's how you do just that. ATR2 must be run using command-line parameters. Here's an example: ATR2 /s #myconfig Any parameter that is preceded by a slash (/) or a dash (-) is a setting. Any parameter preceded by a pound sign (#) is a configuration file (in this case "MYCONFIG.ATS"). If no extension is specified in the filename, ".ATS" is asswumed. Parameters not starting with these characters are assumed to be robot filenames. Example: ATR2 /s /m2 myrobot yourobot In this case two settings are specified, and two robots are loaded, specifically "myrobot.at2" and "yourobot.at2" (if a filename extension is not specified, it is assumed to be ".AT2"). If you want to load a locked robot, you can either specify the ".ATL" extension (i.e. "MYROBOT.ATL") or precede the namee with a question mark (?) (i.e. "?MYROBOT"). Settings: /S = Do not show source code during compile (must appear before robot names) /Dn = Specify game-delay (timing control), [default=30], example: /D20 /Tn = Specify time-slice for robots [default=5] (cpu cycles per game cycle) /Ln = Specify battle time-limit in 1000's, 0 means no limit [default=0] /Q = Quiet Mode, no sound effects. /Mn = Specify number of matches to play. ex- /M10 is 10 matches. /G = No graphics, just generate a quick result. /Rn = Generate a report file after battle (for use with tournament program) * /C = Compile only, do not run battle (for debugging and verifying) /A = Show scan arcs during battle /W = Windoze=off, Do not pause with windowed information. *** /E = Turn on error-logging for robots. /#n = Specify maximum robot program length. ex- /#32 is 32 compiled lines ** /!n = Insane missles (n can be 0 to 15). Never use for tournaments! /@ = Use old shield style (no damage or heat taken from hits). /Xn = Start in debug mode and set the step count 1-9 (/X is equivalent to /X1) * See below for report-file format ** NOTE- parameters affecting compilation, such as /S or /# must come BEFORE the robots they are affecting. This means you can have different program length limitations for different robots. ex- ATR2 /#10 small.at2 /#50 medium.at2 /#1000 large.at2 *** /W turns off the bout results in both graphics and text modes. Only the absolute final results will be desplayed if this parameter is used, and not the intermediate results. This can be toggled at runtime with the "W" key, whether you're in text or graphics mode at the time. Creating a config file is very easy, simply use the same parameters that you would on the command line, except in the file they are placed one per line. For an example, see DEMO.ATS. In a config file, any blank lines or lines starting with a semi-colon (;) are ignored. DURING THE SIMULATION: While the simulation is running, there are several keyboard commands you can use: A = Turn on/off the displaying of scan arcs S = Turn sound effects on/off G = Turn graphics on/off T = Turn timing on/off + = Increase timing delay (game runs slower) - = Decrease timing delay (game runs faster) W = Toggle 'windoze' (pausing at displayed windows) C = recalibrate timing (timer might have mis-calibrated if a cache program such as smartdrive was still writing data). X = Turn the debugger on/off (Robot #1 must be unlocked). While in debug mode, there are several additional keyboard commands you can use: SPACEBAR = Step with current step count 1 .. 9 = Set a new step count and step -,+,[,] = Scroll the memory view ESC or Q = Quit. Backspace = End current match. If the game is running without graphics, timing and sound will also be off since they only make sense when you're watching the action. You can use these keyboard commands whether the game started in graphics mode or not. REPORT FORMAT: The report-file is for use with the tournament program or other shells that want to read information back from ATR2 about the results of the battle. There are multiple formats available. They're all basically the same, except for the amount of information included. The older ones are kept for downward compatability as new ones are added. In each case, the first line is the number of robots in the report. After that, each robot gets its own line. On the robot lines, several numbers are given, seperated by spaces, and the name is listed last. All report modes are enabled with the /R parameter, possibly with a number to denote the specific one. An example /R report: 2 0 1 SNIPER 1 1 RANDMAN3 The line formats for each report mode: /R : Wins Trials Name /R2: Wins Trials Kills Deaths Name /R3: Wins Trials Kills Deaths EndingArmor EndingHeat ShotsFired Name /R4: Wins Trials Kills Deaths EndingArmor EndingHeat ShotsFired Hits DamageTotal CyclesLived ErrorCount Name ---------------------------------------------------------------------------- LOCKING ROBOTS: When it comes time for you to use your robot in a competition, you may want to allow others access to your robot but without making it easy for them to discover its secrets. For this reason, there is a program included with AT-Robots called ATRLOCK. It removes all remarks from the robot and then encrypts it. It's not a particularly complex encryption scheme, just enough to make it unreadable. For all you hackers out there who are thinking of cracking it or making an un-lock program, I ask you nicely to please not do so. To use ATRLOCK, simply specify the robot to be locked: example: ATRLOCK sniper This will encrypt "SNIPER.AT2" into "SNIPER.ATL". To use the LOCKed SNIPER in a game, you could simply load it as "?SNIPER". ---------------------------------------------------------------------------- ACRONYMS & ABREVIATIONS & DEFINITIONS: Here in ATR (see, there's one already) we use several acronyms that you may or may not already be familiar with. At anyrate, here they are (but don't worry about memorizing them): Acronym: Meaning: ATR AT-Robots, or a robot for AT-Robots. ATR1 AT-Robots, versions 1.0 and 1.1 ATR2 AT-Robots, versions 2.0+ ATRA Advanced T-Robots Assembly. BIOS Basic Input/Output System ERR Error GSB Gosub (a call to a subroutine) I/O or IO Input/Output INT Interrupt JMP Jump (like a GOTO in basic) OP Op-Code (numeric codes that represent instructions) RAM Random-Access Memory. REG Register ROM Read-Only Memory. ROS Robot Operating System. SPD Speed VAR Variable LOCK Encryption for robot distribution ---------------------------------------------------------------------------- WHAT'S NEW TO ATR2: If you've never used AT-Robots 1.x, skip this section. One of the most important changes is the memory addressing system, and how operands are stored and decoded internally. In ATR1, what an operand did was completely defined by its value. Anything over 10000 was a memory address. Now you have the full range of integer values to use as numbers, or as values in variables, since there is now seperate microcode stored to define the function of an operand. A few of the I/O ports have changed, but most are the same. All of the Interrupts have been redefined. Most of the instructions in the language are the same, except conditional jumps can not be used as conditional gosubs, and basic math functions use only 2 operands instead of 3. The list of registers has also changed. However, if you were simply using some of the old ones as generic variables, why not create them as variables if you convert your robots over? The variables that are used for passing values back and forth to interrupts have changed of course. The accuracy setting parameter that you send to the weapon port is no longer translated into degrees automatically. You must do this yourself before passing the parameter. One more MAJOR change is that the game uses a 256 degree circle instead of 360. Why so many changes? Especially that circle thing? Here's why- I designed the original AT-Robots before my programming expertise really allowed me to do as good of a job as this project deserved. I was only starting to learn assembly at the time, and here I was making my own version! I was not yet used to dealing with powers of two, individual bits, bit-manipulation instructions, and hexidecimal. I ended up making the language in such a way as to steer you away from these valuable programming techniques, and was therefore teaching the wrong lessons! Now I'm going to beat hexidecimal and powers of two into everyone's skulls... :-) 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536, to name a few... :-) ---------------------------------------------------------------------------- BASICS & GENERAL INFO: The arena is 1 kilometer wide and 1 kilometer long. The coordinate system is set up such that (0,0) is at the upper-left corner and (1000,1000) is at the lower-right. The screen is set up as follows: 0,0 ________________________________________ 1000,0 | | | | | | | |----------| | | status | | | areas | | |----------| (side of | Arena | | screen) | | | | |----------| | | | | | | | |----------| | | | | | | | | | 0,1000 |________________________________________| 1000,1000| Navigation is done in a 256 degree circle, with 0 being north. Here are the directions for each course: 0 (256) 000h (100h) Decimal: | Hexidecimal: | 224 | 32 0E0h | 020h \ | / \ | / 192 ----- + ----- 64 0C0h ----- + ----- 040h / | \ / | \ 160 | 96 0A0h | 060h | | 128 080h (hexidecimal will be briefly explained later) The Robots are all equipped with a scanner, armor, and a weapon. Firing the weapon generates heat, which can impair the robots performance. When the projectile hits an enemy robot, the amount of damage that the target takes will depend entirely on how accurate the shot was. When a robot is destroyed, it explodes, possibly causing damage to nearby robots. Firing the weapon at point-blank can be dangerous, since the weapon blast can hit everything within a given range. How much damage the weapon does depends on how "on-target" the shot was. Each robot is also equipped with a feature called "overburn" which allows the robot to increase its performance by cranking more energy out of its power-supply (by disengaging certain safety measures), but at the cost of easily over-heating. When on overburn, missiles will work more effectively, and the robot will drive faster. 100% throttle is still maximum speed, as the speed of the robot is automatically scaled based upon it's current performance. Robots don't stop, start, or turn on a dime. When you tell the robot to move at a certain speed, it will accelerate until it reaches that speed or it collides with something. Once it has reached that speed it will remain there until you change it or it collides with something. When the robot does in fact collide with something, it's speed and throttle are reduced to zero. If the velocity was greater than half of it's maximum non-overburn and non-overheated velocity, it takes a point of damage. When you instruct the robot to turn, it will rotate until it faces the new direction, or you tell it to do otherwise. The robot will always rotate in the direction that is shortest to face the target heading. if you tell it to turn 270 degrees to the right, it will turn 90 to the left (it's shorter, and is still the same heading). Also note that since it takes time to start/stop/turn, that the program may have executed many commands before the machine actually gets to it's new speed or heading. Each robot has two status bars on the right-hand side of the screen. The upper one (marked with an "A"), is the robot's armor. The one below it (marked with an "H") is the robot's heat scale. Also in the robot's status area is a space dedicated to displaying error codes. These codes will be displayed in both decimal and hexidecimal format. They can be extremely useful as a means of output to see what's going on "in your robot's head". Damage: ~~~~~~~ Collision at high speed: 1 Heat is 300 - 349: 1 every 64 game cycles Heat is 350 - 399: 1 every 32 game cycles Heat is 400 - 449: 1 every 16 game cycles Heat is 450 - 474: 1 every 8 game cycles Heat is 475 - 499: 1 every 4 game cycles Heat is 500 or higher: Robot explodes. Missile blast: 14-range (i.e. 14 for dead center, and 1 at 13 meters) Robot detonation: 25-range (i.e. 25 for dead center, and 1 at 24 meters) Mine blast: 35-range (i.e. 35 for dead center, and 1 at 34 meters) Overburn Missile blast: (14-range)*1.25 Overburn Robot detonation: (25-range)*1.30 It is assumed that the robot bodies have a radius of 4 meters, and thus the closest you can get to an enemy is 8 meters. Therefore the most damage you will actually take from another robot exploding is 17, assuming that it is not on overburn. The missiles however can go off at 0 meters from the robot if it is targetted precisely. Robot detonations cause the same amount of damage whether the robot was killed with a missile or it used a destruct command. Robot performance: per game cycle: ~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~ Normal missile velocity: 32 meters Maximum non-overburn speed: 4 meters Turn rate: 8 degrees Acceleration 4% of max forward speed Turret rotation Instantaneous WATCH YOUR HEAT!! Over-heated robots can easily become DEAD robots! Here is the heat scale: 80+ Max speed reduced to 98% 100+ Max speed reduced to 95%. 150+ Max speed reduced to 85%. 200+ Max speed reduced to 70%. 250+ Max speed reduced to 50%. 300+ Heat starts burning armor off (the hotter, the faster) 400+ Robot stops executing commands until cools below 350 (shutdown). 500+ Robot explodes. Also note that during shutdown, the robot's speed is reduced to 0, making it a sitting duck. The shutdown temperature can be altered by accessing port 20. Normal heat exchanges: (can be altered with robot configs) Firing weapon: 20 Dissipation per game cycle: 1 ( +1/8 if throttle is -25% to 25% ) OVER-BURN SHOULD BE USED WITH CAUTION!!! Overburn effects the following: 1) faster driving speed (130%) 2) weapon does more damage (125%) 3) weapon projectiles move faster (125%) 4) weapon generates more heat (150%) 5) nastier explosion from death or self-destruct (130%) 6) worse heat dissipation ( 66%) (all percentages are of original total- i.e. 130% means 30% increase). Note that Overburn multipliers are applied to your robot's actual status. For instance, if your driving speed has been adjusted to 150% using robot configs, and then you turn on overburn, you're actually going to go 95% over standard speed (195%). ---------------------------------------------------------------------------- HEXIDECIMAL: This section is intended just as a refresher, not as a lesson in hexidecimal. Hexidecimal is very useful to programmers since each digit perfectly represents 4 bits (a nybble, which is half of a byte). 4 bits can store a number from 0 to (2^4)-1, or 0 - 15. Since there are no single-digit symbols for 10 to 15, we use A to F: 0 = 0 1 = 1 2 = 2 3 = 3 4 = 4 5 = 5 6 = 6 7 = 7 8 = 8 9 = 9 A = 10 B = 11 C = 12 D = 13 E = 14 F = 15 10 = 16 The right-most digit in a hexidecimal number is still the one's column, but instead of 10's, 100's and 1000's we have 16's, 256's, and 4096's. To convert a hexidecimal number to decimal, simply take the digit from each column and multiply by the columns value: A148 = A * 4096 = 40960 + 1 * 256 = + 256 + 4 * 16 = + 64 + 8 * 1 = + 8 ~~~~~~~~~ = 41288 Like I said, just a refresher. ---------------------------------------------------------------------------- PROGRAMMING ROBOTS: When a program is loaded into AT-Robots, it undergoes a process called "compiling" where each number, word, and instruction is converted into a number. These numbers are called OP-CODES, or OPs for short. As you will see below, the compiler is extremely flexible, and you can get away with all sorts of bizarre combinations and still get a not only a clean compile, but also a functional robot program. The programming language consists of several basic types of statements. 1) Remarks. - These are not compiled into your program, they are simply notes that you can read when viewing programs. Use these to put comments in about what the program is doing, to make it more understanable when looking through it. 2) Directives - These are used exclusively by the compiler, and are not executed at run-time. The best examples are Var Defs (#def) 3) Labels. - These are the target locations for JUMP/GOTO and GOSUB/CALL commands. They are not executed and do not use your robots processor time. 4) Commands. - These are the functions of your robot. They command the robot to perform specified activities. 5) Variables - You can have up to 256 variables. They are 16 bits (holding a value from -32768 to 32767). Their names must contain only letters, numbers, and underscores, and must begin with a letter. NO symbol-characters! A variable name can be up to 16 characters long. The word "Instruction" will often be using in place of "Command". Also note that "registers" are simply special cases of variables. Now for more detail on these types of statements... - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - STATEMENTS: Remarks: Syntax: ; The semi-colon MUST come before the comments/remarks on a line, and whatever you put on the line after it will be ignored by the compiler. OP-CODE: none, ignored Indirect (colon) Labels: Syntax: :#### The colon MUST be the FIRST character on the line (except for spaces). RIGHT after it, without any spaces in-between, you put a number anywhere from 0 to 32767. That number is the label. Do not use the same number twice within the same program. You can not use a hexidecimal number in a label. OP-CODE: