Project 0: Setting Up Space Settlers

Creating an Initial SpaceSettlers Agent

First you need to get spacesettlers up and running on your machine and ensure you can turn in code on the CS machine.  

1. Download and install an Integrated Development Environment (IDE).
   • You MUST use an IDE for these projects! You can pick your favorite IDE.  In the past, I have used eclipse but I have switched to IntelliJ this year.  You are not required to use either of these.  You could also use Visual Studio Code or any other platform, so long as you use an IDE.  You don’t want to do the later projects in just a text editor as there is a lot of code to learn.  Part of your objectives with the project is implementing code within a working system of code, which means you want to learn to use the existing codebase well!
2. Download and install the Space Settlers code.
   • The code is stored in a github repository. As I mentioned above, it is good for your future jobs to know how to use existing code bases and how to work with a repository. Your next step is to download the latest code from the github repository. The advantage of the online repository is that you will have access to bug fixes. For all projects, both finding and fixing bugs will get you extra credit. You can submit your bug reports using github or through the class slack (more in future projects).
   • If you have never used git before, please look up tutorials online. git support is incorporated into most IDEs or you can clone in GitHub Desktop and then open in your favorite IDE.
     • The main commands you will need to know are: clone and pull. You will NOT be checking any changes directly into the code base this semester so you do not need to worry about push or commit.
   • Note: if you fork the repository into your own GitHub account, ensure the fork is private. You can make private repositories with an academic email account for free with GitHub.  If you make a public fork, anyone else in class can see your code. This can be used for academic misconduct and thus we will give you a zero for any non-private forks we can see (see rubric below)
3. You can test your download of the code in either of two ways.
   1. You can go to the directory where you downloaded the code and type:
      • ant spacesettlers-human
      • Note that this method of compilation requires the “ant” program (if you have a mac, you can install ant through homebrew)
   2. You can also run it from your IDE directly!  If you install IntelliJ, it comes with ant.  If you use VS Code, install the ant extension.  If you use eclipse, you can right click on the build.xml file in eclipse and choosing the second ‘run as ant build’ option. Then choose ‘spacesettlers-human‘.  All IDEs should be able to use the ant buildfile to run.
      • Note: if neither method works, you have either not properly downloaded the code or you need ant or java installed properly.
   3. When you run the human target, you are controlling the RED spaceship with your mouseclicks.  This is good for debugging initial setup but not great for coding up your agent.  See below!

Quick API Overview

I have a quick API overview for what you need for this project (I’m not jumping into the details for future projects in this video!).  

All of your source code must reside in your src/4×4 directory and be in your 4×4 package. You may name your files within this package anything that makes sense to you (remember that we are grading on coding style as well). Your configuration file MUST be named spacesettlersinit.xml.

You are limited to 1 ship per team for this project. We will relax this assumption in later projects.

The client class contains the following useful methods.

• getMovementStart() is called each time an agent is about to begin an action and it must return a valid action for the agent to execute
• getMovementEnd() is called after all agents have ended their actions but before the simulator goes to the next timestep. This may be left empty if you have no need for cleaning up after an action
• getPowerups() is called each time step to find out what powerups the agent may want to use (this is separate from movements)
• getTeamPurchases() is also called each time step to find out what the team wants to purchase (if anything)
• initialize() is called when an agent is created (but not when it comes back to life from being killed)
• shutdown() is called at the end of the simulation and can be used to cleanup (e.g. close file handles, etc) for an agent
• getGraphics() is called each step and can be used to draw on the screen (particularly useful for debugging!). See the HumanTeamClient for an example of using graphics inside an agent. getKeyAdapter() and getMouseAdapter() are called at the start of the simulation and be used to add a UI to your agent (useful for debugging but not useful in the ladders).

Creating a client for this project

1. Create a controllable agent (e.g. something that controls an agent) that makes legal moves. It is perfectly acceptable to start by copying any of the example agents that are provided to you! The point of this project is to ensure you can get the mechanics of your player working, not that you have made the world’s smartest player. Note that although the ladder will run once for this project, it will NOT count for extra credit. You can find the sample random agent at:
   • spacesettlers.clients.RandomTeamClient
   • Your agent needs to run in its own package. This package MUST be your 4×4. If you copy the random agent, be sure to change the package header to be:
     • package your4x4;
   • All of your code must run in a single package based on your OU 4×4 id. To compile and run your code with the spacesettlers code create a directory under spacesettlers/src with your 4×4 such as spacesettlers/src/your4x4. Place your java source files in this directory.
2. To make the simulation know about your new agent, you also need an initialization and configuration file. There is a sample init file in the config/heuristicCooperative and config/heuristicCompetitive subdirectories. You should copy random-clientinit.xml and point it to your own agent. Name the file spacesettlersinit.xml. Then you need to change SpaceSettlersConfig.xml to point to your new agent and config file. Make sure you change the ladderName setting to something with your name in it so that I can give you full credit. The ladder name can be funny but it must follow two rules:
   • It must be G-rated and contain nothing offensive or derogatory
   • It must contain your name somehow so that we can properly give you a grade (e.g. Team Winner doesn’t tell me who you are unless your name happens to be named Winner!)
   • Here is a quick video here about editing the XML files
3. Your agent must do something to move around the environment in a manner other than randomly.  Just to get you started on this project, you should try to create an agent that collects at least one star.  To make this first project simpler, you will be searching in a regular spacesettlers environment but all the obstacles will be static (e.g. not moving) and your only other moving items will be the other ships. This is a very simple task and you could start with the RandomTeamClient as your example agent or look at the example Flag collectors and modify your agent to go collect Stars.  There is no example client that collects Stars so you will need to modify a client at least a little bit.  The idea is to get you into the project, but you do NOT need to make it a smart client, just smart enough to go grab a star.  I don’t even care if it runs into other things on the way (hint, this makes it really easy, look at the example clients!).  No points are taken off if you bounce off other asteroids or ships etc!  Your goal is just to make an agent to collect stars.

Turning your project in for grading

Submit your project on the CS server using the submit script as described below. Note this server is NOT a webserver. You must login as described below.  I have a quick demo video also!

1. Note:  You MUST either be on campus or using the campus VPN to connect!  Follow the steps at the OU IT webpages about installing a VPN as necessary.
   • OU VPN for iOS (this also works for Mac if you want to use the built-in VPN, this is what I did)
   • VPN for android
   • VPN for Windows
   • VPN for Mac (if you don’t want to do the built in one, this also works)
2. ssh into 4×4@sooner.net.ou.edu@spacesettlers.cs.nor.ou.edu using the account that was created for you for this class.  
   • To login to the server, either use ssh at a terminal window (mac or linux) or use an ssh client such as putty (windows)
   • The machine is spacesettlers.cs.nor.ou.edu. Your username is your 4×4@sooner.net.ou.edu.
   • Your password is your OU password!  If you change your OU password, it will be reflected here.  It is using the OU authentication servers (that is why your username is so long).
3. Make sure your working directory contains all the files you want to turn in. For example, my directory contained the following files:
   • AmySimpleAgent.java spacesettlersinit.xml
4. You must copy the files from your laptop or desktop to the spacewar machine. To do this, you can use the scp command (mac, linux) or the pscp or winscp program (windows). Make sure you copy the files to a directory that does not allow everyone else to read your files!
5. Submit your file using the following command (be sure your java files come last):

   • /home/spacewar/bin/submit --config_file spacesettlersinit.xml --project project0 --java_files YourJavaFiles.java

   • After the project deadline, the above command will not accept submissions. If you want to turn in your project late, use:

     /home/spacewar/bin/submit --config_file spacesettlersinit.xml --project project0_late --java_files YourJavaFiles.java

Once you turn your code in, you should get a message that looks like this

Success! Your code compiled and has been submitted.

If you get any other message, your code was NOT submitted and you need to fix your error!  If it is a compile error, that is something in your code to fix.  If it is an error about username or something other than compiling, contact us on the #projects channel on slack and we can help.

We will run a sample ladder after 11:59PM on Sep 1. This ladder will not count for extra-credit points as the focus of this part of the assignment is to make sure that your accounts are setup correctly and that the ladder is able to run each of your players. If you do not see your agent in the final ladder that we post on #annoucements, you will want to fix it before Project 1!

Note, your grade for this part of the project will show up on canvas in Project 0 but you will NOT turn your files in there.  You must turn them in as described above!  If you turn them into canvas, we cannot grade them.

One quick addendum:  please turn in your GitHub username on canvas (and ONLY that!) in the text upload box.  This is just to help us make sure you kept the repo private.