From 73344df0e6574be9a7c1c429b62aee89fb40d8ac Mon Sep 17 00:00:00 2001 From: Neale Pickett Date: Sun, 9 Jul 2017 18:31:12 +0000 Subject: [PATCH] Rework for github jekyll hosting --- COPYING.txt => LICENSE.md | 0 README.md | 154 +++-------------------------------- TODO.txt => doc/TODO.md | 0 HISTORY.md => doc/history.md | 10 ++- doc/index.md | 47 +++++++++++ doc/running.md | 73 +++++++++++++++++ THANKS.md => doc/thanks.md | 0 7 files changed, 137 insertions(+), 147 deletions(-) rename COPYING.txt => LICENSE.md (100%) rename TODO.txt => doc/TODO.md (100%) rename HISTORY.md => doc/history.md (92%) create mode 100644 doc/index.md create mode 100644 doc/running.md rename THANKS.md => doc/thanks.md (100%) diff --git a/COPYING.txt b/LICENSE.md similarity index 100% rename from COPYING.txt rename to LICENSE.md diff --git a/README.md b/README.md index f446fcb..d3a668c 100644 --- a/README.md +++ b/README.md @@ -1,151 +1,19 @@ -CTanks +Tanks ====== -This is a programming game, inspired by Crobots by Tom Poindexter -(http://www.nyx.net/~tpoindex/crob.html). Players write programs for -tanks, with the intent to seek out and destroy other tanks. - -Output is a JSON object, and some scripts are provided to wrap the -object up in a web page. +Dirtbags Tanks is a game in which you pit your coding abilities +against other hackers. You write a program for your tank, set it out +on the battlefield, and watch how your program fares against tanks +written by other players. Dirtbags Tanks is frequently a component of +[Dirtbags Capture The Flag](/ctf/). -Included programs ------------------ +Documentation +------------- -I tried to stick with the Unix philosophy of one program per task. I -also tried to avoid doing any string processing in C. The result is a -hodgepodge of C, Bourne shell, and awk, but at least each piece is -fairly simple to audit. - - -### round.sh tank1 tank2 ... - -Runs a single round, awards points with rank.awk, and creates a new -summary.html with summary.awk. This is the main interface that you want -to run from cron or whatever. - - -### forftanks tank1 tank2 ... - -A program to run a round of tanks and output a JSON description of the -game. This is what tanks.js uses to render a game graphically. -The object printed contains: - - [[game-width, game-height], - [[tank1-color, - [[sensor1range, sensor1angle, sensor1width, sensor1turret], - ...]], - ...], - [[ - [tank1x, tank1y, tank1angle, tank1sensangle, - tank1flags, tank1sensors], - ...], - ...]] - -If file descriptor 3 is open for writes, it also outputs the results of -the round to fd3. - - -### rank.awk - -Processes the fd3 output of forftanks to award points and output an -HTML results table. - - -### summary.awk tank1 tank2 - -Creates summary.html, linking to all rounds and showing overall -standing. - - -### designer.cgi - -Accepts form input and writes a tank. - - - -Building from source --------------------- - -You should be able to just run "make". The C is supposedly ANSI C, and -might even compile on Windows. I've built it on Linux, with glibc and -uClibc, big- and little-endian. - - - -History -------- - -This is a port of the "Tanks" program written by Paul Ferrell - in 2009-2010. Paul created the entire game based -off a brief description I provided him of Crobots and a vague desire to -"make something fun for high school kids to learn some programming." We -ran Paul's Tanks as part of a 100-attendee computer security contest in -February of 2010 and by all accounts it was a huge success. It even -made the nightly news. - -Paul's version was written in Python and provided a custom language -called "Bullet", which looked like this: - - >addsensor(50, 0, 5, 1); # 0 - >addsensor(100, 90, 150, 1); # 1 - >addsensor(100, 270, 150, 1); # 2 - >addsensor(100, 0, 359, 0); # 3 - - # Default movement if nothing is detected - : move(70, 70) . turretccw(); - random(2, 3): move(40, 70) . turretccw(); - random(1, 3): move(70, 40) . turretccw(); - - # We found something!! - sense(3): move(0, 0); - sense(1): turretcw(); - sense(2): turretccw(); - sense(0): fire(); - -Nick Moffitt played with this original version and convinced me (Neale) -that something like Forth would be a better language. I added some code -to accept a scaled-down version of PostScript. The IRC channel we -frequent collectively agreed to give this new language the derisive name -"Forf", which should ideally be followed by punching someone after it is -spoken aloud. I wrote a Python implementation of Forf, which was slow, -and then Adam Glasgall wrote a C implementation, which was quick. - -I decided to take Tanks to Def Con in July 2010, and just for bragging -rights, to have it run on an Asus WL-500gU. This is a $50 device with a -240 MHz MIPS CPU, 16MB RAM, and a 4MB flash disk, along with an -802.11b/g radio, 4-port 10/100 switch, and an additional 10/100 "uplink" -port; it's sold as a home wireless router. I had originally intended to -run it off a lantern battery just for fun, but eventually thought better -of it: doing so would be wasteful for no good reason. - -Aaron McPhall , my summer intern at the time, got -OpenWRT and Python onto the box and benchmarked it at about 60 seconds -for a 16-tank game, after he had profiled the code and optimized a lot -of the math. That wasn't bad, it meant we could run a reasonably-sized -game at one turn per minute, which we knew from past experience was -about the right rate. But it required a USB thumb drive to hold Python, -and when we used the Python Forf implementation, the run-time shot up to -several minutes. I began this C port while Adam Glasgall, another fool -on the previously-mentioned IRC channel, started work on a C version of -a Forf interpreter. - -This C version with Forf runs about 6 times faster than the Python -version with Bullet, on the WL-500gU. A 1GHz Intel Atom runs a 16-tank -game in about 0.2 seconds. - - -What's so great about Forf? ---------------------------- - -Nothing's great about Forf. It's a crummy language that only does -integer math. For this application it's a good choice, for the -following reasons: - -* No library dependencies, not even malloc -* Runs in fixed size memory -* Not Turing-complete, I think (impossible to make endless loops) -* Lends itself to genetic algorithms +* [Homepage](https://dirtbags.github.io/tanks/) +* [History](doc/history.md) +* [Running](doc/running.md) Author diff --git a/TODO.txt b/doc/TODO.md similarity index 100% rename from TODO.txt rename to doc/TODO.md diff --git a/HISTORY.md b/doc/history.md similarity index 92% rename from HISTORY.md rename to doc/history.md index 436baa2..4570e75 100644 --- a/HISTORY.md +++ b/doc/history.md @@ -1,9 +1,11 @@ History -======= +------- This is a port of the "Tanks" program written by Paul Ferrell in 2009-2010. Paul created the entire game based -off a brief description I provided him of Crobots and a vague desire to +off a brief description I provided him of +[Crobots](http://tpoindex.github.io/crobots) +and a vague desire to "make something fun for high school kids to learn some programming." We ran Paul's Tanks as part of a 100-attendee computer security contest in February of 2010 and by all accounts it was a huge success. It even @@ -33,7 +35,8 @@ that something like Forth would be a better language. I added some code to accept a scaled-down version of PostScript. The IRC channel we frequent collectively agreed to give this new language the derisive name "Forf", which should ideally be followed by punching someone after it is -spoken aloud. +spoken aloud. I wrote a Python implementation of Forf, which was slow, +and then Adam Glasgall wrote a C implementation, which was quick. I decided to take Tanks to Def Con in July 2010, and just for bragging rights, to have it run on an Asus WL-500gU. This is a $50 device with a @@ -70,4 +73,3 @@ following reasons: * Runs in fixed size memory * Not Turing-complete, I think (impossible to make endless loops) * Lends itself to genetic algorithms - diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..407e209 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,47 @@ +--- +title: Tanks +--- + + + + +
"Ant Lion" nails "Rabbit With Gun".
+ + + +
+ +Dirtbags Tanks is a game in which you pit your coding abilities +against other hackers. You write a program for your tank, set it out +on the battlefield, and watch how your program fares against tanks +written by other players. Dirtbags Tanks is frequently a component of +[Dirtbags Capture The Flag](/ctf/). + +Each tank has a turret-mounted laser, two treads, up to ten sensors, +and a diagnostic LED. Sensors are used to detect when other tanks are +inside a given arc. In the examples on this page, "triggered" sensors +turn black. Most tanks will take some action if a sensor is +triggered, such as changing speed of the treads, turning the turret, +or firing. + +Tanks are programmed in Forf, a stack-based language similar to +PostScript. + + +Other Versions +-------------- + +Everybody loves tanks! +If you've made a port or done something fun with it, +please let me know and I'll link it here! + +* [Class Lab](https://github.com/Arctem/nmt_python_labs/tree/master/labs/project) at New Mexico Tech, by Russell White + + +Author +------ + +Neale Pickett diff --git a/doc/running.md b/doc/running.md new file mode 100644 index 0000000..3ad5628 --- /dev/null +++ b/doc/running.md @@ -0,0 +1,73 @@ +--- +title: Running Tanks +--- + +Unfortunately, it's kind of a mess right now. +I know there are a few forks of this code, +and I would love it if someone proposed a merge to clearly illustrate how to run tanks. + +When I spin up a new tanks game, +typically I run something like: + + while sleep 60; do ./round.sh */; done + +This assumes all your tanks directories are in the same place as `round.sh`. + + + +Included programs +----------------- + +I tried to stick with the Unix philosophy of one program per task. I +also tried to avoid doing any string processing in C. The result is a +hodgepodge of C, Bourne shell, and awk, but at least each piece is +fairly simple to audit. + + +### round.sh tank1 tank2 ... + +Runs a single round, awards points with rank.awk, and creates a new +summary.html with summary.awk. This is the main interface that you want +to run from cron or whatever. + + +### forftanks tank1 tank2 ... + +A program to run a round of tanks and output a JSON description of the +game. This is what tanks.js uses to render a game graphically. +The object printed contains: + + [[game-width, game-height], + [[tank1-color, + [[sensor1range, sensor1angle, sensor1width, sensor1turret], + ...]], + ...], + [[ + [tank1x, tank1y, tank1angle, tank1sensangle, + tank1flags, tank1sensors], + ...], + ...]] + +If file descriptor 3 is open for writes, it also outputs the results of +the round to fd3. + + +### rank.awk + +Processes the fd3 output of forftanks to award points and output an +HTML results table. + + +### summary.awk tank1 tank2 + +Creates summary.html, linking to all rounds and showing overall +standing. + + +### designer.cgi + +Accepts form input and writes a tank. + + + + diff --git a/THANKS.md b/doc/thanks.md similarity index 100% rename from THANKS.md rename to doc/thanks.md