How to write a plugin

Learn here how to create and use plugins.

Moderator: Plugin Moderators

User avatar
Lobby
Developer
Reactions:
Posts: 3143
Joined: Sun Oct 26, 2008 12:34
Plugins: Show
Version: Beta
Phone model: S7 edge

How to write a plugin

Post by Lobby » Sat Feb 11, 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.

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:
Image
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
Here are some templates for you for the base of different sizes:
Image,Image,Image,Image
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.

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

Post by kangkakang » Sun Jul 23, 2017 17:28

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

User avatar
CommanderABab
Inhabitant of a Multiverse
Reactions:
Posts: 6594
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by CommanderABab » Sun Jul 23, 2017 17:38

kangkakang wrote:
Sun Jul 23, 2017 17:28
이것을 수행하기 위해 어떤 것을 설치해야하나요?
<What should I install to do this?>
546546Currently using alpha? 546. 546 What's new? :)
Bushman!
:)

Telegram - t.me/
🆎️🆎️🆎️🆎️Commander🆎️🆎️

User avatar
CommanderABab
Inhabitant of a Multiverse
Reactions:
Posts: 6594
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by CommanderABab » Sun Jul 23, 2017 17:40

Join the beta program on Google Play
546546Currently using alpha? 546. 546 What's new? :)
Bushman!
:)

Telegram - t.me/
🆎️🆎️🆎️🆎️Commander🆎️🆎️

User avatar
CommanderABab
Inhabitant of a Multiverse
Reactions:
Posts: 6594
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by CommanderABab » Sun Jul 23, 2017 17:43

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

Google Play에서 베타 프로그램 참여
Google Playeseo beta peulogeulaem cham-yeo
546546Currently using alpha? 546. 546 What's new? :)
Bushman!
:)

Telegram - t.me/
🆎️🆎️🆎️🆎️Commander🆎️🆎️

User avatar
Lobby
Developer
Reactions:
Posts: 3143
Joined: Sun Oct 26, 2008 12:34
Plugins: Show
Version: Beta
Phone model: S7 edge

Re: How to write a plugin

Post by Lobby » Sun Jul 23, 2017 17:47

Actually, beta isn't needed anymore :)
...Have a nice stay

User avatar
CommanderABab
Inhabitant of a Multiverse
Reactions:
Posts: 6594
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by CommanderABab » Sun Jul 23, 2017 17:58

: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.
546546Currently using alpha? 546. 546 What's new? :)
Bushman!
:)

Telegram - t.me/
🆎️🆎️🆎️🆎️Commander🆎️🆎️

User avatar
danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2724
Joined: Thu May 05, 2016 9:33
Location: in your dreams
Plugins: Show
Version: Beta
Phone model: Xiaomi Redmi Note 5

Re: How to write a plugin

Post by danekbel » 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.
Can you complete it please?
Last edited by danekbel on Sun Jul 23, 2017 21:18, edited 1 time in total.
some text.

User avatar
KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 1787
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Phone model: Moto Z Force Droid

Re: How to write a plugin

Post by KINGTUT10101 » Sun Jul 23, 2017 21:14

You mean complete?

User avatar
danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2724
Joined: Thu May 05, 2016 9:33
Location: in your dreams
Plugins: Show
Version: Beta
Phone model: Xiaomi Redmi Note 5

Re: How to write a plugin

Post by danekbel » Sun Jul 23, 2017 21:16

I mean add new types.
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.

User avatar
KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 1787
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Phone model: Moto Z Force Droid

Re: How to write a plugin

Post by KINGTUT10101 » Sun Jul 23, 2017 21:17

You said "complement"

User avatar
danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2724
Joined: Thu May 05, 2016 9:33
Location: in your dreams
Plugins: Show
Version: Beta
Phone model: Xiaomi Redmi Note 5

Re: How to write a plugin

Post by danekbel » Sun Jul 23, 2017 21:18

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

User avatar
KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 1787
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Phone model: Moto Z Force Droid

Re: How to write a plugin

Post by KINGTUT10101 » Sun Jul 23, 2017 22:26

How well do you know English?

User avatar
CommanderABab
Inhabitant of a Multiverse
Reactions:
Posts: 6594
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by CommanderABab » Sun Jul 23, 2017 23:07

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.
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.
546546Currently using alpha? 546. 546 What's new? :)
Bushman!
:)

Telegram - t.me/
🆎️🆎️🆎️🆎️Commander🆎️🆎️

User avatar
danekbel
Inhabitant of a Galaxy Cluster
Reactions:
Posts: 2724
Joined: Thu May 05, 2016 9:33
Location: in your dreams
Plugins: Show
Version: Beta
Phone model: Xiaomi Redmi Note 5

Re: How to write a plugin

Post by danekbel » Sun Jul 23, 2017 23:56

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

User avatar
Henderion The Mayor
Inhabitant of a Galaxy
Reactions:
Posts: 2074
Joined: Thu Aug 18, 2016 11:04
Location: Pevosi,Freetradezonia (Tanjong Sepat,Selangor,Malaysia)
Plugins: Show
Version: Beta
Phone model: OK!Note X
Contact:

Re: How to write a plugin

Post by Henderion The Mayor » Mon Aug 21, 2017 11:51

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
KING HENDERION
Chairman/Founder of
TTNMF(Theotown Nations Monetary Fund)
FTZGTSE(Freetradezonia Global Trade Stock Exchange)
CEO of
OKPhones Inc.
Musicmain International Co.
As a Leader of
Freetradezonia
We are one and united!

User avatar
Lancaster Kingdom
Inhabitant of a Continent
Reactions:
Posts: 1145
Joined: Wed Sep 20, 2017 21:38
Location: Royal District, Karlayneer, LK
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by Lancaster Kingdom » Thu Sep 28, 2017 0:37

Lobby, how to put radioactive influence in the building?
Constitutional Monarchy / King- Emmet II / Prime Minister - Jason Knust / President of the Houses of Stymest - Justin Floyer / President of Justice- Hemman Sush

God Save The King!

User avatar
KINGTUT10101
1,000,000 inhabitants
Reactions:
Posts: 1787
Joined: Thu Jul 07, 2016 22:50
Location: 'Merica
Plugins: Show
Version: Beta
Phone model: Moto Z Force Droid

Re: How to write a plugin

Post by KINGTUT10101 » Thu Sep 28, 2017 2:40

Try influence radioactive

User avatar
JustAnyone
Feature manager
Reactions:
Posts: 2380
Joined: Sun Jul 23, 2017 12:45
Location: Pickle command center
Plugins: Show
Version: Beta
Phone model: Picklephone S5

Re: How to write a plugin

Post by JustAnyone » Thu Sep 28, 2017 6:23

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

Code: Select all

"influence radioactive":45

User avatar
emyaqin
Villager
Reactions:
Posts: 11
Joined: Sun Apr 09, 2017 1:59
Location: Tangerang, Banten, Indonesia
Plugins: Show
Version: Beta
Phone model: Evercoss A75A*

Re: How to write a plugin

Post by emyaqin » Thu Nov 30, 2017 6:08

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

User avatar
CommanderABab
Inhabitant of a Multiverse
Reactions:
Posts: 6594
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by CommanderABab » Thu Nov 30, 2017 9:05

A 1x1 plugin is 32 pixels wide. Anything that has height > factor × width is probably dense where factor 2 or greater.
546546Currently using alpha? 546. 546 What's new? :)
Bushman!
:)

Telegram - t.me/
🆎️🆎️🆎️🆎️Commander🆎️🆎️

User avatar
Kylie Schreave
Plugin Helper
Reactions:
Posts: 834
Joined: Wed Nov 15, 2017 7:06
Location: Tottoro, Surea and Seravee
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by Kylie Schreave » Tue Dec 12, 2017 10:11

We can write anything on ID ? Like, for exemple, ID : 12345678 ?
" On m'a dit un jour de ne pas jouer avec le Feu car je pourrait me brûler.
Depuis, je joue avec les étoiles pour briller "

☆~ " Mieux vaut être seul que mal accompagné " ~☆

User avatar
Blyat009
Villager
Reactions:
Posts: 22
Joined: Tue Apr 03, 2018 2:29
Location: Great Nippon Empire
Plugins: Show
Phone model: ASH-077
Contact:

Re: How to write a plugin

Post by Blyat009 » Tue Apr 10, 2018 8: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
My name is "Yoshikawa Yukihide" ........ Estimated age is……
19 years old..Occupation is a soldier, class is "seaman 2nd class"..……….The workforce is the destroyer of the FederalRepublic of Titania "Chernoburg"...

User avatar
CommanderABab
Inhabitant of a Multiverse
Reactions:
Posts: 6594
Joined: Tue Jun 07, 2016 21:12
Plugins: Show
Version: Beta

Re: How to write a plugin

Post by CommanderABab » Tue Apr 10, 2018 10:40

Blyat009 wrote:
Tue Apr 10, 2018 8: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. :)
546546Currently using alpha? 546. 546 What's new? :)
Bushman!
:)

Telegram - t.me/
🆎️🆎️🆎️🆎️Commander🆎️🆎️

User avatar
Blyat009
Villager
Reactions:
Posts: 22
Joined: Tue Apr 03, 2018 2:29
Location: Great Nippon Empire
Plugins: Show
Phone model: ASH-077
Contact:

Re: How to write a plugin

Post by Blyat009 » Wed Apr 11, 2018 6:45

Thank you very much, my tongue was torn
My name is "Yoshikawa Yukihide" ........ Estimated age is……
19 years old..Occupation is a soldier, class is "seaman 2nd class"..……….The workforce is the destroyer of the FederalRepublic of Titania "Chernoburg"...

Post Reply Previous topicNext topic

Return to “Tutorials and Documentation”

Who is online

Users browsing this forum: Ahrefs [Bot] and 0 guests