X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=doc%2Flua_api.txt;h=352b04cb0d4347bd0387597f2d3003e8bd85aa64;hb=cb00632e23a41d8d171631de9d85e168b251b80e;hp=05ea6b4bcfe65262c76e7273b32ee3297ba4d93f;hpb=60ab2d94f07953e74fc98a33d468328c2adac75b;p=minetest.git
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 05ea6b4bc..352b04cb0 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -4,9 +4,8 @@ Minetest Lua Modding API Reference
* More information at
* Developer Wiki:
-
Introduction
-============
+------------
Content and functionality can be added to Minetest using Lua scripting
in run-time loaded mods.
@@ -1171,6 +1170,64 @@ A box of a regular node would look like:
+Map terminology and coordinates
+===============================
+
+Nodes, mapblocks, mapchunks
+---------------------------
+
+A 'node' is the fundamental cubic unit of a world and appears to a player as
+roughly 1x1x1 meters in size.
+
+A 'mapblock' (often abbreviated to 'block') is 16x16x16 nodes and is the
+fundamental region of a world that is stored in the world database, sent to
+clients and handled by many parts of the engine.
+'mapblock' is preferred terminology to 'block' to help avoid confusion with
+'node', however 'block' often appears in the API.
+
+A 'mapchunk' (sometimes abbreviated to 'chunk') is usually 5x5x5 mapblocks
+(80x80x80 nodes) and is the volume of world generated in one operation by
+the map generator.
+The size in mapblocks has been chosen to optimise map generation.
+
+Coordinates
+-----------
+
+### Orientation of axes
+
+For node and mapblock coordinates, +X is East, +Y is up, +Z is North.
+
+### Node coordinates
+
+Almost all positions used in the API use node coordinates.
+
+### Mapblock coordinates
+
+Occasionally the API uses 'blockpos' which refers to mapblock coordinates that
+specify a particular mapblock.
+For example blockpos (0,0,0) specifies the mapblock that extends from
+node position (0,0,0) to node position (15,15,15).
+
+#### Converting node position to the containing blockpos
+
+To calculate the blockpos of the mapblock that contains the node at 'nodepos',
+for each axis:
+
+* blockpos = math.floor(nodepos / 16)
+
+#### Converting blockpos to min/max node positions
+
+To calculate the min/max node positions contained in the mapblock at 'blockpos',
+for each axis:
+
+* Minimum:
+ nodepos = blockpos * 16
+* Maximum:
+ nodepos = blockpos * 16 + 15
+
+
+
+
HUD
===
@@ -1502,6 +1559,7 @@ Special groups
* `fall_damage_add_percent`: damage speed = `speed * (1 + value/100)`
* `bouncy`: value is bounce speed in percent
* `falling_node`: if there is no walkable block under the node it will fall
+* `float`: the node will not fall through liquids
* `attached_node`: if the node under it is not a walkable block the node will be
dropped as an item. If the node is wallmounted the wallmounted direction is
checked.
@@ -2340,6 +2398,8 @@ For the following functions, `v`, `v1`, `v2` are vectors,
* Returns a boolean, `true` if the vectors are identical.
* `vector.sort(v1, v2)`:
* Returns in order minp, maxp vectors of the cuboid defined by `v1`, `v2`.
+* `vector.angle(v1, v2)`:
+ * Returns the angle between `v1` and `v2` in radians.
For the following functions `x` can be either a vector or a number:
@@ -2378,6 +2438,7 @@ Helper functions
* tolerance: number, default: `0.0`
* If the absolute value of `x` is within the `tolerance` or `x` is NaN,
`0` is returned.
+* `math.factorial(x)`: returns the factorial of `x`
* `string.split(str, separator, include_empty, max_splits, sep_is_pattern)`
* `separator`: string, default: `","`
* `include_empty`: boolean, default: `false`
@@ -3191,10 +3252,8 @@ Methods
* To be used only by a `VoxelManip` object from
`minetest.get_mapgen_object`.
* (`p1`, `p2`) is the area in which lighting is set, defaults to the whole
- area if left out or nil.
- * Setting `p1`, `p2` to `emin`, `emax` of the mapgen object voxelmanip (the
- entire volume of the voxelmanip: the mapchunk plus a 1 mapblock thick
- shell around it) will cause an error.
+ area if left out or nil. For almost all uses these should be left out
+ or nil to use the default.
* `propagate_shadow` is an optional boolean deciding whether shadows in a
generated mapchunk above are propagated down into the mapchunk, defaults
to `true` if left out.
@@ -3468,11 +3527,14 @@ Utilities
-- Chat messages are no longer predicted (0.4.16)
no_chat_message_prediction = true,
-- The transparency channel of textures can optionally be used on
- -- objects (ie: players and lua entities) (5.0)
+ -- objects (ie: players and lua entities) (5.0.0)
object_use_texture_alpha = true,
-- Object selectionbox is settable independently from collisionbox
- -- (5.0)
+ -- (5.0.0)
object_independent_selectionbox = true,
+ -- Specifies whether binary data can be uploaded or downloaded using
+ -- the HTTP API (5.1.0)
+ httpfetch_binary_data = true,
}
* `minetest.has_feature(arg)`: returns `boolean, missing_features`
@@ -3659,6 +3721,7 @@ Call these functions only at load time!
* Called after a new player has been created
* `minetest.register_on_punchplayer(function(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))`
* Called when a player is punched
+ * Note: This callback is invoked even if the punched player is dead.
* `player`: ObjectRef - Player that was punched
* `hitter`: ObjectRef - Player that hit
* `time_from_last_punch`: Meant for disallowing spamming of clicks
@@ -3678,15 +3741,16 @@ Call these functions only at load time!
giving a type - use this for custom damage types.
* `punch`: Was punched. `reason.object` will hold the puncher, or nil if none.
* `fall`
- * `node_damage`: damage_per_second from a neighbouring node.
+ * `node_damage`: `damage_per_second` from a neighbouring node.
+ `reason.node` will hold the node name or nil.
* `drown`
* `respawn`
* Any of the above types may have additional fields from mods.
* `reason.from` will be `mod` or `engine`.
* `modifier`: when true, the function should return the actual `hp_change`.
- Note: modifiers only get a temporary hp_change that can be modified by later modifiers.
- modifiers can return true as a second argument to stop the execution of further functions.
- Non-modifiers receive the final hp change calculated by the modifiers.
+ Note: modifiers only get a temporary `hp_change` that can be modified by later modifiers.
+ Modifiers can return true as a second argument to stop the execution of further functions.
+ Non-modifiers receive the final HP change calculated by the modifiers.
* `minetest.register_on_dieplayer(function(ObjectRef, reason))`
* Called when a player dies
* `reason`: a PlayerHPChangeReason table, see register_on_player_hpchange
@@ -5322,6 +5386,11 @@ This is basically a reference to a C++ `ServerActiveObject`
* in first person view
* in third person view (max. values `{x=-10/10,y=-10,15,z=-5/5}`)
* `get_eye_offset()`: returns `offset_first` and `offset_third`
+* `send_mapblock(blockpos)`:
+ * Sends a server-side loaded mapblock to the player.
+ * Returns `false` if failed.
+ * Resource intensive - use sparsely
+ * To get blockpos, integer divide pos by 16
`PcgRandom`
-----------
@@ -5620,7 +5689,7 @@ Used by `ObjectRef` methods. Part of an Entity definition.
automatic_face_movement_max_rotation_per_sec = -1,
-- Limit automatic rotation to this value in degrees per second.
- -- No limit if value < 0.
+ -- No limit if value <= 0.
backface_culling = true,
-- Set to false to disable backface_culling for model
@@ -5980,7 +6049,11 @@ Used by `minetest.register_node`.
place_param2 = nil, -- Force value for param2 when player places node
is_ground_content = true,
- -- If false, the cave generator will not carve through this node
+ -- If false, the cave generator and dungeon generator will not carve
+ -- through this node.
+ -- Specifically, this stops mod-added nodes being removed by caves and
+ -- dungeons when those generate in a neighbor mapchunk and extend out
+ -- beyond the edge of that mapchunk.
sunlight_propagates = false,
-- If true, sunlight will go infinitely through this node
@@ -6071,12 +6144,15 @@ Used by `minetest.register_node`.
legacy_wallmounted = false,
waving = 0,
- -- Valid for mesh, nodebox, plantlike, allfaces_optional nodes.
- -- 1 - wave node like plants (top of node moves, bottom is fixed)
+ -- Valid for drawtypes:
+ -- mesh, nodebox, plantlike, allfaces_optional, liquid, flowingliquid.
+ -- 1 - wave node like plants (node top moves side-to-side, bottom is fixed)
-- 2 - wave node like leaves (whole node moves side-to-side)
- -- caveats: not all models will properly wave.
- -- plantlike drawtype nodes can only wave like plants.
- -- allfaces_optional drawtype nodes can only wave like leaves.
+ -- 3 - wave node like liquids (whole node moves up and down)
+ -- Not all models will properly wave.
+ -- plantlike drawtype can only wave like plants.
+ -- allfaces_optional drawtype can only wave like leaves.
+ -- liquid, flowingliquid drawtypes can only wave like liquids.
sounds = {
footstep = ,
@@ -6088,17 +6164,44 @@ Used by `minetest.register_node`.
},
drop = "",
- -- Name of dropped node when dug. Default is the node itself.
- -- Alternatively:
+ -- Name of dropped item when dug.
+ -- Default dropped item is the node itself.
+ -- Using a table allows multiple items, drop chances and tool filtering:
drop = {
- -- Maximum number of items to drop
max_items = 1,
- -- Choose max_items randomly from this list
+ -- Maximum number of item lists to drop.
+ -- The entries in 'items' are processed in order. For each:
+ -- Tool filtering is applied, chance of drop is applied, if both are
+ -- successful the entire item list is dropped.
+ -- Entry processing continues until the number of dropped item lists
+ -- equals 'max_items'.
+ -- Therefore, entries should progress from low to high drop chance.
items = {
+ -- Entry examples.
+ {
+ -- 1 in 1000 chance of dropping a diamond.
+ -- Default rarity is '1'.
+ rarity = 1000,
+ items = {"default:diamond"},
+ },
+ {
+ -- Only drop if using a tool whose name is identical to one
+ -- of these.
+ tools = {"default:shovel_mese", "default:shovel_diamond"},
+ rarity = 5,
+ items = {"default:dirt"},
+ -- Whether all items in the dropped item list inherit the
+ -- hardware coloring palette color from the dug node.
+ -- Default is 'false'.
+ inherit_color = true,
+ },
{
- items = {"foo:bar", "baz:frob"}, -- Items to drop
- rarity = 1, -- Probability of dropping is 1 / rarity
- inherit_color = true, -- Inherit palette color from the node
+ -- Only drop if using a tool whose name contains
+ -- "default:shovel_".
+ tools = {"~default:shovel_"},
+ rarity = 2,
+ -- The item list dropped.
+ items = {"default:sand", "default:desert_sand"},
},
},
},
@@ -6410,10 +6513,14 @@ Used by `minetest.register_biome`.
depth_riverbed = 2,
-- Node placed under river water and thickness of this layer
- node_cave_liquid = "default:water_source",
- -- Nodes placed as a blob of liquid in 50% of large caves.
- -- If absent, cave liquids fall back to classic behaviour of lava or
- -- water distributed according to a hardcoded 3D noise.
+ node_cave_liquid = "default:lava_source",
+ node_cave_liquid = {"default:water_source", "default:lava_source"},
+ -- Nodes placed inside 50% of the medium size caves.
+ -- Multiple nodes can be specified, each cave will use a randomly
+ -- chosen node from the list.
+ -- If this field is left out or 'nil', cave liquids fall back to
+ -- classic behaviour of lava and water distributed using 3D noise.
+ -- For no cave liquid, specify "air".
node_dungeon = "default:cobble",
-- Node used for primary dungeon structure.