From 37e530728bb6697b107d2d5aee715892a580109f Mon Sep 17 00:00:00 2001 From: rubenwardy Date: Thu, 24 Dec 2020 13:25:31 +0000 Subject: [PATCH] Improve various chapters --- _en/basics/getting_started.md | 55 ++++++---------- _en/games/games.md | 2 +- _en/map/objects.md | 41 +++++------- _en/map/storage.md | 20 +++--- _en/players/formspecs.md | 27 ++++---- _en/players/player_physics.md | 2 +- _en/quality/common_mistakes.md | 55 +++++----------- _en/quality/releasing.md | 112 ++++++++++----------------------- 8 files changed, 107 insertions(+), 207 deletions(-) diff --git a/_en/basics/getting_started.md b/_en/basics/getting_started.md index b754838..2dbc9d4 100644 --- a/_en/basics/getting_started.md +++ b/_en/basics/getting_started.md @@ -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 diff --git a/_en/games/games.md b/_en/games/games.md index 2ead9eb..6d678f7 100644 --- a/_en/games/games.md +++ b/_en/games/games.md @@ -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. diff --git a/_en/map/objects.md b/_en/map/objects.md index b9fe91f..1b86fac 100644 --- a/_en/map/objects.md +++ b/_en/map/objects.md @@ -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. - - - ```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. + + Both an ObjectRef and an entity table provide ways to get the counterpart: diff --git a/_en/map/storage.md b/_en/map/storage.md index 534e40f..3b210da 100644 --- a/_en/map/storage.md +++ b/_en/map/storage.md @@ -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") diff --git a/_en/players/formspecs.md b/_en/players/formspecs.md index c7ca095..e3ba1db 100644 --- a/_en/players/formspecs.md +++ b/_en/players/formspecs.md @@ -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;]") diff --git a/_en/players/player_physics.md b/_en/players/player_physics.md index 91d8ac7..321cdb4 100644 --- a/_en/players/player_physics.md +++ b/_en/players/player_physics.md @@ -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) diff --git a/_en/quality/common_mistakes.md b/_en/quality/common_mistakes.md index 293a5aa..e45ef8d 100644 --- a/_en/quality/common_mistakes.md +++ b/_en/quality/common_mistakes.md @@ -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 diff --git a/_en/quality/releasing.md b/_en/quality/releasing.md index 8d31957..1a52cf0 100644 --- a/_en/quality/releasing.md +++ b/_en/quality/releasing.md @@ -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. - -
- Upload Attachment -
- Upload Attachment tab. -
-
+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]