## How to write a plugin

Learn here how to create and use plugins.

Moderator: Plugin Moderators

Lobby
Developer
Reactions:
Posts: 3488
Joined: Sun Oct 26, 2008 12:34
Plugins: Show
Version: Beta

### How to write a plugin

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.

1. Structure
First of all, plugins are stored in the directoy TheoTown/plugins on your device. In order to work you have to grant TheoTown access to external memory. If that's the case, the directory exists and everything should be fine.

Each plugin has to be placed in an own directory. Let's say it's sample for our plugin example. On startup, TheoTown searches in each of these for *.json-files to load. Graphics for such a file have to lay in the same directory.

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

[
{
"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
}
]
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:
• 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).
Each property has to be separated by a comma. String values (like property names or string values) have to be "quoted". In this sample, only the property smoke is optional.

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.

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.

Maybe you now want to create hundreds of own buildings and also download tons of them from the internet. But also you might have heard that we're using a single big texture to store all graphic information for the game and have problems when no more space is left. And actually, also plugins have to be placed within the big texture. That means, there's no infinite space for plugins and therefore you should try to not create giant buildings for no reason. For plugins, we limited the maximum graphics space to 1024x2048 pixels. So all plugin graphics together have to fit within this window, otherwise parts will get lost.

Is 1024x2048 pixels (actually 2048x2048 for most users) enough? It depends. Let's assume only plugins for small buildings like in the example are created, each consuming a pixel size of 32x32. Then we could fit exactly 2048 buildings into the window. I would say that should be enough for a long time.

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.

kangkakang
Settler
Reactions:
Posts: 1
Joined: Sun Jul 23, 2017 8:44

### Re: How to write a plugin

이것을 수행하기 위해 어떤 것을 설치해야하나요?

CommanderABab
AB
Reactions:
Posts: 8545
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

### Re: How to write a plugin

kangkakang wrote:
Sun Jul 23, 2017 17:28
이것을 수행하기 위해 어떤 것을 설치해야하나요?
<What should I install to do this?>
888!🆎️

CommanderABab
AB
Reactions:
Posts: 8545
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

### Re: How to write a plugin

Join the beta program on Google Play
888!🆎️

CommanderABab
AB
Reactions:
Posts: 8545
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

### Re: How to write a plugin

CommanderABab wrote:
Sun Jul 23, 2017 17:40
Join the beta program on Google Play
Speak English if you can.

888!🆎️

Lobby
Developer
Reactions:
Posts: 3488
Joined: Sun Oct 26, 2008 12:34
Plugins: Show
Version: Beta

### Re: How to write a plugin

Actually, beta isn't needed anymore
=^._.^= ∫

CommanderABab
AB
Reactions:
Posts: 8545
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

### Re: How to write a plugin

Well then, find plugins that you like, download them, unzip them and copy them to the Theotown/plugins folder.

If you are making your own, Pixly and Novix are the two most used pixel apps here.
Quickedit is a great editor for writing the .json files.
888!🆎️

danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2788
Joined: Thu May 05, 2016 9:33
Plugins: Show
Version: Beta

### Re: How to write a plugin

Lobby wrote:
Sun Jul 23, 2017 17:47
• type - States the type of the plugin. Has to be either residential, commercial or industrial.
Last edited by danekbel on Sun Jul 23, 2017 21:18, edited 1 time in total.
some text.

KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 2013
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Contact:

### Re: How to write a plugin

You mean complete?

danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2788
Joined: Thu May 05, 2016 9:33
Plugins: Show
Version: Beta

### Re: How to write a plugin

I looked at the dictionary and it seems I needed to say "complete" instead of "complement"
Last edited by danekbel on Sun Jul 23, 2017 21:17, edited 1 time in total.
some text.

KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 2013
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Contact:

### Re: How to write a plugin

You said "complement"

danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2788
Joined: Thu May 05, 2016 9:33
Plugins: Show
Version: Beta

### Re: How to write a plugin

I edited that
It seems that Google Translate doesn't want to work well
some text.

KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 2013
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Contact:

### Re: How to write a plugin

How well do you know English?

CommanderABab
AB
Reactions:
Posts: 8545
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

### Re: How to write a plugin

danekbel wrote:
Sun Jul 23, 2017 21:11
Lobby wrote:
Sun Jul 23, 2017 17:47
• type - States the type of the plugin. Has to be either residential, commercial or industrial.

I believe that there is another thread where we named just about every type possible. Harbor pier might be good keywords to find it.
888!🆎️

danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2788
Joined: Thu May 05, 2016 9:33
Plugins: Show
Version: Beta

### Re: How to write a plugin

KINGTUT10101 wrote:
Sun Jul 23, 2017 22:26
How well do you know English?
В2-C1 level
some text.

Henderion The Mayor
Inhabitant of a Galaxy
Reactions:
Posts: 2109
Joined: Thu Aug 18, 2016 11:04
Plugins: Show
Version: Beta
Contact:

### Re: How to write a plugin

If You make.json on PC Here its the list of Program can use
KING HENDERION
Chairman/Founder of
TTNMF(Theotown Nations Monetary Fund)
CEO of
OKPhones Inc.
Musicmain International Co.
We are one and united!

Faayr
Former Lancaster Kingdom
Reactions:
Posts: 1469
Joined: Wed Sep 20, 2017 21:38
Location: Arelosov Palace, Ludonesk, Surrev
Plugins: Show

### Re: How to write a plugin

Lobby, how to put radioactive influence in the building?
Czarist Federation of Surrev

Glory to Fatherland! Glory to Czar!
Czar- Faayr IV
Prime Minister- Kenya Macarov

KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 2013
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Contact:

### Re: How to write a plugin

Online
JustAnyone
enjenir
Reactions:
Posts: 2874
Joined: Sun Jul 23, 2017 12:45
Location: Easter Island
Plugins: Show

### Re: How to write a plugin

Lancaster Kingdom wrote:
Thu Sep 28, 2017 0:37
Lobby, how to put radioactive influence in the building?

Code: Select all

"influence radioactive":45

emyaqin
Villager
Reactions:
Posts: 15
Joined: Sun Apr 09, 2017 1:59
Location: Tangerang, Banten, Indonesia
Plugins: Show
Version: Beta
Contact:

### Re: How to write a plugin

excuse me, how do i put the density of building in my plugin?