[Getting Started with Creeper]

Create a main class

Create a .java file with the project name in your main project directory, e.g. create MyProject.java within my/name/MyProject. The main class should contain a static main function, which is the starting point of the program, as well as a constructor that initialises Creeper and any other classes within your project. To start with, paste the following into the MyProject.java:

package my.name.MyProject;

import net.lenkaspace.creeper.CRController;

public class MyProject {

    private CRController crController;

    public MyProject() {

        crController = new CRController("Creeper demo");{

    }

    /**
     * Main function
     */
    public static void main(String[] args) {
        new MyProject();
    }

}

You should be able to run the program now. If neccessary, add libraries contained in the lib folder to the build path of your project. Creeper interface will show up, with a blank world.

Set up a world

You can use Creeper's own world and your own agents. Say that you have created your own Agent class, instances of which need to move within the world. Agent should inherit from Creeper's CRBaseDynamicModel that provides capabilities like turning, movement and calculating vectors to other Agents. For the purposes of this tutorial, it is safe to just copy the Agent class from the demo project (i.e. net/lenkaspace/creeper/creeperDemo/model/Agent.java) and change its pacakge name to match your own.

You then need to pass your agents into crController's instance of CRWorld, using the addDynamicModel method. After the line that created the crController, paste the following:

//-- create agents in the world
Agent agent1 = new Agent(0, new CRVector3d(200,200,0), 0);
Agent agent2 = new Agent(1, new CRVector3d(300,200,0), 45);
Agent agent3 = new Agent(2, new CRVector3d(400,200,0), 180);

You could also add obstacles that are instanced of CRBaseSituatedcModel - obstacles are situated in the world so they need an X,Y position and a rotation, but they do not need to inherit from CRBaseDynamicModel as they do not move. Then add the obstacle into the world using the addSituatedModel method.

//-- create obstacle
CRBaseSituatedModel obstacle = new CRBaseSituatedModel(0, new CRVector3d(350,325,0), new CRVector3d(100,100,0), 180, SHAPE.CIRCLE, CRRenderer.CR_GREEN_DOT);
crController.getWorld().addSituatedModel(obstacle);

You will also need to import classes you just used at the beginning of the class file, using

import net.lenkaspace.creeper.model.CRBaseSituatedModel;
import net.lenkaspace.creeper.model.CRBaseSituatedModel.SHAPE;
import net.lenkaspace.creeper.view.CRRenderer;
import net.lenkaspace.creeper.vo.CRVector3d;
import net.lenkaspace.creeperDemo.model.Agent;

Run the program and press the Start Simulation button. You will notice a green square in the middle of the world, this is our obstacle. But there are no agents showing up, and the Java Console spits out warnings about loading images. This happens because the Agent class you copied from the creeperDemo package relies on an image of an agent that is not standard for Creeper. To make the agents work correctly, we need to setup our own project's ImageProvider first.

Set up an ImageProvider

Each instance or CRBaseSituatedObject or its sublcasses is expected to define what image should be used for its rendering. For example, the obstacle setup above uses CRRenderer.CR_GREEN_DOT, which is an image known to Creeper, supplied in its images directory. To use your own images, you need to create your own images directory with a path my/name/myProject/images and create a subclass of CRImageProvider within it. This subclass can then be used by Creeper's rendering routines to gain access to your own images. Create a file ImageProvider.java inside your images directory and paste the following in:

package my.name.myProject.images;

import net.lenkaspace.creeper.images.CRImageProvider;

public class ImageProvider extends CRImageProvider {

}

The last step is to inform crController in your main class that you have your own ImageProvider. In order to do so, paste the following immediatelly after the line that creates the crController:

//---- create image provider
ImageProvider imageProvider = new ImageProvider();
crController.setImageProvider(imageProvider);

You will also need to import your image provider at the beginning of the main file using:

import net.lenkaspace.creeperDemo.images.ImageProvider;

Run the program again and press Start Simulation. You should see three agents added to the world, now rendering correctly! But the agents should be moving around, why are they not? The reason is that their update loop is throwing a NullPointer exception, as the agents are trying to write their accelleration into a report that existed in the creeperDemo project, but does not exist in ours. To get this working properly, the last step is to create a simple report.

Set up a simple report

Line 26 of the Agent implementation asks a ReportController to provide the agent with a report called "Agent acceleration", so that the agent can record its accelleration in the current update step. You thus need to create this report in your main program.

The report should be a CRTimeSeriesReport, so that you can watch how accelleration of each agent randomly changed over time. The first argument to the report creation is its name that has to match the name the agent calls ("Agent acceleration"). You can then supply variable names, in this case names of your three agents, so that you can identify the individual lines on the graph. Paste the following after the agent and obstacle creation code:

//-- create a simple time series report
CRTimeSeriesReport report1 = new CRTimeSeriesReport("Agent acceleration", new String[] {"Agent 1","Agent 2","Agent 3"}, new Dimension(1000,500));
crController.getReportController().addReport("Agent acceleration", report1);

In order to allow users to view the report, the control panel needs to be recreated and it will automatically register that it should create an option for viewing the report:

//-- tell crController to rebuild the control panel because we added report
crController.createDefaultControlPanel();

You will need the following import statements to complete the program:

import net.lenkaspace.creeper.report.CRTimeSeriesReport;
import java.awt.Dimension;

You can now run the simulation and you will see the agents randomly accellerating. Also, notice the new report option in the control panel. Press the OpenReport button to see the accelleration report.

Creeper allows you to specify any number of reports of different types. To learn more, have a look at what is available in the reports package. Good report examples can also be found in project that use Creeper, Controlling Ant-Based Construction or Boid Game-Playing through Randomised Movement.

TIP: Maintaining a large number of report names can be a pain. You should therefore create string constants somewhere within your code and use these string constants to both create and refer to the reports. An example of this can be seen in the Controlling Ant-Based Construction project.