The current release is version 1.2.2.
For more information about the challenge see the Challenge website .
- Download the latest release files
- Build your own bot
- Submit your bot
- Prepare to fight for the title: Ruler of the high seas.
In this project you will find everything you need to build and run a bot on your local machine. This project contains the following:
- Game Engine - The game engine is responsible for running matches between players.
- Sample Bots - Sample bots can be used a starting point for your bot.
- Reference Bots - The reference bot contains some AI logic that will play the game based on predefined rules. You can use this to play against your bot for testing purposes.
- Sample State Files - Can be used as a starting point to get the parsing working for your bot.
This project can be used to get a better understanding of the rules and to help debug your bot.
Improvements and enhancements will be made to the game engine code over time. The game engine will also evolve during the competition after every battle, so be prepared. Any changes made to the game engine or rules will be updated here, so check in here now and then to see the latest changes and updates.
The game engine has been made available to the community for peer review and bug fixes, so if you find any bugs or have any concerns, please e-mail challenge@entelect.co.za, discuss it with us on the Challenge forum, alternatively submit a pull request on Github and we will review it.
The easiest way to start using the game engine is to download the Game Engine zip. You will also need the .NET framework if you don't have it installed already - you can get the offline installer for .NET Framework here.
Once you have installed .NET and downloaded the binary release zip file, extract it and open a new Command Prompt in the Binaries/{version}/Game Engine folder.
We have included the reference bot in the binaries version folder, so at this point you can simply run the Run.bat to see the bots play a match.
Once you have written your own bot you can you can use the command line arguments to specify the bots that should be run. You can see the available command line arguments by running Battleship.exe --help:
-b, --bot (Default: Empty String Array) Relative path to the folder containing the bot player. You can add multiple bots by separating each with a space.
-c, --console (Default: 0) The amount of console players to add to the game.
--clog (Default: False) Enables Console Logging.
--pretty (Default: False) Draws the game map to console for every round instead of showing logs.
-l, --log (Default: ) Relative path where you want the match replay log files to be output (instead of the default Replays/{matchSeed}).
-s, --size (Default: 2) The map size to use for the match. 1 = small (7 x 7), 2 = medium (10 x 10), 3 = large (14 x 14).
--nolimit (Default: false) Disables the time limit for bot execution.
--debug (Default: false) Halts the game engine when a bot writes to the error stream.
--tournamentMode (Default: false) Will run the game engine in tournament mode, this will delete all game files after every bot execution to prevent cheating and will write all the files again at the end of the match.
--help Display this help screen.So for example you can do something like this to run your bot against the bundled reference bot: Battleship.exe --pretty -b "../Reference Bot" "../My Bot That will win".
You might have to change the configuration file depending on your system in order to run the game. The configuration file is in the game engine folder called Battleship.exe.config. You can modify the file to update where the game engine looks for the various runtime executables such as the java runtime to use. All paths have to be absolute (unless the executable is in the system path).
Entelect will provide Sample Bots for C# and Java. Sample bots are basic started projects that can read game files and make random moves. Reference bots that are capable of playing a game from start to finish are also included for contestants wishing to have something more to work from.
For any additional languages we will be relying on the community contributing a sample bot for the language of their choice. If you would like your language to be supported you will have to submit a sample bot based on the rules outlined in the Sample Bot page. Sample bot submissions will close at Midnight on the 26th of May, after this no additional sample bots will be accepted.
Calibration bots will be included into the game engine before the first battle (after sample bot submission have closed) and will be based on the sample bot for each language.
Same as last year, the system will compile your bot, based on the bot meta file that you included.
Sample bot project files can be downloaded here.
The game engine requires that you have bot.json file. This will tell the game engine how to compile and run your bot. The file must contain the following:
{
"Author":"John Doe",
"Email":"john.doe@example.com",
"NickName" :"John",
"BotType": "CSharp",
"ProjectLocation" : "",
"RunFile" : "Reference\\bin\\Debug\\Reference.exe",
"RunArgs" : ""
}The property fields are as follows:
- Author - Your Name
- Email - Your Email Address,
- Nickname - The nickname you want the visualizer to use
- Bot Type - The type of bot (The language you used to code the bot)
- CSharp
- Java
- JavaScript
- CPlusPlus
- Python2
- Python3
- FSharp
- Project Location - The root location of the project file. For instance in C# solutions, that will point to folder containing the solution (.sln) file. This will be used for bot compilation when you submit your bot.
- Run File - This is the main entry point file for your bot that will be executed to play the game and must be relative to the root location of this meta file.
- Java users have to ensure that the main class is specified in the manifest file, also ensure that maven can compile your project as a fat-jar containing all of your libraries you might use.
- RunArgs - (Optional) Any additional arguments you would like to send your bot. This will be the 3rd argument sent to your bot (if provided).
The game engine might set additional runtime parameter in some scenarios, for instance specifying minimum memory allocation for java bots.
The following package managers are supported by the game engine:
- Microsoft Languages - Nuget. (Requires the nuget.exe to be present in the project location path)
- Java - Maven. (Requires that the project contains a pom file in the project location path)
- JavaScript - NPM. (Requires that project contains a package.json file in the project location path)
- Python - Python Package Index. (Requires that the project contains a requirements.txt file in the project location path)
Your bot will receive two arguments on every execution round of the game:
- Your player key registered in the game
- The directory for the current game files
The game will store game files during a match in the following directory format
...Replays/
..........{Match Time Stamp}/
...................{Phase and Round Number}/
........................................ engine.log
........................................ A - map.txt
........................................ B - map.txt
........................................ state.json
........................................ roundinfo.json
........................................ {Player Key}/
................................................... log.txt
................................................... map.txt
................................................... state.json
................................................... place.txt
................................................... command.txt
The engine has two modes, normal mode or debug mode, and tournament mode. During normal mode no files are deleted, during tournament mode after each round, all files that could leak information to the opposing player is deleted as soon as the round ends, the information is stored in memory and dumped into the appropriate files at the end of match. The rules below will be explained using tournament mode.
There are 2 phases to the game, phase 1 being the place ships phase, during this phase each player will have the map.txt and state.json files in their Player Key folder until they placed their ships in the place.txt file, phase 1 will only end if both players have successfully placed all their ships, if a player fails to place their ships for 5 continues rounds they will be killed off and the other player will win by default. After a successful round in phase 1, the game will proceed to phase 2, the great battle, during this phase the player will have the same files as mentioned above to work from, but this time they will have to place their shot command in the command.txt file. At the end of the round the files will be deleted as well to prevent opposing bots from snooping where they shouldn't...
The engine.log file contains information from the engine while processing the round.
The log.txt file in the player file contains player specific logs, such as the console output from player bots. If your bot is misbehaving this should be the first place to go have a look. In this file you can also view additional information such as bot run time and bot processor time.
The round.info folder is mainly for GUI submissions, and reports player stats and the leaderboard.
The map.txt file will use the following characters to represent the game state:
'~': An empty water block
'!': A missed shot
'*': A succesfully landed shot
'@': A shield was hit (This only show while the shield is active, when the shield is no longer active it will disappear)
'B,C,R,S,D': A healthy ship cell
'b,c,r,s,d': A damaged ship cell
'B-b': BattleShip
'C-c': Carrier
'R-r': Cruiser
'S-s': Submarine
'D-d': Destroyer
The shield will also be displayed on the map info
Shield: (Status: <Activated | Deactivated>, Charges: <Amount of Charges Remaining>, Center Point: <X:<x value>, Y:<y value>>)
The `map.txt` will also have sections underneath the map for each player to give more information about each player like the points, shots fired, shots landed and which ships are still remaining.
Duing the competition the game engine will be upgraded after each battle to support new features to make the game more complex and challenging. Please make sure that you follow the releases to make sure you are always working with the latest features and that your bot can handle the latest changes to the game to ensure you stand a winning chance. Each version of the game engine will be backwards compatible with older bots.
These are the simplified rules. More in depth rules are further down.
- A player can only pass through one command during a round.
- During the first phase a player has to place their ships.
- After a successful phase 1, a player can pass through one of the following commands
- Do Nothing - nothing will happen
- Fire Shot- Fires a shot at the given location
- Fire Double Shot - Fires two shots given a center location
- Fire Corner Shot - Fires four shots given a center location
- Fire Cross Shot Diagonal - Fires five shots given a center location
- Fire Cross Shot Horizontal - Fires five shots given a center location
- Fire Seeker Missile - Finds the nearst ship with an eclidian distance of 2 units or less away, given a center location
- After each round energy is added to the player depending on the size of the map.
- Small Map = 2 Energy per round
- Medium Map = 3 Energy per round
- Large Map = 4 Energy per round
- Each ship has two weapons, a single shot weapon and a special weapon, unique to that ship, each weapon requires energy to use, the unique weapon can only be used if the ship is not destroyed and the player has enough energy.
- Single Shot - All ships - Requires 1 energy to use
- Double Shot - Destroyer - Requires 8 rounds worth of energy to use
- Corner Shot - Carrier - Requires 10 rounds worth of energy to use
- Cross Shot Diagonal - BattleShip - Requires 12 rounds worth of energy to use
- Cross Shot Horizontal - Crusier - Requires 14 rounds worth of energy to use
- Seeker Missile - Submarine - Requires 10 rounds worth of energy to use
- A shot will damage a ship if it hits, else it will just hit the water and do nothing.
- A player earns points for each successful shot landed and for completely destroying an enemy's ship.
- A player is victorious if he destroy's all of the enemy's ships first, in the case of a tie the winner will be the player who landed the first shot successfully, if it is still a tie it will be the player who had the least amount of first phase failed commands.
- Each player is given a shield at the start of the game with 0 charges and a protection radius of 0.
- The shield will only be usable at the start of phase 2.
- After 7 rounds of not using the shield The shield will gain an additional charge.
- For every charge the shield protection radius will grow by 1.
- The shield will protect a square of cells, given the protection radius of the shield.
- The shield has a max radius protection size, depending on the size of the map.
- Small map will be a max radius of 1 unit: so a 3 x 3 block will be covered.
- Medium Map will be a max radius of 2 units: so a 5 x 5 block will be covered.
- Large Map will be a max radius of 3 units: so a 7 x 7 block will be covered.
- The shield will prevent any shots from hitting the cell underneath the shield.
- A shielded cell will only say it is shielded if it was hit.
- Only one shield can be activated at a time.
- Shields do not gain charge while they are active.
- Shields lose 1 charge for each round they are active.
- A shield must have at least 1 charge before it can be placed.
- Shields block seeker missiles from finding targets underneath the shield.
- To Place a shield you have to pass through the following command: 8,<x:pos>,<y:pos> where the x and y pos are the center points of the shield.
- When a shield is hit, it will show an '@' symbol where the shot landed on the respective map while the shield is active.
- When the shield expires there will be no history where any shots landed.
The map will be square sized based on the given size rules. Please note that each player has their own map and this is the size of the player's map and not the entire game map.
- 7 x 7 if small is selected.
- 10 x 10 if medium is selected.
- 14 x 14 if large is selected.
Each player will only see where they hit and missed on their opponent's map.
Players can either be console players or bots. Both follow the same game engine rules.
- Players will only be able submit one command per round. The game engine will reject any additional commands sent by the player.
- Phase 1 will be a maximum of 5 rounds long, if a player is unable to place their ships during these 5 turns they will be destroyed and the opposing player will win.
- During the first phase a player can only pass through the PlaceShipCommand, if another Command is sent through or the player fails to place their ships, their FailedFirstPhaseCommands counter will be incremented, if this reaches 5 they will be killed off.
- After the first phase is done, each player can send through one of the following commands.
- Do Nothing - This will skip their turn, after 20 DoNothing Commands the player will be killed off to protect the game engine from faulty bots.
- Fire Shot Command - This will fire a shot at the enemy's map, if the shot is successful and hits an opposing ship, the player will be awarded points, if the shot destroys an enemy ship, they will be awarded additinal points for sinking the ship. (3 x 1 cells) or (1 x 3 cells)
- Fire Double Shot Command - This will fire two shots at the enemy's map given a center point and a direction, the direction will determine whether the shots are horizontal or vertical. The Shots will be one block to the west and east or the north and south of the center point. (3 x 3 cells)
- Fire Corner Shot Command - This will fire four shots at the enemy's map, given a center point the shots will be one block to the north-west, north-east, south-east and south-west of the center point. (3 x 3 cells)
- Fire Cross Shot Diagonal Command - This will fire five shots givn a center point, with four being the same as the corner shot and inclusive of the center point. (3 x 3 cells)
- Fire Cross Shot Horizontal Command - This will fire five shots, same as the CrossShotDiagonal, but in a horizontal and vertical cross. (3 x 3 cells)
- Fire Seeker Missile Command - This will fire a missile at target area, finding the nearest ship cell with an eclidian distance of 2 units or less away from the center point given , if there is no ship the center point given will be the target of the missile.
- Place Shield Command - This will place a square shield on the map given a center point and the size will be determined by the current protection radius of the shield. And will last until the charges of the shield reach 0.
- Bot players will have the following additional rules
- Bot processes will be forcefully terminated after 4 seconds
- Bots will not be allowed to exceed a total execution time of 2 seconds
- Bots processes might be run with elevated processor priority. (For this reason the game has to be run with administrator privileges)
- Calibrations will be done at the start of a game to determine additional processor time. So if the calibration bot takes 200ms to read the files and make a move decision then your bot will be allowed an additional 200ms to complete.
- Malfunctioning bots or bots that exceed their time limit will send back a do nothing command.
- Bot players that post more than 20 do nothing commands in a row will be assumed broken and will automatically be killed.
- Players must ensure that the bot process exits gracefully within the allotted time (Rule 5-B).
- All bot logic processing must be done within the source code submitted for your bot. You may not use network calls such as web services to aid in your bots decision making. No child processes will be allowed and should it be discovered you will be disqualified.
- The nickname used on the
bot metafile is used in themap.txtfile, for this reason you will only be allowed alphanumeric characters as your nickname, and no special characters such asCarriage Return,Line FeedandNew Linewill not be allowed.
- Entelect reserves the right to change/update these rules at any point during the competition.
The following rules describe how the game engine will run and process the game
- The game is split up into 2 phases:
- Phase 1: the placing of the ships phase. During this phase, each player has 5 chances to place their ships on the map. If a player is not successful they will receive an increase to their failed first phase counter, if this reaches 5 they will be killed off.
- Phase 2: firing shots at the opponent's map. During this phase each player takes a shot at the opposing player's map in hope of hitting a ship and destroying all of the enemy's ships first.
- After each round of phase 2, each player will receive energy depending on the size of the map.
- Small Map = 2 Energy per round
- Medium Map = 3 Energy per round
- Large Map = 4 Energy per round
- The game contains the following entities:
- Empty space
- Player Ship
- An empty space can be occupied by a ship.
- A space occupied by a ship that is hit will be marked as hit (The player who landed the shot will have their shots landed counter increased).
- A space not occupied by a ship that is fired at will be marked as missed (The player who missed the shot will have their shots fired counter increased, regardless if it is a hit or a miss).
- The game engine will process rounds in the following order:
- Process Player Commands (Depending on the phase)
- Add Energy to players, given the size of the map
- Kill off Players (A player will be killed if all of his ships are destroyed)
- If all of a player's ships are destroyed they will be eliminated and the opposing player will be the winner.
- If both players are killed at the same time, the following will be used to determine a winner:
- Player who still has ships remaining
- Player with the most points.
- Player who landed a shot first.
- Player who had the least amount of failed place ship commands.
Players wills be awarded points during the game based on the following.
- For each successful shot you will be awarded 10 points.
- For destroying an enemy ship you will be awarded 30 points.
- For killing the enemy player you will be awarded an additional 100 points.
- Shields are deactivated before any commands are processed and will gain charge after the round processing has ended
- Fixed bug where Player A would have an advantage when placing their shield
- Updated reference bot to place shield over destroyer if it still exists
Change Log:
- Fixed bug with points not being awarded when a ship is destroyed.
- Updated Seeker Missile to ignore shielded cells and damaged cells.
- Seeker Missiles require 12 rounds of energy to be used instead of 10.
- Fixed spelling of missile.
- Updated Rules section of readme to include rules for shield.
- Added Shields (please read Shield Rules for more details).
Change Log:
- Changed order of searching for a seeker missile target
- Fixed issue with starting energy not lining up with mapsize
Change Log:
- Added new weapons to each ship.
- Double Shot - Destroyer - Requires 8 rounds worth of energy to use
- Corner Shot - Carrier - Requires 10 rounds worth of energy to use
- Cross Shot Diagonal - BattleShip - Requires 12 rounds worth of energy to use
- Cross Shot Horizontal - Crusier - Requires 14 rounds worth of energy to use
- Seeker Missile - Submarine - Requires 10 rounds worth of energy to use
- Added new commands and command codes.
- FireDoubleShotCommand
- FireCornerShotCommand
- FireCrossShotCommand
- FireSeekerMissileCommand
- Added energy to players at the end of each round, depending on the map size selected.
- Small Map - 2 Energy
- Medium Map - 3 Energy
- Large Map - 4 Energy
- Updated Console Harness to allow the new commands
- Updated C# and Java Reference Bot to make use of the double (Each time it has energy and the destroyer is still available)
- Fixed readme for seeker missile
- Added Tests for all weapon commands
Change Log:
- Added C++ bot support.
Change Log:
- Fixed a bug where a bot could not fire a shot in the same round that it's last ship was destroyed.
Change Log:
- Added Julia sample bot and support.
- Added support for calibration bots.
Change Log:
- Improved support for Golang bots.
- Fixed a bug where the game engine would continue with the match if a bot fails to write a place file.
- Fixed a bug where ships could not be placed on the border of the map in an easternly or nothernly direction.
- Minor updates to ensure the game engine runs correctly on the tournament server.
Change Log:
- Fixed some typo's in the game engine and output files.
- Updated Java bot to use Java 8 features.
- Fixed a bug where the game engine would throw an InvalidOperationException if a player tries to fire a weapon with no remaining ships.
- Changed Opponent Ship Types in the JSON to be string values instead of integer.
- Updated Game Engine to only pause on exit if it is running in a pretty session.
- Fixed a bug where the game engine could throw exceptions when placing ships in some scenarios.
- Fixed a bug where repeatedly hitting the same block with a ship on would continually award points.
- Fixed a bug where the game engine would not output files for different players with the same name correctly.
- Added additional sample bots.
Change Log:
- Initial release