X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=a1baadf6dbe3aca72518340a4c3309249c28c461;hb=c8303f790ccb03857d031ecb73de7f9f59a6ceba;hp=b083b290770709d1647516fd39c00952e2f0bc26;hpb=f780bae05cc2fdd23a6d7326c770783da8d94ea3;p=dragonfireclient.git diff --git a/doc/lua_api.txt b/doc/lua_api.txt index b083b2907..a1baadf6d 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -62,12 +62,12 @@ Where `` is unique to each game. The game directory can contain the following files: * `game.conf`, with the following keys: - * `name`: Required, human readable name e.g. `name = Minetest` + * `name`: Required, a human readable title to address the game, e.g. `name = Minetest`. * `description`: Short description to be shown in the content tab * `allowed_mapgens = ` e.g. `allowed_mapgens = v5,v6,flat` - Mapgens not in this list are removed from the list of mapgens for - the game. + Mapgens not in this list are removed from the list of mapgens for the + game. If not specified, all mapgens are allowed. * `disallowed_mapgens = ` e.g. `disallowed_mapgens = v5,v6,flat` @@ -75,6 +75,14 @@ The game directory can contain the following files: When both `allowed_mapgens` and `disallowed_mapgens` are specified, `allowed_mapgens` is applied before `disallowed_mapgens`. + * `disallowed_mapgen_settings= ` + e.g. `disallowed_mapgen_settings = mgv5_spflags` + These settings are hidden for this game in the world creation + dialog and game start menu. + * `author`: The author of the game. It only appears when downloaded from + ContentDB. + * `release`: Ignore this: Should only ever be set by ContentDB, as it is + an internal ID used to track versions. * `minetest.conf`: Used to set default settings when running this game. * `settingtypes.txt`: @@ -130,9 +138,15 @@ Mods can be put in a subdirectory, if the parent directory, which otherwise should be a mod, contains a file named `modpack.conf`. The file is a key-value store of modpack details. -* `name`: The modpack name. +* `name`: The modpack name. Allows Minetest to determine the modpack name even + if the folder is wrongly named. * `description`: Description of mod to be shown in the Mods tab of the main menu. +* `author`: The author of the modpack. It only appears when downloaded from + ContentDB. +* `release`: Ignore this: Should only ever be set by ContentDB, as it is an + internal ID used to track versions. +* `title`: A human-readable title to address the modpack. Note: to support 0.4.x, please also create an empty modpack.txt file. @@ -148,7 +162,12 @@ Mod directory structure │   ├── models │   ├── textures │   │   ├── modname_stuff.png - │   │   └── modname_something_else.png + │   │   ├── modname_stuff_normal.png + │   │   ├── modname_something_else.png + │   │   ├── subfolder_foo + │   │   │ ├── modname_more_stuff.png + │   │   │ └── another_subfolder + │   │   └── bar_subfolder │   ├── sounds │   ├── media │   ├── locale @@ -172,6 +191,11 @@ A `Settings` file that provides meta information about the mod. loaded before this mod. * `optional_depends`: A comma separated list of optional dependencies. Like a dependency, but no error if the mod doesn't exist. +* `author`: The author of the mod. It only appears when downloaded from + ContentDB. +* `release`: Ignore this: Should only ever be set by ContentDB, as it is an + internal ID used to track versions. +* `title`: A human-readable title to address the mod. Note: to support 0.4.x, please also provide depends.txt. @@ -217,18 +241,20 @@ registered callbacks. `minetest.settings` can be used to read custom or existing settings at load time, if necessary. (See [`Settings`]) -### `models` - -Models for entities or meshnodes. - -### `textures`, `sounds`, `media` +### `textures`, `sounds`, `media`, `models`, `locale` Media files (textures, sounds, whatever) that will be transferred to the -client and will be available for use by the mod. +client and will be available for use by the mod and translation files for +the clients (see [Translations]). -### `locale` +It is suggested to use the folders for the purpous they are thought for, +eg. put textures into `textures`, translation files into `locale`, +models for entities or meshnodes into `models` et cetera. -Translation files for the clients. (See [Translations]) +These folders and subfolders can contain subfolders. +Subfolders with names starting with `_` or `.` are ignored. +If a subfolder contains a media file with the same name as a media file +in one of its parents, the parent's file is used. Naming conventions ------------------ @@ -374,6 +400,36 @@ stripping out the file extension: * e.g. `foomod_foothing.png` * e.g. `foomod_foothing` + +Normalmap Textures +------------------ + +If shaders and bumpmapping or parallax occlusion is enabled, Minetest tries +to load normalmaps. +Those image files have to end with `_normal.png` and start with the same name +as their corresponding texture. +For example a normalmap for `foomod_foothing.png` has to be called +`foomod_foothing_normal.png`. + +The sRGB R, G and B colour values of a normalmap pixel are each directly +mapped from `{0, ..., 255}` to `[-1, 1]` and, taken together, +define the normal vector. +The alpha channel defines the heightmap for parallax occlusion. +To be safe, the alpha values should always be bigger than zero +because the colour values, which define the normal vector, +may be undefined for image formats where colour is discarded in fully +transparent pixels. + +Bumpmapping and parallax occlusion are currently experimental features: + +* Bumpmapping in Minetest happens in an obscure way; there are no light sources + defined in the shaders except the sunlight direction. +* Parallax occlusion with relief-mapping mode does not yet work correctly + together with Minetest's Fastfaces. +* The normalmap files must end with `.png`, so other image files are not + supported. + + Texture modifiers ----------------- @@ -897,6 +953,7 @@ These sound files are played back by the engine if provided. * `player_damage`: Played when the local player takes damage (gain = 0.5) * `player_falling_damage`: Played when the local player takes damage by falling (gain = 0.5) + * `player_jump`: Played when the local player jumps * `default_dig_`: Default node digging sound (see node sound definition for details) @@ -1064,7 +1121,7 @@ Node drawtypes There are a bunch of different looking node types. -Look for examples in `games/minimal` or `games/minetest_game`. +Look for examples in `games/devtest` or `games/minetest_game`. * `normal` * A node-sized cube. @@ -1288,9 +1345,9 @@ To account for differing resolutions, the position coordinates are the percentage of the screen, ranging in value from `0` to `1`. The name field is not yet used, but should contain a description of what the -HUD element represents. The direction field is the direction in which something -is drawn. +HUD element represents. +The `direction` field is the direction in which something is drawn. `0` draws from left to right, `1` draws from right to left, `2` draws from top to bottom, and `3` draws from bottom to top. @@ -1309,7 +1366,21 @@ factor! The `z_index` field specifies the order of HUD elements from back to front. Lower z-index elements are displayed behind higher z-index elements. Elements with same z-index are displayed in an arbitrary order. Default 0. -Supports negative values. +Supports negative values. By convention, the following values are recommended: + +* -400: Graphical effects, such as vignette +* -300: Name tags, waypoints +* -200: Wieldhand +* -100: Things that block the player's view, e.g. masks +* 0: Default. For standard in-game HUD elements like crosshair, hotbar, + minimap, builtin statbars, etc. +* 100: Temporary text messages or notification icons +* 1000: Full-screen effects such as full-black screen or credits. + This includes effects that cover the entire screen +* Other: If your HUD element doesn't fit into any category, pick a number + between the suggested values + + Below are the specific uses for fields in each type; fields not listed for that type are ignored. @@ -1337,15 +1408,21 @@ Displays text on the HUD. text. Specify `0xFFFFFF` for white text, `0xFF0000` for red, and so on. * `alignment`: The alignment of the text. * `offset`: offset in pixels from position. +* `size`: size of the text. + The player-set font size is multiplied by size.x (y value isn't used). ### `statbar` -Displays a horizontal bar made up of half-images. +Displays a horizontal bar made up of half-images with an optional background. -* `text`: The name of the texture that is used. +* `text`: The name of the texture to use. +* `text2`: Optional texture name to enable a background / "off state" + texture (useful to visualize the maximal value). Both textures + must have the same size. * `number`: The number of half-textures that are displayed. If odd, will end with a vertically center-split texture. -* `direction` +* `item`: Same as `number` but for the "off state" texture +* `direction`: To which direction the images will extend to * `offset`: offset in pixels from position. * `size`: If used, will force full-image size to this value (override texture pack image size) @@ -1364,12 +1441,48 @@ Displays distance to selected world position. * `name`: The name of the waypoint. * `text`: Distance suffix. Can be blank. +* `precision`: Waypoint precision, integer >= 0. Defaults to 10. + If set to 0, distance is not shown. Shown value is `floor(distance*precision)/precision`. + When the precision is an integer multiple of 10, there will be `log_10(precision)` digits after the decimal point. + `precision = 1000`, for example, will show 3 decimal places (eg: `0.999`). + `precision = 2` will show multiples of `0.5`; precision = 5 will show multiples of `0.2` and so on: + `precision = n` will show multiples of `1/n` * `number:` An integer containing the RGB value of the color used to draw the text. * `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. +* `alignment`: The alignment of the waypoint. + +### `image_waypoint` + +Same as `image`, but does not accept a `position`; the position is instead determined by `world_pos`, the world position of the waypoint. + +* `scale`: The scale of the image, with 1 being the original texture size. + Only the X coordinate scale is used (positive values). + Negative values represent that percentage of the screen it + should take; e.g. `x=-100` means 100% (width). +* `text`: The name of the texture that is displayed. +* `alignment`: The alignment of the image. +* `world_pos`: World position of the waypoint. +* `offset`: offset in pixels from position. + +### `compass` +Displays an image oriented or translated according to current heading direction. +* `size`: The size of this element. Negative values represent percentage + of the screen; e.g. `x=-100` means 100% (width). +* `scale`: Scale of the translated image (used only for dir = 2 or dir = 3). +* `text`: The name of the texture to use. +* `alignment`: The alignment of the image. +* `offset`: Offset in pixels from position. +* `dir`: How the image is rotated/translated: + * 0 - Rotate as heading direction + * 1 - Rotate in reverse direction + * 2 - Translate as landscape direction + * 3 - Translate in reverse direction +If translation is chosen, texture is repeated horizontally to fill the whole element. Representations of simple things ================================ @@ -1621,6 +1734,7 @@ to games. * `2`: the node always gets the digging time 0.5 seconds (rail, sign) * `3`: the node always gets the digging time 0 seconds (torch) * `disable_jump`: Player (and possibly other things) cannot jump from node + or if their feet are in the node. Note: not supported for `new_move = false` * `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)` * `falling_node`: if there is no walkable block under the node it will fall * `float`: the node will not fall through liquids @@ -2081,6 +2195,26 @@ Elements * End of a container, following elements are no longer relative to this container. +### `scroll_container[,;,;;;]` + +* Start of a scroll_container block. All contained elements will ... + * take the scroll_container coordinate as position origin, + * be additionally moved by the current value of the scrollbar with the name + `scrollbar name` times `scroll factor` along the orientation `orientation` and + * be clipped to the rectangle defined by `X`, `Y`, `W` and `H`. +* `orientation`: possible values are `vertical` and `horizontal`. +* `scroll factor`: optional, defaults to `0.1`. +* Nesting is possible. +* Some elements might work a little different if they are in a scroll_container. +* Note: If you want the scroll_container to actually work, you also need to add a + scrollbar element with the specified name. Furthermore, it is highly recommended + to use a scrollbaroptions element on this scrollbar. + +### `scroll_container_end[]` + +* End of a scroll_container, following elements are no longer bound to this + container. + ### `list[;;,;,;]` * Show an inventory list if it has been sent to the client. Nothing will @@ -2376,8 +2510,10 @@ Elements * Simple colored box * `color` is color specified as a `ColorString`. If the alpha component is left blank, the box will be semitransparent. + If the color is not specified, the box will use the options specified by + its style. If the color is specified, all styling options will be ignored. -### `dropdown[,;;;,, ...,;]` +### `dropdown[,;;;,, ...,;;]` * Show a dropdown field * **Important note**: There are two different operation modes: @@ -2388,8 +2524,12 @@ Elements * Fieldname data is transferred to Lua * Items to be shown in dropdown * Index of currently selected dropdown item +* `index event` (optional, allowed parameter since formspec version 4): Specifies the + event field value for selected items. + * `true`: Selected item index + * `false` (default): Selected item value -### `dropdown[,;,;;,, ...,;]` +### `dropdown[,;,;;,, ...,;;]` * Show a dropdown field * **Important note**: This syntax for dropdowns can only be used with the @@ -2402,6 +2542,10 @@ Elements * Fieldname data is transferred to Lua * Items to be shown in dropdown * Index of currently selected dropdown item +* `index event` (optional, allowed parameter since formspec version 4): Specifies the + event field value for selected items. + * `true`: Selected item index + * `false` (default): Selected item value ### `checkbox[,;;