Modding Tutorial Book (new: Code architecture, unit testing)

[rubenwardy]

This online book will (eventually be able to) teach you how to create mods in easy chapters. The chapters will explain a concept, give examples, and set tasks for you to complete.

This documentation was created by the Minetest community in order to help new modders gain a foothold.

Work in progress. I'd like suggestions for contents. What chapters would you like to see?

Read it online - Download

Contribute on GitHub, or by sending me documents for new chapters.
(I'll format them and add them, the content is the hardest thing, not the formatting.)

Done

• Folder structure
• Lua Scripts
• Nodes, Items and Crafting
• Creating textures
• Node Drawtypes
• Node Metadata
• Active Block Modifiers
• Chat and Commands
• Player Physics
• Formspecs
• HUD
• ItemStacks
• Inventories
• Releasing a Mod
• Read More

Todo
(please feel free to work on any of these, or any other chapter you want to do)

• Entities
• Particles
• Sound
• Mapgen and LVM
• Organising code - patterns
• ...

[ExeterDad]

You are to be worshipped from this day forward.

[philipbenr]

Hmmm. I think that I might just do one with pure html and css. It would be nicer and easier for most people to make.

[rubenwardy]

Philipbenr, yeah no. Markdown is easier to create, you can still get html exports. I'll start making them when I get more chapters.

Markdown is human readable, so makes sense as plain text.

You can just write chapters as a text file in chapters, and I will link and correct formatting. You never actually need to use Jekyll. Feel free to submit a word document. Writing is the hard bit, not the formatting.

Jekyll allows you to include other HTML files. Much easier.

[Evergreen]

THANK YOU

[leeminer]

I wish I had more thumbs.. two thumbs up!!!

[philipbenr]

Truthfully, I find markdown confusing and html more organized. More complex, but more organized.

Edit: Plus, with css, I can do some really amazing effects, plus make a popup of pure css(3?) (strange, huh?) It would be harder for a person to add to it, but it would be easy for some web developers. Personally, when I used markdown, it took more memorization than html. There were div (dividers) and p (paragraph) and h_ (header, size _) and the like. It is different with different versions of markdown, but I find html easier to memorize.

[leeminer]

For those who don't know what markdown is. Like me.

http://en.wikipedia.org/wiki/Markdown

[rubenwardy]

Anything is confusing if you don't put any time into learning it. The tutorial is supposed to be written by authors, not web developers.

You can use HTML in markdown. Markdown isn't hard. Popups are not needed.

BTW, the HTML is in _includes/header.html and _includes/footer.html.
CSS is in static/style.css

I don't see your point.
These are really the only things you need:
(Plus images)

Code: Select all

Section
-------

Here is some text

### source code
    Code snippets are
    Tabbed one level in.

Another paragraph

* one
* two
* three

[Link](http://URL)

<b>this is perfectly valid<\b>

The tutorials should be printable, in theory

[srifqi]

+1

I don't know which is better HTML or Markdown, for me it's same.

[Linuxdirk]

Markdown isn't hard.

Markdown is easy as pie :D

I don't know which is better HTML or Markdown, for me it's same.

For content … Markdown is better.

[philipbenr]

Okay, I just want to say, I do see your point, but this is what I was talking about when I said you can do cool stuff. There is no javascript involved in this whatsoever. You can hover on the quote slider to stop it, and you can hover on the cards to make them zoom, (Also, sorry about the cards. I was lazy, so I just did a quick fix and put them in a table. I should just change a couple things around and fix that to be normal for all zooms and displays. Same with the height of the quote slider. But still. There is a lot of cool stuff in there, isn't there?)

[rubenwardy]

1) you can do that with my markdown thing. CSS can be used, so can HTML.
2) it's not needed for this project.

I do like CSS, although it is a pain when doing columns or mixing fixed and %.

[leeminer]

To tell you all the truth, if you told me the tutorial Rubenwardy made was a text file without HTML markup I would have thought you were crazy.

The point of a tutorial isn't fancy CSS or HTML or javascript, the point is to show examples, and tutor people with info. I find the format and style super easy to read. We should focus on the content I say.

Rubenwardy, let us know what we can do. Like I suggested before, maybe we start an FAQ and add that to your documentation some how?

What does everyone think of an FAQ idea. For a noob to minetest like me, a FAQ would be greatly helpful, and in conjunction with the tutorial really great.

Maybe even a FAQ for each chapter?

[rubenwardy]

I would like to add 'tip' and 'watch out' boxes. This online book will be in the similar style to a teach teach yourself in 24 hours style book. FAQs will be talked about in the paragraphs.

I would like a list of possible chapters, and suggestions on what common mistakes and problems are.

[Evergreen]

I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.

[leeminer]

I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.

Visually its kind of blah.. Trying to define blah, not much color or variation or anything to draw your eyes to where they should go.. if that makes sense.

[Evergreen]

I found a really great intro to vimscript that we could take some inspiration from. (it uses markdown for its formatting)
http://learnvimscriptthehardway.stevelosh.com/
And no, this was not written by Zed Shaw. In fact, I think it is way better than learn python the hard way.

Visually its kind of blah.. Trying to define blah, not much color or variation or anything to draw your eyes to where they should go.. if that makes sense.

I'm not giving it as an example for color, I'm giving it as an example for content.

[rubenwardy]

Added a chapter on registering nodes, craftitems and crafting. Next I will be doing formspecs.

You can download a zip of the website here: https://github.com/rubenwardy/minetest_doc/releases

[Evergreen]

By the way, here is where you can contribute: https://github.com/rubenwardy/minetest_doc

[leeminer]

Rubenwardy,.. perhaps add a link in your signature to the Tutorial. Would make it easy for us to review it... I'll check the update and give some feedback when able today.

Thanks man..

[Don]

I am looking forward to the formspec chapter. I have put my millwork mod on hold until I figure out how to make a couple machines for it.

One thing that I have trouble with is knowing where to put things. I am not a programmer. In some mods there is code before the node definition and in others it is in the node definition. A chapter on the code structure would be nice.
I learned a little about ipairs and tables. I haven't found much info on how to use them. I am learning from other peoples mods. I would love to learn more about them.
Thank you for doing this book. I means a lot to me and I am sure many other people.

[Zeno]

I'd prefer LaTex before HTML/CSS. Markdown is easy and it's probably easier to get others to help if it's easy to do.

[rubenwardy]

Hi Don. The formspec chapter will be the next I write - you should expect it in the next 48 hours. I will write a chapter on code organisation. It is a great idea.

[Linuxdirk]

I'd prefer LaTex before HTML/CSS.

LaTeX is awesome in it’s field of work but rather not in the web publishing section :) I’d prefer LaTeX over anything else when I want to create text I want to print or publish in PDF form.

Markdown is easy and it's probably easier to get others to help if it's easy to do.

Markdown is more or less “natural writing”. You have little to no syntax elements for parsing except the ones you need to add anyways to structure the context itself (lists, headings, etc.).