Custom Themes for Halite III


We’re delighted to offer theme support this year.

Halite III launched with themes to style the game replay visualizer, including color blind themes:

For Halloween, we’ve added a festive new look with a theme:

We have written up this guide to help you create and share your new visual spin on Halite III.

To create a new theme, you’ll need to write some code, add your artwork, and generate a spritesheet of your art.

Your new theme should have original artwork. Your art will be open sourced under the MIT license that applies to everything in the Halite III repo. Please do not submit art that you did not create.

Define your theme with JavaScript
To get started, fork our repo, and take a look at the theme definition of the default Turtles theme in libhaliteviz/src/theme.js:

“Turtles”: {
tintFactory: false,
tintShip: false,
rotateShip: true,
scaleMapSprite: true,
bloom: true,
scale: {
ship: 1,
base: 1,
dropoff: 1,
playerColors: [0x1BB15A, 0xF54356, 0xFABB2C, 0xFFA2E2],
colorTheme: “TheSea”,

  • tintFactory and tintShip are set to false if your sprite images have colors that you don’t want to override. If you do want to use a tint, set this flag to true.
  • rotateShip enables or disables rotation. When true, your ship sprites will rotate in the direction they are moving.
  • scaleMapSprite enables scaling the map cell sprites based on the amount of halite - i.e. larger light blue squares on the Turtles theme map have more halite than little bitty squares.
  • bloom adds a soft glow to map cells with halite.
  • scale sets the scale for the ship, base, and dropoff sprites. Setting the scale to 1 means that they will appear at the scale they are in your sprite artwork.
  • playerColors specifies the colors of each player. These colors are used as the font color for the player name, and as a tint color if you enabled that option above.
  • colorTheme specifies a color palette for rendering the map. Add these in a separate file, colors.js. At the bottom of colors.js are the THEME definitions, which are a background color (for Turtles, a dark blue), and a color scale. The existing scales have the parameters for the palette generation included as comments; looking at those should help you use this tool to create your own custom color scales for the halite squares on your map.

Add a new entry to libhaliteviz/src/theme.js following the format of the Turtles theme to define your own theme.

Create your spritesheet
Next, you’ll pack your sprites into a spritesheet and generate a JSON atlas. You can see we’ve used spritesheets with .json atlases; we’d prefer you do the same to keep our website load times fast. There are two methods to do this:

  • Use the command line: If you’ve cloned the repo and built the website, you can use the spritesheet-js library to pack your sprites:

    1. Add your individual sprite artwork to libhaliteviz/assets/raw/{your theme}.
    2. Install ImageMagick locally
    3. Navigate to the libhaliteviz directory
    4. Run yarn spritesheet-js -f pixi.js -n {your theme} -p assets assets/raw/{yourtheme}/*.png
    5. Two new files should now be in libhaliteviz/assets/: {your theme}.json and {your theme}.png
  • Use a GUI: If you would prefer to use a GUI, try this tool. As above, place the sprite sheet and the .json files in libhaliteviz/assets/.

Load your sprites
Next, you’ll create the data structure to hold your sprites. Create a new else if branch in the libhaliteviz/src/assets.js file and load up your images by pushing the files into the BASE_SPRITES and TURTLE_SPRITES tables as demonstrated by the other themes. You can choose to make your sprites show when they are full/half-full/empty, as the original Turtles theme does; otherwise, load in the same sprite three times.

Test and submit a PR
It’s time to test it out!

If you haven’t already, build the website locally, and test out your new theme. You should make sure that your art looks good at each map size, and that the colors you have chosen for the Player Colors in theme.js are visible against both the dark blue website background and the white stats panels. If everything seems to be working, go ahead and send us a pull request that includes:

Theme PR Checklist

  • Code additions
  • Packed spritesheet
  • JSON atlas for your spritesheet

We can’t wait to see your take on Halite III!