From 18b914ac74dce62b4d9f6dc65f70e3cf74fca5de Mon Sep 17 00:00:00 2001 From: paramat Date: Tue, 28 Nov 2017 23:22:49 +0000 Subject: Client lua api documentation: .md -> .txt For consistency, and for much improved access on Github. On Github: .md disables being able to link to a line, needed daily when quickly referring people to particular lines. Search returns results in .md files, but you cannot then click the line number to go to that line in the document, making searching difficult. Line numbers are not displayed for .md documents. --- doc/client_lua_api.md | 1208 ------------------------------------------------ doc/client_lua_api.txt | 1208 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1208 insertions(+), 1208 deletions(-) delete mode 100644 doc/client_lua_api.md create mode 100644 doc/client_lua_api.txt (limited to 'doc') diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md deleted file mode 100644 index 3655cf235..000000000 --- a/doc/client_lua_api.md +++ /dev/null @@ -1,1208 +0,0 @@ -Minetest Lua Client Modding API Reference 0.5.0 -================================================ -* More information at -* Developer Wiki: - -Introduction ------------- - -**WARNING: The client API is currently unstable, and may break/change without warning.** - -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. - -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 -source code patches on GitHub (https://github.com/minetest/minetest). - -Programming in Lua ------------------- -If you have any difficulty in understanding this, please read -[Programming in Lua](http://www.lua.org/pil/). - -Startup -------- -Mods are loaded during client startup from the mod load paths by running -the `init.lua` scripts in a shared environment. - -Paths ------ -* `RUN_IN_PLACE=1` (Windows release, local build) - * `$path_user`: - * Linux: `` - * Windows: `` - * `$path_share` - * Linux: `` - * Windows: `` -* `RUN_IN_PLACE=0`: (Linux release) - * `$path_share` - * Linux: `/usr/share/minetest` - * Windows: `/minetest-0.4.x` - * `$path_user`: - * Linux: `$HOME/.minetest` - * Windows: `C:/users//AppData/minetest` (maybe) - -Mod load path -------------- -Generic: - -* `$path_share/clientmods/` -* `$path_user/clientmods/` (User-installed mods) - -In a run-in-place version (e.g. the distributed windows version): - -* `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 ----------------- -**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 ------------------------- - - clientmods - ├── modname - | ├── depends.txt - | ├── init.lua - └── another - -### modname -The location of this directory. - -### depends.txt -List of mods that have to be loaded before loading this mod. - -A single line contains a single modname. - -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. - -### 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. - -`minetest.setting_get(name)` and `minetest.setting_getbool(name)` can be used -to read custom or existing settings at load time, if necessary. - -### `sounds` -Media files (sounds) that will be transferred to the -client and will be available for use by the mod. - -Naming convention for registered textual names ----------------------------------------------- -Registered names should generally be in this format: - - "modname:" ( can have characters a-zA-Z0-9_) - -This is to prevent conflicting names from corrupting maps and is -enforced by the mod loader. - -### Example -In the mod `experimental`, there is the ideal item/node/entity name `tnt`. -So the name should be `experimental:tnt`. - -Enforcement can be overridden by prefixing the name with `:`. This can -be used for overriding the registrations of some other mod. - -Example: Any mod can redefine `experimental:tnt` by using the name - - :experimental:tnt - -when registering it. -(also that mod is required to have `experimental` as a dependency) - -The `:` prefix can also be used for maintaining backwards compatibility. - -Sounds ------- -**NOTE: max_hear_distance and connecting to objects is not implemented.** - -Only Ogg Vorbis files are supported. - -For positional playing of sounds, only single-channel (mono) files are -supported. Otherwise OpenAL will play them non-positionally. - -Mods should generally prefix their sounds with `modname_`, e.g. given -the mod name "`foomod`", a sound could be called: - - foomod_foosound.ogg - -Sounds are referred to by their name with a dot, a single digit and the -file extension stripped out. When a sound is played, the actual sound file -is chosen randomly from the matching sounds. - -When playing the sound `foomod_foosound`, the sound is chosen randomly -from the available ones of the following files: - -* `foomod_foosound.ogg` -* `foomod_foosound.0.ogg` -* `foomod_foosound.1.ogg` -* (...) -* `foomod_foosound.9.ogg` - -Examples of sound parameter tables: - - -- Play locationless - { - gain = 1.0, -- default - } - -- Play locationless, looped - { - gain = 1.0, -- default - loop = true, - } - -- Play in a location - { - pos = {x = 1, y = 2, z = 3}, - gain = 1.0, -- default - max_hear_distance = 32, -- default, uses an euclidean metric - } - -- Play connected to an object, looped - { - object = , - gain = 1.0, -- default - max_hear_distance = 32, -- default, uses an euclidean metric - loop = true, - } - -Looped sounds must either be connected to an object or played locationless. - -### 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 - - {x=num, y=num, z=num} - -For helper functions see "Vector helpers". - -### pointed_thing -* `{type="nothing"}` -* `{type="node", under=pos, above=pos}` -* `{type="object", id=ObjectID}` - -Flag Specifier Format ---------------------- -Flags using the standardized flag specifier format can be specified in either of -two ways, by string or table. - -The string format is a comma-delimited set of flag names; whitespace and -unrecognized flag fields are ignored. Specifying a flag in the string sets the -flag, and specifying a flag prefixed by the string `"no"` explicitly -clears the flag from whatever the default may be. - -In addition to the standard string flag format, the schematic flags field can -also be a table of flag names to boolean values representing whether or not the -flag is set. Additionally, if a field with the flag name prefixed with `"no"` -is present, mapped to a boolean of any value, the specified flag is unset. - -E.g. A flag field of value - - {place_center_x = true, place_center_y=false, place_center_z=true} - -is equivalent to - - {place_center_x = true, noplace_center_y=true, place_center_z=true} - -which is equivalent to - - "place_center_x, noplace_center_y, place_center_z" - -or even - - "place_center_x, place_center_z" - -since, by default, no schematic attributes are set. - -Formspec --------- -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. - -### Examples - -#### Chest - - size[8,9] - list[context;main;0,0;8,4;] - list[current_player;main;0,5;8,4;] - -#### Furnace - - size[8,9] - list[context;fuel;2,3;1,1;] - list[context;src;2,1;1,1;] - list[context;dst;5,1;2,2;] - list[current_player;main;0,5;8,4;] - -#### Minecraft-like player inventory - - size[8,7.5] - image[1,0.6;1,2;player.png] - list[current_player;main;0,3.5;8,4;] - list[current_player;craft;3,0;3,3;] - list[current_player;craftpreview;7,1;1,1;] - -### Elements - -#### `size[,,]` -* Define the size of the menu in inventory slots -* `fixed_size`: `true`/`false` (optional) -* deprecated: `invsize[,;]` - -#### `container[,]` -* Start of a container block, moves all physical elements in the container by (X, Y) -* Must have matching container_end -* Containers can be nested, in which case the offsets are added - (child containers are relative to parent containers) - -#### `container_end[]` -* End of a container, following elements are no longer relative to this container - -#### `list[;;,;,;]` -* Show an inventory list - -#### `list[;;,;,;]` -* Show an inventory list - -#### `listring[;]` -* Allows to create a ring of inventory lists -* Shift-clicking on items in one element of the ring - will send them to the next inventory list inside the ring -* The first occurrence of an element inside the ring will - determine the inventory where items will be sent to - -#### `listring[]` -* Shorthand for doing `listring[;]` - for the last two inventory lists added by list[...] - -#### `listcolors[;]` -* Sets background color of slots as `ColorString` -* Sets background color of slots on mouse hovering - -#### `listcolors[;;]` -* Sets background color of slots as `ColorString` -* Sets background color of slots on mouse hovering -* Sets color of slots border - -#### `listcolors[;;;;]` -* Sets background color of slots as `ColorString` -* Sets background color of slots on mouse hovering -* Sets color of slots border -* Sets default background color of tooltips -* Sets default font color of tooltips - -#### `tooltip[;;,]` -* Adds tooltip for an element -* `` tooltip background color as `ColorString` (optional) -* `` tooltip font color as `ColorString` (optional) - -#### `image[,;,;]` -* Show an image -* Position and size units are inventory slots - -#### `item_image[,;,;]` -* Show an inventory image of registered item/node -* Position and size units are inventory slots - -#### `bgcolor[;]` -* Sets background color of formspec as `ColorString` -* If `true`, the background color is drawn fullscreen (does not effect the size of the formspec) - -#### `background[,;,;]` -* Use a background. Inventory rectangles are not drawn then. -* Position and size units are inventory slots -* Example for formspec 8x4 in 16x resolution: image shall be sized - 8 times 16px times 4 times 16px. - -#### `background[,;,;;]` -* Use a background. Inventory rectangles are not drawn then. -* Position and size units are inventory slots -* Example for formspec 8x4 in 16x resolution: - image shall be sized 8 times 16px times 4 times 16px -* If `true` the background is clipped to formspec size - (`x` and `y` are used as offset values, `w` and `h` are ignored) - -#### `pwdfield[,;,;;