Improve various chapters
This commit is contained in:
rubenwardy
parent
25d346a15b
commit
37e530728b
@ -17,13 +17,11 @@ 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)
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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")
|
||||
|
||||
@ -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;]")
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
- [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)
|
||||
- [mod.conf / game.conf](#modconf--gameconf)
|
||||
- [screenshot.png](#screenshotpng)
|
||||
- [Uploading](#uploading)
|
||||
- [Version Control Systems](#version-control-systems)
|
||||
- [Forum Attachments](#forum-attachments)
|
||||
- [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]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user