How to write a plugin
Posted: 11 Feb 2017, 19:09
Hi,
TheoTown has now a plugin system (since version 227). That means, you can add your own buildings to the game without modifying the apk (don't do the latter one, we really don't like it). You may even share them with others, for example by using this forum or the plugin store.
1. Structure
First of all, plugins are stored in an accessible directoy on your device. The exact location varies depending on the platform that you are using:
2. JSON
JSON-files are used to describe buildings in TheoTown. That said, they are (similar to XML-files) a readable format to store structured information. More about JSON can be found here. We decided to use JSON as it's really simple and easy to read. Such a JSON file may look like
Every JSON file (let's call it sample_dsc.json) in a plugin may contain multiple building descriptions, therefore the file starts with a [ and ends with a ], noting that this is a listing of something (like building objects, in this case). Never forget these brackets as the plugin might not be loaded without!
Speaking of objects, the listing contains a number of objects, each starting with { and ending with }. Multiple objects have to be separated using a comma.
An object consists of multiply "key":"value" pairs that are used to define the properties of the object. Step for step:
Further properties like building time, habitant count etc. are inferred automatically for convenience. So the sample building works immediately (after restarting the game) and can be built manually in sandbox mode.
3. Graphics
The more difficult part when including own buildings is to create the buildings itself. You have to keep in mind that our tiles have a size of 32x16 pixels, so a building of size 2x2 (it has to be a square) needs at least a graphics size of 64x32 pixels (it's important to actually use this width so TheoTown can calculate the pivot point in the left corner of the base, which is used to draw the building). For more details, take a look into theo's step by step guide.
Here an illustration how to measure the coordinates for the smoke of the given sample: The red pixel is the pivot point of our building while the blue pixel is where we want to place our smoke.
In our example we use this graphics with a size of 32x25 pixels, named sample_bmp.png:
Here are some templates for you for the base of different sizes:
,
,
,
Here we have a list of base templates that contains even bigger sizes.
Please use only self-created buildings for your TheoTown plug-ins!
For legal reasons, we are not allowed to provide plug-ins on this website that contain graphics in which you do not have copyrights.
4. Limitations
JSON is just a language for description. Therefore it's not possible to program your own buildings. Functionality is added by TheoTown itself and depends on the set properties. If you have a good idea for new functionality that should be available through plugins, please let us know. However, you can add some sort of functionality in JSON by using FUN. For more fancy behavior you could include a Lua script in your plugin.
Maybe you now want to create hundreds of own buildings and also download tons of them from the internet. However, there is no infinite space for plugins and therefore you should try to not create giant buildings for no reason. Especially when it comes to huge transparent parts you can usually optimize them away.
Speaking of giant buildings, just try to avoid them if possible. If not, keep in mind that the max building size is 8x8 and max building height is 256 pixels.
5. Debugging
We currently have no debug mechanism for you, so you might have to do some testing in order to find the bug if something doesn't work. Most likely there's a syntax issue in the JSON-file, so you might check that first. If there are no syntax errors, maybe you have a typing mistake in the image name.
In case of an issue with a plugin TheoTown shows a plugin error after start up which shows more information about what's wrong. The text is also written to a file error.log in the plugin directory for reference. It should give you a hint of what went wrong. If not, you may post your questions here in the forum.
TheoTown has now a plugin system (since version 227). That means, you can add your own buildings to the game without modifying the apk (don't do the latter one, we really don't like it). You may even share them with others, for example by using this forum or the plugin store.
1. Structure
First of all, plugins are stored in an accessible directoy on your device. The exact location varies depending on the platform that you are using:
- In case of Android that is Android/data/info.flowersoft.theotown.theotown/files From the device itself you may not be able to access that location directly. However, TheoTown should appear as some sort of virtual file storage when using the Android Files app (which can also be called by other apps in order to select files for input or output). Alternatively, you can use the built-in file explorer that can be accessed from the game menu when being in the region view.
- In case of iOS you can access the files via the Files app or, when the device is connected to a Mac, in the storage location for your device in the finder.
- On PC the files are stored in C:/Users/YourUsername/TheoTown (Windows) or ~/TheoTown (MacOS and Linux)
2. JSON
JSON-files are used to describe buildings in TheoTown. That said, they are (similar to XML-files) a readable format to store structured information. More about JSON can be found here. We decided to use JSON as it's really simple and easy to read. Such a JSON file may look like
Code: Select all Reset
[ { "id":"$sample.plugin.unique.id.res00", "type":"residential", "author":"Lobby & theotheoderich", "width":1, "height":1, "frames":[{"bmp":"sample_bmp.png"}], "smoke":[{"id":"$smoke07","x":15,"y":-17}], "level":1 } ]
JSON checker
Speaking of objects, the listing contains a number of objects, each starting with { and ending with }. Multiple objects have to be separated using a comma.
An object consists of multiply "key":"value" pairs that are used to define the properties of the object. Step for step:
- id - Each object has to have a unique id to identify it. So you should add some specific information about the plugin to ensure nobody else ever gonna use this id. Avoid changes to the id afterwards, as it is used to identify buildings in saved cities. Buildings with unknown id cannot be loaded.
- type - States the type of the plugin. Has to be either residential, commercial or industrial. See the advanced topic for more types.
- author - Here you state your name as author of the plugin.
- width - Tile width of the base of the building. Each tile has a pixel size of 32x16.
- height - Has to be the same as width. Therefore, only squared buildings a possible.
- frames - This is the most important part of our definition. The frames (graphics) that are associated to our building. As this property expects an array of frames we have to start with [ and end with ]. In that we can define a frame object using the property bmp which references to an image file in the same directory. Here it's the file sample_bmp.png. The option to provide multiple frames can be used for animations or different building variants (dependent on the optional property animated which can be either true or false).
- smoke - If you want to you can use this property to define a list of smoke spots on the building. Some smoke types like $smoke07 are already defined by TheoTown and may be reused. Have a look at the listing of defined smoke types for more information. Note that the position of the spot is relative to the drawing pivot of the building (the left corner of the base).
- level - Here you can set the level of the building, has to be 1 for $ (poor), 2 for $$ (medium) and 3 for $$$ (rich).
Further properties like building time, habitant count etc. are inferred automatically for convenience. So the sample building works immediately (after restarting the game) and can be built manually in sandbox mode.
3. Graphics
The more difficult part when including own buildings is to create the buildings itself. You have to keep in mind that our tiles have a size of 32x16 pixels, so a building of size 2x2 (it has to be a square) needs at least a graphics size of 64x32 pixels (it's important to actually use this width so TheoTown can calculate the pivot point in the left corner of the base, which is used to draw the building). For more details, take a look into theo's step by step guide.
Here an illustration how to measure the coordinates for the smoke of the given sample: The red pixel is the pivot point of our building while the blue pixel is where we want to place our smoke.
In our example we use this graphics with a size of 32x25 pixels, named sample_bmp.png:
- image.png (3.22 KiB) Viewed 54131 times
- image.png (203 Bytes) Viewed 54131 times
- image.png (422 Bytes) Viewed 54131 times
- image.png (695 Bytes) Viewed 54131 times
- image.png (998 Bytes) Viewed 54131 times
Please use only self-created buildings for your TheoTown plug-ins!
For legal reasons, we are not allowed to provide plug-ins on this website that contain graphics in which you do not have copyrights.
4. Limitations
JSON is just a language for description. Therefore it's not possible to program your own buildings. Functionality is added by TheoTown itself and depends on the set properties. If you have a good idea for new functionality that should be available through plugins, please let us know. However, you can add some sort of functionality in JSON by using FUN. For more fancy behavior you could include a Lua script in your plugin.
Maybe you now want to create hundreds of own buildings and also download tons of them from the internet. However, there is no infinite space for plugins and therefore you should try to not create giant buildings for no reason. Especially when it comes to huge transparent parts you can usually optimize them away.
Speaking of giant buildings, just try to avoid them if possible. If not, keep in mind that the max building size is 8x8 and max building height is 256 pixels.
5. Debugging
We currently have no debug mechanism for you, so you might have to do some testing in order to find the bug if something doesn't work. Most likely there's a syntax issue in the JSON-file, so you might check that first. If there are no syntax errors, maybe you have a typing mistake in the image name.
In case of an issue with a plugin TheoTown shows a plugin error after start up which shows more information about what's wrong. The text is also written to a file error.log in the plugin directory for reference. It should give you a hint of what went wrong. If not, you may post your questions here in the forum.
