[CSM] Fix errors in and improve the CSM documentation. (#5467)

master
red-001 2017-03-28 07:26:54 +01:00 committed by Loïc Blot
parent 4b05feaceb
commit 7c85405d96
1 changed files with 33 additions and 74 deletions

View File

@ -8,14 +8,13 @@ Introduction
**WARNING: The client API is currently unstable, and may break/change without warning.** **WARNING: The client API is currently unstable, and may break/change without warning.**
Content and functionality can be added to Minetest 0.4 by using Lua Content and functionality can be added to Minetest 0.4.15-dev+ by using Lua
scripting in run-time loaded mods. scripting in run-time loaded mods.
A mod is a self-contained bunch of scripts, textures and other related A mod is a self-contained bunch of scripts, textures and other related
things that is loaded by and interfaces with Minetest. things that is loaded by and interfaces with Minetest.
Mods are contained and ran solely on the server side. Definitions and media Transfering client-sided mods form the server to the client is planned, but not implemented yet.
files are automatically transferred to the client.
If you see a deficiency in the API, feel free to attempt to add the 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 functionality in the engine and API. You can send such improvements as
@ -66,6 +65,8 @@ On an installed version on Linux:
Modpack support Modpack support
---------------- ----------------
**NOTE: Not implemented yet.**
Mods can be put in a subdirectory, if the parent directory, which otherwise Mods can be put in a subdirectory, if the parent directory, which otherwise
should be a mod, contains a file named `modpack.txt`. This file shall be should be a mod, contains a file named `modpack.txt`. This file shall be
empty, except for lines starting with `#`, which are comments. empty, except for lines starting with `#`, which are comments.
@ -73,28 +74,16 @@ empty, except for lines starting with `#`, which are comments.
Mod directory structure Mod directory structure
------------------------ ------------------------
mods clientmods
|-- modname ├── modname
| |-- depends.txt | ├── depends.txt
| |-- screenshot.png | ├── init.lua
| |-- description.txt └── another
| |-- settingtypes.txt
| |-- init.lua
| |-- models
| |-- textures
| | |-- modname_stuff.png
| | `-- modname_something_else.png
| |-- sounds
| |-- media
| `-- <custom data>
`-- another
### modname ### modname
The location of this directory can be fetched by using The location of this directory.
`minetest.get_modpath(modname)`.
### `depends.txt` ### depends.txt
List of mods that have to be loaded before loading this mod. List of mods that have to be loaded before loading this mod.
A single line contains a single modname. A single line contains a single modname.
@ -103,18 +92,7 @@ Optional dependencies can be defined by appending a question mark
to a single modname. Their meaning is that if the specified mod to a single modname. Their meaning is that if the specified mod
is missing, that does not prevent this mod from being loaded. is missing, that does not prevent this mod from being loaded.
### `screenshot.png` ### init.lua
A screenshot shown in the mod manager within the main menu. It should
have an aspect ratio of 3:2 and a minimum size of 300×200 pixels.
### `description.txt`
A File containing description to be shown within mainmenu.
### `settingtypes.txt`
A file in the same format as the one in builtin. It will be parsed by the
settings menu and the settings will be displayed in the "Mods" category.
### `init.lua`
The main Lua script. Running this script should register everything it The main Lua script. Running this script should register everything it
wants to register. Subsequent execution depends on minetest calling the wants to register. Subsequent execution depends on minetest calling the
registered callbacks. registered callbacks.
@ -151,29 +129,10 @@ when registering it.
The `:` prefix can also be used for maintaining backwards compatibility. The `:` prefix can also be used for maintaining backwards compatibility.
### Aliases
Aliases can be added by using `minetest.register_alias(name, convert_to)` or
`minetest.register_alias_force(name, convert_to).
This will make Minetest to convert things called name to things called
`convert_to`.
The only difference between `minetest.register_alias` and
`minetest.register_alias_force` is that if an item called `name` exists,
`minetest.register_alias` will do nothing while
`minetest.register_alias_force` will unregister it.
This can be used for maintaining backwards compatibility.
This can be also used for setting quick access names for things, e.g. if
you have an item called `epiclylongmodname:stuff`, you could do
minetest.register_alias("stuff", "epiclylongmodname:stuff")
and be able to use `/giveme stuff`.
Sounds Sounds
------ ------
**NOTE: Not fully implemented yet.**
Only Ogg Vorbis files are supported. Only Ogg Vorbis files are supported.
For positional playing of sounds, only single-channel (mono) files are For positional playing of sounds, only single-channel (mono) files are
@ -231,7 +190,7 @@ Examples of sound parameter tables:
Looped sounds must either be connected to an object or played locationless to Looped sounds must either be connected to an object or played locationless to
one player using `to_player = name,` one player using `to_player = name,`
### `SimpleSoundSpec` ### SimpleSoundSpec
* e.g. `""` * e.g. `""`
* e.g. `"default_place_node"` * e.g. `"default_place_node"`
* e.g. `{}` * e.g. `{}`
@ -247,7 +206,7 @@ Representations of simple things
For helper functions see "Vector helpers". For helper functions see "Vector helpers".
### `pointed_thing` ### pointed_thing
* `{type="nothing"}` * `{type="nothing"}`
* `{type="node", under=pos, above=pos}` * `{type="node", under=pos, above=pos}`
* `{type="object", ref=ObjectRef}` * `{type="object", ref=ObjectRef}`
@ -287,8 +246,7 @@ since, by default, no schematic attributes are set.
Formspec Formspec
-------- --------
Formspec defines a menu. Currently not much else than inventories are Formspec defines a menu. It is a string, with a somewhat strange format.
supported. It is a string, with a somewhat strange format.
Spaces and newlines can be inserted between the blocks, as is used in the Spaces and newlines can be inserted between the blocks, as is used in the
examples. examples.
@ -653,7 +611,7 @@ Helper functions
* `table.copy(table)`: returns a table * `table.copy(table)`: returns a table
* returns a deep copy of `table` * returns a deep copy of `table`
`minetest` namespace reference Minetest namespace reference
------------------------------ ------------------------------
### Utilities ### Utilities
@ -669,7 +627,7 @@ Helper functions
reliable or verifyable. Compatible forks will have a different name and reliable or verifyable. Compatible forks will have a different name and
version entirely. To check for the presence of engine features, test version entirely. To check for the presence of engine features, test
whether the functions exported by the wanted features exist. For example: whether the functions exported by the wanted features exist. For example:
`if core.nodeupdate then ... end`. `if minetest.nodeupdate then ... end`.
### Logging ### Logging
* `minetest.debug(...)` * `minetest.debug(...)`
@ -784,24 +742,26 @@ Call these functions only at load time!
* Encodes a string in base64. * Encodes a string in base64.
* `minetest.decode_base64(string)`: returns string * `minetest.decode_base64(string)`: returns string
* Decodes a string encoded in base64. * Decodes a string encoded in base64.
* `core.gettext(string) : returns string * `minetest.gettext(string) : returns 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, ...)` * `fgettext_ne(string, ...)`
* call core.gettext(string), replace "$1"..."$9" with the given * call minetest.gettext(string), replace "$1"..."$9" with the given
extra arguments and return the result extra arguments and return the result
* `fgettext(string, ...)` : returns string * `fgettext(string, ...)` : returns string
* same as fgettext_ne(), but calls core.formspec_escape before returning result * same as fgettext_ne(), but calls minetest.formspec_escape before returning result
### UI ### UI
* `minetest.ui.minimap` * `minetest.ui.minimap`
* Reference to the minimap object. See `Minimap` class reference for methods. * Reference to the minimap object. See `Minimap` class reference for methods.
* `show_formspec(formname, formspec)` : returns true on success * `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.
Class reference Class reference
--------------- ---------------
### `Minimap` ### Minimap
An interface to manipulate minimap on client UI An interface to manipulate minimap on client UI
* `show()`: shows the minimap (if not disabled by server) * `show()`: shows the minimap (if not disabled by server)
@ -814,7 +774,7 @@ An interface to manipulate minimap on client UI
* `get_mode()`: returns the current minimap mode * `get_mode()`: returns the current minimap mode
* `toggle_shape()`: toggles minimap shape to round or square. * `toggle_shape()`: toggles minimap shape to round or square.
### `Settings` ### Settings
An interface to read config files in the format of `minetest.conf`. An interface to read config files in the format of `minetest.conf`.
It can be created via `Settings(filename)`. It can be created via `Settings(filename)`.
@ -837,8 +797,7 @@ Definition tables
{ {
params = "<name> <privilege>", -- Short parameter description params = "<name> <privilege>", -- Short parameter description
description = "Remove privilege from player", -- Full description description = "Remove privilege from player", -- Full description
privs = {privs=true}, -- Require the "privs" privilege to run func = function(param), -- Called when command is run.
func = function(name, param), -- Called when command is run.
-- Returns boolean success and text output. -- Returns boolean success and text output.
} }
@ -847,14 +806,14 @@ Escape sequences
Most text can contain escape sequences, that can for example color the text. 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. There are a few exceptions: tab headers, dropdowns and vertical labels can't.
The following functions provide escape sequences: The following functions provide escape sequences:
* `core.get_color_escape_sequence(color)`: * `minetest.get_color_escape_sequence(color)`:
* `color` is a ColorString * `color` is a ColorString
* The escape sequence sets the text color to `color` * The escape sequence sets the text color to `color`
* `core.colorize(color, message)`: * `minetest.colorize(color, message)`:
* Equivalent to: * Equivalent to:
`core.get_color_escape_sequence(color) .. `minetest.get_color_escape_sequence(color) ..
message .. message ..
core.get_color_escape_sequence("#ffffff")` minetest.get_color_escape_sequence("#ffffff")`
* `color.get_background_escape_sequence(color)` * `color.get_background_escape_sequence(color)`
* `color` is a ColorString * `color` is a ColorString
* The escape sequence sets the background of the whole text element to * The escape sequence sets the background of the whole text element to
@ -874,4 +833,4 @@ Named colors are also supported and are equivalent to
[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors). [CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
To specify the value of the alpha channel, append `#AA` to the end of the color name To specify the value of the alpha channel, append `#AA` to the end of the color name
(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha (e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
value must (always) be two hexadecima value must (always) be two hexadecimal digits.