How to Write a CodeFray Controller

This guide is meant to be an all-inclusive mini-tutorial explaining how to write a controller. It will include how to download and use the API, how to create a Controller class, and how to test the controller.

Obtaining the API

The easiest way to use the API is via the installer. To use the installer, you first must install Git. You can find it here if you are on a computer that does not block installing packages. If your computer doesn't let you install Git, and you are on a Mac, open a terminal (more on how to get one later) and type 'git' without the quotes, and confirm that you want to install the XCode tool. After setup is complete, open your system's terminal (cmd on windows, Terminal on mac). If you are on Mac and the terminal is blocked, download and run this. Enter the following (type it and press enter. Don't type the '$ ', it's meant to mark lines):

$ git version

If all goes well, the version of git should be printed.

Next, you should create a project in your IDE in which the API will reside. If you are using IntelliJ IDEA, I recommend creating a new module within the project you plan to use when creating your Controllers. The IDE should create a src directory where the API source should reside. Navigate to that directory in File Explorer (Windows) or Finder (Mac).

Next, download the CodeFrayAPI installer. Place the installer in the src folder your IDE created, and run it via a terminal. To do that, first navigate to your src file:

#For Windows:
$ cd C:\\This\\is\\the\\path\\to\\src
#For Mac:
$ cd /This/is/the/path/to/the/src

Then run the installer:

#For Windows:
$ ./CodeFrayInstaller
#For Mac:
$ ./CodeFrayInstaller-Mac

If all goes well, you should get a message stating that the CodeFrayAPI was installed successfully. Keep the installer handy somewhere.

Updating the API

Occasionally, the API may have updates. Without removing the src folder, run the installer again in the same way you did when you first installed the API. This will install only the updates. I recommend keeping the installer in the src folder at all times.

Create the Controller

All that's left to do is write the controller! You will need to create a project (or module in IntelliJ) in your IDE of choice and configure it to use the CodeFrayAPI as a compile-time library (but do not export the API with your JAR). That step is outside the scope of this tutorial.

Once everything's linked, create your controller class! Create a new class that implements GolemController:

import com.github.lg198.codefray.api.golem.Golem;
import com.github.lg198.codefray.api.golem.GolemController;

public class MyController implements GolemController {

    @Override
    public void onRound(Golem g) {

    }

}

Next, add the ControllerDef annotation to the class. This annotation has several fields that contain information about your controller. The fields are:

Field Name	Description	Example
id	A unique id for your controller. It should be a package descriptor.	com.github.lg198.MyController
name	A human-readable name for your controller.	My Very First Controller, Version Uno
version	A version string. It should change every time you submit the controller.	1.3.4
devId	A unique identifier that represents you. Must be the same on all controllers.	layne-gustafson

Now your class should resemble:

import com.github.lg198.codefray.api.golem.ControllerDef;
import com.github.lg198.codefray.api.golem.Golem;
import com.github.lg198.codefray.api.golem.GolemController;

@ControllerDef(
        id = "com.github.lg198.MyController",
        name = "My Very Own Controller, Version Uno",
        version = "1.3.4",
        devId = "layne-gustafson")
public class MyController implements GolemController {

    @Override
    public void onRound(Golem g) {

    }

}

Now we're in business. Let's make those golems move!

Writing the Controller

Check out your Controller class. You will see that it overrides one method, public void onRound(Golem g). For every round, for every golem on your team, this method is invoked with an interface to the golem passed as a parameter. Use this golem object for the current round only - if you store the object in a variable and attempt to cheat by calling its methods in a later round, not only will that not work, but you will automatically lose the game! Check out the rules on the CodeFray wiki.

To get a sense of what you can do with a golem, look at the Golem, GolemInfo, and Game interfaces. Those methods are available for your use via the Golem instance passed in the onRound method. Also, observe the GolemType enum. It contains the different types of golems and specifies their qualities. Be familiar with their restrictions; your code will need to know how many moves or shots a golem can use per round.

Testing the Controller

It is important to test your controller! You'll want to catch bugs so they aren't present in a match. Make sure you build your Controller and export it as a jarfile! To test, launch the CodeFray application. For one of the teams, select an included controller to play against. In the other, browse and find your Controller jar. Then browse to the map you wish to use, or create your own. Finally, start the game and observe! For detailed "what exactly just happened?!" debugging, consult the logs taken in every game. They contain detailed information about everything that occurs during the game.

Saving Your Controller

If you plan to work on your controller from more than one computer, I highly recommend using version control (considering you already downloaded and installed Git). Don't use GitHub, however, because all free repositories are public, and you can't let competitors see your code! Use BitBucket instead (http://bitbucket.com), where you can create unlimited private Git repositories! For more information about using Git, Google it! Just make sure you initialize your repository in an empty folder (so remove all your code first, then initialize, then paste it back if you must).