Skip to content
Permalink
Browse files

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

  • Loading branch information...
red-001 authored and nerzhul committed Mar 28, 2017
1 parent 4b05fea commit 7c85405d96bf10afa83192b3820bacf6e7ccea9f
Showing with 33 additions and 74 deletions.
  1. +33 −74 doc/client_lua_api.md
@@ -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
@@ -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.
@@ -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.
@@ -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
@@ -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. `{}`
@@ -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}`
@@ -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.
@@ -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
@@ -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(...)`
@@ -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)
@@ -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)`.
@@ -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.
}

@@ -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
@@ -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.
You can’t perform that action at this time.