Grobots - Source

The Grobots source is kept in a Mercurial repository. You can view it with your browser, or clone a local copy:

hg clone http://hg.code.sf.net/p/grobots/trunk grobots

There is also a Java port.

The old CVS repository is still accessible by anonymous CVS from grobots.cvs.sourceforge.net. (Use CVSROOT=:pserver:anonymous@grobots.cvs.sourceforge.net:/cvsroot/grobots.) Or view the CVS tree with your browser. You can also download old versions of the source as zipfiles. The latest version that we've gotten around to uploading is that of 26 August 2012.

Grobots is free software, distributed under the GNU General Public License.

Architecture

Grobots is built in four layers. The lowest, Support, provides some useful portable library. The second (in three parts: Sides, Simulation, and Brains) implements the game engine. The third, Views, provides most of the user interface portably. The top layer, UI, embeds the views and engine in a cross-platform application. Lower layers do not depend on higher ones.

Most of the names below correspond to a .cpp file and a header file.

Support (utilities)

General-purpose, lower-level code used by the rest of the system.

GBPlatform.h

File for platform conditionalization.

GBNumber

Fixed-point number class, used throughout the simulation and brains.

GBFinePoint

2-vector of GBNumbers, used for positions and velocities.

GBColor

A more convenient representation of colors.

GBErrors

Most of the exception classes live here. (Maybe they shouldn't.)

GBTypes.h

Header file defining a bunch of widely used types and synonyms.

GBLongNumber

Extra-precision GBNumber, used for keeping scores.

GBSound

Some simple asynchronous sound functions.

GBDeletionReporter

Mixins for classes whose instances tell their dependents when they're deleted, to get around the lack of garbage collection.

GBModel

Mixin to keep a version number on an object, so views can tell when it's changed.

GBRandomState

A random-number generator.

GBstringUtilities

Various string utilities.

GBGraphics

Three classes for portable graphics.

GBMilliseconds

Portable timer function. (GBMilliseconds.h is the smallest file in Grobots.)

Sides

This part describes sides. Some state is also here, but ought to be split out. Everything here should be portable.

GBSide

Side spec class, equivalent to a side file.

GBRobotType

Type spec class.

GBSideReader

Loads side files.

GBHardwareSpec

A huge file describing the nature of hardware.

GBScores

Several classes for scores and statistics.

Simulation

Everything here should be portable.

GBObject and GBWorld are the heart of the engine.

GBObject

Abstract class for simulation objects (sprites).

GBObjectWorld

Class that holds GBObjects and supports some operations on them.

GBWorld

Subclass of GBObjectWorld, with more features and a roster. This is an important class.

Files containing subclasses of GBObject:

GBDecorations

Purely decorative sprites that have no game effect, like smoke and sparks.

GBFood

Classes for food.

GBShot

All shots, including syphons, force fields, and explosions.

GBSensorShot

Sensors are implemented using a sensor shot, which sees things by colliding with them.

GBRobot

Most of the actual work is in GBHardwareState.

Other files supporting GBRobot:

GBHardwareState

Unwieldy file describing most of the behavior of hardware.

GBMessages

Most of the message-passing communications system.

Brains

All brain-related stuff (both spec and state) is here. Only one kind of brain is currently used, but there used to be others (for hardcoded sides), and there could be more in the future (to support other languages, for example).

GBBrainSpec

Abstract class.

GBBrain

Abstract class.

GBStackBrainSpec

Spec for the usual kind of brain. Represents compiled code, mostly. Also contains part of the compiler.

GBStackBrain (including GBStackBrainPrimitives.cpp)

Brain class: a simple stack-based virtual machine.

GBStackBrainOpcodes

Names of stack brain primitives.

Views

Each window displays a GBView.

GBView

Abstract view class, and a few useful subclasses.

GBListView

Parent class for RosterView, ScoresView, and any other views that are lists of something.

GBPortal

The main view.

GBRosterView

GBMiniMap

GBScoresView

GBRobotTypeView

GBTournamentView

GBDebugger

GBAboutBox

UI

Top-level cross-platform user interface code. Nothing outside this part depends on anything in it.

GBApplication

GB-specific application-scope stuff.

GBViewsApplication

Non-Grobots-specific cross-platform application framework.

GBWindow

Cross-platform wrapper class for a window containing a view.

GBMain.cpp

This is a boring file, containing main() and nothing else.

Mac

Mac Interface.rsrc

Mac-specific resource file, containing menus and dialogs.

Grobots*.make

MPW makefiles.

Sounds.rsrc

Resource file with sounds.

Carbon.rsrc

Resource file with one resource needed for the Carbon build.

Grobots.xcodeproj

Project for building with XCode.

info.plist

Property list for OS X build.

Grobots_Prefix.pch

Prefix header for XCode. (It's useless. How do I turn it off?)

Win

Menus.rc, grobots.ico

Windows-specific resource files.

WinGrobots.sln, WinGrobots.vcxproj, WinGrobotsHeadless.vcxproj

Build files for Microsoft Visual C++.

Grobots.dsw, GrobotsWin.dsp, GrobotsHeadless.dsp

Build files for old versions of Microsoft Visual C++.

Problems

• Hardware has big files and poor modularity.
• spec/state aren't distinguished for sides and types.
• GBStackBrain has poor modularity. Adding an operator requires changes to three files.

Places we could use the standard library

• Collections in various places (roster, types)
• Standard exception classes

Porting

Headless

To begin with, port headless mode, which should be entirely portable. The main problem will be compatibility with your compiler. Grobots uses some C++ features which are not universally supported, such as long long, dynamic_cast, and std::string. You may also need to define some missing parts in Support. Simulation, Sides, and Brains shouldn't require any changes.

GBPlatform.h

Add an #if defined to identify your compiler and platform, if it's not there already.

GBMilliseconds

Milliseconds() should return the current time (since startup or whenever) in milliseconds. It doesn't need to be very precise.

Once you have headless mode working, start on the GUI.

Porting the GUI

GBGraphics

Make these three graphics classes work on your platform. Some parts exist only for portability, so it's OK if they don't do anything on your platform. You can live without GBBitmap but you'll lose double buffering, trails, and the portal background.

GBErrors

There are two error-reporting functions in GBErrors.cpp that need porting. These should be easy.

GBSound

This is stubbed out by default, so don't worry about it.

GBWindow

A way to make windows containing a GBView.

GBViewsApplication, and GBApplication

Make this framework work on your platform. This is the hard part, because GUI frameworks vary so much. Fortunately it's mostly independent from the rest of Grobots. Don't worry too much about sharing with the existing code; we can factor out the common stuff later.

The Mac and Win folders should be replaced by an appropriately named one for your platform, containing makefiles and any other platform-specific files.

Note that the interface may want to be structured differently on some platforms, e.g. panes instead of separate windows.

Sending Patches

If you've ported part of Grobots, fixed a bug, or added a feature, we want your changes. Send patches to Devon or to the mailing list.

Patches should include enough context that they can be applied even if other changes have been made. diff -u is good. Or give the old and new versions of each function modified. Or just send us the changed files.

To-do list

A more up-to-date to-do list is on the wiki, where you can add things to it.

These lists are mostly for the benefit of the maintainers, but if you feel like implementing some of these, go ahead. They're in very rough order of priority - items at the tops of the lists are more pressing; ones at the bottom are unlikely to ever happen.

Incomplete ports

If you're looking for something to do, try fixing incompletely ported parts. Many of these are easy if you know the platform or can RTFM:

• [Mac] Add a suitable icon.
• [Mac] Make the About item appear in the application meny. (This used to work.)
• [Mac] Store sounds as separate files, not resources.
• [Mac] Replace the remaining uses of long-deprecated resource files - get dialogs from nib files instead.
• [Mac] Replace deprecated calls (including QuickDraw!) with more recent ones.
• [Carbon] Make cursors work: SetThemeCursor?
• [Mac] Open all sides in a dropped folder.
• [Windows] Replace confusing Abort/Retry/Ignore dialog for NonfatalError with Quit/Abort/Continue.
• [Windows] Make confirmation dialog work.
• [Windows] Make tournament length dialog work.
• [Win] Make sounds work.
• [Windows] Make Rules dialog work. (Low priority, as it might be removed.)

Views and UI

• Menu item IDs should not need to match position in menu.
• [Mac] Why is blitting to the screen so slow?
• Bug: framerate is irregular on Slowest.
• Bug: Doubletime sometimes shows garbage, and isn't available across multiple rounds.
• [Windows] Allow opening sides from command line.
• Support graphing other statistics than biomass.
• Save window positions and states.
• Add more hardware variables to the debugger, and color-code them.
• Debugger should show multiple words on one line.
• Show overall hardware statistics in Types view when no type is selected.
• Bug: profile times are sometimes nonsense.
• Use GBView::lastDrawn for GBRosterView's framerate? (But it's private.)
• Move click-counting to GBView?
• Select next/previous side with arrow keys.
• Allow scrolling with arrow keys?
• Confirm (once) before using destructive tools during tournaments.
• Bug: following jumps far ahead of syphons and forcefields.
• [Windows] Bug: Closing a child window sometimes buries the main window.
• Remove minimap layer options: they're obsolete (except Trails).

Graphics and other glitz

• Make more information visible: sensor results, sensor foci, engine use.
• Move meters outside of cells, to make them larger and easier to read.
• Try inflammation/halos behind cells to indicate transient or rare conditions: damage, syphoning, reloading, transmitting, birth, crashes, prints.
• Replace detached decorations (radio rings, syphon sparkles) with attached ones, for speed and beauty.
• Draw tails on bots to indicate velocity or engine-velocity?
• Allow cells to have a graphics box larger than their radius, so external meters and tails draw reliably at the edge of the viewport.
• Add separate underlay and overlay layers, so external meters and tails are well-behaved when they overlap other cells.
• Deprecate or remove cell decorations?
• Record territory, and draw it in the minimap (instead of trails?).
• Translucent smoke, explosions, forcefields.
• Alternate portal background? (What's the point?)
• Adjust sound volume and balance by viewport.

Engine

• Replace Rules dialog with loading a rules file (more flexible).
• Keep more statistics in history.
• Add a better language for brains. (Lisp? Lua?)
• Replace the remaining GBNumber methods like ToDouble with overloaded functions, to make switching number types easy. Once that's done, we can try using floats instead of fixed-point numbers without breaking anything.
• Report starting line numbers of unclosed compile-time words.
• Make forcefields and syphons move instead of dying and being recreated, so they can be usefully followed. (Either shot or robot might get deleted, so whoever keeps the reference will have to listen for this.)
• Profile and optimize. (Why are Act and Statistics taking so long?)
• Don't make decorations when no one's going to see them.
• More statistics (who killed who?)
• More flexibility in sensors: filters, sorting, tracking?
• Add world-in-use layer between GBWorld and GBPortal. (viewpoint, tournament parameters, selection)
• [Win] support profiling: LARGE_INTEGER, QueryPerformanceCounter
• Add fake time-limit?

Rules changes

We are reluctant to make these changes because they would alter the rules in ways that change the performance of existing sides. If you want to experiment with rules, I suggest implementing rulesets first.

• Bug: shields reduce syphon effectiveness twice.
• More robust seed placement (avoid placing seeds close together).
• Find a better way to discourage large cells in combat than the current extra damage.
• Remove or fix shields. (absorb damage? what's the goal?)
• Fix forcefield balance, possibly by reducing stacking.
• Friendly syphons shouldn't show up on shot sensors.
• Experiment with stunners.
• Make shots last at least one frame. This might mean fiddling with phase order again.
• Physics experiments: dot-product engines? gradual weapon reloading?

Other

• More documentation, including user interface, and the rest of the overview.
• Write tests for lower two layers. (Not urgent, since sides serve as test scripts with excellent coverage.)
• Provide more help for would-be porters.
• Port UI to Linux.
• Merge GBTournamentView, HTML output, and headless output?
• Use STL (especially containers) more.
• Replace pointers with references where appropriate.
• [Mac] Convert FSSpecs to pathnames and use ifstream to load sides.

Statistics

There are automatically generated statistics at ohloh.

(5 April 2003) I counted lines in the source, and was surprised to find it's over 16000 lines and a hundred files. I didn't count the makefile, which is mostly machine-generated, or the two resource files, which don't have lines.

The largest (and smallest) files are: