Getting images into the game
This guide will demonstrate how to get your imagery into Cytopia. It'll start with just getting any imagery into your own local copy of the game and then will go into how to upload images to github so that they can be reviewed and added to the master branch. If this all seems like too much, just chuck your images up on the uploads channel in the discord and someone will get around to uploading them at some point (hopefully).
Through out this guide I will refer to the Cytopia_directory. This is the directory that you have the cytopia source code in (you do have the source code, don't you?), though for add stuff to your local game, just having a cytopia install should be enough.
Cytopia retrieves it's imagery from a directory that can be found at Cytopia_directory/resources/images/... in there you will find a buildings directory which has directories for all the different categories of buildings. Put your image in the directory that corresponds to the type of building that it is.
Preferably images should be named using this convention:
type_widthxheight_building_name_author
- Type is one of res, com, ind, farm, flora, bd (there are a couple more if you look through the image directories)
- widthxheight is the width and height of the building in cells eg 1x1
- building_name is the name of the building (whatever you want that's unique) with underscores instead of spaces between words
- author is a two letter identifier that lets people know who made this image. Eg Bangboom becomes bb (chosen arbitrarily)
Some example file names are: bd_1x1_BlankPlatform_kt.png res_1x1_favela1_RF.png ind_3x3_chemical_industrie_FN.png
The images should all be pngs.
Once your image is in the corresponding directory you need to add the tile to Cytopia_directory/resources/data/TileData.json
If you open this file, you'll see that it's big! It contains an entry for all building images that are in the game. The layout is pretty self explanatory, it's called JSON (JavaScript Object Notation) and there's heaps of info on it on the internet but it's basically key-value pairs that are separated by a colon (:) and are inside an object denoted by the braces ({}). What does all this mean? Basically that you want to copy-paste one of the other entries and change the data in the pasted entry to suit your own.
Here's an example:
In this image, the last entry in TileData.json is being highlighted. Notice that everything is between the pair of braces and that the initial comma is being copied to (the commas separate the objects). Then paste the new entry below the closing brace but before the closing square bracket and then change all the data to suit the new building. Like this:
For reference the fields that are required are: Click here for a detailed explanation of every field.
Once you have added an entry to TileData.json, you should start up Cytopia and start a new game. If the new game map loads then everything has gone well. If the game crashes then something is messed up in your new entry. Check that you have the correct filename, that there is a comma between the last entry and the new one and that everything is surrounded by " (except power, price, count, upkeep and water).
Your new building is now in your local game, though the UI currently makes it hard to know what building you've got selected, if you want to find your new one you might just have to try placing random buildings until you find the right one but remember that for the big categories (res and com) there are buttons that run off the end of the screen and your building could be one of them, so you'll never find it. Hopefully this will be fixed soon.
This project is hosted on github so it uses git for source control. Git is a program that manages changes and versions of source code for the main game. The imagery for the game is also under git control so to get your imagery uploaded you have to play nicely with git. This guide will demonstrate how this is done.
Firstly, git is a command-line tool that can be a bit overwhelming to use so this guide will be using a graphical git UI called git-cola. Get it and install it.
Next, open it up and you'll be presented with a screen that looks like:
Notice that I already have a repo under select_repository. You won't have that but if you do already have a clone of the Cytopia repository you can choose to Select manually and select that. If not then we will clone Cytopia source code using git-cola.
You will need to get a cloning url from github so open browse to the main Cytopia github page and click on the green clone or download button. Then copy the URL provided:
Now go back to git-cola and click on the clone button:
Paste the URL into the dialogue:
and press OK.
Now it will download the entire Cytopia source and every change that has ever been made to it (it's not that big but if you live in a country with awful internet it might take a few minutes). Then you'll be presented with a screen like this:
Notice under branches that you have a branch named master. That is your local representation of the master branch (that exists on github.com). It is only local so if you mess with it, it won't actually make changes to the master branch that everyone else is working from. If you right click on it and click pull, that will update it to the latest version from github.
Now if you want to make changes, you have to make your own branch so that your changes won't interrupt anyone elses. To do this, select Branches from the top-menu and then select Create:
You will probably be able to keep reusing this branch so maybe give it a branch name with your name in it so that people know that it's yours:
Then click Create Branch. Now you'll see the name of your branch just above master. Right-click on it and click checkout. Now you are working on your new branch (it'll have a star icon when it's checked out):
Now you can add your image into the source. You will do this the same way as it was done in Step 1 except your Cytopia_directory will be the directory that you cloned the source code into, and you'll put the images in Cytopia_directory/data/resources/images/... and TileData.json will be in Cytopia_directory/data/resources/data/TileDate.json.
Once you have added your images and put entries in TileData.json then it's time to commit your changes and push them back up to github. First, go back to git-cola and stage your changes. Notice in the status field there are now the names of all the files that you added and changed:
Right click on the ones that you changed and added and select Stage Selected:
Now you want to commit these staged changes. Add a relevant commit name and message, like this:
And click the commit button. Next go to actions and select push:
This will bring up a dialogue with a bunch of options. You want the Remote to be origin, the local branch will be the branch you created and the remote branch will be the name of the branch you created (if you've done this before) or just leave it blank if you haven't done this before. Press the push button:
It'll ask you for credentials for your github account (you do have a github account, right?). If you don't have an account, create one and then you'll need to ask Snails to give you push access to the repositories. If you are one of the regular graphics contributors then I am sure he'll have no issue with this.
Now that your new branch has been uploaded you need to go to the Cytopia github page and create a merge request. On the Cytopia github page select branches:
In the list of branches you should see your branch. Click the New Pull Request button (You'll need to be logged in to do this).
Leave an informative message and click Create Pull Request:
Now you need to wait for someone to review your request and to merge it into the main branch. This might take awhile but it will be quicker if you go on the discord and inform people that you have left a pull request and need a review, probably in the discussion channel under graphics artists.