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

User avatar
rubenwardy
Moderator
 
Posts: 5471
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

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

by rubenwardy » Thu Dec 11, 2014 19:44

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
  • ...
Last edited by rubenwardy on Fri Apr 15, 2016 23:14, edited 32 times in total.
 

User avatar
ExeterDad
Member
 
Posts: 1717
Joined: Sun Jun 01, 2014 20:00
Location: New Hampshire U.S.A
In-game: ExeterDad
 

User avatar
philipbenr
Member
 
Posts: 1688
Joined: Fri Jun 14, 2013 01:56
Location: United States
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi

Re: Minetest Tutorial Book - Creating Better Documentation

by philipbenr » Thu Dec 11, 2014 21:57

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.
 

User avatar
rubenwardy
Moderator
 
Posts: 5471
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Thu Dec 11, 2014 22:04

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.
 

User avatar
Evergreen
Member
 
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
Location: A forest in the midwest
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen
 

leeminer
Member
 
Posts: 90
Joined: Mon Aug 11, 2014 21:29
 

User avatar
philipbenr
Member
 
Posts: 1688
Joined: Fri Jun 14, 2013 01:56
Location: United States
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi

Re: Minetest Tutorial Book - Creating Better Documentation

by philipbenr » Thu Dec 11, 2014 23:16

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.
Last edited by philipbenr on Fri Dec 12, 2014 01:46, edited 1 time in total.
 

leeminer
Member
 
Posts: 90
Joined: Mon Aug 11, 2014 21:29
 

User avatar
rubenwardy
Moderator
 
Posts: 5471
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Fri Dec 12, 2014 07:28

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
 

User avatar
srifqi
Member
 
Posts: 548
Joined: Sat Jun 28, 2014 04:31
Location: Indonesia
GitHub: srifqi
IRC: srifqi
In-game: srifqi

Re: Minetest Tutorial Book - Creating Better Documentation

by srifqi » Fri Dec 12, 2014 12:18

+1

I don't know which is better HTML or Markdown, for me it's same.
I'm from Indonesia! Saya dari Indonesia!
Terjemahkan Minetest!
Mods by me. Modifikasi oleh saya.

Pronounce my nick as in: es-rifqi (IPA: /es rifˈki/)
 

User avatar
Linuxdirk
Member
 
Posts: 1601
Joined: Wed Sep 17, 2014 11:21
Location: Germany
In-game: Linuxdirk

Re: Minetest Tutorial Book - Creating Better Documentation

by Linuxdirk » Fri Dec 12, 2014 12:50

rubenwardy wrote:Markdown isn't hard.

Markdown is easy as pie :D

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

For content … Markdown is better.
 

User avatar
philipbenr
Member
 
Posts: 1688
Joined: Fri Jun 14, 2013 01:56
Location: United States
GitHub: philipbenr
IRC: philipbenr
In-game: robinspi

Re: Minetest Tutorial Book - Creating Better Documentation

by philipbenr » Fri Dec 12, 2014 14:49

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?)
Attachments
Minetest.zip
This is a single html page and single css stylesheet modeled after the homepage. It should work in almost all browsers, but maybe not IE 9 (That one has had compatibility issues in general)
(785.92 KiB) Downloaded 50 times
“Would it save you a lot of time if I just gave up and went mad now?”

“I'd far rather be happy than right any day.”

“What, are you, crazy?" "It's a possibility I haven't ruled out yet"
 

User avatar
rubenwardy
Moderator
 
Posts: 5471
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Minetest Tutorial Book - Creating better Documentation

by rubenwardy » Fri Dec 12, 2014 15:28

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
Member
 
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Fri Dec 12, 2014 15:39

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?
 

User avatar
rubenwardy
Moderator
 
Posts: 5471
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Fri Dec 12, 2014 15:43

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.
 

User avatar
Evergreen
Member
 
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
Location: A forest in the midwest
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen

Re: Minetest Tutorial Book - Creating Better Documentation

by Evergreen » Fri Dec 12, 2014 18:31

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.
Back from the dead!
 

leeminer
Member
 
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Fri Dec 12, 2014 19:14

Evergreen wrote: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.
 

User avatar
Evergreen
Member
 
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
Location: A forest in the midwest
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen

Re: Minetest Tutorial Book - Creating Better Documentation

by Evergreen » Fri Dec 12, 2014 19:15

leeminer wrote:
Evergreen wrote: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.
Back from the dead!
 

User avatar
rubenwardy
Moderator
 
Posts: 5471
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Fri Dec 12, 2014 20:12

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
 

User avatar
Evergreen
Member
 
Posts: 2135
Joined: Sun Jan 06, 2013 01:22
Location: A forest in the midwest
GitHub: 4Evergreen4
IRC: EvergreenTree
In-game: Evergreen
 

leeminer
Member
 
Posts: 90
Joined: Mon Aug 11, 2014 21:29

Re: Minetest Tutorial Book - Creating Better Documentation

by leeminer » Fri Dec 12, 2014 20:35

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

User avatar
Don
Member
 
Posts: 1642
Joined: Sat May 17, 2014 18:40
GitHub: DonBatman
IRC: Batman
In-game: Batman

Re: Minetest Tutorial Book - Creating Better Documentation

by Don » Sat Dec 13, 2014 18:09

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.
Many of my mods are now a part of Minetest-mods. A place where you know they are maintained!

A list of my mods can be found here
 

Zeno
Member
 
Posts: 140
Joined: Sun Jun 29, 2014 03:36
Location: Australia
GitHub: Zeno-

Re: Minetest Tutorial Book - Creating Better Documentation

by Zeno » Sun Dec 14, 2014 08:14

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.
 

User avatar
rubenwardy
Moderator
 
Posts: 5471
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Minetest Tutorial Book - Creating Better Documentation

by rubenwardy » Sun Dec 14, 2014 09:11

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.
 

User avatar
Linuxdirk
Member
 
Posts: 1601
Joined: Wed Sep 17, 2014 11:21
Location: Germany
In-game: Linuxdirk

Re: Minetest Tutorial Book - Creating Better Documentation

by Linuxdirk » Sun Dec 14, 2014 12:27

Zeno wrote: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.

Zeno wrote: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.).
 

Next

Return to Modding Discussion



Who is online

Users browsing this forum: No registered users and 1 guest