minetest
/
minetest
mirror of https://github.com/minetest/minetest.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge 2b7e4973f2 into c4703a7f19

This commit is contained in:
Bradley Pierce 2024-05-17 13:37:00 +00:00 committed by GitHub
parent c4703a7f19 2b7e4973f2
commit 3bdbb9ccee
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
23 changed files with 1813 additions and 1882 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
.github/CONTRIBUTING.md vendored
View File

@ -1,12 +1,10 @@
# Contributing
Contributions are welcome! Here's how you can help:
- [Contributing code](#code)
- [Reporting issues](#issues)
- [Requesting features](#feature-requests)
- [Translating](#translations)
- [Donating](#donations)
* [Contributing code](#code)
* [Reporting issues](#issues)
* [Requesting features](#feature-requests)
* [Translating](#translations)
* [Donating](#donations)
## Code
@ -14,55 +12,56 @@ Contributions are welcome! Here's how you can help:
[clone](https://help.github.com/articles/cloning-a-repository/) your fork.
2. Before you start coding, consider opening an
[issue at Github](https://github.com/minetest/minetest/issues) to discuss the
[issue at GitHub](https://github.com/minetest/minetest/issues) to discuss the
suitability and implementation of your intended contribution with the core
developers.
Any Pull Request that isn't a bug fix and isn't covered by
Any pull request that isn't a bug fix and isn't covered by
[the roadmap](../doc/direction.md) will be closed within a month unless it
receives a concept approval from a Core Developer. For this reason, it is
recommended that you open an issue for any such pull requests before doing
the work, to avoid disappointment.
You may also benefit from discussing on our IRC development channel
[#minetest-dev](http://www.minetest.net/irc/). Note that a proper IRC client
is required to speak on this channel.
You may also benefit from discussing on one of our IRC development channels
[listed here](https://wiki.minetest.net/IRC). Note that a proper IRC client
is required to speak on these channels.
3. Start coding!
- Refer to the
* Refer to the
[Lua API](https://github.com/minetest/minetest/blob/master/doc/lua_api.md),
[Developer Wiki](http://dev.minetest.net/Main_Page) and other
[Developer Wiki](https://dev.minetest.net/Main_Page) and other
[documentation](https://github.com/minetest/minetest/tree/master/doc).
- Follow the [C/C++](http://dev.minetest.net/Code_style_guidelines) and
[Lua](http://dev.minetest.net/Lua_code_style_guidelines) code style guidelines.
- Check your code works as expected and document any changes to the Lua API.
* Follow the [C/C++](https://dev.minetest.net/Code_style_guidelines) and
[Lua](https://dev.minetest.net/Lua_code_style_guidelines) code style guidelines.
* Check your code works as expected and document any changes to the Lua API.
4. Commit & [push](https://help.github.com/articles/pushing-to-a-remote/) your changes to a new branch (not `master`, one change per branch)
- Commit messages should:
- Use the present tense.
- Be descriptive. See the commit messages by core developers for examples.
- The first line should:
- Start with a capital letter.
- Be a compact summary of the commit.
- Preferably have less than 70 characters.
- Have no full stop at the end.
- The second line should be empty.
- The following lines should describe the commit, starting a new line for each point.
4. Commit and [push](https://help.github.com/articles/pushing-to-a-remote/) your changes
to a new branch (not `master`, one change per branch)
* Commit messages should:
* Use the present tense.
* Be descriptive. See the commit messages by core developers for examples.
* The first line should:
* Start with a capital letter.
* Be a compact summary of the commit.
* Preferably have less than 70 characters.
* Have no full stop at the end.
* The second line should be empty.
* The following lines should describe the commit, starting a new line for each point.
5. Once you are happy with your changes, submit a pull request.
- Open the [pull-request form](https://github.com/minetest/minetest/pull/new/master).
- Add a description explaining what you've done (or if it's a
work-in-progress - what you need to do).
- Make sure to fill out the pull request template.
* Open the [pull request form](https://github.com/minetest/minetest/pull/new/master).
* Add a description explaining what you've done (or if it's a work-in-progress -
what you need to do).
* Make sure to fill out the pull request template.
### A pull-request is considered merge-able when:
### A pull request is Considered Mergeable When:
1. It follows [the roadmap](../doc/direction.md) in some way and fits the whole
picture of the project.
2. It works.
3. It follows the code style for
[C/C++](http://dev.minetest.net/Code_style_guidelines) or
[Lua](http://dev.minetest.net/Lua_code_style_guidelines).
[C/C++](https://dev.minetest.net/Code_style_guidelines) or
[Lua](https://dev.minetest.net/Lua_code_style_guidelines).
4. The code's interfaces are well designed, regardless of other aspects that
might need more work in the future.
5. It uses protocols and formats which include the required compatibility.
@ -73,18 +72,18 @@ If you experience an issue, we would like to know the details - especially when
a stable release is on the way.
1. Do a quick search on GitHub to check if the issue has already been reported.
2. Is it an issue with the Minetest *engine*? If not, report it
[elsewhere](http://www.minetest.net/development/#reporting-issues).
2. Is it an issue with the Minetest *engine*? If not, report it.
[elsewhere](https://www.minetest.net/development/#reporting-issues).
3. [Open an issue](https://github.com/minetest/minetest/issues/new) and describe
the issue you are having - you could include:
- Error logs (check the bottom of the `debug.txt` file).
- Screenshots.
- Ways you have tried to solve the issue, and whether they worked or not.
- Your Minetest version and the content (games, mods or texture packs) you have installed.
- Your platform (e.g. Windows 10 or Ubuntu 15.04 x64).
* Error logs (check the bottom of the `debug.txt` file).
* Screenshots.
* Ways you have tried to solve the issue, and whether they worked or not.
* Your Minetest version and the content (games, mods or texture packs) you have installed.
* Your platform (e.g. Windows 10 or Ubuntu 15.04 x64).
After reporting you should aim to answer questions or clarifications as this
helps pinpoint the cause of the issue (if you don't do this your issue may be
After reporting, you should aim to answer questions or clarifications as this
helps pinpoint the cause of the issue (if you don't do this, your issue may be
closed after 1 month).
## Feature requests
@ -108,20 +107,22 @@ translated by editing a `.tr` text file. See
## Donations
If you'd like to monetarily support Minetest development, you can find donation
methods on [our website](http://www.minetest.net/development/#donate).
methods on [our website](https://www.minetest.net/get-involved/#donate).
# Maintaining
* This is a concise version of the
[Rules & Guidelines](http://dev.minetest.net/Category:Rules_and_Guidelines) on the developer wiki.*
[Rules & Guidelines](https://dev.minetest.net/Category:Rules_and_Guidelines) on the developer wiki.*
These notes are for those who have push access Minetest (core developers / maintainers).
- See the [project organisation](http://dev.minetest.net/Organisation) for the people involved.
* See the [project organization](https://dev.minetest.net/Organisation) for the people involved.
## Concept approvals and roadmaps
## Concept Approvals and Roadmaps
If a Pull Request is not a bug fix:
If a pull request is not a bug fix:
* If it matches a goal in [the roadmap](../doc/direction.md), then the PR should
be labeled as "Roadmap" and the goal stated by number in the description.
@ -137,33 +138,33 @@ Pull requests should be reviewed and, if appropriate, checked if they achieve
their intended purpose. You can show that you are in the process of, or will
review the pull request by commenting *"Looks good"* or something similar.
**If the pull-request is not [merge-able](#a-pull-request-is-considered-merge-able-when):**
**If the pull request is not [mergeable](#a-pull-request-is-considered-mergeable-when):**
Submit a comment explaining to the author what they need to change to make the
pull-request merge-able.
pull request merge-able.
- If the author comments or makes changes to the pull-request, it can be
* If the author comments or makes changes to the pull request, it can be
reviewed again.
- If no response is made from the author within 1 month (when improvements are
* If no response is made from the author within 1 month (when improvements are
suggested or a question is asked), it can be closed.
**If the pull-request is [merge-able](#a-pull-request-is-considered-merge-able-when):**
**If the pull request is [mergeable](#a-pull-request-is-considered-mergeable-when):**
Submit a :+1: (+1) or "Looks good" comment to show you believe the pull-request should be merged. "Looks good" comments often signify that the patch might require (more) testing.
Submit a :+1: (+1) or "Looks good" comment to show you believe the pull request should be merged. "Looks good" comments often signify that the patch might require (more) testing.
- Two core developers must agree to the merge before it is carried out and both should +1 the pull request.
- Who intends to merge the pull-request should follow the commit rules:
- The title should follow the commit guidelines (title starts with a capital letter, present tense, descriptive).
- Don't modify history older than 10 minutes.
- Use rebase, not merge to get linear history:
- `curl https://github.com/minetest/minetest/pull/1.patch | git am`
* Two core developers must agree to the merge before it is carried out and both should +1 the pull request.
* Who intends to merge the pull request should follow the commit rules:
* The title should follow the commit guidelines (title starts with a capital letter, present tense, descriptive).
* Don't modify history older than 10 minutes.
* Use rebase, not merge to get linear history:
`curl https://github.com/minetest/minetest/pull/1.patch | git am`
## Reviewing issues and feature requests
## Reviewing Issues and Feature Requests
- If an issue does not get a response from its author within 1 month (when requiring more details), it can be closed.
- When an issue is a duplicate, refer to the first ones and close the later ones.
- Tag issues with the appropriate [labels](https://github.com/minetest/minetest/labels) for devices, platforms etc.
* If an issue does not get a response from its author within 1 month (when requiring more details), it can be closed.
* When an issue is a duplicate, refer to the first ones and close the later ones.
* Tag issues with the appropriate [labels](https://github.com/minetest/minetest/labels) for devices, platforms etc.
## Releasing a new version
## Releasing a New Version
*Refer to [dev.minetest.net/Releasing_Minetest](http://dev.minetest.net/Releasing_Minetest)*
*Refer to [dev.minetest.net/Releasing_Minetest](https://dev.minetest.net/Releasing_Minetest)*

16
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -1,19 +1,19 @@
Add compact, short information about your PR for easier understanding:
- Goal of the PR
- How does the PR work?
- Does it resolve any reported issue?
- Does this relate to a goal in [the roadmap](https://github.com/minetest/minetest/blob/master/doc/direction.md)?
- If not a bug fix, why is this PR needed? What usecases does it solve?
* Goal of the PR
* How does the PR work?
* Does it resolve any reported issue?
* Does this relate to a goal in [the roadmap](https://github.com/minetest/minetest/blob/master/doc/direction.md)?
* If not a bug fix, why is this PR needed? What usecases does it solve?
## To do
This PR is a Work in Progress / Ready for Review.
<!-- ^ delete one -->
- [ ] List
- [ ] Things
- [ ] To do
* [ ] List
* [ ] Things
* [ ] To do
## How to test

6
.github/SECURITY.md vendored
View File

@ -10,11 +10,11 @@ See the [releases page](https://github.com/minetest/minetest/releases).
We ask that you report vulnerabilities privately, by contacting a core developer,
to give us time to fix them. You can do that by emailing one of the following addresses:
* celeron55@gmail.com
* rubenwardy@minetest.net
* <celeron55@gmail.com>
* <rubenwardy@minetest.net>
Depending on severity, we will either create a private issue for the vulnerability
and release a patch version of Minetest, or give you permission to file the issue publicly.
For more information on the justification of this policy, see
[Responsible Disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure).
[Responsible Disclosure](https://en.wikipedia.org/wiki/Responsible_disclosure).

91
README.md
View File

@ -1,5 +1,4 @@
Minetest
========
# Minetest
![Build Status](https://github.com/minetest/minetest/workflows/build/badge.svg)
[![Translation status](https://hosted.weblate.org/widgets/minetest/-/svg-badge.svg)](https://hosted.weblate.org/engage/minetest/?utm_source=widget)
@ -10,30 +9,17 @@ Minetest is a free open-source voxel game engine with easy modding and game crea
Copyright (C) 2010-2022 Perttu Ahola <celeron55@gmail.com>
and contributors (see source file comments and the version control log)
Table of Contents
------------------
## Further Documentation
1. [Further Documentation](#further-documentation)
2. [Default Controls](#default-controls)
3. [Paths](#paths)
4. [Configuration File](#configuration-file)
5. [Command-line Options](#command-line-options)
6. [Compiling](#compiling)
7. [Docker](#docker)
8. [Version Scheme](#version-scheme)
* Website: https://minetest.net/
* Wiki: https://wiki.minetest.net/
* Developer wiki: https://dev.minetest.net/
* Forum: https://forum.minetest.net/
* GitHub: https://github.com/minetest/minetest/
* [doc/](doc/) directory of source distribution
## Default Controls
Further documentation
----------------------
- Website: https://www.minetest.net/
- Wiki: https://wiki.minetest.net/
- Forum: https://forum.minetest.net/
- GitHub: https://github.com/minetest/minetest/
- [Developer documentation](doc/developing/)
- [doc/](doc/) directory of source distribution
Default controls
----------------
All controls are re-bindable using settings.
Some can be changed in the key config dialog in the settings tab.
@ -73,8 +59,8 @@ Some can be changed in the key config dialog in the settings tab.
| F10 | Show/hide console |
| F12 | Take screenshot |
Paths
-----
## Paths
Locations:
* `bin` - Compiled binaries
@ -100,46 +86,43 @@ Where each location is on each platform:
* `share` = `Contents/Resources`
* `user` = `Contents/User` or `~/Library/Application Support/minetest` or `$MINETEST_USER_PATH`
Worlds can be found as separate folders in: `user/worlds/`
Worlds can be found as separate folders in `user/worlds/`
Configuration file
------------------
- Default location:
`user/minetest.conf`
- This file is created by closing Minetest for the first time.
- A specific file can be specified on the command line:
`--config <path-to-file>`
- A run-in-place build will look for the configuration file in
`location_of_exe/../minetest.conf` and also `location_of_exe/../../minetest.conf`
## Configuration File
Command-line options
--------------------
- Use `--help`
* Default location: `user/minetest.conf`
* This file is created by closing Minetest for the first time.
* A specific file can be specified on the command line: `--config <path-to-file>`
* A run-in-place build will look for the configuration file in
`location_of_exe/../minetest.conf` and also `location_of_exe/../../minetest.conf`
Compiling
---------
## Command-Line Options
- [Compiling on GNU/Linux](doc/compiling/linux.md)
- [Compiling on Windows](doc/compiling/windows.md)
- [Compiling on MacOS](doc/compiling/macos.md)
Use `--help`
Docker
------
## Compiling
* [Compiling on GNU/Linux](doc/compiling/linux.md)
* [Compiling on Windows](doc/compiling/windows.md)
* [Compiling on MacOS](doc/compiling/macos.md)
## Docker
- [Developing minetestserver with Docker](doc/developing/docker.md)
- [Running a server with Docker](doc/docker_server.md)
Version scheme
--------------
## Version Scheme
We use `major.minor.patch` since 5.0.0-dev. Prior to that we used `0.major.minor`.
- Major is incremented when the release contains breaking changes, all other
numbers are set to 0.
- Minor is incremented when the release contains new non-breaking features,
patch is set to 0.
- Patch is incremented when the release only contains bugfixes and very
minor/trivial features considered necessary.
* Major is incremented when the release contains breaking changes, all other
numbers are set to 0.
* Minor is incremented when the release contains new non-breaking features,
patch is set to 0.
* Patch is incremented when the release only contains bugfixes and very
minor/trivial features considered necessary.
Since 5.0.0-dev and 0.4.17-dev, the dev notation refers to the next release,
i.e.: 5.0.0-dev is the development version leading to 5.0.0.
Prior to that we used `previous_version-dev`.
Prior to that we used `previous_version-dev`.

88
doc/android.md
View File

@ -1,40 +1,43 @@
# Minetest Android build
# Minetest Android Build
All Minetest builds, including the Android variant, are based on the same code.
However, additional Java code is used for proper Android integration.
## Controls
Compared to Minetest binaries for PC, the Android port has limited functionality
due to limited capabilities of common devices. What can be done is described below:
While you're playing the game normally (that is, no menu or inventory is
shown), the following controls are available:
* Look around: touch screen and slide finger
* Tap: Place a node, punch an object or use the selected item (default)
* Long tap: Dig a node or use the selected item (default)
* Look around: Touch screen and slide finger
* Tap: Place a node, punch an object, or use the wielded item (default)
* Long tap: Dig a node or use the wielded item
* Press back: Pause menu
* Touch buttons: Press button
* Buttons:
1. Left upper corner: Chat
2. Right lower corner: Jump
3. Right lower corner: Crouch
4. Left lower corner (Joystick): Walk/step...
5. Left lower corner: Display inventory
1. Upper-left corner: Chat
2. Lower-right corner: Jump
3. Lower-right corner: Crouch
4. Lower-left corner (Joystick): Walk
5. Lower-left corner: Display inventory
When a menu or inventory is displayed:
* Double tap outside menu area: Close menu
* Press back: Close menu
* Double tap outside menu area / Press back: Close menu
* Tap on an item stack: Select that stack
* Tap on an empty slot: If a stack are selected already, that stack is placed here
* Tap on an empty slot: If a stack is selected already, that stack is placed here
* Drag and drop: Touch stack and hold finger down, move the stack to another
slot, tap another finger while keeping first finger on screen
--> places a single item from dragged stack into current (first touched) slot. If a stack is selected, the stack will be split as half and one of the splitted stack will be selected
### Limitations
* Some old Android device only support 2 touch at a time, some game/mod contain button combination that need 3 touch (example: jump + Aux1 + hold)
* Complicated control can be difficult or impossible on Android device
* Complicated controls can be difficult or impossible on Android devices
* Some old Android devices only support 2 touches at a time, some games/mods contain button combinations that need 3 touches (example: jump + Aux1 + hold)
## File Path
There are some settings especially useful for Android users. The Minetest-wide
configuration file can usually be found at:
@ -46,49 +49,30 @@ configuration file can usually be found at:
* `/storage/emulated/(varying folder name)/Android/data/net.minetest.minetest/` if stored on the SD card
* [Learn more about Android directory](https://wiki.minetest.net/Accessing_Android_Data_Directory)
## Useful settings
## Useful Settings
### gui_scaling
this is a user-specified scaling factor for the GUI in case main menu is too big or small on your device, try changing this value.
### `gui_scaling`
### mapblock_limit
Mobile device generally have less RAM than PC, this setting limit how many mapblock can keep in RAM
This is a user-specified scaling factor for the GUI. If the main menu is too big or small on your device, try changing
this value.
### fps_limit
this setting limit max FPS (Frame per second). Default value is 60, which lowest Android device screen refresh rate commonly found, but if you're using an device have lower refresh rate, change this
### `mapblock_limit`
## Requirements
The minimal and recommended system requirements for Minetest are listed below.
Mobile devices generally have less RAM than PC, this setting limits how many mapblock can be kept in RAM.
### CPU
Supported architectures:
1. ARM v7
2. ARM v8
3. x86
4. x86_64
### `fps_limit`
CPU architectures similar to ARM or x86 might run Minetest but are not tested.
### Minimum
1. Graphics API: OpenGL ES 1.0
* Shaders might not work correctly or work at all on OpenGL ES 1.0.
2. Android version: Android 4.1 (API Level 16)
3. Free RAM: 500 MB
4. Free storage: 100 MB
* More storage is highly recommended
### Recommended
1. Graphics API: OpenGL ES 2.0
2. Android version: Android 4.4 (API Level 19) or newer
3. Empty RAM: 850 MB
4. Free storage: 480 MB
This setting limits maximum FPS. The default value is `60`, which is the lowest commonly found
Android refresh rate, but if you're using a device with a lower refresh rate, change this.
## Rendering
Unlike on PC, Android devices use OpenGL ES which less powerful than OpenGL, thus
some shader settings cannot be used on OpenGL ES.
Changing the graphic driver setting to OpenGL will result in undesirable behavior.
## Building Requirements
In order to build, your PC has to be set up to build Minetest in the usual
manner (see the regular Minetest documentation for how to get this done).
In addition to what is required for Minetest in general, you will need the
@ -104,6 +88,7 @@ Additionally, you'll need to have an Internet connection available on the
build system, as the Android build will download some source packages.
## Build
The new build system Minetest Android is fully functional and is designed to
speed up and simplify the work, as well as adding the possibility of
cross-platform build.
@ -114,13 +99,6 @@ When using gradlew, the newest NDK will be downloaded and installed
automatically. Or you can create a `local.properties` file and specify
`sdk.dir` and `ndk.dir` yourself.
* In order to make a release build you'll have to have a keystore setup to sign
the resulting apk package. How this is done is not part of this README. There
are different tutorials on the web explaining how to do it
- choose one yourself.
* Once your keystore is setup, enter the android subdirectory and create a new
file "ant.properties" there. Add following lines to that file:
> key.store=<path to your keystore>
> key.alias=Minetest
* In order to make a release build, you'll have to have a keystore setup to sign
the resulting APK package. How this is done is not part of this README. There
are tutorials online that explain it.

32
doc/breakages.md
View File

@ -3,21 +3,21 @@
This document contains a list of breaking changes to be made in the next major version.
This list is largely advisory and items may be reevaluated once the time comes.
* remove attachment space multiplier (*10)
* remove space multiplier for models (*10)
* remove player gravity multiplier (*2)
* Remove attachment space multiplier (*10)
* Remove space multiplier for models (*10)
* Remove player gravity multiplier (*2)
* `get_sky()` returns a table (without arg)
* `game.conf` name/id mess
* remove `depends.txt` / `description.txt` (would simplify ContentDB and Minetest code a little)
* rotate moon texture by 180°, making it coherent with the sun
* https://github.com/minetest/minetest/pull/11902
* remove undocumented `set_physics_override(num, num, num)`
* remove special handling of `${key}` syntax in metadata values
* remove old_move
* change physics_override `sneak` to disable the speed change and not just the node clipping
* https://github.com/minetest/minetest/issues/13699
* migrate from player names to UUIDs, this would enable renaming of accounts and unicode player names (if desired)
* harmonize use_texture_alpha between entities & nodes, change default to 'opaque' and remove bool compat code
* merge `sound` and `sounds` table in itemdef
* remove `DIR_DELIM` from Lua
* stop reading initial properties from bare entity def
* Remove `depends.txt` / `description.txt` (would simplify ContentDB and Minetest code a little)
* Rotate moon texture by 180°, making it coherent with the sun
* https://github.com/minetest/minetest/pull/11902
* Remove undocumented `set_physics_override(num, num, num)`
* Remove special handling of `${key}` syntax in metadata values
* Remove `old_move`
* Change physics_override `sneak` to disable the speed change and not just the node clipping
* https://github.com/minetest/minetest/issues/13699
* Migrate from player names to UUIDs, this would enable renaming of accounts and unicode player names (if desired)
* Harmonize `use_texture_alpha` between entities & nodes, change default to 'opaque' and remove bool compat code
* Merge `sound` and `sounds` table in itemdef
* Remove `DIR_DELIM` from Lua
* Stop reading initial properties from bare entity def.

13
doc/builtin_entities.md
View File

@ -1,8 +1,9 @@
# Builtin Entities
Minetest registers two entities by default: Falling nodes and dropped items.
This document describes how they behave and what you can do with them.
## Falling node (`__builtin:falling_node`)
## Falling Node (`__builtin:falling_node`)
This entity is created by `minetest.check_for_falling` in place of a node
with the special group `falling_node=1`. Falling nodes can also be created
@ -24,7 +25,7 @@ Default behavior:
* If the destination node is a leveled node (`paramtype2="leveled"`) of the
same node name, the levels of both are summed.
### Entity fields
### Entity Fields
* `set_node(self, node[, meta])`
* Function to initialize the falling node
@ -35,7 +36,7 @@ Default behavior:
* `meta`: Node metadata of the falling node. Will be used when the falling
nodes tries to place itself as a node. Read-only.
### Rendering / supported nodes
### Rendering / Supported Nodes
Falling nodes have visuals to look as close as possible to the original node.
This works for most drawtypes, but there are limitations.
@ -73,7 +74,7 @@ Supported `paramtype2` values:
* `color4dir`
* `color`
## Dropped item stack (`__builtin:item`)
## Dropped Item Stack (`__builtin:item`)
This is an item stack in a collectable form.
@ -96,7 +97,7 @@ Needs manual initialization when spawned using `/spawnentity`.
* When it's inside a solid (`walkable=true`) node, it tries to escape to a
neighboring non-solid (`walkable=false`) node
### Entity fields
### Entity Fields
* `set_item(self, item)`:
* Function to initialize the dropped item
@ -105,4 +106,4 @@ Needs manual initialization when spawned using `/spawnentity`.
* `itemstring`: Itemstring of the item that this item entity represents.
Read-only.
Other fields are for internal use only.
Other fields are for internal use only.

361
doc/client_lua_api.md
View File

@ -1,12 +1,12 @@
Minetest Lua Client Modding API Reference 5.9.0
================================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
# Minetest Lua Client Modding API Reference 5.9.0
Introduction
------------
* More information at <https://www.minetest.net/>
* Developer Wiki: <https://dev.minetest.net/>
** WARNING: The client API is currently unstable, and may break/change without warning. **
## Introduction
> [!WARNING]
> The client API is currently unstable, and may break/change without warning.
Content and functionality can be added to Minetest by using Lua
scripting in run-time loaded mods.
@ -20,28 +20,30 @@ If you see a deficiency in the API, feel free to attempt to add the
functionality in the engine and API. You can send such improvements as
source code patches on GitHub (https://github.com/minetest/minetest).
Programming in Lua
------------------
## Programming in Lua
If you have any difficulty in understanding this, please read
[Programming in Lua](http://www.lua.org/pil/).
Startup
-------
## Startup
Mods are loaded during client startup from the mod load paths by running
the `init.lua` scripts in a shared environment.
In order to load client-side mods, the following conditions need to be satisfied:
1) `$path_user/minetest.conf` contains the setting `enable_client_modding = true`
1. `$path_user/minetest.conf` contains the setting `enable_client_modding = true`
2. The client-side mod located in `$path_user/clientmods/<modname>` is added to
`$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.
2) The client-side mod located in `$path_user/clientmods/<modname>` is added to
`$path_user/clientmods/mods.conf` as `load_mod_<modname> = true`.
Note: Depending on the remote server's settings, client-side mods might not
> [!NOTE]
> Depending on the remote server's settings, client-side mods might not
be loaded or have limited functionality. See setting `csm_restriction_flags` for reference.
Paths
-----
# Paths
* `RUN_IN_PLACE=1` (Windows release, local build)
* `$path_user`: `<build directory>`
* `$path_share`: `<build directory>`
@ -53,24 +55,23 @@ Paths
* Linux: `$HOME/.minetest`
* Windows: `C:/users/<user>/AppData/minetest` (maybe)
Mod load path
-------------
Generic:
## Mod Load Path
Generic:
aa
* `$path_share/clientmods/`
* `$path_user/clientmods/` (User-installed mods)
In a run-in-place version (e.g. the distributed windows version):
* `minetest/clientmods/` (User-installed mods)
* `minetest-0.4.x/clientmods/` (User-installed mods)
On an installed version on Linux:
* `/usr/share/minetest/clientmods/`
* `$HOME/.minetest/clientmods/` (User-installed mods)
Modpack support
----------------
## Modpack Support
Mods can be put in a subdirectory, if the parent directory, which otherwise
should be a mod, contains a file named `modpack.conf`.
@ -78,33 +79,33 @@ The file is a key-value store of modpack details.
* `name`: The modpack name.
* `description`: Description of mod to be shown in the Mods tab of the main
menu.
menu.
Mod directory structure
------------------------
clientmods
├── modname
│   ├── mod.conf
│   ├── init.lua
│ ├── mod.conf
│ ├── init.lua
└── another
### modname
### `modname`
The location of this directory.
### mod.conf
### `mod.conf`
An (optional) settings file that provides meta information about the mod.
* `name`: The mod name. Allows Minetest to determine the mod name even if the
folder is wrongly named.
folder is wrongly named.
* `description`: Description of mod to be shown in the Mods tab of the main
menu.
menu.
* `depends`: A comma separated list of dependencies. These are mods that must be
loaded before this mod.
loaded before this mod.
* `optional_depends`: A comma separated list of optional dependencies.
Like a dependency, but no error if the mod doesn't exist.
Like a dependency, but no error if the mod doesn't exist.
### `init.lua`
@ -112,12 +113,15 @@ The main Lua script. Running this script should register everything it
wants to register. Subsequent execution depends on minetest calling the
registered callbacks.
**NOTE**: Client mods currently can't provide textures, sounds, or models by
themselves. Any media referenced in function calls must already be loaded
(provided by mods that exist on the server).
> [!NOTE]
> Client mods currently can't provide textures, sounds, or models by
> themselves. Any media referenced in function calls must already be loaded
> (provided by mods that exist on the server).
# Naming Convention For Registered Textual Names
Naming convention for registered textual names
----------------------------------------------
Registered names should generally be in this format:
"modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
@ -125,7 +129,8 @@ Registered names should generally be in this format:
This is to prevent conflicting names from corrupting maps and is
enforced by the mod loader.
### Example
## Example
In the mod `experimental`, there is the ideal item/node/entity name `tnt`.
So the name should be `experimental:tnt`.
@ -141,9 +146,12 @@ when registering it.
The `:` prefix can also be used for maintaining backwards compatibility.
Sounds
------
**NOTE: Connecting sounds to objects is not implemented.**
# Sounds
> [!NOTE]
> Connecting sounds to objects is not implemented.
Only Ogg Vorbis files are supported.
@ -189,17 +197,19 @@ Examples of sound parameter tables:
Looped sounds must be played locationless.
### SimpleSoundSpec
## `SimpleSoundSpec`
* e.g. `""`
* e.g. `"default_place_node"`
* e.g. `{}`
* e.g. `{name = "default_place_node"}`
* e.g. `{name = "default_place_node", gain = 1.0}`
Representations of simple things
--------------------------------
### Position/vector
# Representations of Simple Things
## Position/Vector
```lua
{x=num, y=num, z=num}
@ -207,32 +217,38 @@ Representations of simple things
For helper functions see "Vector helpers".
### pointed_thing
## `pointed_thing`
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
* `{type="object", id=ObjectID}`
Flag Specifier Format
---------------------
# Flag Specifier Format
Refer to `lua_api.md`.
Formspec
--------
# Formspec
Formspec defines a menu. It is a string, with a somewhat strange format.
For details, refer to `lua_api.md`.
Spatial Vectors
---------------
# Spatial Vectors
Refer to `lua_api.md`.
Helper functions
----------------
# Helper Functions
* `dump2(obj, name="_", dumped={})`
* Return object serialized as a string, handles reference loops
* Return object serialized as a string, handles reference loops
* `dump(obj, dumped={})`
* Return object serialized as a string
* `math.hypot(x, y)`
@ -264,21 +280,22 @@ Helper functions
* `table.copy(table)`: returns a table
* returns a deep copy of `table`
Minetest namespace reference
------------------------------
### Utilities
# Minetest Namespace Reference
## Utilities
* `minetest.get_current_modname()`: returns the currently loading mod's name, when we are loading a mod
* `minetest.get_modpath(modname)`: returns virtual path of given mod including
the trailing separator. This is useful to load additional Lua files
contained in your mod:
e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")`
the trailing separator. This is useful to load additional Lua files
contained in your mod:
e.g. `dofile(minetest.get_modpath(minetest.get_current_modname()) .. "stuff.lua")`
* `minetest.get_language()`: returns two strings
* the current gettext locale
* the current language code (the same as used for client-side translations)
* the current gettext locale
* the current language code (the same as used for client-side translations)
* `minetest.get_version()`: returns a table containing components of the
engine version. Components:
engine version. Components:
* `project`: Name of the project, eg, "Minetest"
* `string`: Simple version, eg, "1.2.3-dev"
* `hash`: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
@ -295,22 +312,24 @@ Minetest namespace reference
ColorString. If the ColorSpec is invalid, returns `nil`.
* `colorspec`: The ColorSpec to convert
* `minetest.get_csm_restrictions()`: returns a table of `Flags` indicating the
restrictions applied to the current mod.
* If a flag in this table is set to true, the feature is RESTRICTED.
* Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`,
`read_nodedefs`, `lookup_nodes`, `read_playerinfo`
restrictions applied to the current mod.
* If a flag in this table is set to true, the feature is RESTRICTED.
* Possible flags: `load_client_mods`, `chat_messages`, `read_itemdefs`,
`read_nodedefs`, `lookup_nodes`, `read_playerinfo`
* `minetest.urlencode(str)`: Encodes non-unreserved URI characters by a
percent sign followed by two hex digits. See
[RFC 3986, section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
### Logging
## Logging
* `minetest.debug(...)`
* Equivalent to `minetest.log(table.concat({...}, "\t"))`
* `minetest.log([level,] text)`
* `level` is one of `"none"`, `"error"`, `"warning"`, `"action"`,
`"info"`, or `"verbose"`. Default is `"none"`.
`"info"`, or `"verbose"`. Default is `"none"`.
## Global Callback Registration Functions
### Global callback registration functions
Call these functions only at load time!
* `minetest.register_globalstep(function(dtime))`
@ -319,9 +338,10 @@ Call these functions only at load time!
* Called just after mods have finished loading.
* `minetest.register_on_shutdown(function())`
* Called before client shutdown
* **Warning**: If the client terminates abnormally (i.e. crashes), the registered
callbacks **will likely not be run**. Data should be saved at
semi-frequent intervals as well as on server shutdown.
> [!WARNING]
> If the client terminates abnormally (i.e. crashes), the registered
> callbacks **will likely not be run**. Data should be saved at
> semi-frequent intervals as well as on server shutdown.
* `minetest.register_on_receiving_chat_message(function(message))`
* Called always when a client receive a message
* Return `true` to mark the message as handled, which means that it will not be shown to chat
@ -368,19 +388,21 @@ Call these functions only at load time!
* If message comes from a server mod, `sender` field is an empty string.
* `minetest.register_on_modchannel_signal(function(channel_name, signal))`
* Called when a valid incoming mod channel signal is received
* Signal id permit to react to server mod channel events
* Signal ID permit to react to server mod channel events
* Possible values are:
0: join_ok
1: join_failed
2: leave_ok
3: leave_failed
4: event_on_not_joined_channel
5: state_changed
0: `join_ok`
1: `join_failed`
2: `leave_ok`
3: `leave_failed`
4: `event_on_not_joined_channel`
5: `state_changed`
* `minetest.register_on_inventory_open(function(inventory))`
* Called when the local player open inventory
* Newest functions are called first
* If any function returns true, inventory doesn't open
### Sounds
## Sounds
* `minetest.sound_play(spec, parameters)`: returns a handle
* `spec` is a `SimpleSoundSpec`
* `parameters` is a sound parameter table
@ -393,20 +415,18 @@ Call these functions only at load time!
the sound volume.
* `gain` the target gain for the fade.
### Timing
## Timing
* `minetest.after(time, func, ...)`
* Call the function `func` after `time` seconds, may be fractional
* Optional: Variable number of arguments that are passed to `func`
* Jobs set for earlier times are executed earlier. If multiple jobs expire
at exactly the same time, then they expire in the order in which they were
registered. This basically just applies to jobs registered on the same
step with the exact same delay.
* `minetest.get_us_time()`
* Returns time with microsecond precision. May not return wall time.
* `minetest.get_timeofday()`
* Returns the time of day: `0` for midnight, `0.5` for midday
### Map
## Map
* `minetest.get_node_or_nil(pos)`
* Returns the node at the given position as table in the format
`{name="node_name", param1=0, param2=0}`, returns `nil`
@ -461,7 +481,8 @@ Call these functions only at load time!
* `minetest.get_node_max_level(pos)`
* get max available level for leveled node
### Player
## Player
* `minetest.send_chat_message(message)`
* Act as if `message` was typed by the player into the terminal.
* `minetest.run_server_chatcommand(cmd, param)`
@ -471,14 +492,16 @@ Call these functions only at load time!
* `minetest.localplayer`
* Reference to the LocalPlayer object. See [`LocalPlayer`](#localplayer) class reference for methods.
### Privileges
## Privileges
* `minetest.get_privilege_list()`
* Returns a list of privileges the current player has in the format `{priv1=true,...}`
* `minetest.string_to_privs(str)`: returns `{priv1=true,...}`
* `minetest.privs_to_string(privs)`: returns `"priv1,priv2,..."`
* Convert between two privilege representations
### Client Environment
## Client Environment
* `minetest.get_player_names()`
* Returns list of player names on server (nil if CSM_RF_READ_PLAYERINFO is enabled by server)
* `minetest.disconnect()`
@ -489,20 +512,25 @@ Call these functions only at load time!
* `minetest.send_respawn()`
* Sends a respawn request to the server.
### Storage API
## Storage API
* `minetest.get_mod_storage()`:
* returns reference to mod private `StorageRef`
* must be called during mod load time
### Mod channels
## Mod Channels
![Mod channels communication scheme](docs/mod channels.png)
* `minetest.mod_channel_join(channel_name)`
* Client joins channel `channel_name`, and creates it, if necessary. You
should listen from incoming messages with `minetest.register_on_modchannel_message`
call to receive incoming messages. Warning, this function is asynchronous.
call to receive incoming messages.
> [!WARNING]
> This function is asynchronous.
## Particles
### Particles
* `minetest.add_particle(particle definition)`
* `minetest.add_particlespawner(particlespawner definition)`
@ -512,7 +540,8 @@ Call these functions only at load time!
* `minetest.delete_particlespawner(id)`
* Delete `ParticleSpawner` with `id` (return value from `minetest.add_particlespawner`)
### Misc.
## Misc.
* `minetest.parse_json(string[, nullvalue])`: returns something
* Convert a string containing JSON data into the Lua equivalent
* `nullvalue`: returned in place of the JSON null; defaults to `nil`
@ -523,20 +552,21 @@ Call these functions only at load time!
* Convert a Lua table into a JSON string
* styled: Outputs in a human-readable format if this is set, defaults to false
* Unserializable things like functions and userdata are saved as null.
* **Warning**: JSON is more strict than the Lua table format.
1. You can only use strings and positive integers of at least one as keys.
2. You cannot mix string and integer keys.
This is due to the fact that JSON has two distinct array and object values.
* Example: `write_json({10, {a = false}})`, returns `"[10, {\"a\": false}]"`
> [!WARNING]
> JSON is more strict than the Lua table format.
> 1. You can only use strings and positive integers of at least one as keys.
> 2. You cannot mix string and integer keys. This is due to the fact that JSON has
> two distinct array and object values.
* `minetest.serialize(table)`: returns a string
* Convert a table containing tables, strings, numbers, booleans and `nil`s
into string form readable by `minetest.deserialize`
* Example: `serialize({foo='bar'})`, returns `'return { ["foo"] = "bar" }'`
* Example: `serialize({foo='bar'})`, returns `'return {["foo"] = "bar"}'`
* `minetest.deserialize(string)`: returns a table
* Convert a string returned by `minetest.deserialize` into a table
* `string` is loaded in an empty sandbox environment.
* Will load functions, but they cannot access the global environment.
* Example: `deserialize('return { ["foo"] = "bar" }')`, returns `{foo='bar'}`
* Example: `deserialize('return {["foo"] = "bar"}')`, returns `{foo='bar'}`
* Example: `deserialize('print("foo")')`, returns `nil` (function call fails)
* `error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)`
* `minetest.compress(data, method, ...)`: returns `compressed_data`
@ -578,33 +608,37 @@ Call these functions only at load time!
* `minetest.global_exists(name)`
* Checks if a global variable has been set, without triggering a warning.
### UI
## UI
* `minetest.ui.minimap`
* Reference to the minimap object. See [`Minimap`](#minimap) class reference for methods.
* If client disabled minimap (using enable_minimap setting) this reference will be nil.
* `minetest.camera`
* Reference to the camera object. See [`Camera`](#camera) class reference for methods.
* `minetest.show_formspec(formname, formspec)` : returns true on success
* Shows a formspec to the player
* Shows a formspec to the player
* `minetest.display_chat_message(message)` returns true on success
* Shows a chat message to the current player.
* Shows a chat message to the current player.
Setting-related
---------------
# Setting-Related
* `minetest.settings`: Settings object containing all of the settings from the
main config file (`minetest.conf`). Check lua_api.md for class reference.
main config file (`minetest.conf`). Check `lua_api.md` for class reference.
* `minetest.setting_get_pos(name)`: Loads a setting from the main settings and
parses it as a position (in the format `(1,2,3)`). Returns a position or nil.
Class reference
---------------
### ModChannel
# Class Reference
## `ModChannel`
An interface to use mod channels on client and server
#### Methods
### Methods
* `leave()`: leave the mod channel.
* Client leaves channel `channel_name`.
* No more incoming or outgoing messages can be sent to this channel from client mods.
@ -615,10 +649,12 @@ An interface to use mod channels on client and server
* If mod channel is not writable or invalid, message will be dropped.
* Message size is limited to 65535 characters by protocol.
### Minimap
## Minimap
An interface to manipulate minimap on client UI
#### Methods
### Methods
* `show()`: shows the minimap (if not disabled by server)
* `hide()`: hides the minimap
* `set_pos(pos)`: sets the minimap position on screen
@ -630,11 +666,13 @@ An interface to manipulate minimap on client UI
* `set_shape(shape)`: Sets the minimap shape. (0 = square, 1 = round)
* `get_shape()`: Gets the minimap shape. (0 = square, 1 = round)
### Camera
## Camera
An interface to get or set information about the camera and camera-node.
Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.
#### Methods
### Methods
* `set_camera_mode(mode)`
* Pass `0` for first-person, `1` for third person, and `2` for third person front
* `get_camera_mode()`
@ -664,7 +702,8 @@ Please do not try to access the reference until the camera is initialized, other
* `get_aspect_ratio()`
* Returns aspect ratio of screen
### LocalPlayer
## `LocalPlayer`
An interface to retrieve information about the player.
This object will only be available after the client is initialized. Earlier accesses will yield a `nil` value.
@ -698,7 +737,6 @@ Methods:
* returns true if player is swimming in vertical
* `get_physics_override()`
* returns:
```lua
{
speed = float,
@ -719,7 +757,6 @@ Methods:
new_move = boolean,
}
```
* `get_override_pos()`
* returns override position
* `get_last_pos()`
@ -739,7 +776,6 @@ Methods:
default = float,
}
```
* `get_movement_speed()`
* returns player's speed in different environments
(note: does not take physics overrides into account):
@ -753,7 +789,6 @@ Methods:
climb = float,
}
```
* `get_movement()`
* returns player's movement in different environments
(note: does not take physics overrides into account):
@ -766,14 +801,12 @@ Methods:
gravity = float,
}
```
* `get_last_look_horizontal()`:
* returns last look horizontal angle
* `get_last_look_vertical()`:
* returns last look vertical angle
* `get_control()`:
* returns pressed player controls
```lua
{
up = boolean,
@ -788,7 +821,6 @@ Methods:
place = boolean,
}
```
* `get_armor_groups()`
* returns a table with the armor group ratings
* `hud_add(definition)`
@ -796,23 +828,21 @@ Methods:
* See [`HUD definition`](#hud-definition-hud_add-hud_get)
* `hud_get(id)`
* returns the [`definition`](#hud-definition-hud_add-hud_get) of the HUD with that ID number or `nil`, if non-existent.
* `hud_get_all()`:
* Returns a table in the form `{ [id] = HUD definition, [id] = ... }`.
* A mod should keep track of its introduced IDs and only use this to access foreign elements.
* It is discouraged to change foreign HUD elements.
* `hud_remove(id)`
* remove the HUD element of the specified id, returns `true` on success
* remove the HUD element of the specified ID, returns `true` on success
* `hud_change(id, stat, value)`
* change a value of a previously added HUD element
* element `stat` values: `position`, `name`, `scale`, `text`, `number`, `item`, `dir`
* Returns `true` on success, otherwise returns `nil`
### Settings
## `Settings`
An interface to read config files in the format of `minetest.conf`.
It can be created via `Settings(filename)`.
#### Methods
### Methods
* `get(key)`: returns a value
* `get_bool(key)`: returns a boolean
* `set(key, value)`
@ -822,11 +852,13 @@ It can be created via `Settings(filename)`.
* write changes to file
* `to_table()`: returns `{[key1]=value1,...}`
### NodeMetaRef
## `NodeMetaRef`
Node metadata: reference extra data and functionality stored in a node.
Can be obtained via `minetest.get_meta(pos)`.
#### Methods
### Methods
* `get_string(name)`
* `get_int(name)`
* `get_float(name)`
@ -834,7 +866,7 @@ Can be obtained via `minetest.get_meta(pos)`.
* `fields`: key-value storage
* `inventory`: `{list1 = {}, ...}}`
### `Raycast`
## `Raycast`
A raycast on the map. It works with selection boxes.
Can be used as an iterator in a for loop as:
@ -857,19 +889,21 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or
* `objects`: if false, only nodes will be returned. Default is true.
* `liquids`: if false, liquid nodes won't be returned. Default is false.
#### Methods
### Methods
* `next()`: returns a `pointed_thing` with exact pointing location
* Returns the next thing pointed by the ray or nil.
-----------------
### Definitions
* `minetest.get_node_def(nodename)`
* Returns [node definition](#node-definition) table of `nodename`
* `minetest.get_item_def(itemstring)`
* Returns item definition table of `itemstring`
#### Node Definition
# Definitions
* `minetest.get_node_def(nodename)`
* Returns [node definition](#node-definition) table of `nodename`
* `minetest.get_item_def(itemstring)`
* Returns item definition table of `itemstring`
## Node Definition
```lua
{
@ -931,7 +965,7 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or
}
```
#### Item Definition
## Item Definition
```lua
{
@ -953,9 +987,8 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or
node_placement_prediction = string -- Node placed in client until server catches up
}
```
-----------------
### Chat command definition (`register_chatcommand`)
## Chat Command Definition (`register_chatcommand`)
```lua
{
@ -966,23 +999,25 @@ It can be created via `Raycast(pos1, pos2, objects, liquids)` or
}
```
### Server info
## Server Information
```lua
{
address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
ip = "203.0.113.156", -- The IP address of the server.
port = 30000, -- The port the client is connected to.
protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0.
address = "minetest.example.org", -- The domain name/IP address of a remote server or "" for a local server.
ip = "203.0.113.156", -- The IP address of the server.
port = 30000, -- The port the client is connected to.
protocol_version = 30 -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0.
}
```
### HUD Definition (`hud_add`, `hud_get`)
## HUD Definition (`hud_add`, `hud_get`)
Refer to `lua_api.md`.
Escape sequences
----------------
# Escape Sequences
Most text can contain escape sequences that can for example color the text.
There are a few exceptions: tab headers, dropdowns and vertical labels can't.
The following functions provide escape sequences:
@ -1005,19 +1040,25 @@ The following functions provide escape sequences:
* `minetest.strip_colors(str)`
* Removes all color escape sequences.
`ColorString`
-------------
# `ColorString`
Refer to `lua_api.md`.
`Color`
-------------
# `Color`
`{a = alpha, r = red, g = green, b = blue}` defines an ARGB8 color.
### Particle definition (`add_particle`)
As documented in `lua_api.md`, except for obvious reasons, the `playername` field is not supported.
As documented in `lua_api.md`, except the `playername` field is not supported.
### `ParticleSpawner` definition (`add_particlespawner`)
As documented in `lua_api.md`, except for obvious reasons, the `playername` field is not supported.
As documented in `lua_api.md`, except the `playername` field is not supported.

11
doc/compiling/README.md
View File

@ -1,11 +1,10 @@
# Compiling Minetest
- [Compiling on GNU/Linux](linux.md)
- [Compiling on Windows](windows.md)
- [Compiling on MacOS](macos.md)
* [Compiling on GNU/Linux](linux.md)
* [Compiling on Windows](windows.md)
* [Compiling on MacOS](macos.md)
## CMake options
## CMake Options
General options and their default values:
@ -82,4 +81,4 @@ Library specific options:
ZLIB_LIBRARY - Path to libz.a/libz.so/zlib.lib
ZSTD_DLL - Only on Windows; path to libzstd.dll
ZSTD_INCLUDE_DIR - Directory that contains zstd.h
ZSTD_LIBRARY - Path to libzstd.a/libzstd.so/ztd.lib
ZSTD_LIBRARY - Path to libzstd.a/libzstd.so/ztd.lib

18
doc/compiling/linux.md
View File

@ -46,7 +46,7 @@ For Void users:
## Download
You can install Git for easily keeping your copy up to date.
If you don’t want Git, read below on how to get the source without Git.
If you don't want Git, read below on how to get the source without Git.
This is an example for installing Git on Debian/Ubuntu:
sudo apt install git
@ -57,11 +57,11 @@ For Fedora users:
For Arch users:
sudo pacman -S git
sudo pacman -S git
For Alpine users:
sudo apk add git
sudo apk add git
For Void users:
@ -89,10 +89,10 @@ Run it:
./bin/minetest
- Use `cmake . -LH` to see all CMake options and their current state.
- If you want to install it system-wide (or are making a distribution package),
* Use `cmake . -LH` to see all CMake options and their current state.
* If you want to install it system-wide (or are making a distribution package),
you will want to use `-DRUN_IN_PLACE=FALSE`.
- You can build a bare server by specifying `-DBUILD_SERVER=TRUE`.
- You can disable the client build by specifying `-DBUILD_CLIENT=FALSE`.
- You can select between Release and Debug build by `-DCMAKE_BUILD_TYPE=<Debug or Release>`.
- Debug build is slower, but gives much more useful output in a debugger.
* You can build a bare server by specifying `-DBUILD_SERVER=TRUE`.
* You can disable the client build by specifying `-DBUILD_CLIENT=FALSE`.
* You can select between Release and Debug build by `-DCMAKE_BUILD_TYPE=<Debug or Release>`.
* Debug build is slower, but gives much more useful output in a debugger.

10
doc/compiling/macos.md
View File

@ -2,12 +2,12 @@
## Requirements
- [Homebrew](https://brew.sh/)
- [Git](https://git-scm.com/downloads)
* [Homebrew](https://brew.sh/)
* [Git](https://git-scm.com/downloads)
Install dependencies with homebrew:
```
```bash
brew install cmake freetype gettext gmp hiredis jpeg-turbo jsoncpp leveldb libogg libpng libvorbis luajit zstd gettext
```
@ -40,6 +40,6 @@ codesign --force --deep -s - macos/minetest.app
## Run
```
```bash
open ./build/macos/minetest.app
```
```

30
doc/compiling/windows.md
View File

@ -2,35 +2,33 @@
## Requirements
- [Visual Studio 2015 or newer](https://visualstudio.microsoft.com)
- [CMake](https://cmake.org/download/)
- [vcpkg](https://github.com/Microsoft/vcpkg)
- [Git](https://git-scm.com/downloads)
* [Visual Studio 2015 or newer](https://visualstudio.microsoft.com)
* [CMake](https://cmake.org/download/)
* [vcpkg](https://github.com/Microsoft/vcpkg)
* [Git](https://git-scm.com/downloads)
## Compiling and installing the dependencies
## Compiling and Installing the Dependencies
It is highly recommended to use vcpkg as package manager.
After you successfully built vcpkg you can easily install the required libraries:
```powershell
vcpkg install zlib zstd curl[winssl] openal-soft libvorbis libogg libjpeg-turbo sqlite3 freetype luajit gmp jsoncpp gettext sdl2 --triplet x64-windows
```
- `curl` is optional, but required to read the serverlist, `curl[winssl]` is required to use the content store.
- `openal-soft`, `libvorbis` and `libogg` are optional, but required to use sound.
- `luajit` is optional, it replaces the integrated Lua interpreter with a faster just-in-time interpreter.
- `gmp` and `jsoncpp` are optional, otherwise the bundled versions will be compiled
- `gettext` is optional, but required to use translations.
* `curl` is optional, but required to read the serverlist, `curl[winssl]` is required to use the content store.
* `openal-soft`, `libvorbis` and `libogg` are optional, but required to use sound.
* `luajit` is optional, it replaces the integrated Lua interpreter with a faster just-in-time interpreter.
* `gmp` and `jsoncpp` are optional, otherwise the bundled versions will be compiled.
There are other optional libraries, but they are not tested if they can build and link correctly.
Use `--triplet` to specify the target triplet, e.g. `x64-windows` or `x86-windows`.
## Compile Minetest
### a) Using the vcpkg toolchain and CMake GUI
### a) Using the `vcpkg` toolchain and CMake GUI
1. Start up the CMake GUI
2. Select **Browse Source...** and select DIR/minetest
@ -47,7 +45,7 @@ Use `--triplet` to specify the target triplet, e.g. `x64-windows` or `x86-window
13. Click **Open Project**
14. Compile Minetest inside Visual studio.
### b) Using the vcpkg toolchain and the commandline
### b) Using the `vcpkg` Toolchain and the Command Line
Run the following script in PowerShell:
@ -55,8 +53,8 @@ Run the following script in PowerShell:
cmake . -G"Visual Studio 15 2017 Win64" -DCMAKE_TOOLCHAIN_FILE=D:/vcpkg/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_GETTEXT=OFF -DENABLE_CURSES=OFF
cmake --build . --config Release
```
Make sure that the right compiler is selected and the path to the vcpkg toolchain is correct.
Make sure that the right compiler is selected and the path to the vcpkg toolchain is correct.
## Windows Installer using WiX Toolset
@ -69,4 +67,4 @@ In the Visual Studio 2017 Installer select **Optional Features -> WiX Toolset**.
Build the binaries as described above, but make sure you unselect `RUN_IN_PLACE`.
Open the generated project file with Visual Studio. Right-click **Package** and choose **Generate**.
It may take some minutes to generate the installer.
It may take some minutes to generate the installer.

22
doc/developing/README.md
View File

@ -1,4 +1,4 @@
# Developer documentation
# Developer Documentation
## Wiki
@ -6,18 +6,18 @@ Some important development docs are found in the wiki: https://dev.minetest.net/
Notable pages:
- [Releasing Minetest](https://dev.minetest.net/Releasing_Minetest)
- [Engine translations](https://dev.minetest.net/Translation#Maintaining_engine_translations)
- [Changelog](https://dev.minetest.net/Changelog)
- [Organisation](https://dev.minetest.net/Organisation)
- [Code style guidelines](https://dev.minetest.net/Code_style_guidelines)
* [Releasing Minetest](https://dev.minetest.net/Releasing_Minetest)
* [Engine translations](https://dev.minetest.net/Translation#Maintaining_engine_translations)
* [Changelog](https://dev.minetest.net/Changelog)
* [Organisation](https://dev.minetest.net/Organisation)
* [Code style guidelines](https://dev.minetest.net/Code_style_guidelines)
## In this folder
## In This Folder
- [Developing minetestserver with Docker](docker.md)
- [Android tips & tricks](android.md)
- [OS/library compatibility policy](os-compatibility.md)
- [Miscellaneous](misc.md)
* [Developing minetestserver with Docker](docker.md)
* [Android Tips & Tricks](android.md)
* [OS/library Compatability Policy](os-compatibility.md)
* [Miscellaneous](misc.md)
## IRC

21
doc/direction.md
View File

@ -1,6 +1,6 @@
# Minetest Direction Document
## 1. Long-term Roadmap
## 1. Long-Term Roadmap
The long-term roadmaps, aims, and guiding philosophies are set out using the
following documents:
@ -10,7 +10,7 @@ following documents:
* [celeron55's comment in "A clear mission statement for Minetest is missing"](https://github.com/minetest/minetest/issues/3476#issuecomment-167399287)
* [Core developer to-do/wish lists](https://forum.minetest.net/viewforum.php?f=7)
## 2. Medium-term Roadmap
## 2. Medium-Term Roadmap
These are the current medium-term goals for Minetest development, in no
particular order.
@ -25,22 +25,22 @@ approval within a month, issues can be used for preapproval.
Bug fixes are exempt for this, and are always accepted and prioritized.
See [CONTRIBUTING.md](../.github/CONTRIBUTING.md) for more info.
### 2.1 Rendering/Graphics improvements
### 2.1 Rendering/Graphics Improvements
The priority is fixing the issues, performance, and general correctness.
Once that is done, fancier features can be worked on, such as water shaders,
shadows, and improved lighting.
Examples include
[transparency sorting](https://github.com/minetest/minetest/issues/95),
[particle performance](https://github.com/minetest/minetest/issues/1414),
[general view distance](https://github.com/minetest/minetest/issues/7222).
Examples include:
* [Transparency sorting](https://github.com/minetest/minetest/issues/95)
* [Particle performance](https://github.com/minetest/minetest/issues/1414)
* [General view distance](https://github.com/minetest/minetest/issues/7222)
This includes work on maintaining
[our Irrlicht fork](https://github.com/minetest/irrlicht), and switching to
alternative libraries to replace Irrlicht functionality as needed
### 2.2 Internal code refactoring
### 2.2 Internal Code Refactoring
To ensure sustainable development, Minetest's code needs to be
[refactored and improved](https://github.com/minetest/minetest/pulls?q=is%3Aopen+sort%3Aupdated-desc+label%3A%22Code+quality%22+).
@ -61,9 +61,10 @@ longer be bundled by default.
The UI code is undergoing rapid changes, so it is especially important to make
an issue for any large changes before spending lots of time.
### 2.4 Object and entity improvements
### 2.4 Object and Entity Improvements
There are still a significant number of issues with objects.
Collisions,
[performance](https://github.com/minetest/minetest/issues/6453),
API convenience, and discrepancies between players and entities.
API convenience, and discrepancies between players and entities are some
examples.

2381
doc/lua_api.md
View File

File diff suppressed because it is too large Load Diff

222
doc/menu_lua_api.md
View File

@ -1,24 +1,22 @@
Minetest Lua Mainmenu API Reference 5.9.0
=========================================
# Minetest Lua Mainmenu API Reference 5.8.0
Introduction
-------------
## Introduction
The main menu is defined as a formspec by Lua in `builtin/mainmenu/`
Description of formspec language to show your menu is in `lua_api.md`
Callbacks
---------
# Callbacks
* `core.button_handler(fields)`: called when a button is pressed.
* `fields` = `{name1 = value1, name2 = value2, ...}`
* `fields` = `{name1 = value1, name2 = value2, ...}`
* `core.event_handler(event)`
* `event`: `"MenuQuit"`, `"KeyEnter"`, `"ExitButton"` or `"EditBoxEnter"`
* `event`: `"MenuQuit"`, `"KeyEnter"`, `"ExitButton"` or `"EditBoxEnter"`
Gamedata
--------
# Gamedata
The "gamedata" table is read when calling `core.start()`. It should contain:
@ -34,71 +32,70 @@ The "gamedata" table is read when calling `core.start()`. It should contain:
```
Functions
---------
# Functions
* `core.start()`
* start game session
* start game session
* `core.close()`
* exit engine
* exit engine
* `core.get_min_supp_proto()`
* returns the minimum supported network protocol version
* returns the minimum supported network protocol version
* `core.get_max_supp_proto()`
* returns the maximum supported network protocol version
* returns the maximum supported network protocol version
* `core.open_url(url)`
* opens the URL in a web browser, returns false on failure.
* Must begin with http:// or https://
* opens the URL in a web browser, returns false on failure.
* Must begin with http:// or https://
* `core.open_dir(path)`
* opens the path in the system file browser/explorer, returns false on failure.
* Must be an existing directory.
* opens the path in the system file browser/explorer, returns false on failure.
* Must be an existing directory.
* `core.share_file(path)`
* Android only. Shares file using the share popup
* Android only. Shares file using the share popup
* `core.get_version()` (possible in async calls)
* returns current core version
* returns current core version
Filesystem
----------
# Filesystem
* `core.get_builtin_path()`
* returns path to builtin root
* returns path to builtin root
* `core.create_dir(absolute_path)` (possible in async calls)
* `absolute_path` to directory to create (needs to be absolute)
* returns true/false
* `absolute_path` to directory to create (needs to be absolute)
* returns true/false
* `core.delete_dir(absolute_path)` (possible in async calls)
* `absolute_path` to directory to delete (needs to be absolute)
* returns true/false
* `absolute_path` to directory to delete (needs to be absolute)
* returns true/false
* `core.copy_dir(source,destination,keep_source)` (possible in async calls)
* `source` folder
* `destination` folder
* `keep_source` DEFAULT true --> if set to false `source` is deleted after copying
* returns true/false
* `source` folder
* `destination` folder
* `keep_source` DEFAULT true --> if set to false `source` is deleted after copying
* returns true/false
* `core.is_dir(path)` (possible in async calls)
* returns true if `path` is a valid dir
* returns true if `path` is a valid dir
* `core.extract_zip(zipfile,destination)` [unzip within path required]
* `zipfile` to extract
* `destination` folder to extract to
* returns true/false
* `zipfile` to extract
* `destination` folder to extract to
* returns true/false
* `core.sound_play(spec, looped)` -> handle
* `spec` = `SimpleSoundSpec` (see `lua_api.md`)
* `looped` = bool
* `spec` = `SimpleSoundSpec` (see `lua_api.md`)
* `looped` = bool
* `handle:stop()` or `core.sound_stop(handle)`
* `core.get_video_drivers()`
* get list of video drivers supported by engine (not all modes are guaranteed to work)
* returns list of available video drivers' settings name and 'friendly' display name
e.g. `{ {name="opengl", friendly_name="OpenGL"}, {name="software", friendly_name="Software Renderer"} }`
* first element of returned list is guaranteed to be the NULL driver
* get list of video drivers supported by engine (not all modes are guaranteed to work)
* returns list of available video drivers' settings name and 'friendly' display name
e.g. `{{name="opengl", friendly_name="OpenGL"}, {name="software", friendly_name="Software Renderer"}}`
* first element of returned list is guaranteed to be the NULL driver
* `core.get_mapgen_names([include_hidden=false])` -> table of map generator algorithms
registered in the core (possible in async calls)
* `core.get_cache_path()` -> path of cache
* `core.get_temp_path([param])` (possible in async calls)
* `param`=true: returns path to a newly created temporary file
* `param == true`: returns path to a newly created temporary file
* otherwise: returns path to a newly created temporary folder
HTTP Requests
-------------
# HTTP Requests
* `core.download_file(url, target)` (possible in async calls)
* `url` to download, and `target` to store to
@ -116,7 +113,7 @@ HTTP Requests
* `HTTPApiTable.fetch_async_get(handle)`: returns `HTTPRequestResult`
* Return response data for given asynchronous HTTP request
### `HTTPRequest` definition
## `HTTPRequest` Definition
Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
@ -137,7 +134,7 @@ Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
-- Optional, if specified replaces the default minetest user agent with
-- given string
extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
extra_headers = {"Accept-Language: en-us", "Accept-Charset: utf-8"},
-- Optional, if specified adds additional headers to the HTTP request.
-- You must make sure that the header strings follow HTTP specification
-- ("Key: Value").
@ -148,7 +145,7 @@ Used by `HTTPApiTable.fetch` and `HTTPApiTable.fetch_async`.
}
```
### `HTTPRequestResult` definition
## `HTTPRequestResult` Definition
Passed to `HTTPApiTable.fetch` callback. Returned by
`HTTPApiTable.fetch_async_get`.
@ -173,52 +170,51 @@ Passed to `HTTPApiTable.fetch` callback. Returned by
```
Formspec
--------
# Formspec
* `core.update_formspec(formspec)`
* `core.get_table_index(tablename)` -> index
* can also handle textlists
* can also handle textlists
* `core.formspec_escape(string)` -> string
* escapes characters [ ] \ , ; that cannot be used in formspecs
* escapes characters [ ] \ , ; that cannot be used in formspecs
* `core.explode_table_event(string)` -> table
* returns e.g. `{type="CHG", row=1, column=2}`
* `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
* returns e.g. `{type="CHG", row=1, column=2}`
* `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
* `core.explode_textlist_event(string)` -> table
* returns e.g. `{type="CHG", index=1}`
* `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
* returns e.g. `{type="CHG", index=1}`
* `type`: "INV" (no row selected), "CHG" (selected) or "DCL" (double-click)
* `core.set_formspec_prepend(formspec)`
* `formspec`: string to be added to every mainmenu formspec, to be used for theming.
* `formspec`: string to be added to every mainmenu formspec, to be used for theming.
GUI
---
# GUI
* `core.set_background(type,texturepath,[tile],[minsize])`
* `type`: "background", "overlay", "header" or "footer"
* `tile`: tile the image instead of scaling (background only)
* `minsize`: minimum tile size, images are scaled to at least this size prior
doing tiling (background only)
* `type`: "background", "overlay", "header" or "footer"
* `tile`: tile the image instead of scaling (background only)
* `minsize`: minimum tile size, images are scaled to at least this size prior
doing tiling (background only)
* `core.set_clouds(<true/false>)`
* `core.set_topleft_text(text)`
* `core.show_keys_menu()`
* `core.show_path_select_dialog(formname, caption, is_file_select)`
* shows a path select dialog
* `formname` is base name of dialog response returned in fields
- if dialog was accepted `"_accepted"`
* shows a path select dialog
* `formname` is base name of dialog response returned in fields
* if dialog was accepted `"_accepted"`
will be added to fieldname containing the path
- if dialog was canceled `"_cancelled"`
* if dialog was canceled `"_cancelled"`
will be added to fieldname value is set to formname itself
* if `is_file_select` is `true`, a file and not a folder will be selected
* returns nil or selected file/folder
* if `is_file_select` is `true`, a file and not a folder will be selected
* returns nil or selected file/folder
* `core.get_active_driver()`:
* technical name of active video driver, e.g. "opengl"
* technical name of active video driver, e.g. "opengl"
* `core.get_active_renderer()`:
* name of current renderer, e.g. "OpenGL 4.6"
* name of current renderer, e.g. "OpenGL 4.6"
* `core.get_active_irrlicht_device()`:
* name of current irrlicht device, e.g. "SDL"
* name of current irrlicht device, e.g. "SDL"
* `core.get_window_info()`: Same as server-side `get_player_window_information` API.
```lua
-- Note that none of these things are constant, they are likely to change
-- as the player resizes the window and moves it between monitors
@ -260,8 +256,7 @@ GUI
Content and Packages
--------------------
# Content and Packages
Content - an installed mod, modpack, game, or texture pack (txt)
Package - content which is downloadable from the content db, may or may not be installed.
@ -345,18 +340,19 @@ Package - content which is downloadable from the content db, may or may not be i
will translate "Hello World" into the current user's language
using `mods/mymod/locale/mymod.fr.tr`.
Logging
-------
# Logging
* `core.debug(line)` (possible in async calls)
* Always printed to `stderr` and logfile (`print()` is redirected here)
* Always printed to `stderr` and logfile (`print()` is redirected here)
* `core.log(line)` (possible in async calls)
* `core.log(loglevel, line)` (possible in async calls)
* `loglevel` one of "error", "action", "info", "verbose"
* `loglevel` one of "error", "action", "info", "verbose"
Settings
--------
# Settings
* `core.settings:set(name, value)`
* `core.settings:get(name)` -> string or nil (possible in async calls)
@ -365,14 +361,14 @@ Settings
* `core.settings:save()` -> nil, save all settings to config file
For a complete list of methods of the `Settings` object see
[lua_api.md](https://github.com/minetest/minetest/blob/master/doc/lua_api.md)
[lua_api.md](lua_api.md#methods-18)
Worlds
------
# Worlds
* `core.get_worlds()` -> list of worlds (possible in async calls)
* returns
* returns
```lua
{
[1] = {
@ -386,59 +382,59 @@ Worlds
* `core.delete_world(index)`
Helpers
-------
# Helpers
* `core.get_us_time()`
* returns time with microsecond precision
* returns time with microsecond precision
* `core.gettext(string)` -> string
* look up the translation of a string in the gettext message catalog
* look up the translation of a string in the gettext message catalog
* `fgettext_ne(string, ...)`
* call `core.gettext(string)`, replace "$1"..."$9" with the given
* call `core.gettext(string)`, replace "$1"..."$9" with the given
extra arguments and return the result
* `fgettext(string, ...)` -> string
* same as `fgettext_ne()`, but calls `core.formspec_escape` before returning result
* same as `fgettext_ne()`, but calls `core.formspec_escape` before returning result
* `core.parse_json(string[, nullvalue])` -> something (possible in async calls)
* see `core.parse_json` (`lua_api.md`)
* see `core.parse_json` (`lua_api.md`)
* `dump(obj, dumped={})`
* Return object serialized as a string
* Return object serialized as a string
* `string:split(separator)`
* eg. `string:split("a,b", ",")` == `{"a","b"}`
* eg. `string:split("a,b", ",")` == `{"a","b"}`
* `string:trim()`
* eg. `string.trim("\n \t\tfoo bar\t ")` == `"foo bar"`
* eg. `string.trim("\n \t\tfoo bar\t ")` == `"foo bar"`
* `core.is_yes(arg)` (possible in async calls)
* returns whether `arg` can be interpreted as yes
* returns whether `arg` can be interpreted as yes
* `core.encode_base64(string)` (possible in async calls)
* Encodes a string in base64.
* Encodes a string in base64.
* `core.decode_base64(string)` (possible in async calls)
* Decodes a string encoded in base64.
* Decodes a string encoded in base64.
* `core.urlencode(str)`: Encodes non-unreserved URI characters by a
percent sign followed by two hex digits. See
[RFC 3986, section 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
Async
-----
# Async
* `core.handle_async(async_job,parameters,finished)`
* execute a function asynchronously
* `async_job` is a function receiving one parameter and returning one parameter
* `parameters` parameter table passed to `async_job`
* `finished` function to be called once `async_job` has finished
* execute a function asynchronously
* `async_job` is a function receiving one parameter and returning one parameter
* `parameters` parameter table passed to `async_job`
* `finished` function to be called once `async_job` has finished
the result of `async_job` is passed to this function
### Limitations of Async operations
* No access to global lua variables, don't even try
* Limited set of available functions
e.g. No access to functions modifying menu like `core.start`, `core.close`,
`core.show_path_select_dialog`
## Limitations of Async Operations
* No access to global lua variables, don't even try
* Limited set of available functions, e.g. No access to functions modifying menu
like `core.start`, `core.close`, `core.show_path_select_dialog`
Background music
----------------
# Background Music
The main menu supports background music.
It looks for a `main_menu` sound in `$USER_PATH/sounds`. The same naming
conventions as for normal sounds apply.
This means the player can add a custom sound.
It will be played in the main menu (gain = 1.0), looped.
It will be played in the main menu (gain = 1.0), looped.

3
doc/mkdocs/build.sh
View File

@ -1,7 +1,7 @@
#!/bin/sh -e
# Split lua_api.md on top level headings
cat ../lua_api.md | csplit -sz -f docs/section - '/^=/-1' '{*}'
cat ../lua_api.md | csplit -sz -f docs/section - '/^# /' '{*}'
cat > mkdocs.yml << EOF
site_name: Minetest API Documentation
@ -30,6 +30,7 @@ mv docs/section00 docs/index.md
for f in docs/section*
do
title=$(head -1 $f)
title="${title#??}"
fname=$(echo $title | tr '[:upper:]' '[:lower:]')
fname=$(echo $fname | sed 's/ /-/g')
fname=$(echo $fname | sed "s/'//g").md

60
doc/texture_packs.md
View File

@ -1,11 +1,9 @@
Minetest Texture Pack Reference
===============================
# Minetest Texture Pack Reference
Texture packs allow you to replace textures provided by a mod with your own
textures.
Texture pack directory structure
--------------------------------
## Texture Pack Directory Structure
textures
|-- Texture Pack
@ -17,12 +15,14 @@ Texture pack directory structure
| |-- your_texture_2.png
`-- Another Texture Pack
### Texture Pack
### `Texture Pack`
This is a directory containing the entire contents of a single texture pack.
It can be chosen more or less freely and will also become the name of the
texture pack. The name must not be “base”.
texture pack. The name must not be "base".
### `texture_pack.conf`
A key-value config file with the following keys:
* `name`: The texture pack name. Allows Minetest to determine the texture pack name even if
@ -35,17 +35,20 @@ A key-value config file with the following keys:
See [Translating content meta](lua_api.md#translating-content-meta).
### `description.txt`
**Deprecated**, you should use texture_pack.conf instead.
A file containing a short description of the texture pack to be shown in the
content tab.
### `screenshot.png`
A preview image showing an in-game screenshot of this texture pack; it will be
shown in the texture packs tab. It should have an aspect ratio of 3:2 and a
minimum size of 300×200 pixels.
### `your_texture_1.png`, `your_texture_2.png`, etc.
Any other PNG files will be interpreted as textures. They must have the same
names as the textures they are supposed to override. For example, to override
the apple texture of Minetest Game, add a PNG file named `default_apple.png`.
@ -54,24 +57,18 @@ The custom textures do not necessarily require the same size as their
originals, but this might be required for a few particular textures. When
unsure, just test your texture pack in-game.
Texture modifiers
-----------------
See lua_api.md for texture modifiers
Special textures
----------------
## Special Textures
These texture names are hardcoded into the engine but can also be overwritten
by texture packs. All existing fallback textures can be found in the directory
`textures/base/pack`.
### Gameplay textures
### Gameplay Textures
* `bubble.png`: the bubble texture when the player is drowning
(default size: 12×12)
(default size: 12×12)
* `bubble_gone.png`: like `bubble.png`, but denotes lack of breath
(transparent by default, same size as bubble.png)
(transparent by default, same size as bubble.png)
* `crack_anylength.png`: node overlay texture when digging
@ -88,9 +85,9 @@ by texture packs. All existing fallback textures can be found in the directory
* `halo.png`: used for the node highlighting mesh
* `heart.png`: used to display the health points of the player
(default size: 12×12)
(default size: 12×12)
* `heart_gone.png`: like `heart.png`, but denotes lack of health points
(transparent by default, same size as heart.png)
(transparent by default, same size as heart.png)
* `minimap_mask_round.png`: round minimap mask, white gets replaced by the map
* `minimap_mask_square.png`: mask used for the square minimap
@ -121,10 +118,11 @@ by texture packs. All existing fallback textures can be found in the directory
* `wieldhand.png`: texture of the wieldhand
Note: The default textures of `player.png`, `player_back.png` and `wieldhand.png`
are placeholders intended to be overwritten by the game.
> [!NOTE]
> The default textures of `player.png`, `player_back.png` and `wieldhand.png`
> are placeholders intended to be overwritten by the game.
### Mainmenu textures
### Main Menu Textures
* `menu_bg.png`: used as mainmenu background when the clouds are disabled
* `menu_header.png`: header texture when no texture pack is selected
@ -137,7 +135,7 @@ are placeholders intended to be overwritten by the game.
* `server_flags_favorite.png`: icon for your favorite servers
* `server_flags_pvp.png`: icon for enabled PvP on servers
### Android textures
### Android Textures
* `drop_btn.png`
* `fast_btn.png`
@ -155,8 +153,7 @@ are placeholders intended to be overwritten by the game.
* `rare_controls.png`
* `exit_btn.png`
Texture Overrides
-----------------
## Texture Overrides
You can override the textures of nodes and items from a
texture pack using texture overrides. To do this, create one or
@ -164,23 +161,23 @@ more files in a texture pack called override.txt
Each line in an override.txt file is a rule. It consists of
itemname target texture
itemname target texture
For example,
default:dirt_with_grass sides default_stone.png
default:dirt_with_grass sides default_stone.png
or
default:sword_steel inventory my_steel_sword.png
default:sword_steel inventory my_steel_sword.png
You can list multiple targets on one line as a comma-separated list:
default:tree top,bottom my_special_tree.png
default:tree top,bottom my_special_tree.png
You can use texture modifiers, as usual:
default:dirt_with_grass sides default_stone.png^[brighten
default:dirt_with_grass sides default_stone.png^[brighten
Finally, if a line is empty or starts with '#' it will be considered
a comment and not read as a rule. You can use this to better organize
@ -214,7 +211,7 @@ and 'wield'.
¹ : `N` is an integer [0,255]. Sets align_style = "world" and scale = N on the tile,
refer to lua_api.md for details.
### Using the special targets
### Using the Special Targets
The special* targets only apply to specific drawtypes:
@ -224,8 +221,7 @@ The special* targets only apply to specific drawtypes:
* `glasslike_framed_optional`: Same as `glasslike_framed`
* `plantlike_rooted`: special1 sets the plant's texture
Designing leaves textures for the leaves rendering options
----------------------------------------------------------
## Designing Leaves Textures for the Leaves Rendering Options
Minetest has three modes for rendering leaves nodes if the node has the
`allfaces_optional` drawtype.

57
doc/world_format.md
View File

@ -12,6 +12,8 @@ The block serialization version does not fully specify every aspect of this
format; if compliance with this format is to be checked, it needs to be
done by detecting if the files and data indeed follows it.
# Files
Everything is contained in a directory, the name of which is freeform, but
@ -180,10 +182,13 @@ For `load_mod_<mod>`, the possible values are:
redis_port = 6379 - (optional) Connection port
redis_password = hunter2 - (optional) Server password
# Player File Format
Should be pretty self-explanatory.
> **Note**: Position is in `nodes * 10`
> [!NOTE]
> Position is in `nodes * 10`
Example content:
@ -247,6 +252,8 @@ Example content:
EndInventoryList
EndInventory
# Map File Format
Minetest maps consist of `MapBlock`s, chunks of 16x16x16 nodes.
@ -281,6 +288,7 @@ storing coordinates separately), but the format has been kept unchanged for
that part.
## `map.sqlite`
`map.sqlite` is a `SQLite3` database, containing a single table, called
`blocks`. It looks like this:
@ -329,14 +337,20 @@ The blob is the data that would have otherwise gone into the file.
See below for description.
# MapBlock Serialization Format
> **Notes**:
> * NOTE: Byte order is MSB first (big-endian).
> * NOTE: Zlib data is in such a format that Python's `zlib` at least can
> directly decompress.
> * NOTE: Since version 29 zstd is used instead of zlib. In addition, the entire
> block is first serialized and then compressed (except the version byte).
> [!NOTE]
> Byte order is MSB first (big-endian).
> [!NOTE]
> Zlib data is in such a format that Python's `zlib` at least can
> directly decompress.
> [!NOTE]
> Since version 29 zstd is used instead of zlib. In addition, the entire
> block is first serialized and then compressed (except the version byte).
`u8` version
* map format version number, see serialization.h for the latest number
@ -390,11 +404,11 @@ Timestamp and node ID mappings were introduced in map format version 29.
* `u32` timestamp
* Timestamp when last saved, as seconds from starting the game.
* `0xffffffff` = invalid/unknown timestamp, nothing should be done with the time
difference when loaded
difference when loaded
* `u8` `name_id_mapping_version`
* Should be zero for map format version 29.
* `u16` `num_name_id_mappings`
* foreach `num_name_id_mappings`:
* `u16` `id`
@ -410,7 +424,9 @@ Timestamp and node ID mappings were introduced in map format version 29.
* Always 2
## Node Data
> **Note**: Zlib-compressed before map format version 29
> [!NOTE]
> Zlib-compressed before map format version 29
* If `content_width` is 1:
* `u8[4096]`: `param0` fields
@ -425,7 +441,9 @@ Timestamp and node ID mappings were introduced in map format version 29.
* The location of a node in each of those arrays is `(z*16*16 + y*16 + x)`.
### Node Metadata List
> **Note**: Zlib-compressed before map version format 29
> [!NOTE]
> Zlib-compressed before map version format 29
* Before map format version 23:
* `u16` version (=1)
* `u16` count of metadata
@ -437,7 +455,6 @@ Timestamp and node ID mappings were introduced in map format version 29.
* Since map format version 23:
* `u8` version
> **Note**: Type was `u16` before map format version 23
* = 1 before map format version 28
* = 2 since map format version 28
* `u16` count of metadata
@ -454,11 +471,11 @@ Timestamp and node ID mappings were introduced in map format version 29.
* serialized inventory
## Node Timers
* Map format version 23:
* `u8` unused version (always 0)
* Map format version 24:
> **Note**: Not released as stable
* `u8` `nodetimer_version`
* if `nodetimer_version` == 1:
* `u16` `num_of_timers`
@ -466,6 +483,8 @@ Timestamp and node ID mappings were introduced in map format version 29.
* `u16` timer position (`(z*16*16 + y*16 + x)`)
* `s32` timeout * 1000
* `s32` elapsed * 1000
> [!NOTE]
> Not released as stable
* Since map format version 25:
* `u8` length of the data of a single timer (always 2+4+4=10)
@ -503,6 +522,8 @@ Before map format version 29:
End of File (EOF).
# Format of Nodes
A node is composed of the `u8` fields `param0`, `param1` and `param2`.
@ -517,10 +538,14 @@ Since map format version 24:
The purpose of `param1` and `param2` depend on the definition of the node.
# Name-ID-Mapping
The mapping maps node content IDs to node names.
# Node Metadata Format (Before Map Format Version 23)
The node metadata is serialized depending on the `type_id` field.
@ -560,6 +585,8 @@ The node metadata is serialized depending on the `type_id` field.
* `u8[len]` `owner`
* serialized inventory
# Static Objects
Static objects are persistent freely moving objects in the world.
@ -583,6 +610,8 @@ Since protocol version 37:
* `s32` pitch * 1000
* `s32` roll * 1000
# Itemstring Format
Examples:
@ -598,6 +627,8 @@ Older formats:
The wear value in tools is 0...65535.
# Inventory Serialization Format
* The inventory serialization format is line-based.

2
games/devtest/README.md
View File

@ -17,7 +17,7 @@ This is a basic testing environment that contains a bunch of things to test the
Basically, just create a world and start. A few important things to note:
* Items are gotten from the “Chest of Everything” (`chest_of_everything:chest`)
* Items are gotten from the "Chest of Everything" (`chest_of_everything:chest`)
* When you lost your initial items, type in `/stuff` command to get them back
* By default, Creative Mode activates infinite node placement. This behavior can be changed with the `devtest_infplace` setting
* Use the `/infplace` command to toggle infinite node placement in-game

28
games/devtest/mods/testtools/README.md
View File

@ -5,9 +5,11 @@ Test Tools is a mod for developers that adds a bunch of tools to directly manipu
Here's the list of tools:
## Remover
Removes nodes and non-player entities that you punch.
## Node Setter
Replace a node with another one.
First, punch a node you want to remember.
@ -16,6 +18,7 @@ Then rightclick any other node to replace it with the node you remembered.
If you rightclick while pointing nothing, you can manually enter the node and param2.
## Param2 Tool
Change the value param2 of nodes.
* Punch: Add 1 to param2
@ -23,9 +26,11 @@ Change the value param2 of nodes.
* Place: Subtract 1 from param2
* Sneak+Place: Subtract 8 from param2
Note: Use the debug screen (F5) to see the param2 of the pointed node.
> [!NOTE]
> Use the debug screen (F5) to see the param2 of the pointed node.
## Falling Node Tool
Turns nodes into falling nodes.
Usage:
@ -34,6 +39,7 @@ Usage:
* Place: Try to teleport up to 2 units upwards, then make it fall
## Node Meta Editor
Edit and view metadata of nodes.
Usage:
@ -41,25 +47,28 @@ Usage:
* Punch: Open node metadata editor
## Item Meta Editor
Edit and view metadata of items.
Usage:
* Place/Punch: Opens item metadata editor of the item in the next
inventory slot from the wielded item
inventory slot from the wielded item
## Entity Rotator
Changes the entity rotation (with `set_rotation`).
Usage:
* Punch entity: Rotate yaw
* Punch entity while holding down “Sneak” key: Rotate pitch
* Punch entity while holding down “Special” key (aka “Aux”): Rotate roll
* Punch entity while holding down "Sneak" key: Rotate pitch
* Punch entity while holding down "Special" key (aka "Aux"): Rotate roll
Each usage rotates the entity by 22.5°.
## Entity Spawner
Spawns entities.
Usage:
@ -68,6 +77,7 @@ Usage:
* Place to place selected entity
## Object Property Editor
Edits properties of objects.
Usage:
@ -76,9 +86,10 @@ Usage:
* Punch air to edit properties of your own player object
To edit a property, select it in the list, enter a new value (in Lua syntax)
and hit “Submit”.
and hit "Submit".
## Object Attacher
Allows you to attach an object to another one.
Basic usage:
@ -97,6 +108,7 @@ Hint: To detach all objects nearby you (including on yourself), use the
`/detach` server command.
## Object Mover
Move an object by a given distance.
Usage:
@ -106,6 +118,7 @@ Usage:
* Sneak+place: Decrease move distance
## Children Getter
Shows list of objects that are attached to an object (aka "children") in chat.
Usage:
@ -113,6 +126,7 @@ Usage:
* Punch air: Show your own children
## Entity Visual Scaler
Change visual size of entities
Usage:
@ -121,6 +135,7 @@ Usage:
* Sneak+punch entity to decrease visual size
## Branding Iron
Give an object a temporary name.
Usage:
@ -132,6 +147,7 @@ Usage:
Use `testtools.get_branded_object(name)` to get an ObjRef.
## Note Meta Privatizer
Sets the 'formspec' and 'infotext' metadata fields of a node
to private. This means that clients can no longer access these
fields.
@ -141,6 +157,7 @@ Usage:
* Punch: Set metadata of pointed node to private
## Light Tool
Show light level of node.
Usage:
@ -148,6 +165,7 @@ Usage:
* Place: Show light info of the node that you touched
## Particle Spawner
Spawn a random animated particle.
Usage:

84
util/README_mod_translation_updater.md
View File

@ -1,26 +1,27 @@
# `mod_translation_updater.py`—Minetest Mod Translation Updater
# `mod_translation_updater.py` — Minetest Mod Translation Updater
This Python script is intended for use with localized Minetest mods, i.e., mods that use
`*.tr` and contain translatable strings of the form `S("This string can be translated")`.
It extracts the strings from the mod's source code and updates the localization files
accordingly. It can also be used to update the `*.tr` files in Minetest's `builtin` component.
## Preparing your source code
## Preparing Your Source Code
This script makes assumptions about your source code. Before it is usable, you first have
to prepare your source code accordingly.
### Choosing the textdomain name
### Choosing the `textdomain` Name
It is recommended to set the textdomain name (for `minetest.get_translator`) to be identical
of the mod name as the script will automatically detect it. If the textdomain name differs,
you may have to manually change the `# textdomain:` line of newly generated files.
**Note:** In each `*.tr` file, there **must** be only one textdomain. Multiple textdomains in
the same file are not supported by this script and any additional textdomain line will be
removed.
> [!NOTE]
> In each `*.tr` file, there **must** be only one textdomain. Multiple textdomains in
> the same file are not supported by this script and any additional textdomain line will be
> removed.
### Defining the helper functions
### Defining the Helper Functions
In any source code file with translatable strings, you have to manually define helper
functions at the top with something like `local S = minetest.get_translator("<textdomain>")`.
@ -29,25 +30,27 @@ Optionally, you can also define additional helper functions `FS`, `NS` and `NFS`
Here is the list of all recognized function names. All functions return a string.
* `S`: Returns translation of input. See Minetest's `lua_api.md`. You should always have at
least this function defined.
least this function defined.
* `NS`: Returns the input. Useful to make a string visible to the script without actually
translating it here.
translating it here.
* `FS`: Same as `S`, but returns a formspec-escaped version of the translation of the input.
Supported for convenience.
Supported for convenience.
* `NFS`: Returns a formspec-escaped version of the input, but not translated.
Supported for convenience.
Supported for convenience.
Here is the boilerplate code you have to add at the top of your source code file:
Here is the boilerplate code you can add at the top of your source code file:
local S = minetest.get_translator("<textdomain>")
local NS = function(s) return s end
local FS = function(...) return minetest.formspec_escape(S(...)) end
local NFS = function(s) return minetest.formspec_escape(s) end
```lua
local S = minetest.get_translator("<textdomain>")
local NS = function(s) return s end
local FS = function(...) return minetest.formspec_escape(S(...)) end
local NFS = function(s) return minetest.formspec_escape(s) end
```
Replace `<textdomain>` above and optionally delete `NS`, `FS` and/or `NFS` if you don't need
them.
### Preparing the strings
### Preparing the Strings
This script can detect translatable strings of the notations listed below.
Additional function arguments followed after a literal string are ignored.
@ -67,35 +70,41 @@ Undetectable notations:
Use placeholders (`@1`, ...) for variable text.
* Any literal string concatenation using `[[...]]`
### A minimal example
### A Minimal Example
This minimal code example sends "Hello world!" to all players, but translated according to
each player's language:
local S = minetest.get_translator("example")
minetest.chat_send_all(S("Hello world!"))
```lua
local S = minetest.get_translator("example")
minetest.chat_send_all(S("Hello world!"))
```
### How to use `NS`
### How to Use `NS`
The reason why `NS` exists is for cases like this: Sometimes, you want to define a list of
strings to they can be later output in a function. Like so:
local fruit = { "Apple", "Orange", "Pear" }
local function return_fruit(fruit_id)
return fruit[fruit_id]
end
```lua
local fruit = {"Apple", "Orange", "Pear"}
local function return_fruit(fruit_id)
return fruit[fruit_id]
end
```
If you want to translate the fruit names when `return_fruit` is run, but have the
*untranslated* fruit names in the `fruit` table stored, this is where `NS` will help.
It will show the script the string without Minetest translating it. The script could be made
translatable like this:
local fruit = { NS("Apple"), NS("Orange"), NS("Pear") }
local function return_fruit(fruit_id)
return S(fruit[fruit_id])
end
```lua
local fruit = {NS("Apple"), NS("Orange"), NS("Pear")}
local function return_fruit(fruit_id)
return S(fruit[fruit_id])
end
```
## How to run the script
## How to Run the Script
First, change the working directory to the directory of the mod you want the files to be
updated. From this directory, run the script.
@ -121,21 +130,22 @@ It has the following command line options:
--verbose, -v: add output information
--truncate-unused, -t: delete unused strings from files
## Script output
## Script Output
This section explains how the output of this script works, roughly. This script aims to make
the output more or less stable, i.e. given identical source files and arguments, the script
should produce the same output.
### Textdomain
### `textdomain`
The script will add (if not already present) a `# textdomain: <modname>` at the top, where
`<modname>` is identical to the mod directory name. If a `# textdomain` already exists, it
will be moved to the top, with the textdomain name being left intact (even if it differs
from the mod name).
**Note:** If there are multiple `# textdomain:` lines in the file, all of them except the
first one will be deleted. This script only supports one textdomain per `*.tr` file.
> [!NOTE]
> If there are multiple `# textdomain:` lines in the file, all of them except the
> first one will be deleted. This script only supports one textdomain per `*.tr` file.
### Strings
@ -169,7 +179,7 @@ files, associating them with the line that follows them. So for example:
# This comment pertains to Some Text
Some text=
# Multi-line comments
# are also supported
Text as well=
@ -179,7 +189,7 @@ files and write it above existing comments (if exist).
There are also a couple of special comments that this script gives special treatment to.
#### Source file comments
#### Source File Comments
If `--print-source` or `-p` is provided as option, the script will insert comments to show
from which file or files each string has come from.
@ -204,7 +214,7 @@ If the print source option is not provided, these comments will disappear.
Note that all comments of the form `##[something]##` will be treated as "source file" comments
so they may be moved, changed or removed by the script at will.
#### "not used anymore" section
#### `not used anymore` Section
By default, the exact comment `##### not used anymore #####` will be automatically added to
mark the beginning of a section where old/unused strings will go. Leave the exact wording of

4
worlds/worlds_here.txt
View File

@ -1,4 +1,4 @@
World directories are placed into this location. Each world should contain at least following files:
* map_meta.txt
* world.mt
* map_meta.txt
* world.mt