Battlecode (MIT 6.470) package manager.

USAGE

  1. Make sure you’re using the latest tool version.

    bcpm self

  2. Install the Battlecode distribution. Later, use the same command to update the distribution.

    bcpm dist

3a. Check out a player repository and set it up for development.

cd ~/workspace  # Your Eclipse workspace.
bcpm install [email protected]:six370/yield.git

After executing the commands above, import the project into Eclipse (File > Import > Existing Projects into Workspace).

3b. Create a blank player.

bcpm new team1337

If you go this route, you will have to create the git repositories yourself, and push them.

  1. Confirm that the player is installed.

    bcpm list
bcpm ls

5a. Switch between the 2D and the 3D client.

bcpm set client3d on
bcpm set +client3d
bcpm set client3d off
bcpm set -client3d

5b. Turn the client sound on or off.

bcpm set +sound
bcpm set -sound

  1. See all the maps in the distribution.

    bcpm listmaps
bcpm lsmaps

  2. Run a game against some other player code.

    bcpm match yield team000 venice

# The following command runs the match right away, for maximum enjoyment.
bcpm livematch yield team000 venice

7b. Game too slow? Increase the JVM memory.

bcpm set vm_ram 1024

  1. Run a debugging game against some other player code. Debugging games us use bcpm configuration settings instead of production defaults.

    bcpm debugmatch yield team000 venice

  2. Set the number of simultaneous matches. Match the number of physical cores you have.

    bcpm set match_threads 2

10a. Run a duel between 2 players on multiple maps.

bcpm duel yield team000

# The following command restricts the duel to a subset of maps.
bcpm duel yield team000 venice fortress

10b. Pit a player against other players you have installed.

bcpm pit yield team000 team001

# The following pits against all other installed players.
bcpm pit yield

10c. Rank players by their total scores in all possible pairwise duels.

bcpm rank yield team000 team001

# The following ranks all installed players.
bcpm rank

11a. Show all settings.

bcpm config

11b. Change debugging settings

bcpm set +noupkeep
bcpm set -noupkeep
bcpm set +debugcode
bcpm set -debugcode
bcpm set +breakpoints
bcpm set -breakpoints
bcpm set debuglimit 1000000  # Maximum number of bytecodes per round in debug_ methods.

  1. Run the player’s test suite.

    bcpm test yield

  2. Run a single test case in the player’s test suite.

    bcpm case yield win_vs_yield

    # The following command runs the first match right away, for maximum iterating speed. bcpm livecase yield win_vs_yield

  3. Replay the last match ran in a test.

    bcpm replay

  4. Copy a distribution map into the test suite, for customization.

    bcpm copymap venice

  5. Remove the installed player. (removing the project folder is not enough!)

    bcpm uninstall yield

  6. Create a new player from an existing template.

    bcpm copy myplayer [email protected]:six370/yield.git bcpm copy myplayer [email protected]:six370/yield.git branch_or_tag_name

You’ll need to import the project into Eclipse, and setup a git repository for the player.

  1. If bcpm crashes or you abort it, you’ll need to clean up the temporaries left behind.

    bcpm clean

  2. Use directed find/replace to unroll loops.

    bcpm regen bcpm regen src/yield/test/stubs/LoggingStubs.java

  3. After winning the competition, remove the players and distribution. Commit and push first!

    bcpm reset

TESTING

The test cases are .rb (Ruby) files in the ‘suite’ directory. The following example showcases the functionality available in a test suite. The suite DSL slightly resembles rspec.

# Set the side of the tested player in future matches.
side :b

# Set the opponent for future matches.
vs 'yield'

# Set the map for future matches.
map 'venice'

# Use a custom map from suite/maps.
suite_map 'venice2'

# Disable energon draining. :upkeep is a synonym for 'bc.engine.upkeep'.
option :upkeep, false

# Replace a .java file in the player under test with a .java file in the test suite.
# Both names are automatically prefixed with the team package ('yield.' in this case).
replace_class 'RobotPlayer', 'test.players.TestRobotPlayer'

# Re-route all calls that look like target.canMove(...) to
# yield.test.stubs.LoggingStubs.canMoveStub(target, ...)
stub_member_call 'canMove', 'test.stubs.LoggingStubs.canMoveStub'

# Re-route all calls that look like target.wantStubbing(...) to
# yield.test.stubs.LoggingStubs.wantStubbingStub(...)
stub_static_call 'wantStubbing', 'test.stubs.LoggingStubs.wantStubbingStub'

# Replace the code marked with Stubs.canMove.logo in yield.LoggingStubs with the code marked
# Stubs.canMove.logoSource in yield.test.stubs.LoggingStubs
replace_code 'LoggingStubs', 'Stubs.canMove.logo',
             'test.stubs.LoggingStubs', 'Stubs.canMove.logoSource'

# Run a test match to check some conditions.
match do
  it 'must win in any way' do
    should_win
  end

  it "shouldn't leak exceptions" do
    should_not_throw
  end

  it 'should stub the member call' do
    should_match_unit_output(/This should show up/)
  end

  it 'should stub the static call' do
    should_match_unit_output(/wantStubbing\: this (.*) be printed/) do |unit, match|
      fail 'Static call not stubbed' unless match[1] == 'should'
    end
  end

  it 'should fail' do
    fail
  end
end

# Reset energon draining option to its default value.
option 'bc.engine.upkeep', nil

To prevent infinite recursion, stubbing should be disabled in the actual stubs. To prevent compilation errors, stubbing should also be disabled on the first line of the stubbed method’s definition. The stub implementation below demonstrates the syntax for stubbing and code replacement.

package yield.test.stubs;

import battlecode.common.Direction;
import battlecode.common.RobotController;

public class LoggingStubs {
  //$ -stubs
  public static final boolean canMoveStub(RobotController target, Direction where) {
    boolean returnValue = target.canMove(where);
    //$ +mark: Stubs.canMove.logo
    System.out.println("This should not show up");
    //$ -mark: Stubs.canMove.logo    
    System.out.println("canMove(" + where.toString() + ") -> " + returnValue);
    return returnValue;
  }
  //$ +stubs

  public static void markTest() {
    //$ +mark: Stubs.canMove.logoSource
    System.out.println("This should show up");
    //$ -mark: Stubs.canMove.logoSource
  }
}

The code patching directives use very simple implementations based on file copying and regular expressions. Following these best practices should help avoid broken builds:

* Use Eclipse's "Organize imports" feature to achieve the item below:
* Class names should be unqualified, and imports should use fully qualified names.
* Use the same class name (but different package names) in replace_class.
* A replace_class source class should only depend on classes in other packages.

DIRECTED FIND/REPLACE

bcpm regen reads one or more source files and discovers tagged source blocks, then replaces matching target blocks while renaming tokens. The example below shows the syntax.

System.out.print("Should show numbers 1-3 and letters A-C: ");
//$ +gen:source Numbers A 1
System.out.print("A 1 ");
//$ +gen:off
// This used to be System.out.print("A 1");
//$ -gen:off
//$ -gen:source
//$ +gen:target Numbers B 2
//$ -gen:target
//$ +gen:target Numbers C 3
System.out.print("A 1 ");
//$ -gen:target

INSTALLATION

On Ubuntu:

sudo apt-get install ruby-full rubygems
sudo gem install rubygems-update
sudo `gem env | grep 'EXECUTABLE DIRECTORY' | ruby -e "puts gets.split(': ', 2).last"`/update_rubygems

On OSX:

Get git from http://code.google.com/p/git-osx-installer/

On Windows 7+:

Get git from http://code.google.com/p/msysgit/downloads/
Get ruby 1.8.7 (add it to your path) from http://rubyinstaller.org/downloads/
Get ant from http://code.google.com/p/winant/

On everything (skip the ‘sudo’ prefix on Windows though):

sudo gem install rake echoe
git clone git@git.pwnb.us:six370/bcpm.git
cd bcpm
rake install

You’ll need an administrative shell on Windows.