Introduction and asking for help and criticizing modding documentation

[Ughduty]

Hello Everyone

I'm sorry that with my introduction I already have some critique. Please don't take it personal. I am trying to help. 

I'm new to Simutrans modding but an experienced modder. I started modding games some 20 years ago. And I already put my hands on Simutrans some 8 years ago and created a few small graphics like buildings and trees for the pak128.german. I never published them because they where just made for personal use. However, Simutrans is giving me a very hard time this time around. I spend the whole weekend just trying to figure out how to cut and compile one building. Later more about this.

First critique is that the forum ate my first try at this post just because an attachment was bigger than allowed. On the website I landed after the error message I was greeted by a plank "Start new topic"-Page. All content gone! This second try on the post is therefore much shorter. Maybe that is better anyways. 

Second critique is the more important one and is related to the documentation for content creators in the forums and the Wiki. Because I have a problem creating a factory for the game I tried to find information about how to use in this example the tilecutter but all I found was more or less outdated or made my head explode. I am talking about things like the following example from the wiki which is the first sentence on the page that tries to explain what the BackImage is and how to use it:

Code Select Expand

"BackImage[A][B][C][D][E]=Filename without extension.row in Image file.column in Image file" What? 
A simple step by step guide on how to create a somewhat complex tile with tile cutter and how the dat file for it has to be made would help much more than anything I was able to find! I still don't know what a Frontimage is or what it is used for and when. Because I was just not able to find sufficient explanations.
Because a game like Simutrans would not exist without it's creators and still needs them for it's own survival I think that it is critical that this is addressed. At least if you plan for survival beyhond your own interests.

However, if you could help me firgure out how to solve my issues with content creation I would be grateful. I have a factory image from the pak192.comic I repainted. The original is from Leartin. I hope he doesn't mind  . I tried to cut it with tilecutter but when I try to create the pak file with makeobj it always gives me the error message: "ERROR: image_writer_t:  cannot open ./Gelddruckerei.png".  UPDATE: This error has been solved by taking off the bandage I obviously had my eyes covered with and I was able to create the pak file but unfortunately the resulting building ingame looks completely scrambled.

Summer image:
 
Winter image:

What the tilecutter created from it:


Last the dat content:

Code Select Expand

Obj=factory
Name=moneyprint
copyright=Leartin
Location=city
DistributionWeight=30
MapColor=207
#-----
InputGood[0]=paper
InputCapacity[0]=200
InputFactor[0]=100
InputGood[1]=ink
InputCapacity[1]=200
InputFactor[1]=20
OutputGood[0]=notes
OutputCapacity[0]=200
OutputFactor[0]=100
#-----
Productivity=100
Range=50
expand_probability=100
expand_minimum=30
expand_range=20
expand_times=7
#-----
electricity_amount=200
passenger_demand=30
mail_demand=50
electricity_boost=300
passenger_boost=300
mail_boost=500
#-----
dims=3,2,4
needs_ground=1
BackImage[0][0][0][0][0][0]=Gelddruckerei.0.0
BackImage[0][0][1][0][0][0]=Gelddruckerei.0.1
BackImage[0][0][2][0][0][0]=Gelddruckerei.0.2
BackImage[0][1][0][0][0][0]=Gelddruckerei.0.3
BackImage[0][1][1][0][0][0]=Gelddruckerei.0.4
BackImage[0][1][2][0][0][0]=Gelddruckerei.0.5
BackImage[0][0][0][0][0][1]=Gelddruckerei.0.6
BackImage[0][0][1][0][0][1]=Gelddruckerei.0.7
BackImage[0][0][2][0][0][1]=Gelddruckerei.0.8
BackImage[0][1][0][0][0][1]=Gelddruckerei.0.9
BackImage[0][1][1][0][0][1]=Gelddruckerei.1.0
BackImage[0][1][2][0][0][1]=Gelddruckerei.1.1
BackImage[0][0][0][0][0][2]=Gelddruckerei.1.2
BackImage[0][0][1][0][0][2]=Gelddruckerei.1.3
BackImage[0][0][2][0][0][2]=Gelddruckerei.1.4
BackImage[0][1][0][0][0][2]=Gelddruckerei.1.5
BackImage[0][1][1][0][0][2]=Gelddruckerei.1.6
BackImage[0][1][2][0][0][2]=Gelddruckerei.1.7
BackImage[0][0][0][0][0][3]=Gelddruckerei.1.8
BackImage[0][0][1][0][0][3]=Gelddruckerei.1.9
BackImage[0][0][2][0][0][3]=Gelddruckerei.2.0
BackImage[0][1][0][0][0][3]=Gelddruckerei.2.1
BackImage[0][1][1][0][0][3]=Gelddruckerei.2.2
BackImage[0][1][2][0][0][3]=Gelddruckerei.2.3
BackImage[1][0][0][0][0][0]=Gelddruckerei.2.4
BackImage[1][0][1][0][0][0]=Gelddruckerei.2.5
BackImage[1][1][0][0][0][0]=Gelddruckerei.2.6
BackImage[1][1][1][0][0][0]=Gelddruckerei.2.7
BackImage[1][2][0][0][0][0]=Gelddruckerei.2.8
BackImage[1][2][1][0][0][0]=Gelddruckerei.2.9
BackImage[1][0][0][0][0][1]=Gelddruckerei.3.0
BackImage[1][0][1][0][0][1]=Gelddruckerei.3.1
BackImage[1][1][0][0][0][1]=Gelddruckerei.3.2
BackImage[1][1][1][0][0][1]=Gelddruckerei.3.3
BackImage[1][2][0][0][0][1]=Gelddruckerei.3.4
BackImage[1][2][1][0][0][1]=Gelddruckerei.3.5
BackImage[1][0][0][0][0][2]=Gelddruckerei.3.6
BackImage[1][0][1][0][0][2]=Gelddruckerei.3.7
BackImage[1][1][0][0][0][2]=Gelddruckerei.3.8
BackImage[1][1][1][0][0][2]=Gelddruckerei.3.9
BackImage[1][2][0][0][0][2]=Gelddruckerei.4.0
BackImage[1][2][1][0][0][2]=Gelddruckerei.4.1
BackImage[1][0][0][0][0][3]=Gelddruckerei.4.2
BackImage[1][0][1][0][0][3]=Gelddruckerei.4.3
BackImage[1][1][0][0][0][3]=Gelddruckerei.4.4
BackImage[1][1][1][0][0][3]=Gelddruckerei.4.5
BackImage[1][2][0][0][0][3]=Gelddruckerei.4.6
BackImage[1][2][1][0][0][3]=Gelddruckerei.4.7
BackImage[2][0][0][0][0][0]=Gelddruckerei.4.8
BackImage[2][0][1][0][0][0]=Gelddruckerei.4.9
BackImage[2][0][2][0][0][0]=Gelddruckerei.5.0
BackImage[2][1][0][0][0][0]=Gelddruckerei.5.1
BackImage[2][1][1][0][0][0]=Gelddruckerei.5.2
BackImage[2][1][2][0][0][0]=Gelddruckerei.5.3
BackImage[2][0][0][0][0][1]=Gelddruckerei.5.4
BackImage[2][0][1][0][0][1]=Gelddruckerei.5.5
BackImage[2][0][2][0][0][1]=Gelddruckerei.5.6
BackImage[2][1][0][0][0][1]=Gelddruckerei.5.7
BackImage[2][1][1][0][0][1]=Gelddruckerei.5.8
BackImage[2][1][2][0][0][1]=Gelddruckerei.5.9
BackImage[2][0][0][0][0][2]=Gelddruckerei.6.0
BackImage[2][0][1][0][0][2]=Gelddruckerei.6.1
BackImage[2][0][2][0][0][2]=Gelddruckerei.6.2
BackImage[2][1][0][0][0][2]=Gelddruckerei.6.3
BackImage[2][1][1][0][0][2]=Gelddruckerei.6.4
BackImage[2][1][2][0][0][2]=Gelddruckerei.6.5
BackImage[2][0][0][0][0][3]=Gelddruckerei.6.6
BackImage[2][0][1][0][0][3]=Gelddruckerei.6.7
BackImage[2][0][2][0][0][3]=Gelddruckerei.6.8
BackImage[2][1][0][0][0][3]=Gelddruckerei.6.9
BackImage[2][1][1][0][0][3]=Gelddruckerei.7.0
BackImage[2][1][2][0][0][3]=Gelddruckerei.7.1
BackImage[3][0][0][0][0][0]=Gelddruckerei.7.2
BackImage[3][0][1][0][0][0]=Gelddruckerei.7.3
BackImage[3][1][0][0][0][0]=Gelddruckerei.7.4
BackImage[3][1][1][0][0][0]=Gelddruckerei.7.5
BackImage[3][2][0][0][0][0]=Gelddruckerei.7.6
BackImage[3][2][1][0][0][0]=Gelddruckerei.7.7
BackImage[3][0][0][0][0][1]=Gelddruckerei.7.8
BackImage[3][0][1][0][0][1]=Gelddruckerei.7.9
BackImage[3][1][0][0][0][1]=Gelddruckerei.8.0
BackImage[3][1][1][0][0][1]=Gelddruckerei.8.1
BackImage[3][2][0][0][0][1]=Gelddruckerei.8.2
BackImage[3][2][1][0][0][1]=Gelddruckerei.8.3
BackImage[3][0][0][0][0][2]=Gelddruckerei.8.4
BackImage[3][0][1][0][0][2]=Gelddruckerei.8.5
BackImage[3][1][0][0][0][2]=Gelddruckerei.8.6
BackImage[3][1][1][0][0][2]=Gelddruckerei.8.7
BackImage[3][2][0][0][0][2]=Gelddruckerei.8.8
BackImage[3][2][1][0][0][2]=Gelddruckerei.8.9
BackImage[3][0][0][0][0][3]=Gelddruckerei.9.0
BackImage[3][0][1][0][0][3]=Gelddruckerei.9.1
BackImage[3][1][0][0][0][3]=Gelddruckerei.9.2
BackImage[3][1][1][0][0][3]=Gelddruckerei.9.3
BackImage[3][2][0][0][0][3]=Gelddruckerei.9.4
BackImage[3][2][1][0][0][3]=Gelddruckerei.9.5

I tried several different settings in tilecutter but the resulting error was always the same.

Have fun!

[Vladki]

I have already reported the same problem with tilecutter here https://forum.simutrans.com/index.php/topic,20149.msg192484.html#msg192484
But got no answer ;-(

Regarding Front and BackImage. Those are most commonly used for stations or wayobjects (like overhead electrification).  BackImage is drawn first, then any vehicles, and then the FrontImage.
For houses or factories this does not make any difference, but can be used for animation. Put everything static as BackImage, and just the animated part as Frontimage. A nice example is the benevolent dictators fried birds fast food (aka SFC) in pak128.  https://sourceforge.net/p/simutrans/code/HEAD/tree/pak128/factories/simutrans_fried_chicken.dat?force=True

Is that helpful?

[Ughduty]

@Vladki Thank you very much this little piece of information about the Front and BackImage helped me a lot in understanding what the FrontImage is good for. 

And I solved the problem with the PAK creation and have the building now ingame but it looks completely scrambled.

[Vladki]

Yeah there is apparently a bug in tilecutter, that it "cuts" somehow inverted.  On the image you shared, the white areas should be the building, and vice-versa.

[Leartin]

I have a factory image from the pak192.comic I repainted. The original is from Leartin. I hope he doesn't mind  .

Not as long as you honor the license in case you publish it.

Code Select Expand

BackImage[A][B][C][D][E]=Filename without extension.row in Image file.column in Image file
What? 

It's really not the best rendition, confused me a bit as well. Maybe a bit clearer if everything that needs to be substituted is in brackets.
"BackImage[<A>][<B>][<C>][<D>][<E>][<F>]=<path/name>.<r>.<c>,<x>,<y>"
Substitute the following:
<A> : The rotation of the building
<B> : "Row" of the building tiles (considering top-right edge to be the top)
<C> : "Column" of the building tiles (considering top-right edge to be the top)
<D> : Height level (Usually only used on first row/column)
<E> : Animation step
<F> : Season (buildings can have 1 (always summer), 2 (summer, snowy), or 5 (summer, fall, winter, spring, snowy) seasons)
<path/name> : the image file and it's path relative to the .dat-file, but without file extension (.png) - eg. if the image is in a subfolder "images", and called "my_image.png", you'd write "./images/my_image". If makeobj can't find the image, more often than not it's the path that's wrong, at least in my experience.
<r> : Row the specific graphic is in the image file (start counting at 0)
<c> : Column the specific graphic is in the image file (start counting at 0)
<x> : Offset on the x axis the graphic is displayed at in the game (can be negative)
<y> : Offset on the y axis the graphic is displayed at in the game (can be negative)

There are a lot of parameters, and it gets even more complicated with shorthand dats (instead of writing one line for each image, it can be compressed into one line, as you probably saw in my money printer).
On the one hand, it would be easier to learn by ommitting most of them, reducing it to "BackImage[<A>][<B>][<C>]=<path/name>.<r>.<c>" - but on the other hand, that would cause even more confusion if someone looked at existing datfiles and wouldn't have a reference for what all of it is.

As Vladki mentioned, FrontImage is intended for objects that share a tile with vehicles to tell the game what's in front of the vehicle. Think of Depot roofs. For regular buildings, next to animations, it can also be used with an offset to have parts of a building hang into the next tile (eg. a wide treetop), or to get more out of lightcolors (the lightbulb you removed is an example of that - in the backimage, it's just the color that glows at night, and the Frontimage adds some semitransparent details to it). Not exactly a topic you need to know much for starting out, and it wasn't really intended for FrontImage to be used like that in the first place.

Because a game like Simutrans would not exist without it's creators and still needs them for it's own survival I think that it is critical that this is addressed. At least if you plan for survival beyhond your own interests.

If you adress it, you'll quickly find yourself in a blame game of where to document, how, and who should do it. The only agreement easily reached is that yes, indeed, there should be more documentation (and more translation). At this point, personally, I'd say just ask whatever you want to know and can't find easily using words that the next person would probably use to search for the same question.


Oh yeah... I can't access my regular PC at the moment, but I should still have Photoshop files for that building. With a bit of luck, changing colors could be as simple as applying an effect to a layer/group that contains the element. With less luck, at least the shadows are on a seperate layer, such that colors can be adjusted underneath it.

[Roboron]

First critique is that the forum ate my first try at this post just because an attachment was bigger than allowed.

Always copy your text before hitting any button. Tip valid also outside Simutrans forums

Second critique is the more important one and is related to the documentation for content creators in the forums and the Wiki

Your critique is valid, and I agree with you that the documentation can -and should- be improved. However, note that Simutrans is a project run by volunteers, in their spare time, so if documentation is lacking is because no one have the time (or the will) to do so. Now that you have joined you can help by improving the wiki with the things you are learning about Simutrans, so others don't suffer the same as you. Someone needs to be the first.

[Vladki]

Always copy your text before hitting any button. Tip valid also outside Simutrans forums

I recommend firefox plugin "Textarea Cache" - saved me a lot of typing.

[prissi]

Also it would be great in Leartin post could replace the wiki topic in question ...

[Andarix]

Also it would be great in Leartin post could replace the wiki topic in question ...

Do you mean this page?

https://simutrans-germany.com/wiki/wiki/en_BackImage
https://simutrans-germany.com/wiki/wiki/en_GraphicsCutting
https://simutrans-germany.com/wiki/wiki/en_doPak

offset is missing
The pages just need to be updated a little.


TileCutter Doku
https://github.com/An-dz/tilecutter/wiki

....
Second critique is the more important one and is related to the documentation for content creators in the forums and the Wiki. Because I have a problem creating a factory for the game I tried to find information about how to use in this example the tilecutter but all I found was more or less outdated or made my head explode. I am talking about things like the following example from the wiki which is the first sentence on the page that tries to explain what the BackImage is and how to use it:
...

Documentation has been neglected at Simutrans for ages. For many who have the knowledge there is simply no reason to document it for others. On the contrary, it is probably too much work for them and costs valuable time that they do not want to spend.

see https://forum.simutrans.com/index.php/topic,15643.0.html

[Leartin]

Also it would be great in Leartin post could replace the wiki topic in question ...

Replacement isn't possible, the wiki topic is longer so information would get lost. At best, one could apply the bracket treatment and add the slightly better explanation for the image path, and then update all the outdated information (alpha channel allowed, 5 seasons, include shorthand syntax or explain that elsewhere and just link to it rather than claiming 16 images require 16 lines, change 0=North to 0=south-facing, given that's now named as such in the game, and is pre-0.99 information still relevant?)

But I think the main complaint was that the wikipage is a technical list of possible parameters, rather than a tutorial on how to apply them. You can't learn programming from an alphabetical list of C++ commands, but at the same time, you don't want a preamble explaining what C++ is for such a list. I think there are several tutorials on how to make graphics, what we could use is a tutorial "You got a graphic - now what?" in the same style, explaining the process rather than documenting features. I'll see if I can find time for that.

[Flemmbrav]

Just upload on the pak192.comic github and see if it builds! <- is a proven concept of the whole team.

On a more serious note, where should we post ressources like that now that the wiki is gone? Edit: nevermind it's still here, just that I remembered Frank talking about taking it down.
I would not mind making a small tutorial for vehicles at least, but I'm not sure where to publish it best.
Worst case it'll end up in our git, but that feels a bit like a waste to me.

[Andarix]

..., include shorthand syntax or explain that elsewhere and just link to it rather than claiming 16 images require 16 lines, ...

Your reasoning is a bit confusing.

The 16 parameters are listed with their meaning. Even with their shorthand syntax, these 16 parameters are necessary.

Incidentally, I find the abbreviation you mentioned not so easily accessible. 16 individual lines are in any case easier to understand than a short form that is nowhere really explained. Whereby in the depths of the forums you will find something somewhere, just how long will you have to search for it?

[Leartin]

The object in the image has 16 tiles therefore it would require 16 lines of BackImage[A][ B][C][D][E][F]=... for the summer view and another 16 for the winter view.

I'm talking about this claim that 16 images require 16 lines, which is factually wrong as it can be compacted to one shorthand line. Unless you want to challenge that a string beginning after a linebreak, ending before a linebreak and including no linebreaks is one line rather than 16.

It already uses conditional (would), just add 'but those lines can be compressed using shorthand notation.' That's it. If there is no wiki page explaining shorthand, I guess anyone intrigued has to search in the forum for it, but that's better than acting as if it doesn't exist. Links to pages that don't exist yet are common for wikis, and shorthand should be documented just as much as everything else eventually anyway, shouldn't it?

But I won't fight over it. It's YOUR wiki, that was established well enough. YOU decide. I won't participate.

[Matthew]

I would not mind making a small tutorial for vehicles at least, but I'm not sure where to publish it best.
Worst case it'll end up in our git, but that feels a bit like a waste to me.

It's possible to associate a Github wiki with a repository. For example, here's one I made for my notes about Simutrans. So you could very quickly make a pak192.comic wiki.

I am not saying that it is the best solution for your situation. There are definitely advantages to having all Simutrans knowledge in one place (the TikiWiki). However, pak192.comic already has a Github repo, so there is also a logic to having all the pakset's information in one place. And I worry the TikiWiki has a rather low bus factor. We all hope Frank has a long and healthy life, but so much important code is on GitHub that I think it will around for decades. And since GitHub wikis are just git repositories of text files, it's a lot easier to backup/clone in case something bad does happen. But I would have to concede that TikiWiki has been around for much longer and that some people will be understandably wary of depending on Microsoft's largesse.

[Roboron]

But I would have to concede that TikiWiki has been around for much longer and that some people will be understandably wary of depending on Microsoft's largesse.

I have to speak in favor of having our own solution because of this. I remember some months ago I had to send simutrans (the executable) via e-mail to a user in Cuba who was unable to access neither SourceForge nor GItHub because they were blocked by the US government. The same is happening to documentation only available on github.

If not being in full control over our documentation means that others get to decide who can or not access it, that sounds like a terrible idea to me.

[Isaac Eiland-Hall]

If there's a convenient way to set it up and mirror, say, a zip file via ftp/sftp, the server can absolutely host a mirror of stuff - I meanf or Simutrans. I don't want to dip my toes in the arguments over the wiki, of course.

[Ughduty]

Thank you so far for all your replies and the the advice. 

Simutrans Documentation
When it comes to documentation I understand all the difficulties that come with it. As an IT administrator and programmer with 30 years under his belt I had the chance to deal with documentation more often than one would hope for in a lifetime. If I learned one thing so it is that it helps to prioritize and if the ressources are scarse focus on the most important ones. I'd say that in the case of Simutrans I guess that there are 3 very important processes that should at least be documented well. The first one is the download and installation process, second the process of creating trains and cars and last but not least the process of creating buildings and other scenario stuff. First thing that comes to my mind and maybe the simplest thing too would be to document these 3 each in its own pinned thread in the forum. Additionally create a Q&A thread for each accordingly. This way everyone that has access to the forum can easily participate and the most important information is at a place in the internet where you have the most control over.

Simutrans Graphics/dat Development
When it comes to dat-shorthand I'm tempted to use it because I always like to write code as short as possible. At the same time as a newcomer to Simutrans development I see the risk that this would be more prone to errors and it is much more difficult to read for everyone else new to this and who is looking into the files to learn about how to create Simutrans graphic ressources like I did. When I first looked at a dat file and saw dat-shorthand code and couldn't find valuable documentation easily for it I was somewhat turned off. And I am at least a "somewhat experienced" programmer, guess how one might feel who doesn't have this kind of experience. Therefore I think it might be a good idea to rework dat shorthand in a way that it becomes more easily created and more easily read and last but not least better document it. If this is for whatever reason not that easy to do and also as something for in between how about creating a small tool that automatically creates the necessary dat shorthand code for a graphics file? Wouldn't it be as easy as asking the user to input a few parameters about his graphics and then creating the code from this?

[Andarix]

... If this is for whatever reason not that easy to do and also as something for in between how about creating a small tool that automatically creates the necessary dat shorthand code for a graphics file? Wouldn't it be as easy as asking the user to input a few parameters about his graphics and then creating the code from this?

There is such a tool for simple objects.

online-dat.simutrans-germany.com

[Ughduty]

online-dat.simutrans-germany.com

It is not working for multi tile factory buildings as I see it. At least I couldn't get it to work. I wasn't able to select more then 1x1 dims.
FYI: The website has a ceritificate error.

[Andarix]

...
FYI: The website has a ceritificate error.

direct link

[prissi]

Titlecuttet produces dat files, but not shorthand. Actually, shorthand notation introduces another layer of possible errors (especially for graphically inclined person, who rarely are programmers) and are therefore only used in pak192, as far as I know.

And for most single tile buildings or trains etc. shorthand is overkill. I think the tutorial thread in question illustrates when shorthand is useful, liek for animations.

[Leartin]

Actually, shorthand notation introduces another layer of possible errors (especially for graphically inclined person, who rarely are programmers) and are therefore only used in pak192, as far as I know.

I think it's more a lack of documentation of the feature as a whole (which hopefully got a tiny bit better) and the fact that tilecutter output isn't compatible (so only people who cut manually could use it) as well as the amount of images used for objects (I think in p64, the largest image definition goes to the vulcano as a 4x4 with no seasons, no rotations but 6 animation frames, sums up to 22. A regular citybuilding in p192c can have 20-80. Go figure.)

Shorthand notation was introduced in response to a request regarding "image templates", the original request asked for a way to reuse a block of image definition lines, just with a different filename.
Perhaps I have to underline in my tutorial that you don't really need to be able to read or write shorthand notation. Rather, the graphically inclined person would take an existing object as a template, arrange their own sprite sheets in the same way, and thus can reuse the same shorthand lines by replacing the path/filename of the image. That's what people often do anyway, except without shorthand, they copy a block of many more lines, and if they are... too much graphically inclined, they might not even use search&replace to get their own filename in. And they wouldn't analyze and understand the longform either.

[Vladki]

I think, the reason why only pak192 uses shorthands is that the authors (maintainers) are using the capabilities of simutrans graphics to their maximum - as shown in the tutorial:
- 4 or even 8 rotations
- 4 seasons + snow
I have not seen any other pakset to have more seasons than snow/non-snow, for anything else than agricultural fields and trees
Keep up the good work guys.

[Andarix]

I think, the reason why only pak192 uses shorthands is that the authors (maintainers) are using the capabilities of simutrans graphics to their maximum - as shown in the tutorial:
....

The shorthand was initiated by Leartin.

That's why he uses them extensively.