How to write a plugin

Learn here how to create and use plugins.

Moderator: Plugin Moderators

User avatar
Lobby
Developer
Posts: 3713
Joined: 26 Oct 2008, 12:34
Plugins: Showcase Store
Version: Beta

Platform

How to write a plugin

#1

Post by Lobby »

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:
  • 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)
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    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
Check
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 attachment image.png is no longer available
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
image.png (3.22 KiB) Viewed 71784 times
Here are some templates for you for the base of different sizes:
image.png
image.png (203 Bytes) Viewed 71784 times
,
image.png
image.png (422 Bytes) Viewed 71784 times
,
image.png
image.png (695 Bytes) Viewed 71784 times
,
image.png
image.png (998 Bytes) Viewed 71784 times
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.

User avatar
kangkakang
Settler
Posts: 1
Joined: 23 Jul 2017, 08:44

Re: How to write a plugin

#2

Post by kangkakang »

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

User avatar
CommanderABab
AB
Posts: 11185
Joined: 07 Jun 2016, 21:12
Plugins: Showcase Store
Version: Beta

Plugin Creator

Platform

Re: How to write a plugin

#3

Post by CommanderABab »

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

User avatar
CommanderABab
AB
Posts: 11185
Joined: 07 Jun 2016, 21:12
Plugins: Showcase Store
Version: Beta

Plugin Creator

Platform

Re: How to write a plugin

#4

Post by CommanderABab »

Join the beta program on Google Play

User avatar
CommanderABab
AB
Posts: 11185
Joined: 07 Jun 2016, 21:12
Plugins: Showcase Store
Version: Beta

Plugin Creator

Platform

Re: How to write a plugin

#5

Post by CommanderABab »

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

Google Play에서 베타 프로그램 참여
Google Playeseo beta peulogeulaem cham-yeo

User avatar
Lobby
Developer
Posts: 3713
Joined: 26 Oct 2008, 12:34
Plugins: Showcase Store
Version: Beta

Platform

Re: How to write a plugin

#6

Post by Lobby »

Actually, beta isn't needed anymore :)

User avatar
CommanderABab
AB
Posts: 11185
Joined: 07 Jun 2016, 21:12
Plugins: Showcase Store
Version: Beta

Plugin Creator

Platform

Re: How to write a plugin

#7

Post by CommanderABab »

:lol:
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.

User avatar
KINGTUT10101
1,000,000 inhabitants
Posts: 2226
Joined: 07 Jul 2016, 22:50
Location: 'Merica
Plugins: Showcase Store
Version: Beta
Contact:

Plugin Creator

Platform

Re: How to write a plugin

#8

Post by KINGTUT10101 »

You mean complete?

User avatar
KINGTUT10101
1,000,000 inhabitants
Posts: 2226
Joined: 07 Jul 2016, 22:50
Location: 'Merica
Plugins: Showcase Store
Version: Beta
Contact:

Plugin Creator

Platform

Re: How to write a plugin

#9

Post by KINGTUT10101 »

You said "complement"

User avatar
KINGTUT10101
1,000,000 inhabitants
Posts: 2226
Joined: 07 Jul 2016, 22:50
Location: 'Merica
Plugins: Showcase Store
Version: Beta
Contact:

Plugin Creator

Platform

Re: How to write a plugin

#10

Post by KINGTUT10101 »

How well do you know English?

User avatar
CommanderABab
AB
Posts: 11185
Joined: 07 Jun 2016, 21:12
Plugins: Showcase Store
Version: Beta

Plugin Creator

Platform

Re: How to write a plugin

#11

Post by CommanderABab »

former member wrote:
23 Jul 2017, 21:11
Lobby wrote:
23 Jul 2017, 17:47
  • type - States the type of the plugin. Has to be either residential, commercial or industrial.
Can you complete it please?

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

User avatar
Henderion The Mayor
Inhabitant of a Galaxy
Posts: 2110
Joined: 18 Aug 2016, 11:04
Location: Pevosi,Freetradezonia (Tanjong Sepat,Selangor,Malaysia)
Plugins: Showcase Store
Version: Beta
Contact:

Platform

Re: How to write a plugin

#12

Post by Henderion The Mayor »

If You make.json on PC Here its the list of Program can use
Notepad++(My First Programming/Coding Software)https://notepad-plus-plus.org/ and its free

User avatar
KINGTUT10101
1,000,000 inhabitants
Posts: 2226
Joined: 07 Jul 2016, 22:50
Location: 'Merica
Plugins: Showcase Store
Version: Beta
Contact:

Plugin Creator

Platform

Re: How to write a plugin

#13

Post by KINGTUT10101 »

Try influence radioactive

User avatar
JustAnyone
Developer
Posts: 3534
Joined: 23 Jul 2017, 12:45
Location: Easter Island
Plugins: Showcase Store

Platform

Re: How to write a plugin

#14

Post by JustAnyone »

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

Code: Select all

"influence radioactive":45

User avatar
emyaqin
Villager
Posts: 24
Joined: 09 Apr 2017, 01:59
Location: Tangerang
Plugins: Showcase Store
Version: Beta
Contact:

Platform

Re: How to write a plugin

#15

Post by emyaqin »

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

User avatar
CommanderABab
AB
Posts: 11185
Joined: 07 Jun 2016, 21:12
Plugins: Showcase Store
Version: Beta

Plugin Creator

Platform

Re: How to write a plugin

#16

Post by CommanderABab »

A 1x1 plugin is 32 pixels wide. Anything that has height > factor × width is probably dense where factor 2 or greater.

User avatar
Kylie Schreave
Plugin Helper
Posts: 842
Joined: 15 Nov 2017, 07:06
Location: Tottoro, Surea and Seravee
Plugins: Showcase Store
Version: Beta

Platform

Re: How to write a plugin

#17

Post by Kylie Schreave »

We can write anything on ID ? Like, for exemple, ID : 12345678 ?

User avatar
Blyat009
Villager
Posts: 22
Joined: 03 Apr 2018, 02:29
Location: Great Nippon Empire
Plugins: Showcase Store

Platform

Re: How to write a plugin

#18

Post by Blyat009 »

In /storage/emulated 0/TheoTown/plugins/hentaikusodokata/hentaikusodokata json: org json. JSONException: Unterminated object at character 130 of "id" shittypervertworker, type park, "author" Blyat009, "width" 100, "height" 100, frames" bmp hentaikusodokata.png,

Why was this error caused? :calc

User avatar
CommanderABab
AB
Posts: 11185
Joined: 07 Jun 2016, 21:12
Plugins: Showcase Store
Version: Beta

Plugin Creator

Platform

Re: How to write a plugin

#19

Post by CommanderABab »

Blyat009 wrote:
10 Apr 2018, 08:40
In /storage/emulated 0/TheoTown/plugins/hentaikusodokata/hentaikusodokata json: org json. JSONException: Unterminated object at character 130 of "id" shittypervertworker, type park, "author" Blyat009, "width" 100, "height" 100, frames" bmp hentaikusodokata.png,

Why was this error caused? :calc

Code: Select all

"id":"spworker",
"type":"park", 
"author":"putyournamehere", 
"width":100, 
"height":100, 
"frames":[
  {"bmp" :"hentaikusodokata.png"}
 ],
Is the correct form.

Error caused by lack of correct .json. :)

User avatar
Blyat009
Villager
Posts: 22
Joined: 03 Apr 2018, 02:29
Location: Great Nippon Empire
Plugins: Showcase Store

Platform

Re: How to write a plugin

#20

Post by Blyat009 »

Thank you very much, my tongue was torn

Post Reply Previous topicNext topic

Return to “Tutorials and Documentation”