-Minetest Lua Modding API Reference 0.4.14
+Minetest Lua Modding API Reference 0.4.15
=========================================
* More information at <http://www.minetest.net/>
* Developer Wiki: <http://dev.minetest.net/>
The mask is applied using binary AND.
+#### `[sheet:<w>x<h>:<x>,<y>`
+Retrieves a tile at position x,y from the base image
+which it assumes to be a tilesheet with dimensions w,h.
+
+
#### `[colorize:<color>:<ratio>`
Colorize the textures with the given color.
`<color>` is specified as a `ColorString`.
`<color>` and the alpha of `<color>` multiplied by the alpha of the
texture pixel.
-Particle blend
---------------
-Blend function is defined by integer number.
-There is a huge number of acceptable blend modificators.
-Colour of a resulting pixel calculated using formulae:
-
- red = source_red * source_factor + destination_red * destination_factor
-
-and so on for every channel.
-
-Here is a some examples:
-
-Default value:
-
- material_type_param = 0,
-
-Use this value to disable blending. Texture will be applied to existing pixels
-using alpha channel of it. Its recomended to use 1-bit alpha
-in that case. This value will leave z-buffer writeable.
-
-Additive blend:
-
- material_type_param = 12641,
-
-Source = src_alpha, destination = one, alpha source is a texture and
-vertex_color, modulate_1x.
-Black color is completely transparent, white color is completely opaque.
-Alpha channel still used to calculate result color, but not nessesary.
-'destination = one' means that resulting color will be calculated using
-overwritten pixels values.
-For example with color of source (our texture) RGBA = (0,192,255,63)
-"blue-cyan", 1/4 opaque.
-and already rendered pixel color (40,192,0) "dark lime green" we will get color:
-
-R = source_red(0) * source_factor(src_alpha=63/255) +
- destination_red(40) * destination_factor(one) =
- 0 * 63/255 + 40 * 1 = 40
-
-G = 192 * 63/255 + 192 * 1 = 239
-B = 255 * 63/255 + 0 * 1 = 63
-
-Result: (40,239,63), "green" (a kind of).
-Note, if you made a texture with some kind of shape with colour 662211h
-it will appear dark red with a single particle, then yellow with a
-several of them and white if player looking thru a lot of them. With
-this you could made a nice-looking fire.
-
-Substractive blend:
-
- material_type_param = 12548,
-
-Source = zero, destination = src_color, alpha source is a texture and
-vertex_color, modulate_1x.
-Texture darkness act like an alpha channel.
-Black color is completely opaque, white color is completely transparent.
-'destination = src_color' means that destination in multiplied by
-a source values. 'source = zero' means that source values ignored
-(multiplied by 0).
-
-Invert blend:
-
- material_type_param = 12597,
-
-Source = one_minus_dst_color, destination = one_minus_src_alpha, alpha source
-is a texture and vertex_color, modulate_1x.
-Pixels invert color if source color value is big enough. If not, they just
-black.
-'destination = one_minus_src_alpha' means, that effect is masked by a
-source alpha channel.
-
-You can design and use your own blend using those enum values and function
-'minetest.pack_texture_blend_func'. Returned value of a function is
-your 'material_type_param'.
-
-A values in a brackets is a multiplicators of a red, green, blue
-and alpha channels respectively.
-
-* 'minetest.ebf': global table, containing blend factor enum values. Such as:
- * zero = 0 -- src & dest (0, 0, 0, 0)
- * one = 1 -- src & dest (1, 1, 1, 1)
- * dst_color = 2 -- src (destR, destG, destB, destA)
- * one_minus_dst_color = 3 -- src (1-destR, 1-destG, 1-destB, 1-destA)
- * src_color = 4 -- dest (srcR, srcG, srcB, srcA)
- * one_minus_src_color = 5 -- dest (1-srcR, 1-srcG, 1-srcB, 1-srcA)
- * src_alpha = 6 -- src & dest (srcA, srcA, srcA, srcA)
- * one_minus_src_alpha = 7 -- src & dest (1-srcA, 1-srcA, 1-srcA, 1-srcA)
- * dst_alpha = 8 -- src & dest (destA, destA, destA, destA)
- * one_minus_dst_alpha = 9 -- src & dest (1-destA, 1-destA, 1-destA, 1-destA)
- * src_alpha_saturate = 10 -- src (min(srcA, 1-destA), idem, ...)
-
-* 'minetest.emfn': global table, containing modulate enum values.
- * Multiply the components of the arguments, and shift the products to the
- * left by x bits for brightening. Contain:
- * modulate_1x = 1 -- no bit shift
- * modulate_2x = 2 -- 1 bits shift
- * modulate_4x = 4 -- 2 bits shift
-
-'modulate_4x' is quite useful when you want to make additive blend stronger
-with a lower amount of particles.
-
-* 'minetest.eas': global table, containing alpha source enum values. Such as:
- * none = 0 -- do not use alpha.
- * vertex_color = 1 -- use vertex color alpha.
- * texture = 2 -- use texture alpha.
-
-You can use both 'vertex_color' and 'texture' source by using value 3.
-
-* 'minetest.pack_texture_blend_func(srcFact, dstFact, modulate, alphaSource)': return integer
- * Pack texture blend funcion variable. Depending from that variable blend
- * function will be applied in time of a render poligons with selected material.
- * Therefore resulting pixel will be 'source * srcFact + destination * dstFact'
- * Use result of this function as 'material_type_param'.
-
Sounds
------
Only Ogg Vorbis files are supported.
Examples of sound parameter tables:
- -- Play location-less on all clients
+ -- Play locationless on all clients
{
gain = 1.0, -- default
}
- -- Play location-less to a player
+ -- 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},
+ pos = {x = 1, y = 2, z = 3},
gain = 1.0, -- default
max_hear_distance = 32, -- default, uses an euclidean metric
}
object = <an ObjectRef>,
gain = 1.0, -- default
max_hear_distance = 32, -- default, uses an euclidean metric
- loop = true, -- only sounds connected to objects can be looped
+ 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}`
+* e.g. `{name = "default_place_node"}`
+* e.g. `{name = "default_place_node", gain = 1.0}`
Registered definitions of stuff
-------------------------------
* `"nodemeta:<X>,<Y>,<Z>"`: Any node metadata
* `"detached:<name>"`: A detached inventory
+Player Inventory lists
+----------------------
+* `main`: list containing the default inventory
+* `craft`: list containing the craft input
+* `craftpreview`: list containing the craft output
+* `hand`: list containing an override for the empty hand
+
`ColorString`
-------------
`#RGB` defines a color in hexadecimal format.
* `minetest.register_on_cheat(func(ObjectRef, cheat))`
* Called when a player cheats
* `cheat`: `{type=<cheat_type>}`, where `<cheat_type>` is one of:
- * `"moved_too_fast"`
- * `"interacted_too_far"`
- * `"finished_unknown_dig"`
+ * `moved_too_fast`
+ * `interacted_too_far`
+ * `interacted_while_dead`
+ * `finished_unknown_dig`
* `dug_unbreakable`
* `dug_too_fast`
* `minetest.register_on_chat_message(func(name, message))`
### Other registration functions
* `minetest.register_chatcommand(cmd, chatcommand definition)`
+ * Adds definition to minetest.registered_chatcommands
* `minetest.register_privilege(name, definition)`
* `definition`: `"description text"`
* `definition`: `{ description = "description text", give_to_singleplayer = boolean}`
* `minetest.set_node(pos, node)`
* `minetest.add_node(pos, node): alias set_node(pos, node)`
* Set node at position (`node = {name="foo", param1=0, param2=0}`)
-* `minetest.swap_node(pos, node`
+* `minetest.swap_node(pos, node)`
* Set node at position, but don't remove metadata
* `minetest.remove_node(pos)`
* Equivalent to `set_node(pos, "air")`
* `{type="player", name="celeron55"}`
* `{type="node", pos={x=, y=, z=}}`
* `{type="detached", name="creative"}`
-* `minetest.create_detached_inventory(name, callbacks)`: returns an `InvRef`
+* `minetest.create_detached_inventory(name, callbacks, [player_name])`: returns an `InvRef`
* callbacks: See "Detached inventory callbacks"
+ * player_name: Make detached inventory available to one player exclusively,
+ by default they will be sent to every player (even if not used).
+ Note that this parameter is mostly just a workaround and will be removed in future releases.
* Creates a detached inventory. If it already exists, it is cleared.
* `minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)`:
returns left over ItemStack
* `formname`: name passed to `on_player_receive_fields` callbacks.
It should follow the `"modname:<whatever>"` naming convention
* `formspec`: formspec to display
+* `minetest.close_formspec(playername, formname)`
+ * `playername`: name of player to close formspec
+ * `formname`: has to exactly match the one given in show_formspec, or the formspec will
+ not close.
+ * calling show_formspec(playername, formname, "") is equal to this expression
+ * to close a formspec regardless of the formname, call
+ minetest.close_formspec(playername, ""). USE THIS ONLY WHEN ABSOLUTELY NECESSARY!
* `minetest.formspec_escape(string)`: returns a string
* escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs
* `minetest.explode_table_event(string)`: returns a table
### Misc.
* `minetest.get_connected_players()`: returns list of `ObjectRefs`
+* `minetest.hud_replace_builtin(name, hud_definition)`
+ * Replaces definition of a builtin hud element
+ * `name`: `"breath"` or `"health"`
+ * `hud_definition`: definition to replace builtin definition
* `minetest.hash_node_position({x=,y=,z=})`: returns an 48-bit integer
* Gives a unique hash number for a node position (16+16+16=48bit)
* `minetest.get_position_from_hash(hash)`: returns a position
* Map of object references, indexed by active object id
* `minetest.luaentities`
* Map of Lua entities, indexed by active object id
+* `minetest.registered_chatcommands`
+ * Map of registered chat command definitions, indexed by name
* `minetest.registered_ores`
* List of registered ore definitions.
* `minetest.registered_biomes`
* `hud_set_hotbar_selected_image(texturename)`
* sets image for selected item of hotbar
* `hud_get_hotbar_selected_image`: returns texturename
-* `hud_replace_builtin(name, hud_definition)`
- * replace definition of a builtin hud element
- * `name`: `"breath"` or `"health"`
- * `hud_definition`: definition to replace builtin definition
* `set_sky(bgcolor, type, {texture names})`
* `bgcolor`: ColorSpec, defaults to white
* Available types:
-- ^ Called sometimes; the string returned is passed to on_activate when
-- the entity is re-activated from static state
- -- Also you can define arbitrary member variables here
- myvariable = whatever,
+ -- Also you can define arbitrary member variables here (see item definition for
+ -- more info)
+ _custom_field = whatever,
}
### ABM (ActiveBlockModifier) definition (`register_abm`)
actual result to client in a short moment.
]]
sound = {
+ breaks = "default_tool_break", -- tools only
place = --[[<SimpleSoundSpec>]],
},
end
^ The user may be any ObjectRef or nil.
]]
+ _custom_field = whatever,
+ --[[
+ ^ Add your own custom fields. By convention, all custom field names
+ should start with `_` to avoid naming collisions with future engine
+ usage.
+ ]]
}
### Tile definition
* `"image.png"`
-* `{name="image.png", animation={Animation definition}}`
+* `{name="image.png", animation={Tile Animation definition}}`
* `{name="image.png", backface_culling=bool, tileable_vertical=bool,
tileable_horizontal=bool}`
* backface culling enabled by default for most nodes
* deprecated, yet still supported field names:
* `image` (name)
-### Animation definition
-
-#### Node animation, particle and particle spawners
-* `{ type="vertical_frames",
- aspect_w=16,
- -- ^ specify width of a picture in pixels.
- aspect_h=16,
- -- ^ specify height of a frame in pixels.
- length=3.0
- -- ^ specify full loop length.
- first_frame = 0, -- <- only for particles, use
- min_first_frame = 0, -- <- for particle spawners
- max_first_frame = 0,
- loop_animation = true, -- <- only for particles and particle spawners
- -- specify if animation should start from beginning after last frame.
-}`
-
-#### Particle and particle spawners only
-* `{
- type="2d_animation_sheet", -- <- only for particles and particle spawners
- vertical_frame_num = 1,
- horizontal_frame_num = 1,
- -- ^ specify amount of frames in texture.
- -- Can be used both for animation or for texture transform
- -- together with first_frame variable.
- -- A animation texture separated on equal parts of frames,
- -- by horizontal and vertical numbers. For example with
- -- vertical_frame_num = 4 and horizontal_frame_num = 3 we got
- -- 4*3 = 12 frames in total. Animation sequence start from
- -- left top frame and go on to the right until reach end of
- -- row. Next row also start from left frame.
- first_frame = 0, -- <- only for particles, use
- min_first_frame = 0, -- <- for particle spawners
- max_first_frame = 0,
- -- ^ specify first frame to start animation.
- frame_length = -1,
- -- ^ specify length of a frame in seconds. Negative and zero values
- -- disable animation. A sequence with vertical_frame_num = 4 and
- -- horizontal_frame_num = 3, first_frame = 4 and frame_length = 0.1
- -- will end in (4*3-4)*0.1 = 0.8 seconds.
- loop_animation = true,
- -- specify if animation should start from beginning after last frame.
-}`
- * All settings are optional. Default values is located in this example.
+### Tile animation definition
+
+ {
+ type = "vertical_frames",
+ aspect_w = 16,
+ -- ^ specify width of a frame in pixels
+ aspect_h = 16,
+ -- ^ specify height of a frame in pixels
+ length = 3.0,
+ -- ^ specify full loop length
+ }
+
+ {
+ type = "sheet_2d",
+ frames_w = 5,
+ -- ^ specify width in number of frames
+ frames_h = 3,
+ -- ^ specify height in number of frames
+ frame_length = 0.5,
+ -- ^ specify length of a single frame
+ }
### Node definition (`register_node`)
-- ^ Number of nodes high the decoration is made.
-- ^ If height_max is not 0, this is the lower bound of the randomly selected height.
height_max = 0,
- -- ^ Number of nodes the decoration can be at maximum.
+ -- ^ Number of nodes the decoration can be at maximum.
-- ^ If absent, the parameter 'height' is used as a constant.
+ param2 = 0,
+ -- ^ Param2 value of placed decoration node.
----- Schematic-type parameters
schematic = "foobar.mts",
-- ^ Uses texture (string)
playername = "singleplayer"
-- ^ optional, if specified spawns particle only on the player's client
- material_type_param = 12641,
- -- ^ optional, if specified spawns particle with
- -- specified material type param and disable z-buffer.
- -- Some examples:
- -- Default value: 0,
- -- Additive blend: 12641,
- -- Substractive blend: 12548,
- -- Invert blend: 12597,
- -- See also "Particle blend".
- animation = {Animation definition},
- -- ^ see above. Note, that particle and particle spawners have differences.
- glow = 15,
- -- ^ optional, specify particle self-luminescence in darkness.
- values may vary from 0 (no glow) to 15 (bright glow).
}
### `ParticleSpawner` definition (`add_particlespawner`)
-- ^ collision_removal: if true then particle is removed when it collides,
-- ^ requires collisiondetection = true to have any effect
attached = ObjectRef,
- -- ^ attached: if defined, makes particle positions relative to this object.
+ -- ^ attached: if defined, particle positions, velocities and accelerations
+ -- ^ are relative to this object's position and yaw.
vertical = false,
-- ^ vertical: if true faces player using y axis only
texture = "image.png",
-- ^ Uses texture (string)
playername = "singleplayer"
-- ^ Playername is optional, if specified spawns particle only on the player's client
- material_type_param = 12641,
- -- ^ optional, if specified spawns particle with specified material type
- -- param and disable z-buffer.
- -- Some examples:
- -- Default value: 0,
- -- Additive blend: 12641,
- -- Substractive blend: 12548,
- -- Invert blend: 12597,
- -- See also "Particle blend".
- animation = {Animation definition},
- -- ^ see above. Note, that particle and particle spawners have differences.
- glow = 15,
- -- ^ optional, specify particle self-luminescence in darkness.
- values may vary from 0 (no glow) to 15 (bright glow).
}
### `HTTPRequest` definition (`HTTPApiTable.fetch_async`, `HTTPApiTable.fetch_async`)
projects / oweals / minetest.git / blobdiff