Mod Template/Standard

[LNJ]

I created a mod template. (actually for a friend to show him how I do it)

So I came up with the idea, to make a official one. So every mod would be uniformly.
And you can say what I should change. And when the devs are satisfied with it, we could also move it to the minetest-mods organization on GitHub (if thats ok).

Here is the repo: https://github.com/LNJ2/mod_template

[MineYoshi]

Seems to be a nice template, i like the idea of uniformly mods..
Also, would be nice if you add "FAQ" about the mod in the README.txt template, likely: "i have some trouble, i can't dig this block" or "exactly how i get this item called <itemname>"...

[LNJ]

I added Links to GitHub, MT Forum, MT Wiki to the README. (https://git.io/vKvrV)
I added "How to use this mod" heading with a link to the MT Wiki (is that ok? - on the wiki can be a very detailed description on how to use the mod) (https://git.io/vKvrw)

MineYoshi: Is that ok?

[Wuzzy]

It's a lame template. It's just using the style used in most Minetest Game mods, I hate this style since it is so useless most of the time.

First some criticisms about the template design and content:
The license information comes before the actual description. But the description is more important and should come first. It is the main reason why people bother to read readme files in the first place. Also, why making LGPLv2.1 part of the template? That decision seems arbitrary.
The section “How to use this mod:” suggests to add external links which point to the actual manual of the mod. This is a very bad idea and I hate it whenever I open readme files. This defeats the whole purpose of a readme file. If the user is not online at the moment, then the readme file becomes useless. There are many situations where you can be offline, e.g. you are travelling, your router is broken, the ISP screwed up, and so on. The readme should contain the help text, not just pointers to the help text.
But I am OK with links to licenses since this is not as important as the actual description.

Finally, I prefer to use Markdown syntax and call the file “README.md” instead of “README.txt”. First its syntax is well-defined and second Markdown's syntax is already actively being used to pretty-print the readme file on Minetest Bower. That's very useful! Here's an example:
https://minetest-bower.herokuapp.com/mods/pep

Markdown files can also be read without problems in any text editor:
http://repo.or.cz/minetest_pep.git/blob ... /README.md

IMO this approach is better than using ad-hoc syntax where everyone uses a different style, and your template is, frankly, not helping as you have not formally defined the syntax.

[LNJ]

It's a lame template. It's just using the style used in most Minetest Game mods, I hate this style since it is so useless most of the time.

First some criticisms about the template design and content:
The license information comes before the actual description. But the description is more important and should come first. It is the main reason why people bother to read readme files in the first place. Also, why making LGPLv2.1 part of the template? That decision seems arbitrary.
The section “How to use this mod:” suggests to add external links which point to the actual manual of the mod. This is a very bad idea and I hate it whenever I open readme files. This defeats the whole purpose of a readme file. If the user is not online at the moment, then the readme file becomes useless. There are many situations where you can be offline, e.g. you are travelling, your router is broken, the ISP screwed up, and so on. The readme should contain the help text, not just pointers to the help text.
But I am OK with links to licenses since this is not as important as the actual description.

Finally, I prefer to use Markdown syntax and call the file “README.md” instead of “README.txt”. First its syntax is well-defined and second Markdown's syntax is already actively being used to pretty-print the readme file on Minetest Bower. That's very useful! Here's an example:
https://minetest-bower.herokuapp.com/mods/pep

Markdown files can also be read without problems in any text editor:
http://repo.or.cz/minetest_pep.git/blob ... /README.md

IMO this approach is better than using ad-hoc syntax where everyone uses a different style, and your template is, frankly, not helping as you have not formally defined the syntax.

I have to say, I didn't even know that there is something like Minetest Bower. I'm going to remake it with a Markdown README and a bower.json file.

The license of the template can be WTFPL, I just wanted to describe how you should add the license. My mistake.

[Wuzzy]

Adding bower.json might be overkill (I also don't know 100% how Minetest Bower works), I think. But Markdown would be a good idea, even if the mod never shows up on Minetest Bower.
And okay, I almost guessed the license thing was more like an example. But still, people tend to be lazy and forget to change it, so it should be something like “insert license here” or whatever. ;-)

[LNJ]

Adding bower.json might be overkill (I also don't know 100% how Minetest Bower works), I think. But Markdown would be a good idea, even if the mod never shows up on Minetest Bower.
And okay, I almost guessed the license thing was more like an example. But still, people tend to be lazy and forget to change it, so it should be something like “insert license here” or whatever. ;-)

Ok, no bower.json. But I'll spilt the README into LICENSE.txt and README.md.

In the LICENSE.txt there are only information about the license(s) of the textures and the code.

And in the README.md there will be all information on how to use the mod and a small note that it's LGPLv2.1/WTFPL/whatever, without author, year and e-mail address.

[Wuzzy]

I suggest to also add the following dummy files:

- screenshot.png
- description.txt
- settingtypes.txt
- Empty directories: sounds, textures, media, models

Screenshot can be just a dummy image, but of the correct size because it can be easily forgotten.
Description can contain just a dummy description and settingtypes.txt contains maybe some examples or just a referece to builtin/settingtypes.txt of the Minetest installation.

The idea is that the user can always delete files which are not required.

[LNJ]

I suggest to also add the following dummy files:

- screenshot.png
- description.txt
- settingtypes.txt
- Empty directories: sounds, textures, media, models

Screenshot can be just a dummy image, but of the correct size because it can be easily forgotten.
Description can contain just a dummy description and settingtypes.txt contains maybe some examples or just a referece to builtin/settingtypes.txt of the Minetest installation.

The idea is that the user can always delete files which are not required.

But I can't add empty directories in git. There have to be at least one file inside them (as in minetest mods/mods_here.txt).
Or is there a special option in git, that I don't know?

And which size should have the screenshot?

[twoelk]

I had just been working on the http://wiki.minetest.net/Mods page adding a new file structure tree.

I very much agree to add templates for as many meta-data files as are known; even a bower.json file as Wuzzy stated before these can easily be deleted if not needed.
As such I think each file should have a comment as header that states it's purpose and declares wether it is optional or recommended. Analog to this each folder could contain a blah_goes_here.txt that starts with some info of the folder use, wether it is optional and what file types and formats it might contain.

It seems that a 300*200 picture works well for the screenshot.png although sizes double that have been used but most have a ratio of 3 by 2.
It may be of interest that in the default resolution on startup the text of the description.txt file is not wraped but cut of after around 45 characters in a line. Maybe a hint to include line breaks might be usefull or rather to simply keep the description short.

You might want to browse the Repositories at https://github.com/minetest-mods as efforts are made to bring all the mods included to a common standard.

In fact I would suggest to indeed stick to the standards developed there, so that mods using this template may be easily added.

[srifqi]

But I can't add empty directories in git. There have to be at least one file inside them (as in minetest mods/mods_here.txt).
Or is there a special option in git, that I don't know?

You can't, as stated in Git FAQ:

Currently the design of the Git index (staging area) only permits files to be listed, and nobody competent enough to make the change to allow empty directories has cared enough about this situation to remedy it.
Directories are added automatically when adding files inside them. That is, directories never have to be added to the repository, and are not tracked on their own.
You can say "git add <dir>" and it will add the files in there.
If you really need a directory to exist in checkouts you should create a file in it. .gitignore works well for this purpose (there is also a tool MarkEmptyDirs using the .NET framework which allows you to automate this task); you can leave it empty or fill in the names of files you do not expect to show up in the directory.

And which size should have the screenshot?

About 3:2 in aspect ratio, as kaeza said:

From the source, it seems the aspect ratio is 3:2. The *actual* (as in, pixel) dimensions of the image vary depending on screen resolution/window size and is scaled accordingly.

EDIT: Maybe 360x240 would be a good choice (480x320 if you want/need more detail).

Also, from ExcaliburZero's comment on this.

[LNJ]

I nearly had forgotten to post it here, but I updated the mod template.
And I also added a GUIDE.txt that explains everything what you have to do.
See here: https://github.com/LNJ2/mod_template

[LNJ]

And a question:
The mod directory is not empty anymore, so it can be confusing when you split your code up into several files, to see all the lua-files totally mixed up with the README.md, LICENSE.txt, mod.conf, description.txt, screenshot.png and depends.txt.
I'd suggest to add another folder for lua-files. I already saw this in some mods before.