Skip to content

Commit

Permalink
[CSM] Fix errors in and improve the CSM documentation. (#5467)
Browse files Browse the repository at this point in the history
  • Loading branch information
@red-001 @nerzhul
red-001 authored and nerzhul committed Mar 28, 2017
1 parent 4b05fea commit 7c85405
Showing 1 changed file with 33 additions and 74 deletions.
107 changes: 33 additions & 74 deletions doc/client_lua_api.md
View file
Expand Up @@ -8,14 +8,13 @@ Introduction

**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.

A mod is a self-contained bunch of scripts, textures and other related
things that is loaded by and interfaces with Minetest.

Mods are contained and ran solely on the server side. Definitions and media
files are automatically transferred to the client.
Transfering client-sided mods form the server to the client is planned, but not implemented yet.

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
Expand Down Expand Up @@ -66,35 +65,25 @@ On an installed version on Linux:

Modpack support
----------------
**NOTE: Not implemented yet.**

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
empty, except for lines starting with `#`, which are comments.

Mod directory structure
------------------------

mods
|-- modname
| |-- depends.txt
| |-- screenshot.png
| |-- description.txt
| |-- settingtypes.txt
| |-- init.lua
| |-- models
| |-- textures
| | |-- modname_stuff.png
| | `-- modname_something_else.png
| |-- sounds
| |-- media
| `-- <custom data>
`-- another

clientmods
├── modname
| ├── depends.txt
| ├── init.lua
└── another

### modname
The location of this directory can be fetched by using
`minetest.get_modpath(modname)`.
The location of this directory.

### `depends.txt`
### depends.txt
List of mods that have to be loaded before loading this mod.

A single line contains a single modname.
Expand All @@ -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
is missing, that does not prevent this mod from being loaded.

### `screenshot.png`
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`
### init.lua
The main Lua script. Running this script should register everything it
wants to register. Subsequent execution depends on minetest calling the
registered callbacks.
Expand Down Expand Up @@ -151,29 +129,10 @@ when registering it.

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
------
**NOTE: Not fully implemented yet.**

Only Ogg Vorbis files are supported.

For positional playing of sounds, only single-channel (mono) files are
Expand Down Expand Up @@ -231,7 +190,7 @@ Examples of sound parameter tables:
Looped sounds must either be connected to an object or played locationless to
one player using `to_player = name,`

### `SimpleSoundSpec`
### SimpleSoundSpec
* e.g. `""`
* e.g. `"default_place_node"`
* e.g. `{}`
Expand All @@ -247,7 +206,7 @@ Representations of simple things

For helper functions see "Vector helpers".

### `pointed_thing`
### pointed_thing
* `{type="nothing"}`
* `{type="node", under=pos, above=pos}`
* `{type="object", ref=ObjectRef}`
Expand Down Expand Up @@ -287,8 +246,7 @@ since, by default, no schematic attributes are set.

Formspec
--------
Formspec defines a menu. Currently not much else than inventories are
supported. It is a string, with a somewhat strange format.
Formspec defines a menu. It is a string, with a somewhat strange format.

Spaces and newlines can be inserted between the blocks, as is used in the
examples.
Expand Down Expand Up @@ -653,7 +611,7 @@ Helper functions
* `table.copy(table)`: returns a table
* returns a deep copy of `table`

`minetest` namespace reference
Minetest namespace reference
------------------------------

### Utilities
Expand All @@ -669,7 +627,7 @@ Helper functions
reliable or verifyable. Compatible forks will have a different name and
version entirely. To check for the presence of engine features, test
whether the functions exported by the wanted features exist. For example:
`if core.nodeupdate then ... end`.
`if minetest.nodeupdate then ... end`.

### Logging
* `minetest.debug(...)`
Expand Down Expand Up @@ -784,24 +742,26 @@ Call these functions only at load time!
* Encodes a string in base64.
* `minetest.decode_base64(string)`: returns string
* 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
* `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
* `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
* `minetest.ui.minimap`
* 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
* `minetest.display_chat_message(message)` returns true on success
* Shows a chat message to the current player.

Class reference
---------------

### `Minimap`
### Minimap
An interface to manipulate minimap on client UI

* `show()`: shows the minimap (if not disabled by server)
Expand All @@ -814,7 +774,7 @@ An interface to manipulate minimap on client UI
* `get_mode()`: returns the current minimap mode
* `toggle_shape()`: toggles minimap shape to round or square.

### `Settings`
### Settings
An interface to read config files in the format of `minetest.conf`.

It can be created via `Settings(filename)`.
Expand All @@ -837,8 +797,7 @@ Definition tables
{
params = "<name> <privilege>", -- Short parameter description
description = "Remove privilege from player", -- Full description
privs = {privs=true}, -- Require the "privs" privilege to run
func = function(name, param), -- Called when command is run.
func = function(param), -- Called when command is run.
-- Returns boolean success and text output.
}

Expand All @@ -847,14 +806,14 @@ 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:
* `core.get_color_escape_sequence(color)`:
* `minetest.get_color_escape_sequence(color)`:
* `color` is a ColorString
* The escape sequence sets the text color to `color`
* `core.colorize(color, message)`:
* `minetest.colorize(color, message)`:
* Equivalent to:
`core.get_color_escape_sequence(color) ..
`minetest.get_color_escape_sequence(color) ..
message ..
core.get_color_escape_sequence("#ffffff")`
minetest.get_color_escape_sequence("#ffffff")`
* `color.get_background_escape_sequence(color)`
* `color` is a ColorString
* The escape sequence sets the background of the whole text element to
Expand All @@ -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).
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
value must (always) be two hexadecima
value must (always) be two hexadecimal digits.

0 comments on commit 7c85405

Please sign in to comment.