-Minetest Lua Modding API Reference 0.4.7
+Minetest Lua Modding API Reference 0.4.8
========================================
More information at http://www.minetest.net/
Developer Wiki: http://dev.minetest.net/
mods
|-- modname
| |-- depends.txt
+| |-- screenshot.png
+| |-- description.txt
| |-- init.lua
| |-- textures
| | |-- modname_stuff.png
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 modmanager within mainmenu.
+
+description.txt:
+ File containing desctiption to be shown within mainmenu.
+
optdepends.txt:
An alternative way of specifying optional dependencies.
Like depends.txt, a single line contains a single modname.
- image
Displays an image on the HUD.
- - scale: The scale of the image, with 1 being the original texture size.
- Only the X coordinate scale is used.
+ - 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.
- offset: offset in pixels from position.
list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]
^ Show an inventory list
+listcolors[<slot_bg_normal>;<slot_bg_hover>]
+^ Sets background color of slots in HEX-Color format
+^ Sets background color of slots on mouse hovering
+
+listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]
+^ Sets background color of slots in HEX-Color format
+^ Sets background color of slots on mouse hovering
+^ Sets color of slots border
+
+listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]
+^ Sets background color of slots in HEX-Color format
+^ Sets background color of slots on mouse hovering
+^ Sets color of slots border
+^ Sets background color of tooltips
+^ Sets font color of tooltips
+
image[<X>,<Y>;<W>,<H>;<texture name>]
^ Show an image
^ Position and size units are inventory slots
^ Show an inventory image of registered item/node
^ Position and size units are inventory slots
+bgcolor[<color>;<fullscreen>]
+^ Sets background color of formspec in HEX-Color format
+^ If true the background color is drawn fullscreen (does not effect the size of the formspec)
+
background[<X>,<Y>;<W>,<H>;<texture name>]
^ 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*16px x 4*16px
+background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]
+^ 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*16px x 4*16px
+^ If true the background is clipped to formspec size (x and y are used as offset values, w and h are ignored)
+
pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]
^ Textual password style field; will be sent to server when a button is clicked
^ x and y position the field relative to the top left of the menu
^ x and y position the itemlist relative to the top left of the menu
^ w and h are the size of the itemlist
^ name fieldname sent to server on doubleclick value is current selected element
-^ listelements can be prepended by #color in hexadecimal format RRGGBB,
+^ listelements can be prepended by #color in hexadecimal format RRGGBB (only),
^ if you want a listelement to start with # write ##
textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]
^ x and y position the itemlist relative to the top left of the menu
^ w and h are the size of the itemlist
^ name fieldname sent to server on doubleclick value is current selected element
-^ listelements can be prepended by #RRGGBB in hexadecimal format
+^ listelements can be prepended by #RRGGBB (only) in hexadecimal format
^ if you want a listelement to start with # write ##
^ index to be selected within textlist
^ true/false draw transparent background
^ simple colored semitransparent box
^ x and y position the box relative to the top left of the menu
^ w and h are the size of box
-^ color in hexadecimal format RRGGBB
+^ color in HEX-Color format
dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]
^ show a dropdown field
^ fieldname data is transfered to lua
^ items to be shown in dropdown
^ index of currently selected dropdown item
-^ color in hexadecimal format RRGGBB
+^ color in hexadecimal format RRGGBB (only)
checkbox[<X>,<Y>;<name>;<label>;<selected>]
^ show a checkbox
- "nodemeta:<X>,<Y>,<Z>": Any node metadata
- "detached:<name>": A detached inventory
+HEX-Color
+---------
+#RGB
+^ defines a color in hexadecimal format
+#RGBA
+^ defines a color in hexadecimal format and alpha channel
+#RRGGBB
+^ defines a color in hexadecimal format
+#RRGGBBAA
+^ defines a color in hexadecimal format and alpha channel
+
Vector helpers
---------------
vector.new([x[, y, z]]) -> vector
vector.length(v) -> number
vector.normalize(v) -> vector
vector.round(v) -> vector
-vector.equal(v1, v2) -> bool
+vector.equals(v1, v2) -> bool
+For the folowing x can be either a vector or a number.
vector.add(v, x) -> vector
- ^ x can be annother vector or a number
vector.subtract(v, x) -> vector
vector.multiply(v, x) -> vector
vector.divide(v, x) -> vector
-You can also use Lua operators on vectors.
-For example:
- v1 = vector.new()
- v1 = v1 + 5
- v2 = vector.new(v1)
- v1 = v1 * v2
- if v1 == v2 then
- error("Math broke")
- end
-
Helper functions
-----------------
dump2(obj, name="_", dumped={})
minetest.string_to_pos(string) -> position
^ Same but in reverse
^ escapes characters [ ] \ , ; that can not be used in formspecs
+minetest.is_yes(arg)
+^ returns whether arg can be interpreted as yes
minetest namespace reference
-----------------------------
Global callback registration functions: (Call these only at load time)
minetest.register_globalstep(func(dtime))
-^ Called every server step, usually interval of 0.05s
+^ Called every server step, usually interval of 0.1s
minetest.register_on_shutdown(func())
^ Called before server shutdown
^ WARNING: If the server terminates abnormally (i.e. crashes), the registered
minetest.register_on_mapgen_init(func(MapgenParams))
^ Called just before the map generator is initialized but before the environment is initialized
^ MapgenParams consists of a table with the fields mgname, seed, water_level, and flags
+minetest.register_on_craft(func(itemstack, player, old_craft_grid, craft_inv))
+^ Called when player crafts something
+^ itemstack is the output
+^ old_craft_grid contains the recipe (Note: the one in the inventory is cleared)
+^ craft_inv is the inventory with the crafting grid
+^ Return either an ItemStack, to replace the output, or nil, to not modify it
+minetest.register_craft_predict(func(itemstack, player, old_craft_grid, craft_inv))
+^ The same as before, except that it is called before the player crafts, to make
+^ craft prediction, and it should not change anything.
+minetest.register_on_protection_violation(func(pos, name))
+^ Called by builtin and mods when a player violates protection at a position
+ (eg, digs a node or punches a protected entity).
+^ The registered functions can be called using minetest.record_protection_violation
+^ The provided function should check that the position is protected by the mod
+ calling this function before it prints a message, if it does, to allow for
+ multiple protection mods.
Other registration functions:
minetest.register_chatcommand(cmd, chatcommand definition)
minetest.get_objects_inside_radius(pos, radius)
minetest.set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
minetest.get_timeofday()
+minetest.get_gametime(): returns the time, in seconds, since the world was created
minetest.find_node_near(pos, radius, nodenames) -> pos or nil
^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
minetest.find_nodes_in_area(minp, maxp, nodenames) -> list of positions
^ Can be overridden to get different functionality (eg. dropping items on
ground)
-Rollbacks:
-minetest.rollback_get_last_node_actor(p, range, seconds) -> actor, p, seconds
+Rollback:
+minetest.rollback_get_node_actions(pos, range, seconds, limit) -> {{actor, pos, time, oldnode, newnode}, ...}
^ Find who has done something to a node, or near a node
^ actor: "player:<name>", also "liquid".
minetest.rollback_revert_actions_by(actor, seconds) -> bool, log messages
Defaults for the on_* item definition functions:
(These return the leftover itemstack)
-minetest.item_place_node(itemstack, placer, pointed_thing)
+minetest.item_place_node(itemstack, placer, pointed_thing, param2)
^ Place item as a node
+^ param2 overrides facedir and wallmounted param2
+^ returns itemstack, success
minetest.item_place_object(itemstack, placer, pointed_thing)
^ Place item as-is
-minetest.item_place(itemstack, placer, pointed_thing)
+minetest.item_place(itemstack, placer, pointed_thing, param2)
^ Use one of the above based on what the item is.
^ Calls on_rightclick of pointed_thing.under if defined instead
^ Note: is not called when wielded item overrides on_place
+^ param2 overrides facedir and wallmounted param2
+^ returns itemstack, success
minetest.item_drop(itemstack, dropper, pos)
^ Drop the item
minetest.item_eat(hp_change, replace_with_item)
^ Example: deserialize('return { ["foo"] = "bar" }') -> {foo='bar'}
^ Example: deserialize('print("foo")') -> nil (function call fails)
^ error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)
+minetest.is_protected(pos, name) -> bool
+^ This function should be overriden by protection mods and should be used to
+ check if a player can interact at a position.
+^ This function should call the old version of itself if the position is not
+ protected by the mod.
+^ Example:
+ local old_is_protected = minetest.is_protected
+ function minetest.is_protected(pos, name)
+ if mymod:position_protected_from(pos, name) then
+ return true
+ end
+ return old_is_protected(pos, name)
+ end
+minetest.record_protection_violation(pos, name)
+^ This function calls functions registered with
+ minetest.register_on_protection_violation.
+minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)
+^ Attempt to predict the desired orientation of the facedir-capable node
+ defined by itemstack, and place it accordingly (on-wall, on the floor, or
+ hanging from the ceiling). Stacks are handled normally if the infinitestacks
+ field is false or omitted (else, the itemstack is not changed). orient_flags
+ is an optional table containing extra tweaks to the placement code:
+ invert_wall: if true, place wall-orientation on the ground and ground-
+ orientation on the wall.
+ force_wall: if true, always place the node in wall orientation.
+ force_ceiling: if true, always place on the ceiling.
+ force_floor: if true, always place the node on the floor.
+
+ The above four options are mutually-exclusive; the last in the list takes
+ precedence over the first.
+
+ force_facedir: if true, forcably reset the facedir to north when placing on
+ the floor or ceiling
+
+minetest.rotate_node(itemstack, placer, pointed_thing)
+^ calls rotate_and_place() with infinitestacks set according to the state of
+ the creative mode setting, and checks for "sneak" to set the invert_wall
+ parameter.
Global objects:
minetest.env - EnvRef of the server environment and world.
^ if a flag is nil, the flag is not modified
- hud_set_hotbar_itemcount(count): sets number of items in builtin hotbar
^ count: number of items, must be between 1 and 23
+- hud_set_hotbar_image(texturename)
+ ^ sets background image for hotbar
+- hud_set_hotbar_selected_image(texturename)
+ ^ sets image for selected item of hotbar
InvRef: Reference to an inventory
methods:
- is_empty(listname): return true if list is empty
- get_size(listname): get size of a list
- set_size(listname, size): set size of a list
+ ^ returns false on error (e.g. invalid listname or listsize)
- get_width(listname): get width of a list
- set_width(listname, width): set width of list; currently used for crafting
- get_stack(listname, i): get a copy of stack index i in list
methods:
- is_empty(): return true if stack is empty
- get_name(): returns item name (e.g. "default:stone")
+- set_name(itemname)
- get_count(): returns number of items on the stack
+- set_count(count)
- get_wear(): returns tool wear (0-65535), 0 for non-tools
+- set_wear(wear)
- get_metadata(): returns metadata (a string attached to an item stack)
+- set_metadata(metadata)
- clear(): removes all items from the stack, making it empty
- replace(item): replace the contents of this stack (item can also
be an itemstring or table)
- update_map(): Update map after writing chunk back to map.
^ To be used only by VoxelManip objects created by the mod itself; not a VoxelManip that was
^ retrieved from minetest.get_mapgen_object
-- set_lighting(light): Set the lighting within the VoxelManip
+- set_lighting(light, p1, p2): Set the lighting within the VoxelManip to a uniform value
^ light is a table, {day=<0...15>, night=<0...15>}
^ To be used only by a VoxelManip object from minetest.get_mapgen_object
-- calc_lighting(): Calculate lighting within the VoxelManip
+ ^ (p1, p2) is the area in which lighting is set; defaults to the whole area if left out
+- get_light_data(): Gets the light data read into the VoxelManip object
+ ^ Returns an array (indicies 1 to volume) of integers ranging from 0 to 255
+ ^ Each value is the bitwise combination of day and night light values (0..15 each)
+ ^ light = day + (night * 16)
+- set_light_data(light_data): Sets the param1 (light) contents of each node in the VoxelManip
+ ^ expects lighting data in the same format that get_light_data() returns
+- calc_lighting(p1, p2): Calculate lighting within the VoxelManip
^ 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
- update_liquids(): Update liquid flow
VoxelArea: A helper class for voxel areas
^ from (minx,miny,minz) to (maxx,maxy,maxz) in the order of [z [y [x]]]
- iterp(minp, maxp): same as above, except takes a vector
+Settings: An interface to read config files in the format of minetest.conf
+- Can be created via Settings(filename)
+methods:
+- get(key) -> value
+- get_bool(key) -> boolean
+- set(key, value)
+- remove(key) -> success
+- get_names() -> {key1,...}
+- write() -> success
+ ^ write changes to file
+- to_table() -> {[key1]=value1,...}
+
Mapgen objects
---------------
A mapgen object is a construct used in map generation. Mapgen objects can be used by an on_generate
- on_activate(self, staticdata)
^ Called when the object is instantiated.
- on_step(self, dtime)
- ^ Called on every server tick (dtime is usually 0.05 seconds)
+ ^ Called on every server tick (dtime is usually 0.1 seconds)
- on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
^ Called when somebody punches the object.
^ Note that you probably want to handle most punches using the
makes_footstep_sound = false,
automatic_rotate = false,
stepheight = 0,
- automatic_face_movement_dir = false,
+ automatic_face_movement_dir = 0.0,
+ ^ automatically set yaw to movement direction; offset in degrees; false to disable
}
Entity definition (register_entity)
eg. itemstack:take_item(); return itemstack
^ Otherwise, the function is free to do what it wants.
^ The default functions handle regular use cases.
+ after_use = func(itemstack, user, node, digparams),
+ ^ default: nil
+ ^ If defined, should return an itemstack and will be called instead of
+ wearing out the tool. If returns nil, does nothing.
+ If after_use doesn't exist, it is the same as:
+ function(itemstack, user, node, digparams)
+ itemstack:add_wear(digparams.wear)
+ return itemstack
+ end
}
Tile definition:
drawtype = "normal", -- See "Node drawtypes"
visual_scale = 1.0,
+ ^ Supported for drawtypes "plantlike", "signlike", "torchlike".
+ ^ For plantlike, the image will start at the bottom of the node; for the
+ ^ other drawtypes, the image will be centered on the node.
+ ^ Note that positioning for "torchlike" may still change.
tiles = {tile definition 1, def2, def3, def4, def5, def6},
^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
^ List can be shortened to needed length
projects / dragonfireclient.git / blobdiff