From 84f4565e132e469f802fa139820045210aa35ba3 Mon Sep 17 00:00:00 2001 From: rubenwardy Date: Tue, 14 Mar 2017 06:51:07 +0000 Subject: Add disclaimer to client_lua_api.txt (#5391) --- doc/client_lua_api.txt | 818 ------------------------------------------------- 1 file changed, 818 deletions(-) delete mode 100644 doc/client_lua_api.txt (limited to 'doc/client_lua_api.txt') diff --git a/doc/client_lua_api.txt b/doc/client_lua_api.txt deleted file mode 100644 index 7440c4014..000000000 --- a/doc/client_lua_api.txt +++ /dev/null @@ -1,818 +0,0 @@ -Minetest Lua Modding API Reference 0.4.15 -========================================= -* More information at -* Developer Wiki: - -Introduction ------------- -Content and functionality can be added to Minetest 0.4 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. - -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 ----------------- -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 - | `-- - `-- another - - -### modname -The location of this directory can be fetched by using -`minetest.get_modpath(modname)`. - -### `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. - -### `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` -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. - -### 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 ------- -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 on all clients - { - gain = 1.0, -- default - } - -- Play locationless to one player - { - to_player = name, - gain = 1.0, -- default - } - -- Play locationless to one player, looped - { - to_player = name, - 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 to -one player using `to_player = name,` - -### `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", ref=ObjectRef}` - -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. Currently not much else than inventories are -supported. 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[,;,;;