rubenwardy
/
minetest_doc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve various chapters

master
rubenwardy 2020-12-24 13:25:31 +00:00
parent 25d346a15b
commit 37e530728b
8 changed files with 107 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
_en/basics/getting_started.md
View File

@ -17,15 +17,13 @@ creating mods.
- [What are Games and Mods?](#what-are-games-and-mods)
- [Where are mods stored?](#where-are-mods-stored)
- [Mod Directory](#mod-directory)
- [Dependencies](#dependencies)
- [mod.conf](#modconf)
- [depends.txt](#dependstxt)
- [mod.conf](#modconf)
- [Dependencies](#dependencies)
- [Mod Packs](#mod-packs)
- [Example](#example)
- [Mod Folder](#mod-folder)
- [depends.txt](#dependstxt-1)
- [init.lua](#initlua)
- [mod.conf](#modconf-1)
- [Mod Folder](#mod-folder)
- [init.lua](#initlua)
- [mod.conf](#modconf-1)
## What are Games and Mods?
@ -119,8 +117,18 @@ Only the init.lua file is required in a mod for it to run on game load;
however, mod.conf is recommended and other components may be needed
depending on the mod's functionality.
## mod.conf
## Dependencies
This file is used for mod metadata including the mod's name, description, and other
information.
For example:
name = mymod
description = Adds foo, bar, and bo.
depends = modone, modtwo
### Dependencies
A dependency occurs when a mod requires another mod to be loaded before itself.
One mod may require another mod's code, items, or other resources to be available
@ -134,34 +142,14 @@ dependency might lead to fewer features being enabled.
An optional dependency is useful if you want to optionally support another mod; it can
enable extra content if the user wishes to use both the mods at the same time.
Dependencies should be listed in mod.conf.
Dependencies are specified in a comma-separated list in mod.conf.
### mod.conf
This file is used for mod metadata including the mod's name, description, and other
information. For example:
name = mymod
description = Adds foo, bar, and bo.
depends = modone, modtwo
optional_depends = modthree
### depends.txt
For compatibility with 0.4.x versions of Minetest, instead of only specifying
dependencies in mod.conf, you need to provide a depends.txt file in which
you list all dependencies:
modone
modtwo
modthree?
Each mod name is on its own line, and mod names with a question mark
following them are optional dependencies.
## Mod Packs
Mods can be grouped into mod packs which allow multiple mods to be packaged
Mods can be grouped into mod packs, which allow multiple mods to be packaged
and moved together. They are useful if you want to supply multiple mods to
a player, but don't want to make them download each one individually.
@ -184,13 +172,9 @@ Here is an example which puts all of this together:
mymod
├── textures
│   └── mymod_node.png files
├── depends.txt
├── init.lua
└── mod.conf
### depends.txt
default
### init.lua
```lua
print("This file will be run at load time!")
@ -207,8 +191,7 @@ minetest.register_node("mymod:node", {
descriptions = Adds a node
depends = default
This mod has the name "mymod". It has three text files: init.lua, mod.conf,
and depends.txt.\\
This mod has the name "mymod". It has two text files: init.lua and mod.conf.\\
The script prints a message and then registers a node –
which will be explained in the next chapter.\\
There's a single dependency, the

2
_en/games/games.md
View File

@ -57,7 +57,7 @@ convenient, as it'll make porting mods to another game much easier.
The best way to keep compatibility with another game is to keep API compatibility
with any mods which have the same name.
That is, if a mod uses the same name as another mod, even if third party,
That is, if a mod uses the same name as another mod, even if third-party,
it should have a compatible API.
For example, if a game includes a mod called `doors`, then it should have the
same API as `doors` in Minetest Game.

41
_en/map/objects.md
View File

@ -103,28 +103,6 @@ An Entity has a definition table that resembles an item definition table.
This table can contain callback methods, initial object properties, and custom
members.
However, entities differ in one very important way from items. When an entity is
emerged (ie: loaded or created), a new table is created for that entity that
*inherits* from the definition table using metatables.
This new table is commonly referred to as a Lua Entity table.
Metatables are an important Lua feature that you will need
to be aware of, as it is an essential part of the Lua language.
In layman's terms, a metatable allows you to control how the table behaves when
using certain Lua syntax. The most common use of metatables is the ability to use
another table as a prototype, defaulting to the other table's properties and methods when
they do not exist in the current table.
Say you want to access member X on table A. If table A has that member, then
it will be returned as normal. However, if the table doesn't have that member but
it does have a metatable could table B, then table B will be checked to see if it
has that member.
<!--table A is a metatable of table B, then table
B will have all the properties and methods of table A if the derived table doesn't
have any itself.-->
```lua
local MyEntity = {
initial_properties = {
@ -147,9 +125,22 @@ function MyEntity:set_message(msg)
end
```
When an entity has emerged, a table is created for it by copying everything from
its type table.
This table can be used to store variables for that particular entity.
Entity definitions differ in one very important way from Item definitions.
When an entity is emerged (ie: loaded or created), a new table is created for
that entity that *inherits* from the definition table.
<!--
This inheritance is done using a Metatables are an important Lua feature that you will need
to be aware of, as it is an essential part of the Lua language.
In layman's terms, a metatable allows you to control how the table behaves when
using certain Lua syntax. The most common use of metatables is the ability to use
another table as a prototype, defaulting to the other table's properties and methods when
they do not exist in the current table.
Say you want to access `a.x`. If the table `a` has that member, then it will be
returned as normal. However, if the table doesn't have that member and the
metatable lists a table `b` as a prototype, then table `b` will be checked to see
if it has that member.
-->
Both an ObjectRef and an entity table provide ways to get the counterpart:

20
_en/map/storage.md
View File

@ -14,13 +14,13 @@ redirect_from:
In this chapter, you will learn how you can store data.
- [Metadata](#metadata)
- [What is Metadata?](#what-is-metadata)
- [Obtaining a Metadata Object](#obtaining-a-metadata-object)
- [Reading and Writing](#reading-and-writing)
- [Special Keys](#special-keys)
- [Storing Tables](#storing-tables)
- [Private Metadata](#private-metadata)
- [Lua Tables](#lua-tables)
- [What is Metadata?](#what-is-metadata)
- [Obtaining a Metadata Object](#obtaining-a-metadata-object)
- [Reading and Writing](#reading-and-writing)
- [Special Keys](#special-keys)
- [Storing Tables](#storing-tables)
- [Private Metadata](#private-metadata)
- [Lua Tables](#lua-tables)
- [Mod Storage](#mod-storage)
- [Databases](#databases)
- [Deciding Which to Use](#deciding-which-to-use)
@ -111,7 +111,7 @@ Minetest offers two formats for doing this: Lua and JSON.
The Lua method tends to be a lot faster and matches the format Lua
uses for tables, while JSON is a more standard format, is better
structured, and is well suited when you need to exchange information
structured, and is well suited for when you need to exchange information
with another program.
```lua
@ -123,8 +123,8 @@ data = minetest.deserialize(minetest:get_string("foo"))
### Private Metadata
Entries in Node Metadata can be marked as private, and not sent to the client.
Entries not marked as private will be sent to the client.
By default, all node metadata is sent to the client.
You can mark keys as private to prevent this.
```lua
meta:set_string("secret", "asd34dn")

27
_en/players/formspecs.md
View File

@ -35,16 +35,16 @@ unexpected windows tend to disrupt gameplay.
- [Real or Legacy Coordinates](#real-or-legacy-coordinates)
- [Anatomy of a Formspec](#anatomy-of-a-formspec)
- [Elements](#elements)
- [Header](#header)
- [Elements](#elements)
- [Header](#header)
- [Guessing Game](#guessing-game)
- [Padding and Spacing](#padding-and-spacing)
- [Receiving Formspec Submissions](#receiving-formspec-submissions)
- [Contexts](#contexts)
- [Padding and Spacing](#padding-and-spacing)
- [Receiving Formspec Submissions](#receiving-formspec-submissions)
- [Contexts](#contexts)
- [Formspec Sources](#formspec-sources)
- [Node Meta Formspecs](#node-meta-formspecs)
- [Player Inventory Formspecs](#player-inventory-formspecs)
- [Your Turn](#your-turn)
- [Node Meta Formspecs](#node-meta-formspecs)
- [Player Inventory Formspecs](#player-inventory-formspecs)
- [Your Turn](#your-turn)
## Real or Legacy Coordinates
@ -56,6 +56,8 @@ called real coordinates which aims to rectify this by introducing a consistent
coordinate system. The use of real coordinates is highly recommended, and so
this chapter will use them exclusively.
Using a formspec_version of 2 or above will enable real coordinates.
## Anatomy of a Formspec
### Elements
@ -93,7 +95,7 @@ The size is in formspec slots - a unit of measurement which is roughly
around 64 pixels, but varies based on the screen density and scaling
settings of the client. Here's a formspec which is `2,2` in size:
formspec_version[3]
formspec_version[4]
size[2,2]
Notice how we explicitly defined the formspec language version.
@ -106,9 +108,8 @@ the center (`0.5,0.5`). The anchor sets where on the formspec the position is,
allowing you to line the formspec up with the edge of the screen. The formspec
can be placed to the left of the screen like so:
formspec_version[3]
formspec_version[4]
size[2,2]
real_coordinates[true]
position[0,0.5]
anchor[0,0.5]
@ -143,7 +144,7 @@ function guessing.get_formspec(name)
local text = "I'm thinking of a number... Make a guess!"
local formspec = {
"formspec_version[3]",
"formspec_version[4]",
"size[6,3.476]",
"label[0.375,0.5;", minetest.formspec_escape(text), "]",
"field[0.375,1.25;5.25,0.8;number;Number;]",
@ -334,7 +335,7 @@ minetest.register_node("mymod:rightclick", {
local meta = minetest.get_meta(pos)
meta:set_string("formspec",
"formspec_version[3]" ..
"formspec_version[4]" ..
"size[5,5]" ..
"label[1,1;This is shown on right click]" ..
"field[1,2;2,1;x;x;]")

2
_en/players/player_physics.md
View File

@ -18,7 +18,7 @@ For example, a value of 2 for gravity would make gravity twice as strong.
- [Basic Example](#basic-example)
- [Available Overrides](#available-overrides)
- [Old Movement Behaviour](#old-movement-behaviour)
- [Old Movement Behaviour](#old-movement-behaviour)
- [Mod Incompatibility](#mod-incompatibility)
- [Your Turn](#your-turn)

55
_en/quality/common_mistakes.md
View File

@ -10,54 +10,27 @@ redirect_from: /en/chapters/common_mistakes.html
This chapter details common mistakes, and how to avoid them.
- [Never Store ObjectRefs (ie: players or entities)](#never-store-objectrefs-ie-players-or-entities)
- [Be Careful When Storing ObjectRefs (ie: players or entities)](#be-careful-when-storing-objectrefs-ie-players-or-entities)
- [Don't Trust Formspec Submissions](#dont-trust-formspec-submissions)
- [Set ItemStacks After Changing Them](#set-itemstacks-after-changing-them)
## Never Store ObjectRefs (ie: players or entities)
## Be Careful When Storing ObjectRefs (ie: players or entities)
If the object an ObjectRef represents is deleted - for example, if the player goes
offline or the entity is unloaded - then calling methods on that object
will result in a crash.
An ObjectRef is invalidated when the player or entity it represents leaves
the game. This may happen when the player goes offline, or the entity is unloaded
or removed.
For example, don't do this:
The methods of ObjectRefs will always return nil when invalid, since Minetest 5.2.
Any call will essentially be ignored.
You should avoid storing ObjectRefs where possible. If you do to store an
ObjectRef, you should make you check it before use, like so:
```lua
minetest.register_on_joinplayer(function(player)
local function func()
local pos = player:get_pos() -- BAD!
-- `player` is stored then accessed later.
-- If the player leaves in that second, the server *will* crash.
end
minetest.after(1, func)
foobar[player:get_player_name()] = player
-- RISKY
-- It's not recommended to do this.
-- Use minetest.get_connected_players() and
-- minetest.get_player_by_name() instead.
end)
```
Do this instead:
```lua
minetest.register_on_joinplayer(function(player)
local function func(name)
-- Attempt to get the ref again
local player = minetest.get_player_by_name(name)
-- Check that the player is still online
if player then
-- Yay! This is fine
local pos = player:get_pos()
end
end
-- Pass the name into the function
minetest.after(1, func, player:get_player_name())
end)
-- This only works in Minetest 5.2+
if obj:get_pos() then
-- is valid!
end
```
## Don't Trust Formspec Submissions

112
_en/quality/releasing.md
View File

@ -11,21 +11,20 @@ redirect_from: /en/chapters/releasing.html
Releasing, or publishing, a mod allows other people to make use of it. Once a mod has been
released it might be used in singleplayer games or on servers, including public servers.
- [License Choices](#license-choices)
- [LGPL and CC-BY-SA](#lgpl-and-cc-by-sa)
- [CC0](#cc0)
- [MIT](#mit)
- [Choosing a License](#choosing-a-license)
- [LGPL and CC-BY-SA](#lgpl-and-cc-by-sa)
- [CC0](#cc0)
- [MIT](#mit)
- [Packaging](#packaging)
- [README.txt](#readmetxt)
- [description.txt](#descriptiontxt)
- [screenshot.png](#screenshotpng)
- [README.txt](#readmetxt)
- [mod.conf / game.conf](#modconf--gameconf)
- [screenshot.png](#screenshotpng)
- [Uploading](#uploading)
- [Version Control Systems](#version-control-systems)
- [Forum Attachments](#forum-attachments)
- [Version Control Systems](#version-control-systems)
- [Releasing on ContentDB](#releasing-on-contentdb)
- [Forum Topic](#forum-topic)
- [Subject](#subject)
## License Choices
## Choosing a License
You need to specify a license for your mod. This is important because it tells other
people the ways in which they are allowed to use your work. If your mod doesn't have
@ -85,19 +84,19 @@ The README file should state:
* Current version of the mod.
* Optionally, the where to report problems or get help.
### description.txt
### mod.conf / game.conf
This should explain what your mod does. Be concise without being vague.
Make sure you add a description key to explain what your mod does. Be concise without being vague.
It should be short because it will be displayed in the content installer which has
limited space.
Good example:
Adds soup, cakes, bakes and juices.
description = Adds soup, cakes, bakes and juices.
Avoid this:
(BAD) The food mod for Minetest.
description = The food mod for Minetest. (<-- BAD! It's vague)
### screenshot.png
@ -114,54 +113,41 @@ approach that works best for you, as long as it meets these requirements, and an
others which may be added by forum moderators:
* **Stable** - The hosting website should be unlikely to shut down without warning.
* **Direct link** - You should be able to click a link on the forum and download the file
* **Direct link** - You should be able to click a link and download the file
without having to view another page.
* **Virus Free** - Mods with malicious content will be removed from the forum.
ContentDB allows you to upload zip files, and meets these criteria.
### Version Control Systems
It is recommended that you use a version control system which:
A Version Control System (VCS) is software that manages changes to software,
often making it easier to distribute and receive contributed changes.
* Allows other developers to easily submit changes.
* Allows the code to be previewed before downloading.
* Allows users to submit bug reports.
The majority of Minetest modders use Git and a website like GitHub to distribute
their code.
The majority of Minetest modders use GitHub as a website to host their code,
but alternatives are possible.
Using a GitHub can be difficult at first. If you need help with this, for
information on using GitHub, please see:
Using git can be difficult at first. If you need help with this please see:
* [Pro Git book](http://git-scm.com/book/en/v1/Getting-Started) - Free to read online.
* [GitHub for Windows app](https://help.github.com/articles/getting-started-with-github-for-windows/) -
Using a graphical interface on Windows to upload your code.
### Forum Attachments
## Releasing on ContentDB
As an alternative to using a version management system, you can use forum attachments to share
your mods. This can be done when creating a mod's forum topic (covered below).
ContentDB is the official place to find and distribute mods and games. Users can
find content using the website, or download and install using the integration
built into the Minetest main menu.
You need to zip the files for the mod into a single file. How to do this varies from
operating system to operating system.
This is nearly always done using the right click menu after selecting all files.
When making a forum topic, on the "Create a Topic" page (see below), go to the
"Upload Attachment" tab at the bottom.
Click "Browse" and select the zipped file. It is recommended that you
enter the version of your mod in the comment field.
<figure>
<img src="{{ page.root }}/static/releasing_attachments.png" alt="Upload Attachment">
<figcaption>
Upload Attachment tab.
</figcaption>
</figure>
Sign up to [ContentDB](https://content.minetest.net) and add your mod or game.
Make sure to read the guidance given in the Help section.
## Forum Topic
You can now create a forum topic. You should create it in
the ["WIP Mods"](https://forum.minetest.net/viewforum.php?f=9) (Work In Progress)
forum.\\
You can also create a forum topic to let users discuss your mod or game.
Mod topics should be created in ["WIP Mods"](https://forum.minetest.net/viewforum.php?f=9) (Work In Progress)
forum, and Game topics in the ["WIP Games"](https://forum.minetest.net/viewforum.php?f=50) forum.
When you no longer consider your mod a work in progress, you can
[request that it be moved](https://forum.minetest.net/viewtopic.php?f=11&t=10418)
to "Mod Releases."
@ -170,40 +156,6 @@ The forum topic should contain similar content to the README, but should
be more promotional and also include a link to download the mod.
It's a good idea to include screenshots of your mod in action, if possible.
The Minetest forum uses bbcode for formatting. Here is an example for a
mod named superspecial:
Adds magic, rainbows and other special things.
See download attached.
[b]Version:[/b] 1.1
[b]License:[/b] LGPL 2.1 or later
Dependencies: default mod (found in minetest_game)
Report bugs or request help on the forum topic.
[h]Installation[/h]
Unzip the archive, rename the folder to superspecial and
place it in minetest/mods/
( GNU/Linux: If you use a system-wide installation place
it in ~/.minetest/mods/. )
( If you only want this to be used in a single world, place
the folder in worldmods/ in your world directory. )
For further information or help see:
[url]https://wiki.minetest.net/Installing_Mods[/url]
If you modify the above example for your mod topic, remember to
change "superspecial" to the name of your mod.
### Subject
The subject of topic must be in one of these formats:
* [Mod] Mod Title [modname]