5525 lines
366 KiB
HTML
5525 lines
366 KiB
HTML
---
|
||
title: Lua Modding API Reference
|
||
layout: default
|
||
---
|
||
<div class='notice'>
|
||
<h2>This is lua_api.txt nicely formated: I did not write this</h2>
|
||
This page was last updated 08/August/2017.<br />See <a href="https://github.com/minetest/minetest/blob/master/doc/lua_api.txt">doc/lua_api.txt</a> for the latest version (in plaintext).<br />Generated using <a href="https://github.com/rubenwardy/minetest_modding_book/blob/gh-pages/update_lua_api.py">a Python script</a>.</div>
|
||
<h2 id="table-of-contents">Table of Contents</h2>
|
||
<div class="toc">
|
||
<ul>
|
||
<li><a href="#minetest-lua-modding-api-reference-0416">Minetest Lua Modding API Reference 0.4.16</a><ul>
|
||
<li><a href="#introduction">Introduction</a></li>
|
||
<li><a href="#programming-in-lua">Programming in Lua</a></li>
|
||
<li><a href="#startup">Startup</a></li>
|
||
<li><a href="#paths">Paths</a></li>
|
||
<li><a href="#games">Games</a><ul>
|
||
<li><a href="#menu-images">Menu images</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#mod-load-path">Mod load path</a></li>
|
||
<li><a href="#mod-load-path-for-world-specific-games">Mod load path for world-specific games</a></li>
|
||
<li><a href="#modpack-support">Modpack support</a></li>
|
||
<li><a href="#mod-directory-structure">Mod directory structure</a><ul>
|
||
<li><a href="#modname">modname</a></li>
|
||
<li><a href="#dependstxt">depends.txt</a></li>
|
||
<li><a href="#screenshotpng">screenshot.png</a></li>
|
||
<li><a href="#descriptiontxt">description.txt</a></li>
|
||
<li><a href="#settingtypestxt">settingtypes.txt</a></li>
|
||
<li><a href="#initlua">init.lua</a></li>
|
||
<li><a href="#models">models</a></li>
|
||
<li><a href="#textures-sounds-media">textures, sounds, media</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#naming-convention-for-registered-textual-names">Naming convention for registered textual names</a><ul>
|
||
<li><a href="#example">Example</a></li>
|
||
<li><a href="#aliases">Aliases</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#textures">Textures</a></li>
|
||
<li><a href="#texture-modifiers">Texture modifiers</a><ul>
|
||
<li><a href="#texture-overlaying">Texture overlaying</a></li>
|
||
<li><a href="#texture-grouping">Texture grouping</a></li>
|
||
<li><a href="#escaping">Escaping</a></li>
|
||
<li><a href="#advanced-texture-modifiers">Advanced texture modifiers</a><ul>
|
||
<li><a href="#cracknp">[crack:<n>:<p></a></li>
|
||
<li><a href="#combinewxhx1y1file1x2y2file2">[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>:...</a></li>
|
||
<li><a href="#resizewxh">[resize:<w>x<h></a></li>
|
||
<li><a href="#opacityr">[opacity:<r></a></li>
|
||
<li><a href="#invertmode">[invert:<mode></a></li>
|
||
<li><a href="#brighten">[brighten</a></li>
|
||
<li><a href="#noalpha">[noalpha</a></li>
|
||
<li><a href="#makealphargb">[makealpha:<r>,<g>,<b></a></li>
|
||
<li><a href="#transformt">[transform<t></a></li>
|
||
<li><a href="#inventorycubetopleftright">[inventorycube{<top>{<left>{<right></a></li>
|
||
<li><a href="#lowpartpercentfile">[lowpart:<percent>:<file></a></li>
|
||
<li><a href="#verticalframetn">[verticalframe:<t>:<n></a></li>
|
||
<li><a href="#maskfile">[mask:<file></a></li>
|
||
<li><a href="#sheetwxhxy">[sheet:<w>x<h>:<x>,<y></a></li>
|
||
<li><a href="#colorizecolorratio">[colorize:<color>:<ratio></a></li>
|
||
<li><a href="#multiplycolor">[multiply:<color></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#hardware-coloring">Hardware coloring</a><ul>
|
||
<li><a href="#static-coloring">Static coloring</a><ul>
|
||
<li><a href="#global-color">Global color</a></li>
|
||
<li><a href="#tile-color">Tile color</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#palettes">Palettes</a><ul>
|
||
<li><a href="#palette-indexing">Palette indexing</a></li>
|
||
<li><a href="#using-palettes-with-items">Using palettes with items</a></li>
|
||
<li><a href="#linking-palettes-with-nodes">Linking palettes with nodes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#conversion-between-nodes-in-the-inventory-and-the-on-the-map">Conversion between nodes in the inventory and the on the map</a></li>
|
||
<li><a href="#colored-items-in-craft-recipes">Colored items in craft recipes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#soft-texture-overlay">Soft texture overlay</a></li>
|
||
<li><a href="#sounds">Sounds</a><ul>
|
||
<li><a href="#simplesoundspec">SimpleSoundSpec</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#registered-definitions-of-stuff">Registered definitions of stuff</a></li>
|
||
<li><a href="#nodes">Nodes</a></li>
|
||
<li><a href="#node-drawtypes">Node drawtypes</a></li>
|
||
<li><a href="#node-boxes">Node boxes</a></li>
|
||
<li><a href="#meshes">Meshes</a></li>
|
||
<li><a href="#noise-parameters">Noise Parameters</a><ul>
|
||
<li><a href="#offset">offset</a></li>
|
||
<li><a href="#scale">scale</a></li>
|
||
<li><a href="#spread">spread</a></li>
|
||
<li><a href="#seed">seed</a></li>
|
||
<li><a href="#octaves">octaves</a></li>
|
||
<li><a href="#persistence">persistence</a></li>
|
||
<li><a href="#lacunarity">lacunarity</a></li>
|
||
<li><a href="#flags">flags</a><ul>
|
||
<li><a href="#defaults">defaults</a></li>
|
||
<li><a href="#eased">eased</a></li>
|
||
<li><a href="#absvalue">absvalue</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#ore-types">Ore types</a><ul>
|
||
<li><a href="#scatter">scatter</a></li>
|
||
<li><a href="#sheet">sheet</a></li>
|
||
<li><a href="#puff">puff</a></li>
|
||
<li><a href="#blob">blob</a></li>
|
||
<li><a href="#vein">vein</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#ore-attributes">Ore attributes</a><ul>
|
||
<li><a href="#puff_cliffs">puff_cliffs</a></li>
|
||
<li><a href="#puff_additive_composition">puff_additive_composition</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#decoration-types">Decoration types</a><ul>
|
||
<li><a href="#simple">simple</a></li>
|
||
<li><a href="#schematic">schematic</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#schematic-specifier">Schematic specifier</a></li>
|
||
<li><a href="#schematic-attributes">Schematic attributes</a></li>
|
||
<li><a href="#hud-element-types">HUD element types</a><ul>
|
||
<li><a href="#image">image</a></li>
|
||
<li><a href="#text">text</a></li>
|
||
<li><a href="#statbar">statbar</a></li>
|
||
<li><a href="#inventory">inventory</a></li>
|
||
<li><a href="#waypoint">waypoint</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#representations-of-simple-things">Representations of simple things</a><ul>
|
||
<li><a href="#positionvector">Position/vector</a></li>
|
||
<li><a href="#pointed_thing">pointed_thing</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#flag-specifier-format">Flag Specifier Format</a></li>
|
||
<li><a href="#items">Items</a><ul>
|
||
<li><a href="#item-types">Item types</a></li>
|
||
<li><a href="#amount-and-wear">Amount and wear</a></li>
|
||
<li><a href="#item-formats">Item formats</a><ul>
|
||
<li><a href="#serialized">Serialized</a></li>
|
||
<li><a href="#table-format">Table format</a></li>
|
||
<li><a href="#itemstack">ItemStack</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#groups">Groups</a><ul>
|
||
<li><a href="#usage">Usage</a></li>
|
||
<li><a href="#groups-of-items">Groups of items</a></li>
|
||
<li><a href="#groups-of-nodes">Groups of nodes</a></li>
|
||
<li><a href="#groups-of-entities">Groups of entities</a></li>
|
||
<li><a href="#groups-of-tools">Groups of tools</a></li>
|
||
<li><a href="#groups-in-crafting-recipes">Groups in crafting recipes</a></li>
|
||
<li><a href="#special-groups">Special groups</a></li>
|
||
<li><a href="#known-damage-and-digging-time-defining-groups">Known damage and digging time defining groups</a></li>
|
||
<li><a href="#examples-of-custom-groups">Examples of custom groups</a></li>
|
||
<li><a href="#digging-time-calculation-specifics">Digging time calculation specifics</a><ul>
|
||
<li><a href="#tools-definition">Tools definition</a></li>
|
||
<li><a href="#full-punch-interval">Full punch interval</a></li>
|
||
<li><a href="#maximum-drop-level">Maximum drop level</a></li>
|
||
<li><a href="#uses">Uses</a></li>
|
||
<li><a href="#maximum-level">Maximum level</a></li>
|
||
<li><a href="#digging-times">Digging times</a></li>
|
||
<li><a href="#damage-groups">Damage groups</a></li>
|
||
<li><a href="#example-definition-of-the-capabilities-of-a-tool">Example definition of the capabilities of a tool</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#entity-damage-mechanism">Entity damage mechanism</a></li>
|
||
<li><a href="#node-metadata">Node Metadata</a></li>
|
||
<li><a href="#item-metadata">Item Metadata</a></li>
|
||
<li><a href="#formspec">Formspec</a><ul>
|
||
<li><a href="#examples">Examples</a><ul>
|
||
<li><a href="#chest">Chest</a></li>
|
||
<li><a href="#furnace">Furnace</a></li>
|
||
<li><a href="#minecraft-like-player-inventory">Minecraft-like player inventory</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#elements">Elements</a><ul>
|
||
<li><a href="#sizewhfixed_size">size[<W>,<H>,<fixed_size>]</a></li>
|
||
<li><a href="#positionxy">position[<X>,<Y>]</a></li>
|
||
<li><a href="#anchorxy">anchor[<X>,<Y>]</a></li>
|
||
<li><a href="#containerxy">container[<X>,<Y>]</a></li>
|
||
<li><a href="#container_end">container_end[]</a></li>
|
||
<li><a href="#listinventory-locationlist-namexywh">list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]</a></li>
|
||
<li><a href="#listinventory-locationlist-namexywhstarting-item-index">list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]</a></li>
|
||
<li><a href="#listringinventory-locationlist-name">listring[<inventory location>;<list name>]</a></li>
|
||
<li><a href="#listring">listring[]</a></li>
|
||
<li><a href="#listcolorsslot_bg_normalslot_bg_hover">listcolors[<slot_bg_normal>;<slot_bg_hover>]</a></li>
|
||
<li><a href="#listcolorsslot_bg_normalslot_bg_hoverslot_border">listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]</a></li>
|
||
<li><a href="#listcolorsslot_bg_normalslot_bg_hoverslot_bordertooltip_bgcolortooltip_fontcolor">listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]</a></li>
|
||
<li><a href="#tooltipgui_element_nametooltip_textbgcolorfontcolor">tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>;<fontcolor>]</a></li>
|
||
<li><a href="#imagexywhtexture-name">image[<X>,<Y>;<W>,<H>;<texture name>]</a></li>
|
||
<li><a href="#item_imagexywhitem-name">item_image[<X>,<Y>;<W>,<H>;<item name>]</a></li>
|
||
<li><a href="#bgcolorcolorfullscreen">bgcolor[<color>;<fullscreen>]</a></li>
|
||
<li><a href="#backgroundxywhtexture-name">background[<X>,<Y>;<W>,<H>;<texture name>]</a></li>
|
||
<li><a href="#backgroundxywhtexture-nameauto_clip">background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]</a></li>
|
||
<li><a href="#pwdfieldxywhnamelabel">pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]</a></li>
|
||
<li><a href="#fieldxywhnamelabeldefault">field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]</a></li>
|
||
<li><a href="#fieldnamelabeldefault">field[<name>;<label>;<default>]</a></li>
|
||
<li><a href="#field_close_on_enternameclose_on_enter">field_close_on_enter[<name>;<close_on_enter>]</a></li>
|
||
<li><a href="#textareaxywhnamelabeldefault">textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]</a></li>
|
||
<li><a href="#labelxylabel">label[<X>,<Y>;<label>]</a></li>
|
||
<li><a href="#vertlabelxylabel">vertlabel[<X>,<Y>;<label>]</a></li>
|
||
<li><a href="#buttonxywhnamelabel">button[<X>,<Y>;<W>,<H>;<name>;<label>]</a></li>
|
||
<li><a href="#image_buttonxywhtexture-namenamelabel">image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]</a></li>
|
||
<li><a href="#image_buttonxywhtexture-namenamelabelnoclipdrawborderpressed-texture-name">image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]</a></li>
|
||
<li><a href="#item_image_buttonxywhitem-namenamelabel">item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]</a></li>
|
||
<li><a href="#button_exitxywhnamelabel">button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]</a></li>
|
||
<li><a href="#image_button_exitxywhtexture-namenamelabel">image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]</a></li>
|
||
<li><a href="#textlistxywhnamelistelem-1listelem-2listelem-n">textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]</a></li>
|
||
<li><a href="#textlistxywhnamelistelem-1listelem-2listelem-nselected-idxtransparent">textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]</a></li>
|
||
<li><a href="#tabheaderxynamecaption-1caption-2caption-ncurrent_tabtransparentdraw_border">tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]</a></li>
|
||
<li><a href="#boxxywhcolor">box[<X>,<Y>;<W>,<H>;<color>]</a></li>
|
||
<li><a href="#dropdownxywnameitem-1item-2-item-nselected-idx">dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]</a></li>
|
||
<li><a href="#checkboxxynamelabelselected">checkbox[<X>,<Y>;<name>;<label>;<selected>]</a></li>
|
||
<li><a href="#scrollbarxywhorientationnamevalue">scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]</a></li>
|
||
<li><a href="#tablexywhnamecell-1cell-2cell-nselected-idx">table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]</a></li>
|
||
<li><a href="#tableoptionsopt-1opt-2">tableoptions[<opt 1>;<opt 2>;...]</a></li>
|
||
<li><a href="#tablecolumnstype-1opt-1aopt-1btype-2opt-2aopt-2b">tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#inventory-locations">Inventory locations</a></li>
|
||
<li><a href="#player-inventory-lists">Player Inventory lists</a></li>
|
||
<li><a href="#colorstring">ColorString</a></li>
|
||
<li><a href="#colorspec">ColorSpec</a></li>
|
||
<li><a href="#escape-sequences">Escape sequences</a></li>
|
||
<li><a href="#spatial-vectors">Spatial Vectors</a></li>
|
||
<li><a href="#helper-functions">Helper functions</a></li>
|
||
<li><a href="#minetest-namespace-reference">minetest namespace reference</a><ul>
|
||
<li><a href="#utilities">Utilities</a></li>
|
||
<li><a href="#logging">Logging</a></li>
|
||
<li><a href="#registration-functions">Registration functions</a></li>
|
||
<li><a href="#global-callback-registration-functions">Global callback registration functions</a></li>
|
||
<li><a href="#other-registration-functions">Other registration functions</a></li>
|
||
<li><a href="#setting-related">Setting-related</a></li>
|
||
<li><a href="#authentication">Authentication</a></li>
|
||
<li><a href="#chat">Chat</a></li>
|
||
<li><a href="#environment-access">Environment access</a></li>
|
||
<li><a href="#inventory_1">Inventory</a></li>
|
||
<li><a href="#formspec_1">Formspec</a></li>
|
||
<li><a href="#item-handling">Item handling</a></li>
|
||
<li><a href="#rollback">Rollback</a></li>
|
||
<li><a href="#defaults-for-the-on_-item-definition-functions">Defaults for the on_* item definition functions</a></li>
|
||
<li><a href="#defaults-for-the-on_punch-and-on_dig-node-definition-callbacks">Defaults for the on_punch and on_dig node definition callbacks</a></li>
|
||
<li><a href="#sounds_1">Sounds</a></li>
|
||
<li><a href="#timing">Timing</a></li>
|
||
<li><a href="#server">Server</a></li>
|
||
<li><a href="#bans">Bans</a></li>
|
||
<li><a href="#particles">Particles</a></li>
|
||
<li><a href="#schematics">Schematics</a></li>
|
||
<li><a href="#http-requests">HTTP Requests:</a></li>
|
||
<li><a href="#storage-api">Storage API:</a></li>
|
||
<li><a href="#misc">Misc.</a></li>
|
||
<li><a href="#global-objects">Global objects</a></li>
|
||
<li><a href="#global-tables">Global tables</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#class-reference">Class reference</a><ul>
|
||
<li><a href="#metadataref">MetaDataRef</a><ul>
|
||
<li><a href="#methods">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#nodemetaref">NodeMetaRef</a><ul>
|
||
<li><a href="#methods_1">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#itemstackmetaref">ItemStackMetaRef</a><ul>
|
||
<li><a href="#methods_2">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#storageref">StorageRef</a><ul>
|
||
<li><a href="#methods_3">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#nodetimerref">NodeTimerRef</a><ul>
|
||
<li><a href="#methods_4">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#objectref">ObjectRef</a><ul>
|
||
<li><a href="#methods_5">Methods</a><ul>
|
||
<li><a href="#luaentitysao-only-no-op-for-other-objects">LuaEntitySAO-only (no-op for other objects)</a></li>
|
||
<li><a href="#player-only-no-op-for-other-objects">Player-only (no-op for other objects)</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#invref">InvRef</a><ul>
|
||
<li><a href="#methods_6">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#areastore">AreaStore</a><ul>
|
||
<li><a href="#methods_7">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#itemstack_1">ItemStack</a><ul>
|
||
<li><a href="#methods_8">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#pseudorandom">PseudoRandom</a><ul>
|
||
<li><a href="#methods_9">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#pcgrandom">PcgRandom</a><ul>
|
||
<li><a href="#methods_10">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#securerandom">SecureRandom</a><ul>
|
||
<li><a href="#methods_11">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#perlinnoise">PerlinNoise</a><ul>
|
||
<li><a href="#methods_12">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#perlinnoisemap">PerlinNoiseMap</a><ul>
|
||
<li><a href="#methods_13">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#voxelmanip">VoxelManip</a><ul>
|
||
<li><a href="#about-voxelmanip">About VoxelManip</a></li>
|
||
<li><a href="#using-voxelmanip">Using VoxelManip</a><ul>
|
||
<li><a href="#flat-array-format">Flat array format</a></li>
|
||
<li><a href="#content-ids">Content IDs</a></li>
|
||
<li><a href="#mapgen-voxelmanip-objects">Mapgen VoxelManip objects</a></li>
|
||
<li><a href="#other-api-functions-operating-on-a-voxelmanip">Other API functions operating on a VoxelManip</a></li>
|
||
<li><a href="#notes">Notes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#methods_14">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#voxelarea">VoxelArea</a><ul>
|
||
<li><a href="#methods_15">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#settings">Settings</a><ul>
|
||
<li><a href="#methods_16">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#raycast">Raycast</a><ul>
|
||
<li><a href="#methods_17">Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#mapgen-objects">Mapgen objects</a><ul>
|
||
<li><a href="#voxelmanip_1">voxelmanip</a></li>
|
||
<li><a href="#heightmap">heightmap</a></li>
|
||
<li><a href="#biomemap">biomemap</a></li>
|
||
<li><a href="#heatmap">heatmap</a></li>
|
||
<li><a href="#humiditymap">humiditymap</a></li>
|
||
<li><a href="#gennotify">gennotify</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#registered-entities">Registered entities</a></li>
|
||
<li><a href="#l-system-trees">L-system trees</a><ul>
|
||
<li><a href="#tree-definition">Tree definition</a></li>
|
||
<li><a href="#key-for-special-l-system-symbols-used-in-axioms">Key for Special L-System Symbols used in Axioms</a></li>
|
||
<li><a href="#example_1">Example</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#definition-tables">Definition tables</a><ul>
|
||
<li><a href="#object-properties">Object Properties</a></li>
|
||
<li><a href="#entity-definition-register_entity">Entity definition (register_entity)</a></li>
|
||
<li><a href="#abm-activeblockmodifier-definition-register_abm">ABM (ActiveBlockModifier) definition (register_abm)</a></li>
|
||
<li><a href="#lbm-loadingblockmodifier-definition-register_lbm">LBM (LoadingBlockModifier) definition (register_lbm)</a></li>
|
||
<li><a href="#item-definition-register_node-register_craftitem-register_tool">Item definition (register_node, register_craftitem, register_tool)</a></li>
|
||
<li><a href="#tile-definition">Tile definition</a></li>
|
||
<li><a href="#tile-animation-definition">Tile animation definition</a></li>
|
||
<li><a href="#node-definition-register_node">Node definition (register_node)</a></li>
|
||
<li><a href="#recipe-for-register_craft-shaped">Recipe for register_craft (shaped)</a></li>
|
||
<li><a href="#recipe-for-register_craft-shapeless">Recipe for register_craft (shapeless)</a></li>
|
||
<li><a href="#recipe-for-register_craft-tool-repair">Recipe for register_craft (tool repair)</a></li>
|
||
<li><a href="#recipe-for-register_craft-cooking">Recipe for register_craft (cooking)</a></li>
|
||
<li><a href="#recipe-for-register_craft-furnace-fuel">Recipe for register_craft (furnace fuel)</a></li>
|
||
<li><a href="#ore-definition-register_ore">Ore definition (register_ore)</a></li>
|
||
<li><a href="#biome-definition-register_biome">Biome definition (register_biome)</a></li>
|
||
<li><a href="#decoration-definition-register_decoration">Decoration definition (register_decoration)</a></li>
|
||
<li><a href="#chat-command-definition-register_chatcommand">Chat command definition (register_chatcommand)</a></li>
|
||
<li><a href="#detached-inventory-callbacks">Detached inventory callbacks</a></li>
|
||
<li><a href="#hud-definition-hud_add-hud_get">HUD Definition (hud_add, hud_get)</a></li>
|
||
<li><a href="#particle-definition-add_particle">Particle definition (add_particle)</a></li>
|
||
<li><a href="#particlespawner-definition-add_particlespawner">ParticleSpawner definition (add_particlespawner)</a></li>
|
||
<li><a href="#httprequest-definition-httpapitablefetch_async-httpapitablefetch_async">HTTPRequest definition (HTTPApiTable.fetch_async, HTTPApiTable.fetch_async)</a></li>
|
||
<li><a href="#httprequestresult-definition-httpapitablefetch-callback-httpapitablefetch_async_get">HTTPRequestResult definition (HTTPApiTable.fetch callback, HTTPApiTable.fetch_async_get)</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<h1 id="minetest-lua-modding-api-reference-0416">Minetest Lua Modding API Reference 0.4.16</h1>
|
||
<h2 id="introduction">Introduction</h2>
|
||
<p>Content and functionality can be added to Minetest 0.4 by using Lua
|
||
scripting in run-time loaded mods.</p>
|
||
<p>A mod is a self-contained bunch of scripts, textures and other related
|
||
things that is loaded by and interfaces with Minetest.</p>
|
||
<p>Mods are contained and ran solely on the server side. Definitions and media
|
||
files are automatically transferred to the client.</p>
|
||
<p>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 to <a href="mailto:celeron55@gmail.com">celeron55@gmail.com</a>.</p>
|
||
<ul>
|
||
<li>More information at <a href="http://www.minetest.net/">http://www.minetest.net/</a></li>
|
||
<li>Developer Wiki: <a href="http://dev.minetest.net/">http://dev.minetest.net/</a></li>
|
||
</ul>This page was last updated 08/August/2017.<br/>See <a href="https://github.com/minetest/minetest/blob/master/doc/lua_api.txt">doc/lua_api.txt</a> for the latest version (in plaintext).<br/>Generated using <a href="https://github.com/rubenwardy/minetest_modding_book/blob/gh-pages/update_lua_api.py">a Python script</a>.<h2 id="programming-in-lua">Programming in Lua</h2>
|
||
<p>If you have any difficulty in understanding this, please read
|
||
<a href="http://www.lua.org/pil/">Programming in Lua</a>.</p>
|
||
<h2 id="startup">Startup</h2>
|
||
<p>Mods are loaded during server startup from the mod load paths by running
|
||
the <code>init.lua</code> scripts in a shared environment.</p>
|
||
<h2 id="paths">Paths</h2>
|
||
<ul>
|
||
<li><a class="anchor" href="#RUN_IN_PLACE1" name="RUN_IN_PLACE1">#</a><code>RUN_IN_PLACE=1</code> (Windows release, local build)<ul>
|
||
<li><a class="anchor" href="#path_user" name="path_user">#</a><code>$path_user</code>:<ul>
|
||
<li><a class="anchor" href="#builddirectory" name="builddirectory">#</a>Linux: <code><build directory></code></li>
|
||
<li><a class="anchor" href="#builddirectory_1" name="builddirectory_1">#</a>Windows: <code><build directory></code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#path_share" name="path_share">#</a><code>$path_share</code><ul>
|
||
<li><a class="anchor" href="#builddirectory_2" name="builddirectory_2">#</a>Linux: <code><build directory></code></li>
|
||
<li><a class="anchor" href="#builddirectory_3" name="builddirectory_3">#</a>Windows: <code><build directory></code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#RUN_IN_PLACE0" name="RUN_IN_PLACE0">#</a><code>RUN_IN_PLACE=0</code>: (Linux release)<ul>
|
||
<li><a class="anchor" href="#path_share_1" name="path_share_1">#</a><code>$path_share</code><ul>
|
||
<li><a class="anchor" href="#usrshareminetest" name="usrshareminetest">#</a>Linux: <code>/usr/share/minetest</code></li>
|
||
<li><a class="anchor" href="#installdirectoryminetest04x" name="installdirectoryminetest04x">#</a>Windows: <code><install directory>/minetest-0.4.x</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#path_user_1" name="path_user_1">#</a><code>$path_user</code>:<ul>
|
||
<li><a class="anchor" href="#HOMEminetest" name="HOMEminetest">#</a>Linux: <code>$HOME/.minetest</code></li>
|
||
<li><a class="anchor" href="#CusersuserAppDataminetest" name="CusersuserAppDataminetest">#</a>Windows: <code>C:/users/<user>/AppData/minetest</code> (maybe)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h2 id="games">Games</h2>
|
||
<p>Games are looked up from:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#path_sharegamesgameid" name="path_sharegamesgameid">#</a><code>$path_share/games/gameid/</code></li>
|
||
<li><a class="anchor" href="#path_usergamesgameid" name="path_usergamesgameid">#</a><code>$path_user/games/gameid/</code></li>
|
||
</ul>
|
||
<p>where <code>gameid</code> is unique to each game.</p>
|
||
<p>The game directory contains the file <code>game.conf</code>, which contains these fields:</p>
|
||
<pre><code>name = <Human-readable full name of the game>
|
||
</code></pre>
|
||
<p>e.g.</p>
|
||
<pre><code>name = Minetest
|
||
</code></pre>
|
||
<p>The game directory can contain the file minetest.conf, which will be used
|
||
to set default settings when running the particular game.
|
||
It can also contain a settingtypes.txt in the same format as the one in builtin.
|
||
This settingtypes.txt will be parsed by the menu and the settings will be displayed
|
||
in the "Games" category in the settings tab.</p>
|
||
<h3 id="menu-images">Menu images</h3>
|
||
<p>Games can provide custom main menu images. They are put inside a <code>menu</code> directory
|
||
inside the game directory.</p>
|
||
<p>The images are named <code>$identifier.png</code>, where <code>$identifier</code> is
|
||
one of <code>overlay,background,footer,header</code>.
|
||
If you want to specify multiple images for one identifier, add additional images named
|
||
like <code>$identifier.$n.png</code>, with an ascending number $n starting with 1, and a random
|
||
image will be chosen from the provided ones.</p>
|
||
<h2 id="mod-load-path">Mod load path</h2>
|
||
<p>Generic:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#path_sharegamesgameidmods" name="path_sharegamesgameidmods">#</a><code>$path_share/games/gameid/mods/</code></li>
|
||
<li><a class="anchor" href="#path_sharemods" name="path_sharemods">#</a><code>$path_share/mods/</code></li>
|
||
<li><a class="anchor" href="#path_usergamesgameidmods" name="path_usergamesgameidmods">#</a><code>$path_user/games/gameid/mods/</code></li>
|
||
<li><a class="anchor" href="#path_usermods" name="path_usermods">#</a><code>$path_user/mods/</code> (User-installed mods)</li>
|
||
<li><a class="anchor" href="#worldpathworldmods" name="worldpathworldmods">#</a><code>$worldpath/worldmods/</code></li>
|
||
</ul>
|
||
<p>In a run-in-place version (e.g. the distributed windows version):</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetest04xgamesgameidmods" name="minetest04xgamesgameidmods">#</a><code>minetest-0.4.x/games/gameid/mods/</code></li>
|
||
<li><a class="anchor" href="#minetest04xmods" name="minetest04xmods">#</a><code>minetest-0.4.x/mods/</code> (User-installed mods)</li>
|
||
<li><a class="anchor" href="#minetest04xworldsworldnameworldmods" name="minetest04xworldsworldnameworldmods">#</a><code>minetest-0.4.x/worlds/worldname/worldmods/</code></li>
|
||
</ul>
|
||
<p>On an installed version on Linux:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#usrshareminetestgamesgameidmods" name="usrshareminetestgamesgameidmods">#</a><code>/usr/share/minetest/games/gameid/mods/</code></li>
|
||
<li><a class="anchor" href="#HOMEminetestmods" name="HOMEminetestmods">#</a><code>$HOME/.minetest/mods/</code> (User-installed mods)</li>
|
||
<li><a class="anchor" href="#HOMEminetestworldsworldnameworldmods" name="HOMEminetestworldsworldnameworldmods">#</a><code>$HOME/.minetest/worlds/worldname/worldmods</code></li>
|
||
</ul>
|
||
<h2 id="mod-load-path-for-world-specific-games">Mod load path for world-specific games</h2>
|
||
<p>It is possible to include a game in a world; in this case, no mods or
|
||
games are loaded or checked from anywhere else.</p>
|
||
<p>This is useful for e.g. adventure worlds.</p>
|
||
<p>This happens if the following directory exists:</p>
|
||
<pre><code>$world/game/
|
||
</code></pre>
|
||
<p>Mods should be then be placed in:</p>
|
||
<pre><code>$world/game/mods/
|
||
</code></pre>
|
||
<h2 id="modpack-support">Modpack support</h2>
|
||
<p>Mods can be put in a subdirectory, if the parent directory, which otherwise
|
||
should be a mod, contains a file named <code>modpack.txt</code>. This file shall be
|
||
empty, except for lines starting with <code>#</code>, which are comments.</p>
|
||
<h2 id="mod-directory-structure">Mod directory structure</h2>
|
||
<pre><code>mods
|
||
|-- modname
|
||
| |-- depends.txt
|
||
| |-- screenshot.png
|
||
| |-- description.txt
|
||
| |-- settingtypes.txt
|
||
| |-- init.lua
|
||
| |-- models
|
||
| |-- textures
|
||
| | |-- modname_stuff.png
|
||
| | `-- modname_something_else.png
|
||
| |-- sounds
|
||
| |-- media
|
||
| `-- <custom data>
|
||
`-- another
|
||
</code></pre>
|
||
<h3 id="modname">modname</h3>
|
||
<p>The location of this directory can be fetched by using
|
||
<code>minetest.get_modpath(modname)</code>.</p>
|
||
<h3 id="dependstxt"><code>depends.txt</code></h3>
|
||
<p>List of mods that have to be loaded before loading this mod.</p>
|
||
<p>A single line contains a single modname.</p>
|
||
<p>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.</p>
|
||
<h3 id="screenshotpng"><code>screenshot.png</code></h3>
|
||
<p>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.</p>
|
||
<h3 id="descriptiontxt"><code>description.txt</code></h3>
|
||
<p>A File containing description to be shown within mainmenu.</p>
|
||
<h3 id="settingtypestxt"><code>settingtypes.txt</code></h3>
|
||
<p>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.</p>
|
||
<h3 id="initlua"><code>init.lua</code></h3>
|
||
<p>The main Lua script. Running this script should register everything it
|
||
wants to register. Subsequent execution depends on minetest calling the
|
||
registered callbacks.</p>
|
||
<p><code>minetest.settings</code> can be used to read custom or existing settings at load
|
||
time, if necessary. (See <code>Settings</code>)</p>
|
||
<h3 id="models"><code>models</code></h3>
|
||
<p>Models for entities or meshnodes.</p>
|
||
<h3 id="textures-sounds-media"><code>textures</code>, <code>sounds</code>, <code>media</code></h3>
|
||
<p>Media files (textures, sounds, whatever) that will be transferred to the
|
||
client and will be available for use by the mod.</p>
|
||
<h2 id="naming-convention-for-registered-textual-names">Naming convention for registered textual names</h2>
|
||
<p>Registered names should generally be in this format:</p>
|
||
<pre><code>`modname:<whatever>`
|
||
</code></pre>
|
||
<p><code><whatever></code> can have these characters:</p>
|
||
<pre><code>a-zA-Z0-9_
|
||
</code></pre>
|
||
<p>This is to prevent conflicting names from corrupting maps and is
|
||
enforced by the mod loader.</p>
|
||
<h3 id="example">Example</h3>
|
||
<p>In the mod <code>experimental</code>, there is the ideal item/node/entity name <code>tnt</code>.
|
||
So the name should be <code>experimental:tnt</code>.</p>
|
||
<p>Enforcement can be overridden by prefixing the name with <code>:</code>. This can
|
||
be used for overriding the registrations of some other mod.</p>
|
||
<p>Example: Any mod can redefine <code>experimental:tnt</code> by using the name</p>
|
||
<pre><code>:experimental:tnt
|
||
</code></pre>
|
||
<p>when registering it.
|
||
(also that mod is required to have <code>experimental</code> as a dependency)</p>
|
||
<p>The <code>:</code> prefix can also be used for maintaining backwards compatibility.</p>
|
||
<h3 id="aliases">Aliases</h3>
|
||
<p>Aliases can be added by using <code>minetest.register_alias(name, convert_to)</code> or
|
||
<code>minetest.register_alias_force(name, convert_to)</code>.</p>
|
||
<p>This will make Minetest to convert things called name to things called
|
||
<code>convert_to</code>.</p>
|
||
<p>The only difference between <code>minetest.register_alias</code> and
|
||
<code>minetest.register_alias_force</code> is that if an item called <code>name</code> exists,
|
||
<code>minetest.register_alias</code> will do nothing while
|
||
<code>minetest.register_alias_force</code> will unregister it.</p>
|
||
<p>This can be used for maintaining backwards compatibility.</p>
|
||
<p>This can be also used for setting quick access names for things, e.g. if
|
||
you have an item called <code>epiclylongmodname:stuff</code>, you could do</p>
|
||
<pre><code>minetest.register_alias("stuff", "epiclylongmodname:stuff")
|
||
</code></pre>
|
||
<p>and be able to use <code>/giveme stuff</code>.</p>
|
||
<h2 id="textures">Textures</h2>
|
||
<p>Mods should generally prefix their textures with <code>modname_</code>, e.g. given
|
||
the mod name <code>foomod</code>, a texture could be called:</p>
|
||
<pre><code>foomod_foothing.png
|
||
</code></pre>
|
||
<p>Textures are referred to by their complete name, or alternatively by
|
||
stripping out the file extension:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#foomod_foothingpng" name="foomod_foothingpng">#</a>e.g. <code>foomod_foothing.png</code></li>
|
||
<li><a class="anchor" href="#foomod_foothing" name="foomod_foothing">#</a>e.g. <code>foomod_foothing</code></li>
|
||
</ul>
|
||
<h2 id="texture-modifiers">Texture modifiers</h2>
|
||
<p>There are various texture modifiers that can be used
|
||
to generate textures on-the-fly.</p>
|
||
<h3 id="texture-overlaying">Texture overlaying</h3>
|
||
<p>Textures can be overlaid by putting a <code>^</code> between them.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_dirt.png^default_grass_side.png
|
||
</code></pre>
|
||
<p><code>default_grass_side.png</code> is overlayed over <code>default_dirt.png</code>.
|
||
The texture with the lower resolution will be automatically upscaled to
|
||
the higher resolution texture.</p>
|
||
<h3 id="texture-grouping">Texture grouping</h3>
|
||
<p>Textures can be grouped together by enclosing them in <code>(</code> and <code>)</code>.</p>
|
||
<p>Example: <code>cobble.png^(thing1.png^thing2.png)</code></p>
|
||
<p>A texture for <code>thing1.png^thing2.png</code> is created and the resulting
|
||
texture is overlaid on top of <code>cobble.png</code>.</p>
|
||
<h3 id="escaping">Escaping</h3>
|
||
<p>Modifiers that accept texture names (e.g. <code>[combine</code>) accept escaping to allow
|
||
passing complex texture names as arguments. Escaping is done with backslash and
|
||
is required for <code>^</code> and <code>:</code>.</p>
|
||
<p>Example: <code>cobble.png^[lowpart:50:color.png\^[mask\:trans.png</code></p>
|
||
<p>The lower 50 percent of <code>color.png^[mask:trans.png</code> are overlaid
|
||
on top of <code>cobble.png</code>.</p>
|
||
<h3 id="advanced-texture-modifiers">Advanced texture modifiers</h3>
|
||
<h4 id="cracknp"><code>[crack:<n>:<p></code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#n" name="n">#</a><code><n></code> = animation frame count</li>
|
||
<li><a class="anchor" href="#p" name="p">#</a><code><p></code> = current animation frame</li>
|
||
</ul>
|
||
<p>Draw a step of the crack animation on the texture.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_cobble.png^[crack:10:1
|
||
</code></pre>
|
||
<h4 id="combinewxhx1y1file1x2y2file2"><code>[combine:<w>x<h>:<x1>,<y1>=<file1>:<x2>,<y2>=<file2>:...</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#w" name="w">#</a><code><w></code> = width</li>
|
||
<li><a class="anchor" href="#h" name="h">#</a><code><h></code> = height</li>
|
||
<li><a class="anchor" href="#x" name="x">#</a><code><x></code> = x position</li>
|
||
<li><a class="anchor" href="#y" name="y">#</a><code><y></code> = y position</li>
|
||
<li><a class="anchor" href="#file" name="file">#</a><code><file></code> = texture to combine</li>
|
||
</ul>
|
||
<p>Creates a texture of size <code><w></code> times <code><h></code> and blits the listed files to their
|
||
specified coordinates.</p>
|
||
<p>Example:</p>
|
||
<pre><code>[combine:16x32:0,0=default_cobble.png:0,16=default_wood.png
|
||
</code></pre>
|
||
<h4 id="resizewxh"><code>[resize:<w>x<h></code></h4>
|
||
<p>Resizes the texture to the given dimensions.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_sandstone.png^[resize:16x16
|
||
</code></pre>
|
||
<h4 id="opacityr"><code>[opacity:<r></code></h4>
|
||
<p>Makes the base image transparent according to the given ratio.</p>
|
||
<p><code>r</code> must be between 0 and 255.
|
||
0 means totally transparent. 255 means totally opaque.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_sandstone.png^[opacity:127
|
||
</code></pre>
|
||
<h4 id="invertmode"><code>[invert:<mode></code></h4>
|
||
<p>Inverts the given channels of the base image.
|
||
Mode may contain the characters "r", "g", "b", "a".
|
||
Only the channels that are mentioned in the mode string will be inverted.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_apple.png^[invert:rgb
|
||
</code></pre>
|
||
<h4 id="brighten"><code>[brighten</code></h4>
|
||
<p>Brightens the texture.</p>
|
||
<p>Example:</p>
|
||
<pre><code>tnt_tnt_side.png^[brighten
|
||
</code></pre>
|
||
<h4 id="noalpha"><code>[noalpha</code></h4>
|
||
<p>Makes the texture completely opaque.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_leaves.png^[noalpha
|
||
</code></pre>
|
||
<h4 id="makealphargb"><code>[makealpha:<r>,<g>,<b></code></h4>
|
||
<p>Convert one color to transparency.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_cobble.png^[makealpha:128,128,128
|
||
</code></pre>
|
||
<h4 id="transformt"><code>[transform<t></code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#t" name="t">#</a><code><t></code> = transformation(s) to apply</li>
|
||
</ul>
|
||
<p>Rotates and/or flips the image.</p>
|
||
<p><code><t></code> can be a number (between 0 and 7) or a transform name.
|
||
Rotations are counter-clockwise.</p>
|
||
<pre><code>0 I identity
|
||
1 R90 rotate by 90 degrees
|
||
2 R180 rotate by 180 degrees
|
||
3 R270 rotate by 270 degrees
|
||
4 FX flip X
|
||
5 FXR90 flip X then rotate by 90 degrees
|
||
6 FY flip Y
|
||
7 FYR90 flip Y then rotate by 90 degrees
|
||
</code></pre>
|
||
<p>Example:</p>
|
||
<pre><code>default_stone.png^[transformFXR90
|
||
</code></pre>
|
||
<h4 id="inventorycubetopleftright"><code>[inventorycube{<top>{<left>{<right></code></h4>
|
||
<p>Escaping does not apply here and <code>^</code> is replaced by <code>&</code> in texture names instead.</p>
|
||
<p>Create an inventory cube texture using the side textures.</p>
|
||
<p>Example:</p>
|
||
<pre><code>[inventorycube{grass.png{dirt.png&grass_side.png{dirt.png&grass_side.png
|
||
</code></pre>
|
||
<p>Creates an inventorycube with <code>grass.png</code>, <code>dirt.png^grass_side.png</code> and
|
||
<code>dirt.png^grass_side.png</code> textures</p>
|
||
<h4 id="lowpartpercentfile"><code>[lowpart:<percent>:<file></code></h4>
|
||
<p>Blit the lower <code><percent></code>% part of <code><file></code> on the texture.</p>
|
||
<p>Example:</p>
|
||
<pre><code>base.png^[lowpart:25:overlay.png
|
||
</code></pre>
|
||
<h4 id="verticalframetn"><code>[verticalframe:<t>:<n></code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#t_1" name="t_1">#</a><code><t></code> = animation frame count</li>
|
||
<li><a class="anchor" href="#n_1" name="n_1">#</a><code><n></code> = current animation frame</li>
|
||
</ul>
|
||
<p>Crops the texture to a frame of a vertical animation.</p>
|
||
<p>Example:</p>
|
||
<pre><code>default_torch_animated.png^[verticalframe:16:8
|
||
</code></pre>
|
||
<h4 id="maskfile"><code>[mask:<file></code></h4>
|
||
<p>Apply a mask to the base image.</p>
|
||
<p>The mask is applied using binary AND.</p>
|
||
<h4 id="sheetwxhxy"><code>[sheet:<w>x<h>:<x>,<y></code></h4>
|
||
<p>Retrieves a tile at position x,y from the base image
|
||
which it assumes to be a tilesheet with dimensions w,h.</p>
|
||
<h4 id="colorizecolorratio"><code>[colorize:<color>:<ratio></code></h4>
|
||
<p>Colorize the textures with the given color.
|
||
<code><color></code> is specified as a <code>ColorString</code>.
|
||
<code><ratio></code> is an int ranging from 0 to 255 or the word "<code>alpha</code>". If
|
||
it is an int, then it specifies how far to interpolate between the
|
||
colors where 0 is only the texture color and 255 is only <code><color></code>. If
|
||
omitted, the alpha of <code><color></code> will be used as the ratio. If it is
|
||
the word "<code>alpha</code>", then each texture pixel will contain the RGB of
|
||
<code><color></code> and the alpha of <code><color></code> multiplied by the alpha of the
|
||
texture pixel.</p>
|
||
<h4 id="multiplycolor"><code>[multiply:<color></code></h4>
|
||
<p>Multiplies texture colors with the given color.
|
||
<code><color></code> is specified as a <code>ColorString</code>.
|
||
Result is more like what you'd expect if you put a color on top of another
|
||
color. Meaning white surfaces get a lot of your new color while black parts don't
|
||
change very much.</p>
|
||
<h2 id="hardware-coloring">Hardware coloring</h2>
|
||
<p>The goal of hardware coloring is to simplify the creation of
|
||
colorful nodes. If your textures use the same pattern, and they only
|
||
differ in their color (like colored wool blocks), you can use hardware
|
||
coloring instead of creating and managing many texture files.
|
||
All of these methods use color multiplication (so a white-black texture
|
||
with red coloring will result in red-black color).</p>
|
||
<h3 id="static-coloring">Static coloring</h3>
|
||
<p>This method is useful if you wish to create nodes/items with
|
||
the same texture, in different colors, each in a new node/item definition.</p>
|
||
<h4 id="global-color">Global color</h4>
|
||
<p>When you register an item or node, set its <code>color</code> field (which accepts a
|
||
<code>ColorSpec</code>) to the desired color.</p>
|
||
<p>An <code>ItemStack</code>s static color can be overwritten by the <code>color</code> metadata
|
||
field. If you set that field to a <code>ColorString</code>, that color will be used.</p>
|
||
<h4 id="tile-color">Tile color</h4>
|
||
<p>Each tile may have an individual static color, which overwrites every
|
||
other coloring methods. To disable the coloring of a face,
|
||
set its color to white (because multiplying with white does nothing).
|
||
You can set the <code>color</code> property of the tiles in the node's definition
|
||
if the tile is in table format.</p>
|
||
<h3 id="palettes">Palettes</h3>
|
||
<p>For nodes and items which can have many colors, a palette is more
|
||
suitable. A palette is a texture, which can contain up to 256 pixels.
|
||
Each pixel is one possible color for the node/item.
|
||
You can register one node/item, which can have up to 256 colors.</p>
|
||
<h4 id="palette-indexing">Palette indexing</h4>
|
||
<p>When using palettes, you always provide a pixel index for the given
|
||
node or <code>ItemStack</code>. The palette is read from left to right and from
|
||
top to bottom. If the palette has less than 256 pixels, then it is
|
||
stretched to contain exactly 256 pixels (after arranging the pixels
|
||
to one line). The indexing starts from 0.</p>
|
||
<p>Examples:
|
||
<em> 16x16 palette, index = 0: the top left corner
|
||
</em> 16x16 palette, index = 4: the fifth pixel in the first row
|
||
<em> 16x16 palette, index = 16: the pixel below the top left corner
|
||
</em> 16x16 palette, index = 255: the bottom right corner
|
||
<em> 2 (width)x4 (height) palette, index=31: the top left corner.
|
||
The palette has 8 pixels, so each pixel is stretched to 32 pixels,
|
||
to ensure the total 256 pixels.
|
||
</em> 2x4 palette, index=32: the top right corner
|
||
<em> 2x4 palette, index=63: the top right corner
|
||
</em> 2x4 palette, index=64: the pixel below the top left corner</p>
|
||
<h4 id="using-palettes-with-items">Using palettes with items</h4>
|
||
<p>When registering an item, set the item definition's <code>palette</code> field to
|
||
a texture. You can also use texture modifiers.</p>
|
||
<p>The <code>ItemStack</code>'s color depends on the <code>palette_index</code> field of the
|
||
stack's metadata. <code>palette_index</code> is an integer, which specifies the
|
||
index of the pixel to use.</p>
|
||
<h4 id="linking-palettes-with-nodes">Linking palettes with nodes</h4>
|
||
<p>When registering a node, set the item definition's <code>palette</code> field to
|
||
a texture. You can also use texture modifiers.
|
||
The node's color depends on its <code>param2</code>, so you also must set an
|
||
appropriate <code>drawtype</code>:
|
||
<em> <code>drawtype = "color"</code> for nodes which use their full <code>param2</code> for
|
||
palette indexing. These nodes can have 256 different colors.
|
||
The palette should contain 256 pixels.
|
||
</em> <code>drawtype = "colorwallmounted"</code> for nodes which use the first
|
||
five bits (most significant) of <code>param2</code> for palette indexing.
|
||
The remaining three bits are describing rotation, as in <code>wallmounted</code>
|
||
draw type. Division by 8 yields the palette index (without stretching the
|
||
palette). These nodes can have 32 different colors, and the palette
|
||
should contain 32 pixels.
|
||
Examples:
|
||
* <code>param2 = 17</code> is 2 * 8 + 1, so the rotation is 1 and the third (= 2 + 1)
|
||
pixel will be picked from the palette.
|
||
* <code>param2 = 35</code> is 4 * 8 + 3, so the rotation is 3 and the fifth (= 4 + 1)
|
||
pixel will be picked from the palette.
|
||
* <code>drawtype = "colorfacedir"</code> for nodes which use the first
|
||
three bits of <code>param2</code> for palette indexing. The remaining
|
||
five bits are describing rotation, as in <code>facedir</code> draw type.
|
||
Division by 32 yields the palette index (without stretching the
|
||
palette). These nodes can have 8 different colors, and the
|
||
palette should contain 8 pixels.
|
||
Examples:
|
||
* <code>param2 = 17</code> is 0 * 32 + 17, so the rotation is 17 and the
|
||
first (= 0 + 1) pixel will be picked from the palette.
|
||
* <code>param2 = 35</code> is 1 * 32 + 3, so the rotation is 3 and the
|
||
second (= 1 + 1) pixel will be picked from the palette.</p>
|
||
<p>To colorize a node on the map, set its <code>param2</code> value (according
|
||
to the node's draw type).</p>
|
||
<h3 id="conversion-between-nodes-in-the-inventory-and-the-on-the-map">Conversion between nodes in the inventory and the on the map</h3>
|
||
<p>Static coloring is the same for both cases, there is no need
|
||
for conversion.</p>
|
||
<p>If the <code>ItemStack</code>'s metadata contains the <code>color</code> field, it will be
|
||
lost on placement, because nodes on the map can only use palettes.</p>
|
||
<p>If the <code>ItemStack</code>'s metadata contains the <code>palette_index</code> field, it is
|
||
automatically transferred between node and item forms by the engine,
|
||
when a player digs or places a colored node.
|
||
You can disable this feature by setting the <code>drop</code> field of the node
|
||
to itself (without metadata).</p>
|
||
<h3 id="colored-items-in-craft-recipes">Colored items in craft recipes</h3>
|
||
<p>Craft recipes only support item strings, but fortunately item strings
|
||
can also contain metadata. Example craft recipe registration:</p>
|
||
<pre><code>minetest.register_craft({
|
||
output = minetest.itemstring_with_palette("wool:block", 3),
|
||
type = "shapeless",
|
||
recipe = {
|
||
"wool:block",
|
||
"dye:red",
|
||
},
|
||
})
|
||
</code></pre>
|
||
<p>To set the <code>color</code> field, you can use <code>minetest.itemstring_with_color</code>.</p>
|
||
<p>Metadata field filtering in the <code>recipe</code> field are not supported yet,
|
||
so the craft output is independent of the color of the ingredients.</p>
|
||
<h2 id="soft-texture-overlay">Soft texture overlay</h2>
|
||
<p>Sometimes hardware coloring is not enough, because it affects the
|
||
whole tile. Soft texture overlays were added to Minetest to allow
|
||
the dynamic coloring of only specific parts of the node's texture.
|
||
For example a grass block may have colored grass, while keeping the
|
||
dirt brown.</p>
|
||
<p>These overlays are 'soft', because unlike texture modifiers, the layers
|
||
are not merged in the memory, but they are simply drawn on top of each
|
||
other. This allows different hardware coloring, but also means that
|
||
tiles with overlays are drawn slower. Using too much overlays might
|
||
cause FPS loss.</p>
|
||
<p>To define an overlay, simply set the <code>overlay_tiles</code> field of the node
|
||
definition. These tiles are defined in the same way as plain tiles:
|
||
they can have a texture name, color etc.
|
||
To skip one face, set that overlay tile to an empty string.</p>
|
||
<p>Example (colored grass block):</p>
|
||
<pre><code>minetest.register_node("default:dirt_with_grass", {
|
||
description = "Dirt with Grass",
|
||
-- Regular tiles, as usual
|
||
-- The dirt tile disables palette coloring
|
||
tiles = { {name = "default_grass.png"},
|
||
{name = "default_dirt.png", color = "white"}},
|
||
-- Overlay tiles: define them in the same style
|
||
-- The top and bottom tile does not have overlay
|
||
overlay_tiles = {"", "",
|
||
{name = "default_grass_side.png", tileable_vertical = false}},
|
||
-- Global color, used in inventory
|
||
color = "green",
|
||
-- Palette in the world
|
||
paramtype2 = "color",
|
||
palette = "default_foilage.png",
|
||
})
|
||
</code></pre>
|
||
<h2 id="sounds">Sounds</h2>
|
||
<p>Only Ogg Vorbis files are supported.</p>
|
||
<p>For positional playing of sounds, only single-channel (mono) files are
|
||
supported. Otherwise OpenAL will play them non-positionally.</p>
|
||
<p>Mods should generally prefix their sounds with <code>modname_</code>, e.g. given
|
||
the mod name "<code>foomod</code>", a sound could be called:</p>
|
||
<pre><code>foomod_foosound.ogg
|
||
</code></pre>
|
||
<p>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.</p>
|
||
<p>When playing the sound <code>foomod_foosound</code>, the sound is chosen randomly
|
||
from the available ones of the following files:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#foomod_foosoundogg" name="foomod_foosoundogg">#</a><code>foomod_foosound.ogg</code></li>
|
||
<li><a class="anchor" href="#foomod_foosound0ogg" name="foomod_foosound0ogg">#</a><code>foomod_foosound.0.ogg</code></li>
|
||
<li><a class="anchor" href="#foomod_foosound1ogg" name="foomod_foosound1ogg">#</a><code>foomod_foosound.1.ogg</code></li>
|
||
<li>(...)</li>
|
||
<li><a class="anchor" href="#foomod_foosound9ogg" name="foomod_foosound9ogg">#</a><code>foomod_foosound.9.ogg</code></li>
|
||
</ul>
|
||
<p>Examples of sound parameter tables:</p>
|
||
<pre><code>-- Play locationless on all clients
|
||
{
|
||
gain = 1.0, -- default
|
||
fade = 0.0, -- default, change to a value > 0 to fade the sound in
|
||
pitch = 1.0, -- default
|
||
}
|
||
-- Play locationless to one player
|
||
{
|
||
to_player = name,
|
||
gain = 1.0, -- default
|
||
fade = 0.0, -- default, change to a value > 0 to fade the sound in
|
||
pitch = 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 = <an ObjectRef>,
|
||
gain = 1.0, -- default
|
||
max_hear_distance = 32, -- default, uses an euclidean metric
|
||
loop = true,
|
||
}
|
||
</code></pre>
|
||
<p>Looped sounds must either be connected to an object or played locationless to
|
||
one player using <code>to_player = name,</code></p>
|
||
<h3 id="simplesoundspec"><code>SimpleSoundSpec</code></h3>
|
||
<ul>
|
||
<li>e.g. <code>""</code></li>
|
||
<li><a class="anchor" href="#default_place_node" name="default_place_node">#</a>e.g. <code>"default_place_node"</code></li>
|
||
<li>e.g. <code>{}</code></li>
|
||
<li><a class="anchor" href="#namedefault_place_node" name="namedefault_place_node">#</a>e.g. <code>{name = "default_place_node"}</code></li>
|
||
<li><a class="anchor" href="#namedefault_place_nodegain10" name="namedefault_place_nodegain10">#</a>e.g. <code>{name = "default_place_node", gain = 1.0}</code></li>
|
||
<li><a class="anchor" href="#namedefault_place_nodegain10pitch10" name="namedefault_place_nodegain10pitch10">#</a>e.g. <code>{name = "default_place_node", gain = 1.0, pitch = 1.0}</code></li>
|
||
</ul>
|
||
<h2 id="registered-definitions-of-stuff">Registered definitions of stuff</h2>
|
||
<p>Anything added using certain <code>minetest.register_*</code> functions get added to
|
||
the global <code>minetest.registered_*</code> tables.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregister_entitynameprototypetable" name="minetestregister_entitynameprototypetable">#</a>
|
||
<p><code>minetest.register_entity(name, prototype table)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregistered_entitiesname" name="minetestregistered_entitiesname">#</a>added to <code>minetest.registered_entities[name]</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_nodenamenodedefinition" name="minetestregister_nodenamenodedefinition">#</a>
|
||
<p><code>minetest.register_node(name, node definition)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregistered_itemsname" name="minetestregistered_itemsname">#</a>added to <code>minetest.registered_items[name]</code></li>
|
||
<li><a class="anchor" href="#minetestregistered_nodesname" name="minetestregistered_nodesname">#</a>added to <code>minetest.registered_nodes[name]</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_toolnameitemdefinition" name="minetestregister_toolnameitemdefinition">#</a>
|
||
<p><code>minetest.register_tool(name, item definition)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregistered_itemsname_1" name="minetestregistered_itemsname_1">#</a>added to <code>minetest.registered_items[name]</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_craftitemnameitemdefinition" name="minetestregister_craftitemnameitemdefinition">#</a>
|
||
<p><code>minetest.register_craftitem(name, item definition)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregistered_itemsname_2" name="minetestregistered_itemsname_2">#</a>added to <code>minetest.registered_items[name]</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestunregister_itemname" name="minetestunregister_itemname">#</a>
|
||
<p><code>minetest.unregister_item(name)</code></p>
|
||
<ul>
|
||
<li>Unregisters the item name from engine, and deletes the entry with key</li>
|
||
<li><a class="anchor" href="#name" name="name">#</a><code>name</code> from <code>minetest.registered_items</code> and from the associated item</li>
|
||
<li><a class="anchor" href="#minetestregistered_nodes" name="minetestregistered_nodes">#</a>table according to its nature: <code>minetest.registered_nodes[]</code> etc</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_biomebiomedefinition" name="minetestregister_biomebiomedefinition">#</a>
|
||
<p><code>minetest.register_biome(biome definition)</code></p>
|
||
<ul>
|
||
<li>returns an integer uniquely identifying the registered biome</li>
|
||
<li><a class="anchor" href="#minetestregistered_biome" name="minetestregistered_biome">#</a>added to <code>minetest.registered_biome</code> with the key of <code>biome.name</code></li>
|
||
<li><a class="anchor" href="#biomename" name="biomename">#</a>if <code>biome.name</code> is nil, the key is the returned ID</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_oreoredefinition" name="minetestregister_oreoredefinition">#</a>
|
||
<p><code>minetest.register_ore(ore definition)</code></p>
|
||
<ul>
|
||
<li>returns an integer uniquely identifying the registered ore</li>
|
||
<li><a class="anchor" href="#minetestregistered_ores" name="minetestregistered_ores">#</a>added to <code>minetest.registered_ores</code> with the key of <code>ore.name</code></li>
|
||
<li><a class="anchor" href="#orename" name="orename">#</a>if <code>ore.name</code> is nil, the key is the returned ID</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_decorationdecorationdefinition" name="minetestregister_decorationdecorationdefinition">#</a>
|
||
<p><code>minetest.register_decoration(decoration definition)</code></p>
|
||
<ul>
|
||
<li>returns an integer uniquely identifying the registered decoration</li>
|
||
<li><a class="anchor" href="#minetestregistered_decorations" name="minetestregistered_decorations">#</a>added to <code>minetest.registered_decorations</code> with the key of <code>decoration.name</code></li>
|
||
<li><a class="anchor" href="#decorationname" name="decorationname">#</a>if <code>decoration.name</code> is nil, the key is the returned ID</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_schematicschematicdefinition" name="minetestregister_schematicschematicdefinition">#</a>
|
||
<p><code>minetest.register_schematic(schematic definition)</code></p>
|
||
<ul>
|
||
<li>returns an integer uniquely identifying the registered schematic</li>
|
||
<li><a class="anchor" href="#minetestregistered_schematic" name="minetestregistered_schematic">#</a>added to <code>minetest.registered_schematic</code> with the key of <code>schematic.name</code></li>
|
||
<li><a class="anchor" href="#schematicname" name="schematicname">#</a>if <code>schematic.name</code> is nil, the key is the returned ID</li>
|
||
<li>if the schematic is loaded from a file, schematic.name is set to the filename</li>
|
||
<li>if the function is called when loading the mod, and schematic.name is a relative
|
||
path, then the current mod path will be prepended to the schematic filename</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclear_registered_biomes" name="minetestclear_registered_biomes">#</a>
|
||
<p><code>minetest.clear_registered_biomes()</code></p>
|
||
<ul>
|
||
<li>clears all biomes currently registered</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclear_registered_ores" name="minetestclear_registered_ores">#</a>
|
||
<p><code>minetest.clear_registered_ores()</code></p>
|
||
<ul>
|
||
<li>clears all ores currently registered</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclear_registered_decorations" name="minetestclear_registered_decorations">#</a>
|
||
<p><code>minetest.clear_registered_decorations()</code></p>
|
||
<ul>
|
||
<li>clears all decorations currently registered</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclear_registered_schematics" name="minetestclear_registered_schematics">#</a>
|
||
<p><code>minetest.clear_registered_schematics()</code></p>
|
||
<ul>
|
||
<li>clears all schematics currently registered</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p>Note that in some cases you will stumble upon things that are not contained
|
||
in these tables (e.g. when a mod has been removed). Always check for
|
||
existence before trying to access the fields.</p>
|
||
<p>Example: If you want to check the drawtype of a node, you could do:</p>
|
||
<pre><code>local function get_nodedef_field(nodename, fieldname)
|
||
if not minetest.registered_nodes[nodename] then
|
||
return nil
|
||
end
|
||
return minetest.registered_nodes[nodename][fieldname]
|
||
end
|
||
local drawtype = get_nodedef_field(nodename, "drawtype")
|
||
</code></pre>
|
||
<p>Example: <code>minetest.get_item_group(name, group)</code> has been implemented as:</p>
|
||
<pre><code>function minetest.get_item_group(name, group)
|
||
if not minetest.registered_items[name] or not
|
||
minetest.registered_items[name].groups[group] then
|
||
return 0
|
||
end
|
||
return minetest.registered_items[name].groups[group]
|
||
end
|
||
</code></pre>
|
||
<h2 id="nodes">Nodes</h2>
|
||
<p>Nodes are the bulk data of the world: cubes and other things that take the
|
||
space of a cube. Huge amounts of them are handled efficiently, but they
|
||
are quite static.</p>
|
||
<p>The definition of a node is stored and can be accessed by name in</p>
|
||
<pre><code>minetest.registered_nodes[node.name]
|
||
</code></pre>
|
||
<p>See "Registered definitions of stuff".</p>
|
||
<p>Nodes are passed by value between Lua and the engine.
|
||
They are represented by a table:</p>
|
||
<pre><code>{name="name", param1=num, param2=num}
|
||
</code></pre>
|
||
<p><code>param1</code> and <code>param2</code> are 8-bit integers ranging from 0 to 255. The engine uses
|
||
them for certain automated functions. If you don't use these functions, you can
|
||
use them to store arbitrary values.</p>
|
||
<p>The functions of <code>param1</code> and <code>param2</code> are determined by certain fields in the
|
||
node definition:</p>
|
||
<p><code>param1</code> is reserved for the engine when <code>paramtype != "none"</code>:</p>
|
||
<pre><code>paramtype = "light"
|
||
^ The value stores light with and without sun in its upper and lower 4 bits
|
||
respectively. Allows light to propagate from or through the node with
|
||
light value falling by 1 per node. This is essential for a light source
|
||
node to spread its light.
|
||
</code></pre>
|
||
<p><code>param2</code> is reserved for the engine when any of these are used:</p>
|
||
<pre><code>liquidtype == "flowing"
|
||
^ The level and some flags of the liquid is stored in param2
|
||
drawtype == "flowingliquid"
|
||
^ The drawn liquid level is read from param2
|
||
drawtype == "torchlike"
|
||
drawtype == "signlike"
|
||
paramtype2 == "wallmounted"
|
||
^ The rotation of the node is stored in param2. You can make this value
|
||
by using minetest.dir_to_wallmounted().
|
||
paramtype2 == "facedir"
|
||
^ The rotation of the node is stored in param2. Furnaces and chests are
|
||
rotated this way. Can be made by using minetest.dir_to_facedir().
|
||
Values range 0 - 23
|
||
facedir / 4 = axis direction:
|
||
0 = y+ 1 = z+ 2 = z- 3 = x+ 4 = x- 5 = y-
|
||
facedir modulo 4 = rotation around that axis
|
||
paramtype2 == "leveled"
|
||
paramtype2 == "degrotate"
|
||
^ The rotation of this node is stored in param2. Plants are rotated this way.
|
||
Values range 0 - 179. The value stored in param2 is multiplied by two to
|
||
get the actual rotation of the node.
|
||
paramtype2 == "meshoptions"
|
||
^ Only valid for "plantlike". The value of param2 becomes a bitfield which can
|
||
be used to change how the client draws plantlike nodes. Bits 0, 1 and 2 form
|
||
a mesh selector. Currently the following meshes are choosable:
|
||
0 = a "x" shaped plant (ordinary plant)
|
||
1 = a "+" shaped plant (just rotated 45 degrees)
|
||
2 = a "*" shaped plant with 3 faces instead of 2
|
||
3 = a "#" shaped plant with 4 faces instead of 2
|
||
4 = a "#" shaped plant with 4 faces that lean outwards
|
||
5-7 are unused and reserved for future meshes.
|
||
Bits 3 through 7 are optional flags that can be combined and give these
|
||
effects:
|
||
bit 3 (0x08) - Makes the plant slightly vary placement horizontally
|
||
bit 4 (0x10) - Makes the plant mesh 1.4x larger
|
||
bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
|
||
bits 6-7 are reserved for future use.
|
||
paramtype2 == "color"
|
||
^ `param2` tells which color is picked from the palette.
|
||
The palette should have 256 pixels.
|
||
paramtype2 == "colorfacedir"
|
||
^ Same as `facedir`, but with colors.
|
||
The first three bits of `param2` tells which color
|
||
is picked from the palette.
|
||
The palette should have 8 pixels.
|
||
paramtype2 == "colorwallmounted"
|
||
^ Same as `wallmounted`, but with colors.
|
||
The first five bits of `param2` tells which color
|
||
is picked from the palette.
|
||
The palette should have 32 pixels.
|
||
paramtype2 == "glasslikeliquidlevel"
|
||
^ Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes.
|
||
param2 defines 64 levels of internal liquid.
|
||
Liquid texture is defined using `special_tiles = {"modname_tilename.png"},`
|
||
</code></pre>
|
||
<p>Nodes can also contain extra data. See "Node Metadata".</p>
|
||
<h2 id="node-drawtypes">Node drawtypes</h2>
|
||
<p>There are a bunch of different looking node types.</p>
|
||
<p>Look for examples in <code>games/minimal</code> or <code>games/minetest_game</code>.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#normal" name="normal">#</a><code>normal</code></li>
|
||
<li><a class="anchor" href="#airlike" name="airlike">#</a><code>airlike</code></li>
|
||
<li><a class="anchor" href="#liquid" name="liquid">#</a><code>liquid</code></li>
|
||
<li><a class="anchor" href="#flowingliquid" name="flowingliquid">#</a><code>flowingliquid</code></li>
|
||
<li><a class="anchor" href="#glasslike" name="glasslike">#</a><code>glasslike</code></li>
|
||
<li><a class="anchor" href="#glasslike_framed" name="glasslike_framed">#</a><code>glasslike_framed</code></li>
|
||
<li><a class="anchor" href="#glasslike_framed_optional" name="glasslike_framed_optional">#</a><code>glasslike_framed_optional</code></li>
|
||
<li><a class="anchor" href="#allfaces" name="allfaces">#</a><code>allfaces</code></li>
|
||
<li><a class="anchor" href="#allfaces_optional" name="allfaces_optional">#</a><code>allfaces_optional</code></li>
|
||
<li><a class="anchor" href="#torchlike" name="torchlike">#</a><code>torchlike</code></li>
|
||
<li><a class="anchor" href="#signlike" name="signlike">#</a><code>signlike</code></li>
|
||
<li><a class="anchor" href="#plantlike" name="plantlike">#</a><code>plantlike</code></li>
|
||
<li><a class="anchor" href="#firelike" name="firelike">#</a><code>firelike</code></li>
|
||
<li><a class="anchor" href="#fencelike" name="fencelike">#</a><code>fencelike</code></li>
|
||
<li><a class="anchor" href="#raillike" name="raillike">#</a><code>raillike</code></li>
|
||
<li><a class="anchor" href="#nodebox" name="nodebox">#</a><code>nodebox</code> -- See below. (<strong>Experimental!</strong>)</li>
|
||
<li><a class="anchor" href="#mesh" name="mesh">#</a><code>mesh</code> -- use models for nodes</li>
|
||
<li><a class="anchor" href="#plantlike_rooted" name="plantlike_rooted">#</a><code>plantlike_rooted</code></li>
|
||
</ul>
|
||
<p><code>*_optional</code> drawtypes need less rendering time if deactivated (always client side).</p>
|
||
<h2 id="node-boxes">Node boxes</h2>
|
||
<p>Node selection boxes are defined using "node boxes"</p>
|
||
<p>The <code>nodebox</code> node drawtype allows defining visual of nodes consisting of
|
||
arbitrary number of boxes. It allows defining stuff like stairs. Only the
|
||
<code>fixed</code> and <code>leveled</code> box type is supported for these.</p>
|
||
<p>Please note that this is still experimental, and may be incompatibly
|
||
changed in the future.</p>
|
||
<p>A nodebox is defined as any of:</p>
|
||
<pre><code>{
|
||
-- A normal cube; the default in most things
|
||
type = "regular"
|
||
}
|
||
{
|
||
-- A fixed box (facedir param2 is used, if applicable)
|
||
type = "fixed",
|
||
fixed = box OR {box1, box2, ...}
|
||
}
|
||
{
|
||
-- A box like the selection box for torches
|
||
-- (wallmounted param2 is used, if applicable)
|
||
type = "wallmounted",
|
||
wall_top = box,
|
||
wall_bottom = box,
|
||
wall_side = box
|
||
}
|
||
{
|
||
-- A node that has optional boxes depending on neighbouring nodes'
|
||
-- presence and type. See also `connects_to`.
|
||
type = "connected",
|
||
fixed = box OR {box1, box2, ...}
|
||
connect_top = box OR {box1, box2, ...}
|
||
connect_bottom = box OR {box1, box2, ...}
|
||
connect_front = box OR {box1, box2, ...}
|
||
connect_left = box OR {box1, box2, ...}
|
||
connect_back = box OR {box1, box2, ...}
|
||
connect_right = box OR {box1, box2, ...}
|
||
}
|
||
</code></pre>
|
||
<p>A <code>box</code> is defined as:</p>
|
||
<pre><code>{x1, y1, z1, x2, y2, z2}
|
||
</code></pre>
|
||
<p>A box of a regular node would look like:</p>
|
||
<pre><code>{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
|
||
</code></pre>
|
||
<p><code>type = "leveled"</code> is same as <code>type = "fixed"</code>, but <code>y2</code> will be automatically
|
||
set to level from <code>param2</code>.</p>
|
||
<h2 id="meshes">Meshes</h2>
|
||
<p>If drawtype <code>mesh</code> is used, tiles should hold model materials textures.
|
||
Only static meshes are implemented.
|
||
For supported model formats see Irrlicht engine documentation.</p>
|
||
<h2 id="noise-parameters">Noise Parameters</h2>
|
||
<p>Noise Parameters, or commonly called "<code>NoiseParams</code>", define the properties of
|
||
perlin noise.</p>
|
||
<h3 id="offset"><code>offset</code></h3>
|
||
<p>Offset that the noise is translated by (i.e. added) after calculation.</p>
|
||
<h3 id="scale"><code>scale</code></h3>
|
||
<p>Factor that the noise is scaled by (i.e. multiplied) after calculation.</p>
|
||
<h3 id="spread"><code>spread</code></h3>
|
||
<p>Vector containing values by which each coordinate is divided by before calculation.
|
||
Higher spread values result in larger noise features.</p>
|
||
<p>A value of <code>{x=250, y=250, z=250}</code> is common.</p>
|
||
<h3 id="seed"><code>seed</code></h3>
|
||
<p>Random seed for the noise. Add the world seed to a seed offset for world-unique noise.
|
||
In the case of <code>minetest.get_perlin()</code>, this value has the world seed automatically added.</p>
|
||
<h3 id="octaves"><code>octaves</code></h3>
|
||
<p>Number of times the noise gradient is accumulated into the noise.</p>
|
||
<p>Increase this number to increase the amount of detail in the resulting noise.</p>
|
||
<p>A value of <code>6</code> is common.</p>
|
||
<h3 id="persistence"><code>persistence</code></h3>
|
||
<p>Factor by which the effect of the noise gradient function changes with each successive octave.</p>
|
||
<p>Values less than <code>1</code> make the details of successive octaves' noise diminish, while values
|
||
greater than <code>1</code> make successive octaves stronger.</p>
|
||
<p>A value of <code>0.6</code> is common.</p>
|
||
<h3 id="lacunarity"><code>lacunarity</code></h3>
|
||
<p>Factor by which the noise feature sizes change with each successive octave.</p>
|
||
<p>A value of <code>2.0</code> is common.</p>
|
||
<h3 id="flags"><code>flags</code></h3>
|
||
<p>Leave this field unset for no special handling.</p>
|
||
<p>Currently supported are <code>defaults</code>, <code>eased</code> and <code>absvalue</code>.</p>
|
||
<h4 id="defaults"><code>defaults</code></h4>
|
||
<p>Specify this if you would like to keep auto-selection of eased/not-eased while specifying
|
||
some other flags.</p>
|
||
<h4 id="eased"><code>eased</code></h4>
|
||
<p>Maps noise gradient values onto a quintic S-curve before performing interpolation.
|
||
This results in smooth, rolling noise. Disable this (<code>noeased</code>) for sharp-looking noise.
|
||
If no flags are specified (or defaults is), 2D noise is eased and 3D noise is not eased.</p>
|
||
<h4 id="absvalue"><code>absvalue</code></h4>
|
||
<p>Accumulates the absolute value of each noise gradient result.</p>
|
||
<p>Noise parameters format example for 2D or 3D perlin noise or perlin noise maps:</p>
|
||
<pre><code>np_terrain = {
|
||
offset = 0,
|
||
scale = 1,
|
||
spread = {x=500, y=500, z=500},
|
||
seed = 571347,
|
||
octaves = 5,
|
||
persist = 0.63,
|
||
lacunarity = 2.0,
|
||
flags = "defaults, absvalue"
|
||
}
|
||
^ A single noise parameter table can be used to get 2D or 3D noise,
|
||
when getting 2D noise spread.z is ignored.
|
||
</code></pre>
|
||
<h2 id="ore-types">Ore types</h2>
|
||
<p>These tell in what manner the ore is generated.</p>
|
||
<p>All default ores are of the uniformly-distributed scatter type.</p>
|
||
<h3 id="scatter"><code>scatter</code></h3>
|
||
<p>Randomly chooses a location and generates a cluster of ore.</p>
|
||
<p>If <code>noise_params</code> is specified, the ore will be placed if the 3D perlin noise at
|
||
that point is greater than the <code>noise_threshold</code>, giving the ability to create
|
||
a non-equal distribution of ore.</p>
|
||
<h3 id="sheet"><code>sheet</code></h3>
|
||
<p>Creates a sheet of ore in a blob shape according to the 2D perlin noise
|
||
described by <code>noise_params</code> and <code>noise_threshold</code>. This is essentially an
|
||
improved version of the so-called "stratus" ore seen in some unofficial mods.</p>
|
||
<p>This sheet consists of vertical columns of uniform randomly distributed height,
|
||
varying between the inclusive range <code>column_height_min</code> and <code>column_height_max</code>.
|
||
If <code>column_height_min</code> is not specified, this parameter defaults to 1.
|
||
If <code>column_height_max</code> is not specified, this parameter defaults to <code>clust_size</code>
|
||
for reverse compatibility. New code should prefer <code>column_height_max</code>.</p>
|
||
<p>The <code>column_midpoint_factor</code> parameter controls the position of the column at which
|
||
ore eminates from. If 1, columns grow upward. If 0, columns grow downward. If 0.5,
|
||
columns grow equally starting from each direction. <code>column_midpoint_factor</code> is a
|
||
decimal number ranging in value from 0 to 1. If this parameter is not specified,
|
||
the default is 0.5.</p>
|
||
<p>The ore parameters <code>clust_scarcity</code> and <code>clust_num_ores</code> are ignored for this ore type.</p>
|
||
<h3 id="puff"><code>puff</code></h3>
|
||
<p>Creates a sheet of ore in a cloud-like puff shape.</p>
|
||
<p>As with the <code>sheet</code> ore type, the size and shape of puffs are described by
|
||
<code>noise_params</code> and <code>noise_threshold</code> and are placed at random vertical positions
|
||
within the currently generated chunk.</p>
|
||
<p>The vertical top and bottom displacement of each puff are determined by the noise
|
||
parameters <code>np_puff_top</code> and <code>np_puff_bottom</code>, respectively.</p>
|
||
<h3 id="blob"><code>blob</code></h3>
|
||
<p>Creates a deformed sphere of ore according to 3d perlin noise described by
|
||
<code>noise_params</code>. The maximum size of the blob is <code>clust_size</code>, and
|
||
<code>clust_scarcity</code> has the same meaning as with the <code>scatter</code> type.</p>
|
||
<h3 id="vein"><code>vein</code></h3>
|
||
<p>Creates veins of ore varying in density by according to the intersection of two
|
||
instances of 3d perlin noise with diffferent seeds, both described by
|
||
<code>noise_params</code>. <code>random_factor</code> varies the influence random chance has on
|
||
placement of an ore inside the vein, which is <code>1</code> by default. Note that
|
||
modifying this parameter may require adjusting <code>noise_threshold</code>.
|
||
The parameters <code>clust_scarcity</code>, <code>clust_num_ores</code>, and <code>clust_size</code> are ignored
|
||
by this ore type. This ore type is difficult to control since it is sensitive
|
||
to small changes. The following is a decent set of parameters to work from:</p>
|
||
<pre><code>noise_params = {
|
||
offset = 0,
|
||
scale = 3,
|
||
spread = {x=200, y=200, z=200},
|
||
seed = 5390,
|
||
octaves = 4,
|
||
persist = 0.5,
|
||
flags = "eased",
|
||
},
|
||
noise_threshold = 1.6
|
||
</code></pre>
|
||
<p><strong>WARNING</strong>: Use this ore type <em>very</em> sparingly since it is ~200x more
|
||
computationally expensive than any other ore.</p>
|
||
<h2 id="ore-attributes">Ore attributes</h2>
|
||
<p>See section "Flag Specifier Format".</p>
|
||
<p>Currently supported flags:
|
||
<code>puff_cliffs</code>, <code>puff_additive_composition</code>.</p>
|
||
<h3 id="puff_cliffs"><code>puff_cliffs</code></h3>
|
||
<p>If set, puff ore generation will not taper down large differences in displacement
|
||
when approaching the edge of a puff. This flag has no effect for ore types other
|
||
than <code>puff</code>.</p>
|
||
<h3 id="puff_additive_composition"><code>puff_additive_composition</code></h3>
|
||
<p>By default, when noise described by <code>np_puff_top</code> or <code>np_puff_bottom</code> results in a
|
||
negative displacement, the sub-column at that point is not generated. With this
|
||
attribute set, puff ore generation will instead generate the absolute difference in
|
||
noise displacement values. This flag has no effect for ore types other than <code>puff</code>.</p>
|
||
<h2 id="decoration-types">Decoration types</h2>
|
||
<p>The varying types of decorations that can be placed.</p>
|
||
<h3 id="simple"><code>simple</code></h3>
|
||
<p>Creates a 1 times <code>H</code> times 1 column of a specified node (or a random node from
|
||
a list, if a decoration list is specified). Can specify a certain node it must
|
||
spawn next to, such as water or lava, for example. Can also generate a
|
||
decoration of random height between a specified lower and upper bound.
|
||
This type of decoration is intended for placement of grass, flowers, cacti,
|
||
papyri, waterlilies and so on.</p>
|
||
<h3 id="schematic"><code>schematic</code></h3>
|
||
<p>Copies a box of <code>MapNodes</code> from a specified schematic file (or raw description).
|
||
Can specify a probability of a node randomly appearing when placed.
|
||
This decoration type is intended to be used for multi-node sized discrete
|
||
structures, such as trees, cave spikes, rocks, and so on.</p>
|
||
<h2 id="schematic-specifier">Schematic specifier</h2>
|
||
<p>A schematic specifier identifies a schematic by either a filename to a
|
||
Minetest Schematic file (<code>.mts</code>) or through raw data supplied through Lua,
|
||
in the form of a table. This table specifies the following fields:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#size" name="size">#</a>The <code>size</code> field is a 3D vector containing the dimensions of the provided schematic. (required)</li>
|
||
<li><a class="anchor" href="#yslice_prob" name="yslice_prob">#</a>The <code>yslice_prob</code> field is a table of {ypos, prob} which sets the <code>ypos</code>th vertical slice
|
||
of the schematic to have a <code>prob / 256 * 100</code> chance of occuring. (default: 255)</li>
|
||
<li><a class="anchor" href="#data" name="data">#</a>The <code>data</code> field is a flat table of MapNode tables making up the schematic,
|
||
in the order of <code>[z [y [x]]]</code>. (required)
|
||
Each MapNode table contains:</li>
|
||
<li><a class="anchor" href="#name_1" name="name_1">#</a><code>name</code>: the name of the map node to place (required)</li>
|
||
<li><a class="anchor" href="#prob" name="prob">#</a><code>prob</code> (alias <code>param1</code>): the probability of this node being placed (default: 255)</li>
|
||
<li><a class="anchor" href="#param2" name="param2">#</a><code>param2</code>: the raw param2 value of the node being placed onto the map (default: 0)</li>
|
||
<li><a class="anchor" href="#force_place" name="force_place">#</a><code>force_place</code>: boolean representing if the node should forcibly overwrite any
|
||
previous contents (default: false)</li>
|
||
</ul>
|
||
<p>About probability values:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#0" name="0">#</a>A probability value of <code>0</code> or <code>1</code> means that node will never appear (0% chance).</li>
|
||
<li><a class="anchor" href="#254" name="254">#</a>A probability value of <code>254</code> or <code>255</code> means the node will always appear (100% chance).</li>
|
||
<li><a class="anchor" href="#p_1" name="p_1">#</a>If the probability value <code>p</code> is greater than <code>1</code>, then there is a
|
||
<code>(p / 256 * 100)</code> percent chance that node will appear when the schematic is
|
||
placed on the map.</li>
|
||
</ul>
|
||
<h2 id="schematic-attributes">Schematic attributes</h2>
|
||
<p>See section "Flag Specifier Format".</p>
|
||
<p>Currently supported flags: <code>place_center_x</code>, <code>place_center_y</code>, <code>place_center_z</code>,
|
||
<code>force_placement</code>.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#place_center_x" name="place_center_x">#</a><code>place_center_x</code>: Placement of this decoration is centered along the X axis.</li>
|
||
<li><a class="anchor" href="#place_center_y" name="place_center_y">#</a><code>place_center_y</code>: Placement of this decoration is centered along the Y axis.</li>
|
||
<li><a class="anchor" href="#place_center_z" name="place_center_z">#</a><code>place_center_z</code>: Placement of this decoration is centered along the Z axis.</li>
|
||
<li><a class="anchor" href="#force_placement" name="force_placement">#</a><code>force_placement</code>: Schematic nodes other than "ignore" will replace existing nodes.</li>
|
||
</ul>
|
||
<h2 id="hud-element-types">HUD element types</h2>
|
||
<p>The position field is used for all element types.</p>
|
||
<p>To account for differing resolutions, the position coordinates are the percentage
|
||
of the screen, ranging in value from <code>0</code> to <code>1</code>.</p>
|
||
<p>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.</p>
|
||
<p><code>0</code> draws from left to right, <code>1</code> draws from right to left, <code>2</code> draws from
|
||
top to bottom, and <code>3</code> draws from bottom to top.</p>
|
||
<p>The <code>alignment</code> field specifies how the item will be aligned. It ranges from <code>-1</code> to <code>1</code>,
|
||
with <code>0</code> being the center, <code>-1</code> is moved to the left/up, and <code>1</code> is to the right/down.
|
||
Fractional values can be used.</p>
|
||
<p>The <code>offset</code> field specifies a pixel offset from the position. Contrary to position,
|
||
the offset is not scaled to screen size. This allows for some precisely-positioned
|
||
items in the HUD.</p>
|
||
<p><strong>Note</strong>: <code>offset</code> <em>will</em> adapt to screen DPI as well as user defined scaling factor!</p>
|
||
<p>Below are the specific uses for fields in each type; fields not listed for that type are ignored.</p>
|
||
<p><strong>Note</strong>: Future revisions to the HUD API may be incompatible; the HUD API is still
|
||
in the experimental stages.</p>
|
||
<h3 id="image"><code>image</code></h3>
|
||
<p>Displays an image on the HUD.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#scale_1" name="scale_1">#</a><code>scale</code>: 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. <code>x=-100</code> means 100% (width).</li>
|
||
<li><a class="anchor" href="#text_1" name="text_1">#</a><code>text</code>: The name of the texture that is displayed.</li>
|
||
<li><a class="anchor" href="#alignment" name="alignment">#</a><code>alignment</code>: The alignment of the image.</li>
|
||
<li><a class="anchor" href="#offset_1" name="offset_1">#</a><code>offset</code>: offset in pixels from position.</li>
|
||
</ul>
|
||
<h3 id="text"><code>text</code></h3>
|
||
<p>Displays text on the HUD.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#scale_2" name="scale_2">#</a><code>scale</code>: Defines the bounding rectangle of the text.
|
||
A value such as <code>{x=100, y=100}</code> should work.</li>
|
||
<li><a class="anchor" href="#text_2" name="text_2">#</a><code>text</code>: The text to be displayed in the HUD element.</li>
|
||
<li><a class="anchor" href="#number" name="number">#</a><code>number</code>: An integer containing the RGB value of the color used to draw the text.
|
||
Specify <code>0xFFFFFF</code> for white text, <code>0xFF0000</code> for red, and so on.</li>
|
||
<li><a class="anchor" href="#alignment_1" name="alignment_1">#</a><code>alignment</code>: The alignment of the text.</li>
|
||
<li><a class="anchor" href="#offset_2" name="offset_2">#</a><code>offset</code>: offset in pixels from position.</li>
|
||
</ul>
|
||
<h3 id="statbar"><code>statbar</code></h3>
|
||
<p>Displays a horizontal bar made up of half-images.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#text_3" name="text_3">#</a><code>text</code>: The name of the texture that is used.</li>
|
||
<li><a class="anchor" href="#number_1" name="number_1">#</a><code>number</code>: The number of half-textures that are displayed.
|
||
If odd, will end with a vertically center-split texture.</li>
|
||
<li><a class="anchor" href="#direction" name="direction">#</a><code>direction</code></li>
|
||
<li><a class="anchor" href="#offset_3" name="offset_3">#</a><code>offset</code>: offset in pixels from position.</li>
|
||
<li><a class="anchor" href="#size_1" name="size_1">#</a><code>size</code>: If used, will force full-image size to this value (override texture pack image size)</li>
|
||
</ul>
|
||
<h3 id="inventory"><code>inventory</code></h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#text_4" name="text_4">#</a><code>text</code>: The name of the inventory list to be displayed.</li>
|
||
<li><a class="anchor" href="#number_2" name="number_2">#</a><code>number</code>: Number of items in the inventory to be displayed.</li>
|
||
<li><a class="anchor" href="#item" name="item">#</a><code>item</code>: Position of item that is selected.</li>
|
||
<li><a class="anchor" href="#direction_1" name="direction_1">#</a><code>direction</code></li>
|
||
<li><a class="anchor" href="#offset_4" name="offset_4">#</a><code>offset</code>: offset in pixels from position.</li>
|
||
</ul>
|
||
<h3 id="waypoint"><code>waypoint</code></h3>
|
||
<p>Displays distance to selected world position.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#name_2" name="name_2">#</a><code>name</code>: The name of the waypoint.</li>
|
||
<li><a class="anchor" href="#text_5" name="text_5">#</a><code>text</code>: Distance suffix. Can be blank.</li>
|
||
<li><a class="anchor" href="#number_3" name="number_3">#</a><code>number:</code> An integer containing the RGB value of the color used to draw the text.</li>
|
||
<li><a class="anchor" href="#world_pos" name="world_pos">#</a><code>world_pos</code>: World position of the waypoint.</li>
|
||
</ul>
|
||
<h2 id="representations-of-simple-things">Representations of simple things</h2>
|
||
<h3 id="positionvector">Position/vector</h3>
|
||
<pre><code>{x=num, y=num, z=num}
|
||
</code></pre>
|
||
<p>For helper functions see "Vector helpers".</p>
|
||
<h3 id="pointed_thing"><code>pointed_thing</code></h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#typenothing" name="typenothing">#</a><code>{type="nothing"}</code></li>
|
||
<li><a class="anchor" href="#typenodeunderposabovepos" name="typenodeunderposabovepos">#</a><code>{type="node", under=pos, above=pos}</code></li>
|
||
<li><a class="anchor" href="#typeobjectrefObjectRef" name="typeobjectrefObjectRef">#</a><code>{type="object", ref=ObjectRef}</code></li>
|
||
</ul>
|
||
<h2 id="flag-specifier-format">Flag Specifier Format</h2>
|
||
<p>Flags using the standardized flag specifier format can be specified in either of
|
||
two ways, by string or table.</p>
|
||
<p>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 <code>"no"</code> explicitly
|
||
clears the flag from whatever the default may be.</p>
|
||
<p>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 <code>"no"</code>
|
||
is present, mapped to a boolean of any value, the specified flag is unset.</p>
|
||
<p>E.g. A flag field of value</p>
|
||
<pre><code>{place_center_x = true, place_center_y=false, place_center_z=true}
|
||
</code></pre>
|
||
<p>is equivalent to</p>
|
||
<pre><code>{place_center_x = true, noplace_center_y=true, place_center_z=true}
|
||
</code></pre>
|
||
<p>which is equivalent to</p>
|
||
<pre><code>"place_center_x, noplace_center_y, place_center_z"
|
||
</code></pre>
|
||
<p>or even</p>
|
||
<pre><code>"place_center_x, place_center_z"
|
||
</code></pre>
|
||
<p>since, by default, no schematic attributes are set.</p>
|
||
<h2 id="items">Items</h2>
|
||
<h3 id="item-types">Item types</h3>
|
||
<p>There are three kinds of items: nodes, tools and craftitems.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#register_node" name="register_node">#</a>Node (<code>register_node</code>): A node from the world.</li>
|
||
<li><a class="anchor" href="#register_tool" name="register_tool">#</a>Tool (<code>register_tool</code>): A tool/weapon that can dig and damage
|
||
things according to <code>tool_capabilities</code>.</li>
|
||
<li><a class="anchor" href="#register_craftitem" name="register_craftitem">#</a>Craftitem (<code>register_craftitem</code>): A miscellaneous item.</li>
|
||
</ul>
|
||
<h3 id="amount-and-wear">Amount and wear</h3>
|
||
<p>All item stacks have an amount between 0 to 65535. It is 1 by
|
||
default. Tool item stacks can not have an amount greater than 1.</p>
|
||
<p>Tools use a wear (=damage) value ranging from 0 to 65535. The
|
||
value 0 is the default and used is for unworn tools. The values
|
||
1 to 65535 are used for worn tools, where a higher value stands for
|
||
a higher wear. Non-tools always have a wear value of 0.</p>
|
||
<h3 id="item-formats">Item formats</h3>
|
||
<p>Items and item stacks can exist in three formats: Serializes, table format
|
||
and <code>ItemStack</code>.</p>
|
||
<h4 id="serialized">Serialized</h4>
|
||
<p>This is called "stackstring" or "itemstring". It is a simple string with
|
||
1-3 components: the full item identifier, an optional amount and an optional
|
||
wear value. Syntax:</p>
|
||
<pre><code><identifier> [<amount>[ <wear>]]
|
||
</code></pre>
|
||
<p>Examples:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#defaultapple" name="defaultapple">#</a><code>'default:apple'</code>: 1 apple</li>
|
||
<li><a class="anchor" href="#defaultdirt5" name="defaultdirt5">#</a><code>'default:dirt 5'</code>: 5 dirt</li>
|
||
<li><a class="anchor" href="#defaultpick_stone" name="defaultpick_stone">#</a><code>'default:pick_stone'</code>: a new stone pickaxe</li>
|
||
<li><a class="anchor" href="#defaultpick_wood121323" name="defaultpick_wood121323">#</a><code>'default:pick_wood 1 21323'</code>: a wooden pickaxe, ca. 1/3 worn out</li>
|
||
</ul>
|
||
<h4 id="table-format">Table format</h4>
|
||
<p>Examples:</p>
|
||
<p>5 dirt nodes:</p>
|
||
<pre><code>{name="default:dirt", count=5, wear=0, metadata=""}
|
||
</code></pre>
|
||
<p>A wooden pick about 1/3 worn out:</p>
|
||
<pre><code>{name="default:pick_wood", count=1, wear=21323, metadata=""}
|
||
</code></pre>
|
||
<p>An apple:</p>
|
||
<pre><code>{name="default:apple", count=1, wear=0, metadata=""}
|
||
</code></pre>
|
||
<h4 id="itemstack"><code>ItemStack</code></h4>
|
||
<p>A native C++ format with many helper methods. Useful for converting
|
||
between formats. See the Class reference section for details.</p>
|
||
<p>When an item must be passed to a function, it can usually be in any of
|
||
these formats.</p>
|
||
<h2 id="groups">Groups</h2>
|
||
<p>In a number of places, there is a group table. Groups define the
|
||
properties of a thing (item, node, armor of entity, capabilities of
|
||
tool) in such a way that the engine and other mods can can interact with
|
||
the thing without actually knowing what the thing is.</p>
|
||
<h3 id="usage">Usage</h3>
|
||
<p>Groups are stored in a table, having the group names with keys and the
|
||
group ratings as values. For example:</p>
|
||
<pre><code>groups = {crumbly=3, soil=1}
|
||
-- ^ Default dirt
|
||
|
||
groups = {crumbly=2, soil=1, level=2, outerspace=1}
|
||
-- ^ A more special dirt-kind of thing
|
||
</code></pre>
|
||
<p>Groups always have a rating associated with them. If there is no
|
||
useful meaning for a rating for an enabled group, it shall be <code>1</code>.</p>
|
||
<p>When not defined, the rating of a group defaults to <code>0</code>. Thus when you
|
||
read groups, you must interpret <code>nil</code> and <code>0</code> as the same value, <code>0</code>.</p>
|
||
<p>You can read the rating of a group for an item or a node by using</p>
|
||
<pre><code>minetest.get_item_group(itemname, groupname)
|
||
</code></pre>
|
||
<h3 id="groups-of-items">Groups of items</h3>
|
||
<p>Groups of items can define what kind of an item it is (e.g. wool).</p>
|
||
<h3 id="groups-of-nodes">Groups of nodes</h3>
|
||
<p>In addition to the general item things, groups are used to define whether
|
||
a node is destroyable and how long it takes to destroy by a tool.</p>
|
||
<h3 id="groups-of-entities">Groups of entities</h3>
|
||
<p>For entities, groups are, as of now, used only for calculating damage.
|
||
The rating is the percentage of damage caused by tools with this damage group.
|
||
See "Entity damage mechanism".</p>
|
||
<pre><code>object.get_armor_groups() --> a group-rating table (e.g. {fleshy=100})
|
||
object.set_armor_groups({fleshy=30, cracky=80})
|
||
</code></pre>
|
||
<h3 id="groups-of-tools">Groups of tools</h3>
|
||
<p>Groups in tools define which groups of nodes and entities they are
|
||
effective towards.</p>
|
||
<h3 id="groups-in-crafting-recipes">Groups in crafting recipes</h3>
|
||
<p>An example: Make meat soup from any meat, any water and any bowl:</p>
|
||
<pre><code>{
|
||
output = 'food:meat_soup_raw',
|
||
recipe = {
|
||
{'group:meat'},
|
||
{'group:water'},
|
||
{'group:bowl'},
|
||
},
|
||
-- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
|
||
}
|
||
</code></pre>
|
||
<p>Another example: Make red wool from white wool and red dye:</p>
|
||
<pre><code>{
|
||
type = 'shapeless',
|
||
output = 'wool:red',
|
||
recipe = {'wool:white', 'group:dye,basecolor_red'},
|
||
}
|
||
</code></pre>
|
||
<h3 id="special-groups">Special groups</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#immortal" name="immortal">#</a><code>immortal</code>: Disables the group damage system for an entity</li>
|
||
<li><a class="anchor" href="#punch_operable" name="punch_operable">#</a><code>punch_operable</code>: For entities; disables the regular damage mechanism for
|
||
players punching it by hand or a non-tool item, so that it can do something
|
||
else than take damage.</li>
|
||
<li><a class="anchor" href="#level" name="level">#</a><code>level</code>: Can be used to give an additional sense of progression in the game.<ul>
|
||
<li>A larger level will cause e.g. a weapon of a lower level make much less
|
||
damage, and get worn out much faster, or not be able to get drops
|
||
from destroyed nodes.</li>
|
||
<li><a class="anchor" href="#0_1" name="0_1">#</a><code>0</code> is something that is directly accessible at the start of gameplay</li>
|
||
<li>There is no upper limit</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#dig_immediate" name="dig_immediate">#</a><code>dig_immediate</code>: (player can always pick up node without reducing tool wear)<ul>
|
||
<li><a class="anchor" href="#2" name="2">#</a><code>2</code>: the node always gets the digging time 0.5 seconds (rail, sign)</li>
|
||
<li><a class="anchor" href="#3" name="3">#</a><code>3</code>: the node always gets the digging time 0 seconds (torch)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#disable_jump" name="disable_jump">#</a><code>disable_jump</code>: Player (and possibly other things) cannot jump from node</li>
|
||
<li><a class="anchor" href="#fall_damage_add_percent" name="fall_damage_add_percent">#</a><code>fall_damage_add_percent</code>: damage speed = <code>speed * (1 + value/100)</code></li>
|
||
<li><a class="anchor" href="#bouncy" name="bouncy">#</a><code>bouncy</code>: value is bounce speed in percent</li>
|
||
<li><a class="anchor" href="#falling_node" name="falling_node">#</a><code>falling_node</code>: if there is no walkable block under the node it will fall</li>
|
||
<li><a class="anchor" href="#attached_node" name="attached_node">#</a><code>attached_node</code>: 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.</li>
|
||
<li><a class="anchor" href="#soil" name="soil">#</a><code>soil</code>: saplings will grow on nodes in this group</li>
|
||
<li><a class="anchor" href="#connect_to_raillike" name="connect_to_raillike">#</a><code>connect_to_raillike</code>: makes nodes of raillike drawtype with same group value
|
||
connect to each other</li>
|
||
</ul>
|
||
<h3 id="known-damage-and-digging-time-defining-groups">Known damage and digging time defining groups</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#crumbly" name="crumbly">#</a><code>crumbly</code>: dirt, sand</li>
|
||
<li><a class="anchor" href="#cracky" name="cracky">#</a><code>cracky</code>: tough but crackable stuff like stone.</li>
|
||
<li><a class="anchor" href="#snappy" name="snappy">#</a><code>snappy</code>: something that can be cut using fine tools; e.g. leaves, small
|
||
plants, wire, sheets of metal</li>
|
||
<li><a class="anchor" href="#choppy" name="choppy">#</a><code>choppy</code>: something that can be cut using force; e.g. trees, wooden planks</li>
|
||
<li><a class="anchor" href="#fleshy" name="fleshy">#</a><code>fleshy</code>: Living things like animals and the player. This could imply
|
||
some blood effects when hitting.</li>
|
||
<li><a class="anchor" href="#explody" name="explody">#</a><code>explody</code>: Especially prone to explosions</li>
|
||
<li><a class="anchor" href="#oddly_breakable_by_hand" name="oddly_breakable_by_hand">#</a><code>oddly_breakable_by_hand</code>:
|
||
Can be added to nodes that shouldn't logically be breakable by the
|
||
hand but are. Somewhat similar to <code>dig_immediate</code>, but times are more
|
||
like <code>{[1]=3.50,[2]=2.00,[3]=0.70}</code> and this does not override the
|
||
speed of a tool if the tool can dig at a faster speed than this
|
||
suggests for the hand.</li>
|
||
</ul>
|
||
<h3 id="examples-of-custom-groups">Examples of custom groups</h3>
|
||
<p>Item groups are often used for defining, well, <em>groups of items</em>.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#meat" name="meat">#</a><code>meat</code>: any meat-kind of a thing (rating might define the size or healing
|
||
ability or be irrelevant -- it is not defined as of yet)</li>
|
||
<li><a class="anchor" href="#eatable" name="eatable">#</a><code>eatable</code>: anything that can be eaten. Rating might define HP gain in half
|
||
hearts.</li>
|
||
<li><a class="anchor" href="#flammable" name="flammable">#</a><code>flammable</code>: can be set on fire. Rating might define the intensity of the
|
||
fire, affecting e.g. the speed of the spreading of an open fire.</li>
|
||
<li><a class="anchor" href="#wool" name="wool">#</a><code>wool</code>: any wool (any origin, any color)</li>
|
||
<li><a class="anchor" href="#metal" name="metal">#</a><code>metal</code>: any metal</li>
|
||
<li><a class="anchor" href="#weapon" name="weapon">#</a><code>weapon</code>: any weapon</li>
|
||
<li><a class="anchor" href="#heavy" name="heavy">#</a><code>heavy</code>: anything considerably heavy</li>
|
||
</ul>
|
||
<h3 id="digging-time-calculation-specifics">Digging time calculation specifics</h3>
|
||
<p>Groups such as <code>crumbly</code>, <code>cracky</code> and <code>snappy</code> are used for this
|
||
purpose. Rating is <code>1</code>, <code>2</code> or <code>3</code>. A higher rating for such a group implies
|
||
faster digging time.</p>
|
||
<p>The <code>level</code> group is used to limit the toughness of nodes a tool can dig
|
||
and to scale the digging times / damage to a greater extent.</p>
|
||
<p><strong>Please do understand this</strong>, otherwise you cannot use the system to it's
|
||
full potential.</p>
|
||
<p>Tools define their properties by a list of parameters for groups. They
|
||
cannot dig other groups; thus it is important to use a standard bunch of
|
||
groups to enable interaction with tools.</p>
|
||
<h4 id="tools-definition">Tools definition</h4>
|
||
<p>Tools define:</p>
|
||
<ul>
|
||
<li>Full punch interval</li>
|
||
<li>Maximum drop level</li>
|
||
<li><a class="anchor" href="#0_2" name="0_2">#</a>For an arbitrary list of groups:<ul>
|
||
<li><a class="anchor" href="#0_3" name="0_3">#</a>Uses (until the tool breaks)<ul>
|
||
<li><a class="anchor" href="#0_4" name="0_4">#</a>Maximum level (usually <code>0</code>, <code>1</code>, <code>2</code> or <code>3</code>)</li>
|
||
<li>Digging times</li>
|
||
<li>Damage groups</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h4 id="full-punch-interval">Full punch interval</h4>
|
||
<p>When used as a weapon, the tool will do full damage if this time is spent
|
||
between punches. If e.g. half the time is spent, the tool will do half
|
||
damage.</p>
|
||
<h4 id="maximum-drop-level">Maximum drop level</h4>
|
||
<p>Suggests the maximum level of node, when dug with the tool, that will drop
|
||
it's useful item. (e.g. iron ore to drop a lump of iron).</p>
|
||
<p>This is not automated; it is the responsibility of the node definition
|
||
to implement this.</p>
|
||
<h4 id="uses">Uses</h4>
|
||
<p>Determines how many uses the tool has when it is used for digging a node,
|
||
of this group, of the maximum level. For lower leveled nodes, the use count
|
||
is multiplied by <code>3^leveldiff</code>.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#uses10leveldiff0" name="uses10leveldiff0">#</a><code>uses=10, leveldiff=0</code>: actual uses: 10</li>
|
||
<li><a class="anchor" href="#uses10leveldiff1" name="uses10leveldiff1">#</a><code>uses=10, leveldiff=1</code>: actual uses: 30</li>
|
||
<li><a class="anchor" href="#uses10leveldiff2" name="uses10leveldiff2">#</a><code>uses=10, leveldiff=2</code>: actual uses: 90</li>
|
||
</ul>
|
||
<h4 id="maximum-level">Maximum level</h4>
|
||
<p>Tells what is the maximum level of a node of this group that the tool will
|
||
be able to dig.</p>
|
||
<h4 id="digging-times">Digging times</h4>
|
||
<p>List of digging times for different ratings of the group, for nodes of the
|
||
maximum level.</p>
|
||
<p>For example, as a Lua table, <code>times={2=2.00, 3=0.70}</code>. This would
|
||
result in the tool to be able to dig nodes that have a rating of <code>2</code> or <code>3</code>
|
||
for this group, and unable to dig the rating <code>1</code>, which is the toughest.
|
||
Unless there is a matching group that enables digging otherwise.</p>
|
||
<p>If the result digging time is 0, a delay of 0.15 seconds is added between
|
||
digging nodes; If the player releases LMB after digging, this delay is set to 0,
|
||
i.e. players can more quickly click the nodes away instead of holding LMB.</p>
|
||
<h4 id="damage-groups">Damage groups</h4>
|
||
<p>List of damage for groups of entities. See "Entity damage mechanism".</p>
|
||
<h4 id="example-definition-of-the-capabilities-of-a-tool">Example definition of the capabilities of a tool</h4>
|
||
<pre><code>tool_capabilities = {
|
||
full_punch_interval=1.5,
|
||
max_drop_level=1,
|
||
groupcaps={
|
||
crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
|
||
}
|
||
damage_groups = {fleshy=2},
|
||
}
|
||
</code></pre>
|
||
<p>This makes the tool be able to dig nodes that fulfil both of these:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#crumbly_1" name="crumbly_1">#</a>Have the <code>crumbly</code> group</li>
|
||
<li><a class="anchor" href="#level_1" name="level_1">#</a>Have a <code>level</code> group less or equal to <code>2</code></li>
|
||
</ul>
|
||
<p>Table of resulting digging times:</p>
|
||
<pre><code>crumbly 0 1 2 3 4 <- level
|
||
-> 0 - - - - -
|
||
1 0.80 1.60 1.60 - -
|
||
2 0.60 1.20 1.20 - -
|
||
3 0.40 0.80 0.80 - -
|
||
|
||
level diff: 2 1 0 -1 -2
|
||
</code></pre>
|
||
<p>Table of resulting tool uses:</p>
|
||
<pre><code>-> 0 - - - - -
|
||
1 180 60 20 - -
|
||
2 180 60 20 - -
|
||
3 180 60 20 - -
|
||
</code></pre>
|
||
<p><strong>Notes</strong>:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#crumbly0" name="crumbly0">#</a>At <code>crumbly==0</code>, the node is not diggable.</li>
|
||
<li><a class="anchor" href="#crumbly3" name="crumbly3">#</a>At <code>crumbly==3</code>, the level difference digging time divider kicks in and makes
|
||
easy nodes to be quickly breakable.</li>
|
||
<li><a class="anchor" href="#level2" name="level2">#</a>At <code>level > 2</code>, the node is not diggable, because it's <code>level > maxlevel</code></li>
|
||
</ul>
|
||
<h2 id="entity-damage-mechanism">Entity damage mechanism</h2>
|
||
<p>Damage calculation:</p>
|
||
<pre><code>damage = 0
|
||
foreach group in cap.damage_groups:
|
||
damage += cap.damage_groups[group] * limit(actual_interval /
|
||
cap.full_punch_interval, 0.0, 1.0)
|
||
* (object.armor_groups[group] / 100.0)
|
||
-- Where object.armor_groups[group] is 0 for inexistent values
|
||
return damage
|
||
</code></pre>
|
||
<p>Client predicts damage based on damage groups. Because of this, it is able to
|
||
give an immediate response when an entity is damaged or dies; the response is
|
||
pre-defined somehow (e.g. by defining a sprite animation) (not implemented;
|
||
TODO).
|
||
Currently a smoke puff will appear when an entity dies.</p>
|
||
<p>The group <code>immortal</code> completely disables normal damage.</p>
|
||
<p>Entities can define a special armor group, which is <code>punch_operable</code>. This
|
||
group disables the regular damage mechanism for players punching it by hand or
|
||
a non-tool item, so that it can do something else than take damage.</p>
|
||
<p>On the Lua side, every punch calls:</p>
|
||
<pre><code>entity:on_punch(puncher, time_from_last_punch, tool_capabilities, direction, damage)
|
||
</code></pre>
|
||
<p>This should never be called directly, because damage is usually not handled by
|
||
the entity itself.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#puncher" name="puncher">#</a><code>puncher</code> is the object performing the punch. Can be <code>nil</code>. Should never be
|
||
accessed unless absolutely required, to encourage interoperability.</li>
|
||
<li><a class="anchor" href="#time_from_last_punch" name="time_from_last_punch">#</a><code>time_from_last_punch</code> is time from last punch (by <code>puncher</code>) or <code>nil</code>.</li>
|
||
<li><a class="anchor" href="#tool_capabilities" name="tool_capabilities">#</a><code>tool_capabilities</code> can be <code>nil</code>.</li>
|
||
<li><a class="anchor" href="#direction_2" name="direction_2">#</a><code>direction</code> is a unit vector, pointing from the source of the punch to
|
||
the punched object.</li>
|
||
<li><a class="anchor" href="#damage" name="damage">#</a><code>damage</code> damage that will be done to entity
|
||
Return value of this function will determin if damage is done by this function
|
||
(retval true) or shall be done by engine (retval false)</li>
|
||
</ul>
|
||
<p>To punch an entity/object in Lua, call:</p>
|
||
<pre><code>object:punch(puncher, time_from_last_punch, tool_capabilities, direction)
|
||
</code></pre>
|
||
<ul>
|
||
<li>Return value is tool wear.</li>
|
||
<li>Parameters are equal to the above callback.</li>
|
||
<li><a class="anchor" href="#direction_3" name="direction_3">#</a>If <code>direction</code> equals <code>nil</code> and <code>puncher</code> does not equal <code>nil</code>,
|
||
<code>direction</code> will be automatically filled in based on the location of <code>puncher</code>.</li>
|
||
</ul>
|
||
<h2 id="node-metadata">Node Metadata</h2>
|
||
<p>The instance of a node in the world normally only contains the three values
|
||
mentioned in "Nodes". However, it is possible to insert extra data into a
|
||
node. It is called "node metadata"; See <code>NodeMetaRef</code>.</p>
|
||
<p>Node metadata contains two things:</p>
|
||
<ul>
|
||
<li>A key-value store</li>
|
||
<li>An inventory</li>
|
||
</ul>
|
||
<p>Some of the values in the key-value store are handled specially:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#formspec_2" name="formspec_2">#</a><code>formspec</code>: Defines a right-click inventory menu. See "Formspec".</li>
|
||
<li><a class="anchor" href="#infotext" name="infotext">#</a><code>infotext</code>: Text shown on the screen when the node is pointed at</li>
|
||
</ul>
|
||
<p>Example stuff:</p>
|
||
<pre><code>local meta = minetest.get_meta(pos)
|
||
meta:set_string("formspec",
|
||
"size[8,9]"..
|
||
"list[context;main;0,0;8,4;]"..
|
||
"list[current_player;main;0,5;8,4;]")
|
||
meta:set_string("infotext", "Chest");
|
||
local inv = meta:get_inventory()
|
||
inv:set_size("main", 8*4)
|
||
print(dump(meta:to_table()))
|
||
meta:from_table({
|
||
inventory = {
|
||
main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "",
|
||
[5] = "", [6] = "", [7] = "", [8] = "", [9] = "",
|
||
[10] = "", [11] = "", [12] = "", [13] = "",
|
||
[14] = "default:cobble", [15] = "", [16] = "", [17] = "",
|
||
[18] = "", [19] = "", [20] = "default:cobble", [21] = "",
|
||
[22] = "", [23] = "", [24] = "", [25] = "", [26] = "",
|
||
[27] = "", [28] = "", [29] = "", [30] = "", [31] = "",
|
||
[32] = ""}
|
||
},
|
||
fields = {
|
||
formspec = "size[8,9]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
|
||
infotext = "Chest"
|
||
}
|
||
})
|
||
</code></pre>
|
||
<h2 id="item-metadata">Item Metadata</h2>
|
||
<p>Item stacks can store metadata too. See <code>ItemStackMetaRef</code>.</p>
|
||
<p>Item metadata only contains a key-value store.</p>
|
||
<p>Some of the values in the key-value store are handled specially:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#description" name="description">#</a><code>description</code>: Set the item stack's description. Defaults to <code>idef.description</code></li>
|
||
<li><a class="anchor" href="#color" name="color">#</a><code>color</code>: A <code>ColorString</code>, which sets the stack's color.</li>
|
||
<li><a class="anchor" href="#palette_index" name="palette_index">#</a><code>palette_index</code>: If the item has a palette, this is used to get the
|
||
current color from the palette.</li>
|
||
</ul>
|
||
<p>Example stuff:</p>
|
||
<pre><code>local meta = stack:get_meta()
|
||
meta:set_string("key", "value")
|
||
print(dump(meta:to_table()))
|
||
</code></pre>
|
||
<h2 id="formspec">Formspec</h2>
|
||
<p>Formspec defines a menu. Currently not much else than inventories are
|
||
supported. It is a string, with a somewhat strange format.</p>
|
||
<p>Spaces and newlines can be inserted between the blocks, as is used in the
|
||
examples.</p>
|
||
<h3 id="examples">Examples</h3>
|
||
<h4 id="chest">Chest</h4>
|
||
<pre><code>size[8,9]
|
||
list[context;main;0,0;8,4;]
|
||
list[current_player;main;0,5;8,4;]
|
||
</code></pre>
|
||
<h4 id="furnace">Furnace</h4>
|
||
<pre><code>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;]
|
||
</code></pre>
|
||
<h4 id="minecraft-like-player-inventory">Minecraft-like player inventory</h4>
|
||
<pre><code>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;]
|
||
</code></pre>
|
||
<h3 id="elements">Elements</h3>
|
||
<h4 id="sizewhfixed_size"><code>size[<W>,<H>,<fixed_size>]</code></h4>
|
||
<ul>
|
||
<li>Define the size of the menu in inventory slots</li>
|
||
<li><a class="anchor" href="#fixed_size" name="fixed_size">#</a><code>fixed_size</code>: <code>true</code>/<code>false</code> (optional)</li>
|
||
<li><a class="anchor" href="#invsizeWH" name="invsizeWH">#</a>deprecated: <code>invsize[<W>,<H>;]</code></li>
|
||
</ul>
|
||
<h4 id="positionxy"><code>position[<X>,<Y>]</code></h4>
|
||
<ul>
|
||
<li>Define the position of the formspec</li>
|
||
<li>A value between 0.0 and 1.0 represents a position inside the screen</li>
|
||
<li>The default value is the center of the screen (0.5, 0.5)</li>
|
||
</ul>
|
||
<h4 id="anchorxy"><code>anchor[<X>,<Y>]</code></h4>
|
||
<ul>
|
||
<li>Define the anchor of the formspec</li>
|
||
<li>A value between 0.0 and 1.0 represents an anchor inside the formspec</li>
|
||
<li>The default value is the center of the formspec (0.5, 0.5)</li>
|
||
</ul>
|
||
<h4 id="containerxy"><code>container[<X>,<Y>]</code></h4>
|
||
<ul>
|
||
<li>Start of a container block, moves all physical elements in the container by (X, Y)</li>
|
||
<li><a class="anchor" href="#container_end_1" name="container_end_1">#</a>Must have matching <code>container_end</code></li>
|
||
<li>Containers can be nested, in which case the offsets are added
|
||
(child containers are relative to parent containers)</li>
|
||
</ul>
|
||
<h4 id="container_end"><code>container_end[]</code></h4>
|
||
<ul>
|
||
<li>End of a container, following elements are no longer relative to this container</li>
|
||
</ul>
|
||
<h4 id="listinventory-locationlist-namexywh"><code>list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]</code></h4>
|
||
<ul>
|
||
<li>Show an inventory list</li>
|
||
</ul>
|
||
<h4 id="listinventory-locationlist-namexywhstarting-item-index"><code>list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]</code></h4>
|
||
<ul>
|
||
<li>Show an inventory list</li>
|
||
</ul>
|
||
<h4 id="listringinventory-locationlist-name"><code>listring[<inventory location>;<list name>]</code></h4>
|
||
<ul>
|
||
<li>Allows to create a ring of inventory lists</li>
|
||
<li>Shift-clicking on items in one element of the ring
|
||
will send them to the next inventory list inside the ring</li>
|
||
<li>The first occurrence of an element inside the ring will
|
||
determine the inventory where items will be sent to</li>
|
||
</ul>
|
||
<h4 id="listring"><code>listring[]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#listringinventorylocationlistname" name="listringinventorylocationlistname">#</a>Shorthand for doing <code>listring[<inventory location>;<list name>]</code>
|
||
for the last two inventory lists added by list[...]</li>
|
||
</ul>
|
||
<h4 id="listcolorsslot_bg_normalslot_bg_hover"><code>listcolors[<slot_bg_normal>;<slot_bg_hover>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#ColorString" name="ColorString">#</a>Sets background color of slots as <code>ColorString</code></li>
|
||
<li>Sets background color of slots on mouse hovering</li>
|
||
</ul>
|
||
<h4 id="listcolorsslot_bg_normalslot_bg_hoverslot_border"><code>listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#ColorString_1" name="ColorString_1">#</a>Sets background color of slots as <code>ColorString</code></li>
|
||
<li>Sets background color of slots on mouse hovering</li>
|
||
<li>Sets color of slots border</li>
|
||
</ul>
|
||
<h4 id="listcolorsslot_bg_normalslot_bg_hoverslot_bordertooltip_bgcolortooltip_fontcolor"><code>listcolors[<slot_bg_normal>;<slot_bg_hover>;<slot_border>;<tooltip_bgcolor>;<tooltip_fontcolor>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#ColorString_2" name="ColorString_2">#</a>Sets background color of slots as <code>ColorString</code></li>
|
||
<li>Sets background color of slots on mouse hovering</li>
|
||
<li>Sets color of slots border</li>
|
||
<li>Sets default background color of tooltips</li>
|
||
<li>Sets default font color of tooltips</li>
|
||
</ul>
|
||
<h4 id="tooltipgui_element_nametooltip_textbgcolorfontcolor"><code>tooltip[<gui_element_name>;<tooltip_text>;<bgcolor>;<fontcolor>]</code></h4>
|
||
<ul>
|
||
<li>Adds tooltip for an element</li>
|
||
<li><a class="anchor" href="#bgcolor" name="bgcolor">#</a><code><bgcolor></code> tooltip background color as <code>ColorString</code> (optional)</li>
|
||
<li><a class="anchor" href="#fontcolor" name="fontcolor">#</a><code><fontcolor></code> tooltip font color as <code>ColorString</code> (optional)</li>
|
||
</ul>
|
||
<h4 id="imagexywhtexture-name"><code>image[<X>,<Y>;<W>,<H>;<texture name>]</code></h4>
|
||
<ul>
|
||
<li>Show an image</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
</ul>
|
||
<h4 id="item_imagexywhitem-name"><code>item_image[<X>,<Y>;<W>,<H>;<item name>]</code></h4>
|
||
<ul>
|
||
<li>Show an inventory image of registered item/node</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
</ul>
|
||
<h4 id="bgcolorcolorfullscreen"><code>bgcolor[<color>;<fullscreen>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#ColorString_3" name="ColorString_3">#</a>Sets background color of formspec as <code>ColorString</code></li>
|
||
<li><a class="anchor" href="#true" name="true">#</a>If <code>true</code>, the background color is drawn fullscreen (does not effect the size of the formspec)</li>
|
||
</ul>
|
||
<h4 id="backgroundxywhtexture-name"><code>background[<X>,<Y>;<W>,<H>;<texture name>]</code></h4>
|
||
<ul>
|
||
<li>Use a background. Inventory rectangles are not drawn then.</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
<li>Example for formspec 8x4 in 16x resolution: image shall be sized
|
||
8 times 16px times 4 times 16px.</li>
|
||
</ul>
|
||
<h4 id="backgroundxywhtexture-nameauto_clip"><code>background[<X>,<Y>;<W>,<H>;<texture name>;<auto_clip>]</code></h4>
|
||
<ul>
|
||
<li>Use a background. Inventory rectangles are not drawn then.</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
<li>Example for formspec 8x4 in 16x resolution:
|
||
image shall be sized 8 times 16px times 4 times 16px</li>
|
||
<li><a class="anchor" href="#true_1" name="true_1">#</a>If <code>true</code> the background is clipped to formspec size
|
||
(<code>x</code> and <code>y</code> are used as offset values, <code>w</code> and <code>h</code> are ignored)</li>
|
||
</ul>
|
||
<h4 id="pwdfieldxywhnamelabel"><code>pwdfield[<X>,<Y>;<W>,<H>;<name>;<label>]</code></h4>
|
||
<ul>
|
||
<li>Textual password style field; will be sent to server when a button is clicked</li>
|
||
<li>When enter is pressed in field, fields.key_enter_field will be sent with the name
|
||
of this field.</li>
|
||
<li><a class="anchor" href="#x_1" name="x_1">#</a><code>x</code> and <code>y</code> position the field relative to the top left of the menu</li>
|
||
<li><a class="anchor" href="#w_1" name="w_1">#</a><code>w</code> and <code>h</code> are the size of the field</li>
|
||
<li><a class="anchor" href="#h_1" name="h_1">#</a>Fields are a set height, but will be vertically centred on <code>h</code></li>
|
||
<li>Position and size units are inventory slots</li>
|
||
<li><a class="anchor" href="#name_3" name="name_3">#</a><code>name</code> is the name of the field as returned in fields to <code>on_receive_fields</code></li>
|
||
<li><a class="anchor" href="#label" name="label">#</a><code>label</code>, if not blank, will be text printed on the top left above the field</li>
|
||
<li>See field_close_on_enter to stop enter closing the formspec</li>
|
||
</ul>
|
||
<h4 id="fieldxywhnamelabeldefault"><code>field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]</code></h4>
|
||
<ul>
|
||
<li>Textual field; will be sent to server when a button is clicked</li>
|
||
<li><a class="anchor" href="#fieldskey_enter_field" name="fieldskey_enter_field">#</a>When enter is pressed in field, <code>fields.key_enter_field</code> will be sent with the name
|
||
of this field.</li>
|
||
<li><a class="anchor" href="#x_2" name="x_2">#</a><code>x</code> and <code>y</code> position the field relative to the top left of the menu</li>
|
||
<li><a class="anchor" href="#w_2" name="w_2">#</a><code>w</code> and <code>h</code> are the size of the field</li>
|
||
<li><a class="anchor" href="#h_2" name="h_2">#</a>Fields are a set height, but will be vertically centred on <code>h</code></li>
|
||
<li>Position and size units are inventory slots</li>
|
||
<li><a class="anchor" href="#name_4" name="name_4">#</a><code>name</code> is the name of the field as returned in fields to <code>on_receive_fields</code></li>
|
||
<li><a class="anchor" href="#label_1" name="label_1">#</a><code>label</code>, if not blank, will be text printed on the top left above the field</li>
|
||
<li><a class="anchor" href="#default" name="default">#</a><code>default</code> is the default value of the field<ul>
|
||
<li><a class="anchor" href="#default_1" name="default_1">#</a><code>default</code> may contain variable references such as <code>${text}'</code> which
|
||
will fill the value from the metadata value <code>text</code></li>
|
||
<li><strong>Note</strong>: no extra text or more than a single variable is supported ATM.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#field_close_on_enter" name="field_close_on_enter">#</a>See <code>field_close_on_enter</code> to stop enter closing the formspec</li>
|
||
</ul>
|
||
<h4 id="fieldnamelabeldefault"><code>field[<name>;<label>;<default>]</code></h4>
|
||
<ul>
|
||
<li>As above, but without position/size units</li>
|
||
<li><a class="anchor" href="#fieldskey_enter_field_1" name="fieldskey_enter_field_1">#</a>When enter is pressed in field, <code>fields.key_enter_field</code> will be sent with the name
|
||
of this field.</li>
|
||
<li>Special field for creating simple forms, such as sign text input</li>
|
||
<li><a class="anchor" href="#size_2" name="size_2">#</a>Must be used without a <code>size[]</code> element</li>
|
||
<li>A "Proceed" button will be added automatically</li>
|
||
<li><a class="anchor" href="#field_close_on_enter_1" name="field_close_on_enter_1">#</a>See <code>field_close_on_enter</code> to stop enter closing the formspec</li>
|
||
</ul>
|
||
<h4 id="field_close_on_enternameclose_on_enter"><code>field_close_on_enter[<name>;<close_on_enter>]</code></h4>
|
||
<ul>
|
||
<li><name> is the name of the field</name></li>
|
||
<li>if <close_on_enter> is false, pressing enter in the field will submit the form but not close it</close_on_enter></li>
|
||
<li>defaults to true when not specified (ie: no tag for a field)</li>
|
||
</ul>
|
||
<h4 id="textareaxywhnamelabeldefault"><code>textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]</code></h4>
|
||
<ul>
|
||
<li>Same as fields above, but with multi-line input</li>
|
||
</ul>
|
||
<h4 id="labelxylabel"><code>label[<X>,<Y>;<label>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#x_3" name="x_3">#</a><code>x</code> and <code>y</code> work as per field</li>
|
||
<li><a class="anchor" href="#label_2" name="label_2">#</a><code>label</code> is the text on the label</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
</ul>
|
||
<h4 id="vertlabelxylabel"><code>vertlabel[<X>,<Y>;<label>]</code></h4>
|
||
<ul>
|
||
<li>Textual label drawn vertically</li>
|
||
<li><a class="anchor" href="#x_4" name="x_4">#</a><code>x</code> and <code>y</code> work as per field</li>
|
||
<li><a class="anchor" href="#label_3" name="label_3">#</a><code>label</code> is the text on the label</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
</ul>
|
||
<h4 id="buttonxywhnamelabel"><code>button[<X>,<Y>;<W>,<H>;<name>;<label>]</code></h4>
|
||
<ul>
|
||
<li>Clickable button. When clicked, fields will be sent.</li>
|
||
<li><a class="anchor" href="#x_5" name="x_5">#</a><code>x</code>, <code>y</code> and <code>name</code> work as per field</li>
|
||
<li><a class="anchor" href="#w_3" name="w_3">#</a><code>w</code> and <code>h</code> are the size of the button</li>
|
||
<li><a class="anchor" href="#h_3" name="h_3">#</a>Fixed button height. It will be vertically centred on <code>h</code></li>
|
||
<li><a class="anchor" href="#label_4" name="label_4">#</a><code>label</code> is the text on the button</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
</ul>
|
||
<h4 id="image_buttonxywhtexture-namenamelabel"><code>image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#x_6" name="x_6">#</a><code>x</code>, <code>y</code>, <code>w</code>, <code>h</code>, and <code>name</code> work as per button</li>
|
||
<li><a class="anchor" href="#texturename" name="texturename">#</a><code>texture name</code> is the filename of an image</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
</ul>
|
||
<h4 id="image_buttonxywhtexture-namenamelabelnoclipdrawborderpressed-texture-name"><code>image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>;<noclip>;<drawborder>;<pressed texture name>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#x_7" name="x_7">#</a><code>x</code>, <code>y</code>, <code>w</code>, <code>h</code>, and <code>name</code> work as per button</li>
|
||
<li><a class="anchor" href="#texturename_1" name="texturename_1">#</a><code>texture name</code> is the filename of an image</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
<li><a class="anchor" href="#nocliptrue" name="nocliptrue">#</a><code>noclip=true</code> means the image button doesn't need to be within specified formsize</li>
|
||
<li><a class="anchor" href="#drawborder" name="drawborder">#</a><code>drawborder</code>: draw button border or not</li>
|
||
<li><a class="anchor" href="#pressedtexturename" name="pressedtexturename">#</a><code>pressed texture name</code> is the filename of an image on pressed state</li>
|
||
</ul>
|
||
<h4 id="item_image_buttonxywhitem-namenamelabel"><code>item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#x_8" name="x_8">#</a><code>x</code>, <code>y</code>, <code>w</code>, <code>h</code>, <code>name</code> and <code>label</code> work as per button</li>
|
||
<li><a class="anchor" href="#itemname" name="itemname">#</a><code>item name</code> is the registered name of an item/node,
|
||
tooltip will be made out of its description
|
||
to override it use tooltip element</li>
|
||
<li>Position and size units are inventory slots</li>
|
||
</ul>
|
||
<h4 id="button_exitxywhnamelabel"><code>button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]</code></h4>
|
||
<ul>
|
||
<li>When clicked, fields will be sent and the form will quit.</li>
|
||
</ul>
|
||
<h4 id="image_button_exitxywhtexture-namenamelabel"><code>image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]</code></h4>
|
||
<ul>
|
||
<li>When clicked, fields will be sent and the form will quit.</li>
|
||
</ul>
|
||
<h4 id="textlistxywhnamelistelem-1listelem-2listelem-n"><code>textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>]</code></h4>
|
||
<ul>
|
||
<li>Scrollable item list showing arbitrary text elements</li>
|
||
<li><a class="anchor" href="#x_9" name="x_9">#</a><code>x</code> and <code>y</code> position the itemlist relative to the top left of the menu</li>
|
||
<li><a class="anchor" href="#w_4" name="w_4">#</a><code>w</code> and <code>h</code> are the size of the itemlist</li>
|
||
<li><a class="anchor" href="#name_5" name="name_5">#</a><code>name</code> fieldname sent to server on doubleclick value is current selected element</li>
|
||
<li><a class="anchor" href="#listelements" name="listelements">#</a><code>listelements</code> can be prepended by #color in hexadecimal format RRGGBB (only),<ul>
|
||
<li>if you want a listelement to start with "#" write "##".</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h4 id="textlistxywhnamelistelem-1listelem-2listelem-nselected-idxtransparent"><code>textlist[<X>,<Y>;<W>,<H>;<name>;<listelem 1>,<listelem 2>,...,<listelem n>;<selected idx>;<transparent>]</code></h4>
|
||
<ul>
|
||
<li>Scrollable itemlist showing arbitrary text elements</li>
|
||
<li><a class="anchor" href="#x_10" name="x_10">#</a><code>x</code> and <code>y</code> position the item list relative to the top left of the menu</li>
|
||
<li><a class="anchor" href="#w_5" name="w_5">#</a><code>w</code> and <code>h</code> are the size of the item list</li>
|
||
<li><a class="anchor" href="#name_6" name="name_6">#</a><code>name</code> fieldname sent to server on doubleclick value is current selected element</li>
|
||
<li><a class="anchor" href="#listelements_1" name="listelements_1">#</a><code>listelements</code> can be prepended by #RRGGBB (only) in hexadecimal format<ul>
|
||
<li>if you want a listelement to start with "#" write "##"</li>
|
||
</ul>
|
||
</li>
|
||
<li>Index to be selected within textlist</li>
|
||
<li><a class="anchor" href="#true_2" name="true_2">#</a><code>true</code>/<code>false</code>: draw transparent background</li>
|
||
<li><a class="anchor" href="#minetestexplode_textlist_event" name="minetestexplode_textlist_event">#</a>See also <code>minetest.explode_textlist_event</code> (main menu: <code>engine.explode_textlist_event</code>)</li>
|
||
</ul>
|
||
<h4 id="tabheaderxynamecaption-1caption-2caption-ncurrent_tabtransparentdraw_border"><code>tabheader[<X>,<Y>;<name>;<caption 1>,<caption 2>,...,<caption n>;<current_tab>;<transparent>;<draw_border>]</code></h4>
|
||
<ul>
|
||
<li>Show a tab<strong>header</strong> at specific position (ignores formsize)</li>
|
||
<li><a class="anchor" href="#x_11" name="x_11">#</a><code>x</code> and <code>y</code> position the itemlist relative to the top left of the menu</li>
|
||
<li><a class="anchor" href="#name_7" name="name_7">#</a><code>name</code> fieldname data is transferred to Lua</li>
|
||
<li><a class="anchor" href="#caption1" name="caption1">#</a><code>caption 1</code>...: name shown on top of tab</li>
|
||
<li><a class="anchor" href="#current_tab" name="current_tab">#</a><code>current_tab</code>: index of selected tab 1...</li>
|
||
<li><a class="anchor" href="#transparent" name="transparent">#</a><code>transparent</code> (optional): show transparent</li>
|
||
<li><a class="anchor" href="#draw_border" name="draw_border">#</a><code>draw_border</code> (optional): draw border</li>
|
||
</ul>
|
||
<h4 id="boxxywhcolor"><code>box[<X>,<Y>;<W>,<H>;<color>]</code></h4>
|
||
<ul>
|
||
<li>Simple colored semitransparent box</li>
|
||
<li><a class="anchor" href="#x_12" name="x_12">#</a><code>x</code> and <code>y</code> position the box relative to the top left of the menu</li>
|
||
<li><a class="anchor" href="#w_6" name="w_6">#</a><code>w</code> and <code>h</code> are the size of box</li>
|
||
<li><a class="anchor" href="#color_1" name="color_1">#</a><code>color</code> is color specified as a <code>ColorString</code></li>
|
||
</ul>
|
||
<h4 id="dropdownxywnameitem-1item-2-item-nselected-idx"><code>dropdown[<X>,<Y>;<W>;<name>;<item 1>,<item 2>, ...,<item n>;<selected idx>]</code></h4>
|
||
<ul>
|
||
<li>Show a dropdown field</li>
|
||
<li><strong>Important note</strong>: There are two different operation modes:<ol>
|
||
<li>handle directly on change (only changed dropdown is submitted)</li>
|
||
<li>read the value on pressing a button (all dropdown values are available)</li>
|
||
</ol>
|
||
</li>
|
||
<li><a class="anchor" href="#x_13" name="x_13">#</a><code>x</code> and <code>y</code> position of dropdown</li>
|
||
<li>Width of dropdown</li>
|
||
<li>Fieldname data is transferred to Lua</li>
|
||
<li>Items to be shown in dropdown</li>
|
||
<li>Index of currently selected dropdown item</li>
|
||
</ul>
|
||
<h4 id="checkboxxynamelabelselected"><code>checkbox[<X>,<Y>;<name>;<label>;<selected>]</code></h4>
|
||
<ul>
|
||
<li>Show a checkbox</li>
|
||
<li><a class="anchor" href="#x_14" name="x_14">#</a><code>x</code> and <code>y</code>: position of checkbox</li>
|
||
<li><a class="anchor" href="#name_8" name="name_8">#</a><code>name</code> fieldname data is transferred to Lua</li>
|
||
<li><a class="anchor" href="#label_5" name="label_5">#</a><code>label</code> to be shown left of checkbox</li>
|
||
<li><a class="anchor" href="#selected" name="selected">#</a><code>selected</code> (optional): <code>true</code>/<code>false</code></li>
|
||
</ul>
|
||
<h4 id="scrollbarxywhorientationnamevalue"><code>scrollbar[<X>,<Y>;<W>,<H>;<orientation>;<name>;<value>]</code></h4>
|
||
<ul>
|
||
<li>Show a scrollbar</li>
|
||
<li>There are two ways to use it:<ol>
|
||
<li>handle the changed event (only changed scrollbar is available)</li>
|
||
<li>read the value on pressing a button (all scrollbars are available)</li>
|
||
</ol>
|
||
</li>
|
||
<li><a class="anchor" href="#x_15" name="x_15">#</a><code>x</code> and <code>y</code>: position of trackbar</li>
|
||
<li><a class="anchor" href="#w_7" name="w_7">#</a><code>w</code> and <code>h</code>: width and height</li>
|
||
<li><a class="anchor" href="#orientation" name="orientation">#</a><code>orientation</code>: <code>vertical</code>/<code>horizontal</code></li>
|
||
<li>Fieldname data is transferred to Lua</li>
|
||
<li><a class="anchor" href="#0_5" name="0_5">#</a>Value this trackbar is set to (<code>0</code>-<code>1000</code>)</li>
|
||
<li><a class="anchor" href="#minetestexplode_scrollbar_event" name="minetestexplode_scrollbar_event">#</a>See also <code>minetest.explode_scrollbar_event</code> (main menu: <code>engine.explode_scrollbar_event</code>)</li>
|
||
</ul>
|
||
<h4 id="tablexywhnamecell-1cell-2cell-nselected-idx"><code>table[<X>,<Y>;<W>,<H>;<name>;<cell 1>,<cell 2>,...,<cell n>;<selected idx>]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#tableoptions" name="tableoptions">#</a>Show scrollable table using options defined by the previous <code>tableoptions[]</code></li>
|
||
<li><a class="anchor" href="#tablecolumns" name="tablecolumns">#</a>Displays cells as defined by the previous <code>tablecolumns[]</code></li>
|
||
<li><a class="anchor" href="#x_16" name="x_16">#</a><code>x</code> and <code>y</code>: position the itemlist relative to the top left of the menu</li>
|
||
<li><a class="anchor" href="#w_8" name="w_8">#</a><code>w</code> and <code>h</code> are the size of the itemlist</li>
|
||
<li><a class="anchor" href="#name_9" name="name_9">#</a><code>name</code>: fieldname sent to server on row select or doubleclick</li>
|
||
<li><a class="anchor" href="#cell1" name="cell1">#</a><code>cell 1</code>...<code>cell n</code>: cell contents given in row-major order</li>
|
||
<li><a class="anchor" href="#selectedidx" name="selectedidx">#</a><code>selected idx</code>: index of row to be selected within table (first row = <code>1</code>)</li>
|
||
<li><a class="anchor" href="#minetestexplode_table_event" name="minetestexplode_table_event">#</a>See also <code>minetest.explode_table_event</code> (main menu: <code>engine.explode_table_event</code>)</li>
|
||
</ul>
|
||
<h4 id="tableoptionsopt-1opt-2"><code>tableoptions[<opt 1>;<opt 2>;...]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#table" name="table">#</a>Sets options for <code>table[]</code></li>
|
||
<li><a class="anchor" href="#colorRRGGBB" name="colorRRGGBB">#</a><code>color=#RRGGBB</code><ul>
|
||
<li><a class="anchor" href="#ColorString_4" name="ColorString_4">#</a>default text color (<code>ColorString</code>), defaults to <code>#FFFFFF</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#backgroundRRGGBB" name="backgroundRRGGBB">#</a><code>background=#RRGGBB</code><ul>
|
||
<li><a class="anchor" href="#ColorString_5" name="ColorString_5">#</a>table background color (<code>ColorString</code>), defaults to <code>#000000</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#bordertruefalse" name="bordertruefalse">#</a><code>border=<true/false></code><ul>
|
||
<li><a class="anchor" href="#true_3" name="true_3">#</a>should the table be drawn with a border? (default: <code>true</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#highlightRRGGBB" name="highlightRRGGBB">#</a><code>highlight=#RRGGBB</code><ul>
|
||
<li><a class="anchor" href="#ColorString_6" name="ColorString_6">#</a>highlight background color (<code>ColorString</code>), defaults to <code>#466432</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#highlight_textRRGGBB" name="highlight_textRRGGBB">#</a><code>highlight_text=#RRGGBB</code><ul>
|
||
<li><a class="anchor" href="#ColorString_7" name="ColorString_7">#</a>highlight text color (<code>ColorString</code>), defaults to <code>#FFFFFF</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#opendepthvalue" name="opendepthvalue">#</a><code>opendepth=<value></code><ul>
|
||
<li><a class="anchor" href="#depthvalue" name="depthvalue">#</a>all subtrees up to <code>depth < value</code> are open (default value = <code>0</code>)</li>
|
||
<li>only useful when there is a column of type "tree"</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h4 id="tablecolumnstype-1opt-1aopt-1btype-2opt-2aopt-2b"><code>tablecolumns[<type 1>,<opt 1a>,<opt 1b>,...;<type 2>,<opt 2a>,<opt 2b>;...]</code></h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#table_1" name="table_1">#</a>Sets columns for <code>table[]</code></li>
|
||
<li><a class="anchor" href="#text_6" name="text_6">#</a>Types: <code>text</code>, <code>image</code>, <code>color</code>, <code>indent</code>, <code>tree</code><ul>
|
||
<li><a class="anchor" href="#text_7" name="text_7">#</a><code>text</code>: show cell contents as text</li>
|
||
<li><a class="anchor" href="#image_1" name="image_1">#</a><code>image</code>: cell contents are an image index, use column options to define images</li>
|
||
<li><a class="anchor" href="#color_2" name="color_2">#</a><code>color</code>: cell contents are a ColorString and define color of following cell</li>
|
||
<li><a class="anchor" href="#indent" name="indent">#</a><code>indent</code>: cell contents are a number and define indentation of following cell</li>
|
||
<li><a class="anchor" href="#tree" name="tree">#</a><code>tree</code>: same as indent, but user can open and close subtrees (treeview-like)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#alignvalue" name="alignvalue">#</a>Column options:<ul>
|
||
<li><a class="anchor" href="#alignvalue_1" name="alignvalue_1">#</a><code>align=<value></code><ul>
|
||
<li><a class="anchor" href="#text_8" name="text_8">#</a>for <code>text</code> and <code>image</code>: content alignment within cells.
|
||
Available values: <code>left</code> (default), <code>center</code>, <code>right</code>, <code>inline</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#widthvalue" name="widthvalue">#</a><code>width=<value></code><ul>
|
||
<li><a class="anchor" href="#text_9" name="text_9">#</a>for <code>text</code> and <code>image</code>: minimum width in em (default: <code>0</code>)</li>
|
||
<li><a class="anchor" href="#indent_1" name="indent_1">#</a>for <code>indent</code> and <code>tree</code>: indent width in em (default: <code>1.5</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#paddingvalue" name="paddingvalue">#</a><code>padding=<value></code>: padding left of the column, in em (default <code>0.5</code>).
|
||
Exception: defaults to 0 for indent columns</li>
|
||
<li><a class="anchor" href="#tooltipvalue" name="tooltipvalue">#</a><code>tooltip=<value></code>: tooltip text (default: empty)</li>
|
||
<li><a class="anchor" href="#image_2" name="image_2">#</a><code>image</code> column options:<ul>
|
||
<li><a class="anchor" href="#0value" name="0value">#</a><code>0=<value></code> sets image for image index 0</li>
|
||
<li><a class="anchor" href="#1value" name="1value">#</a><code>1=<value></code> sets image for image index 1</li>
|
||
<li><a class="anchor" href="#2value" name="2value">#</a><code>2=<value></code> sets image for image index 2</li>
|
||
<li><a class="anchor" href="#0_6" name="0_6">#</a>and so on; defined indices need not be contiguous empty or
|
||
non-numeric cells are treated as <code>0</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#color_3" name="color_3">#</a><code>color</code> column options:<ul>
|
||
<li><a class="anchor" href="#spanvalue" name="spanvalue">#</a><code>span=<value></code>: number of following columns to affect (default: infinite)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<p><strong>Note</strong>: do <em>not</em> use a element name starting with <code>key_</code>; those names are reserved to
|
||
pass key press events to formspec!</p>
|
||
<h2 id="inventory-locations">Inventory locations</h2>
|
||
<ul>
|
||
<li><a class="anchor" href="#context" name="context">#</a><code>"context"</code>: Selected node metadata (deprecated: <code>"current_name"</code>)</li>
|
||
<li><a class="anchor" href="#current_player" name="current_player">#</a><code>"current_player"</code>: Player to whom the menu is shown</li>
|
||
<li><a class="anchor" href="#playername" name="playername">#</a><code>"player:<name>"</code>: Any player</li>
|
||
<li><a class="anchor" href="#nodemetaXYZ" name="nodemetaXYZ">#</a><code>"nodemeta:<X>,<Y>,<Z>"</code>: Any node metadata</li>
|
||
<li><a class="anchor" href="#detachedname" name="detachedname">#</a><code>"detached:<name>"</code>: A detached inventory</li>
|
||
</ul>
|
||
<h2 id="player-inventory-lists">Player Inventory lists</h2>
|
||
<ul>
|
||
<li><a class="anchor" href="#main" name="main">#</a><code>main</code>: list containing the default inventory</li>
|
||
<li><a class="anchor" href="#craft" name="craft">#</a><code>craft</code>: list containing the craft input</li>
|
||
<li><a class="anchor" href="#craftpreview" name="craftpreview">#</a><code>craftpreview</code>: list containing the craft output</li>
|
||
<li><a class="anchor" href="#hand" name="hand">#</a><code>hand</code>: list containing an override for the empty hand</li>
|
||
</ul>
|
||
<h2 id="colorstring"><code>ColorString</code></h2>
|
||
<p><code>#RGB</code> defines a color in hexadecimal format.</p>
|
||
<p><code>#RGBA</code> defines a color in hexadecimal format and alpha channel.</p>
|
||
<p><code>#RRGGBB</code> defines a color in hexadecimal format.</p>
|
||
<p><code>#RRGGBBAA</code> defines a color in hexadecimal format and alpha channel.</p>
|
||
<p>Named colors are also supported and are equivalent to
|
||
<a href="http://dev.w3.org/csswg/css-color/#named-colors">CSS Color Module Level 4</a>.
|
||
To specify the value of the alpha channel, append <code>#AA</code> to the end of the color name
|
||
(e.g. <code>colorname#08</code>). For named colors the hexadecimal string representing the alpha
|
||
value must (always) be two hexadecimal digits.</p>
|
||
<h2 id="colorspec"><code>ColorSpec</code></h2>
|
||
<p>A ColorSpec specifies a 32-bit color. It can be written in either:
|
||
table form, each element ranging from 0..255 (a, if absent, defaults to 255):
|
||
<code>colorspec = {a=255, r=0, g=255, b=0}</code>
|
||
numerical form, the raw integer value of an ARGB8 quad:
|
||
<code>colorspec = 0xFF00FF00</code>
|
||
or string form, a ColorString (defined above):
|
||
<code>colorspec = "green"</code></p>
|
||
<h2 id="escape-sequences">Escape sequences</h2>
|
||
<p>Most text can contain escape sequences, that can for example color the text.
|
||
There are a few exceptions: tab headers, dropdowns and vertical labels can't.
|
||
The following functions provide escape sequences:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestget_color_escape_sequencecolor" name="minetestget_color_escape_sequencecolor">#</a><code>minetest.get_color_escape_sequence(color)</code>:<ul>
|
||
<li><a class="anchor" href="#color_4" name="color_4">#</a><code>color</code> is a ColorString</li>
|
||
<li><a class="anchor" href="#color_5" name="color_5">#</a>The escape sequence sets the text color to <code>color</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestcolorizecolormessage" name="minetestcolorizecolormessage">#</a><code>minetest.colorize(color, message)</code>:<ul>
|
||
<li><a class="anchor" href="#minetestget_color_escape_sequencecolormessageminetestget_color_escape_sequenceffffff" name="minetestget_color_escape_sequencecolormessageminetestget_color_escape_sequenceffffff">#</a>Equivalent to:
|
||
<code>minetest.get_color_escape_sequence(color) ..
|
||
message ..
|
||
minetest.get_color_escape_sequence("#ffffff")</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_background_escape_sequencecolor" name="minetestget_background_escape_sequencecolor">#</a><code>minetest.get_background_escape_sequence(color)</code><ul>
|
||
<li><a class="anchor" href="#color_6" name="color_6">#</a><code>color</code> is a ColorString</li>
|
||
<li><a class="anchor" href="#color_7" name="color_7">#</a>The escape sequence sets the background of the whole text element to
|
||
<code>color</code>. Only defined for item descriptions and tooltips.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mineteststrip_foreground_colorsstr" name="mineteststrip_foreground_colorsstr">#</a><code>minetest.strip_foreground_colors(str)</code><ul>
|
||
<li><a class="anchor" href="#get_color_escape_sequence" name="get_color_escape_sequence">#</a>Removes foreground colors added by <code>get_color_escape_sequence</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mineteststrip_background_colorsstr" name="mineteststrip_background_colorsstr">#</a><code>minetest.strip_background_colors(str)</code><ul>
|
||
<li><a class="anchor" href="#get_background_escape_sequence" name="get_background_escape_sequence">#</a>Removes background colors added by <code>get_background_escape_sequence</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mineteststrip_colorsstr" name="mineteststrip_colorsstr">#</a><code>minetest.strip_colors(str)</code><ul>
|
||
<li>Removes all color escape sequences.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h2 id="spatial-vectors">Spatial Vectors</h2>
|
||
<ul>
|
||
<li><a class="anchor" href="#vectornewabc" name="vectornewabc">#</a><code>vector.new(a[, b, c])</code>: returns a vector:<ul>
|
||
<li><a class="anchor" href="#a" name="a">#</a>A copy of <code>a</code> if <code>a</code> is a vector.</li>
|
||
<li><a class="anchor" href="#xaybzc" name="xaybzc">#</a><code>{x = a, y = b, z = c}</code>, if all <code>a, b, c</code> are defined</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#vectordirectionp1p2" name="vectordirectionp1p2">#</a><code>vector.direction(p1, p2)</code>: returns a vector</li>
|
||
<li><a class="anchor" href="#vectordistancep1p2" name="vectordistancep1p2">#</a><code>vector.distance(p1, p2)</code>: returns a number</li>
|
||
<li><a class="anchor" href="#vectorlengthv" name="vectorlengthv">#</a><code>vector.length(v)</code>: returns a number</li>
|
||
<li><a class="anchor" href="#vectornormalizev" name="vectornormalizev">#</a><code>vector.normalize(v)</code>: returns a vector</li>
|
||
<li><a class="anchor" href="#vectorfloorv" name="vectorfloorv">#</a><code>vector.floor(v)</code>: returns a vector, each dimension rounded down</li>
|
||
<li><a class="anchor" href="#vectorroundv" name="vectorroundv">#</a><code>vector.round(v)</code>: returns a vector, each dimension rounded to nearest int</li>
|
||
<li><a class="anchor" href="#vectorapplyvfunc" name="vectorapplyvfunc">#</a><code>vector.apply(v, func)</code>: returns a vector</li>
|
||
<li><a class="anchor" href="#vectorequalsv1v2" name="vectorequalsv1v2">#</a><code>vector.equals(v1, v2)</code>: returns a boolean</li>
|
||
<li><a class="anchor" href="#vectorsortv1v2" name="vectorsortv1v2">#</a><code>vector.sort(v1, v2)</code>: returns minp, maxp vectors of the cuboid defined by v1 and v2</li>
|
||
</ul>
|
||
<p>For the following functions <code>x</code> can be either a vector or a number:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#vectoraddvx" name="vectoraddvx">#</a><code>vector.add(v, x)</code>: returns a vector</li>
|
||
<li><a class="anchor" href="#vectorsubtractvx" name="vectorsubtractvx">#</a><code>vector.subtract(v, x)</code>: returns a vector</li>
|
||
<li><a class="anchor" href="#vectormultiplyvx" name="vectormultiplyvx">#</a><code>vector.multiply(v, x)</code>: returns a scaled vector or Schur product</li>
|
||
<li><a class="anchor" href="#vectordividevx" name="vectordividevx">#</a><code>vector.divide(v, x)</code>: returns a scaled vector or Schur quotient</li>
|
||
</ul>
|
||
<h2 id="helper-functions">Helper functions</h2>
|
||
<ul>
|
||
<li><a class="anchor" href="#dump2objname_dumped" name="dump2objname_dumped">#</a><code>dump2(obj, name="_", dumped={})</code><ul>
|
||
<li>Return object serialized as a string, handles reference loops</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#dumpobjdumped" name="dumpobjdumped">#</a><code>dump(obj, dumped={})</code><ul>
|
||
<li>Return object serialized as a string</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mathhypotxy" name="mathhypotxy">#</a><code>math.hypot(x, y)</code><ul>
|
||
<li>Get the hypotenuse of a triangle with legs x and y.
|
||
Useful for distance calculation.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mathsignxtolerance" name="mathsignxtolerance">#</a><code>math.sign(x, tolerance)</code><ul>
|
||
<li><a class="anchor" href="#0_7" name="0_7">#</a>Get the sign of a number.
|
||
Optional: Also returns <code>0</code> when the absolute value is within the tolerance (default: <code>0</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#stringsplitstrseparatorinclude_emptyfalsemax_splits1sep_is_patternfalse" name="stringsplitstrseparatorinclude_emptyfalsemax_splits1sep_is_patternfalse">#</a><code>string.split(str, separator=",", include_empty=false, max_splits=-1, sep_is_pattern=false)</code><ul>
|
||
<li><a class="anchor" href="#max_splits" name="max_splits">#</a>If <code>max_splits</code> is negative, do not limit splits.</li>
|
||
<li><a class="anchor" href="#sep_is_pattern" name="sep_is_pattern">#</a><code>sep_is_pattern</code> specifies if separator is a plain string or a pattern (regex).</li>
|
||
<li><a class="anchor" href="#stringsplitabab" name="stringsplitabab">#</a>e.g. <code>string:split("a,b", ",") == {"a","b"}</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#stringtrim" name="stringtrim">#</a><code>string:trim()</code><ul>
|
||
<li><a class="anchor" href="#stringtrimnttfoobartfoobar" name="stringtrimnttfoobartfoobar">#</a>e.g. <code>string.trim("\n \t\tfoo bar\t ") == "foo bar"</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestwrap_textstrlimit" name="minetestwrap_textstrlimit">#</a><code>minetest.wrap_text(str, limit)</code>: returns a string<ul>
|
||
<li>Adds new lines to the string to keep it within the specified character limit</li>
|
||
<li>limit: Maximal amount of characters in one line</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestpos_to_stringxXyYzZdecimal_places" name="minetestpos_to_stringxXyYzZdecimal_places">#</a><code>minetest.pos_to_string({x=X,y=Y,z=Z}, decimal_places))</code>: returns string <code>"(X,Y,Z)"</code><ul>
|
||
<li>Convert position to a printable string
|
||
Optional: 'decimal_places' will round the x, y and z of the pos to the given decimal place.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mineteststring_to_posstring" name="mineteststring_to_posstring">#</a><code>minetest.string_to_pos(string)</code>: returns a position<ul>
|
||
<li><a class="anchor" href="#nil" name="nil">#</a>Same but in reverse. Returns <code>nil</code> if the string can't be parsed to a position.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mineteststring_to_areaX1Y1Z1X2Y2Z2" name="mineteststring_to_areaX1Y1Z1X2Y2Z2">#</a><code>minetest.string_to_area("(X1, Y1, Z1) (X2, Y2, Z2)")</code>: returns two positions<ul>
|
||
<li>Converts a string representing an area box into two positions</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestformspec_escapestring" name="minetestformspec_escapestring">#</a><code>minetest.formspec_escape(string)</code>: returns a string<ul>
|
||
<li>escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestis_yesarg" name="minetestis_yesarg">#</a><code>minetest.is_yes(arg)</code><ul>
|
||
<li>returns true if passed 'y', 'yes', 'true' or a number that isn't zero.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_us_time" name="minetestget_us_time">#</a><code>minetest.get_us_time()</code><ul>
|
||
<li>returns time with microsecond precision. May not return wall time.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#tablecopytable" name="tablecopytable">#</a><code>table.copy(table)</code>: returns a table<ul>
|
||
<li><a class="anchor" href="#table_2" name="table_2">#</a>returns a deep copy of <code>table</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestpointed_thing_to_face_posplacerpointed_thing" name="minetestpointed_thing_to_face_posplacerpointed_thing">#</a><code>minetest.pointed_thing_to_face_pos(placer, pointed_thing)</code>: returns a position<ul>
|
||
<li>returns the exact position on the surface of a pointed node</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h2 id="minetest-namespace-reference"><code>minetest</code> namespace reference</h2>
|
||
<h3 id="utilities">Utilities</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestget_current_modname" name="minetestget_current_modname">#</a><code>minetest.get_current_modname()</code>: returns the currently loading mod's name, when we are loading a mod</li>
|
||
<li><a class="anchor" href="#minetestget_modpathmodname" name="minetestget_modpathmodname">#</a><code>minetest.get_modpath(modname)</code>: returns e.g. <code>"/home/user/.minetest/usermods/modname"</code><ul>
|
||
<li><a class="anchor" href="#lua" name="lua">#</a>Useful for loading additional <code>.lua</code> modules or static data from mod</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_modnames" name="minetestget_modnames">#</a><code>minetest.get_modnames()</code>: returns a list of installed mods<ul>
|
||
<li>Return a list of installed mods, sorted alphabetically</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_worldpath" name="minetestget_worldpath">#</a><code>minetest.get_worldpath()</code>: returns e.g. <code>"/home/user/.minetest/world"</code><ul>
|
||
<li>Useful for storing custom data</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestis_singleplayer" name="minetestis_singleplayer">#</a><code>minetest.is_singleplayer()</code></li>
|
||
<li><a class="anchor" href="#minetestfeatures" name="minetestfeatures">#</a><code>minetest.features</code>: Table containing API feature flags<pre><code>{
|
||
glasslike_framed = true,
|
||
nodebox_as_selectionbox = true,
|
||
chat_send_player_param3 = true,
|
||
get_all_craft_recipes_works = true,
|
||
use_texture_alpha = true,
|
||
-- ^ The transparency channel of textures can be used optionally
|
||
no_legacy_abms = true,
|
||
-- ^ Tree and grass ABMs are no longer done from C++
|
||
texture_names_parens = true,
|
||
-- ^ Texture grouping is possible using parentheses
|
||
area_store_custom_ids = true,
|
||
-- ^ Unique Area ID for AreaStore:insert_area
|
||
add_entity_with_staticdata = true,
|
||
-- ^ add_entity supports passing initial staticdata to on_activate
|
||
no_chat_message_prediction = true,
|
||
-- ^ Chat messages are no longer predicted
|
||
}
|
||
</code></pre>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetesthas_featurearg" name="minetesthas_featurearg">#</a><code>minetest.has_feature(arg)</code>: returns <code>boolean, missing_features</code></li>
|
||
<li><a class="anchor" href="#arg" name="arg">#</a><code>arg</code>: string or table in format <code>{foo=true, bar=true}</code></li>
|
||
<li><a class="anchor" href="#missing_features" name="missing_features">#</a><code>missing_features</code>: <code>{foo=true, bar=true}</code></li>
|
||
<li><a class="anchor" href="#minetestget_player_informationplayer_name" name="minetestget_player_informationplayer_name">#</a><code>minetest.get_player_information(player_name)</code>:</li>
|
||
<li><a class="anchor" href="#address127001IPaddressofclientip_version4IPv4IPv6min_rtt001minimumroundtriptimemax_rtt02maximumroundtriptimeavg_rtt002averageroundtriptimemin_jitter001minimumpackettimejittermax_jitter05maximumpackettimejitteravg_jitter003averagepackettimejitterconnection_uptime200secondssinceclientconnectedprot_vers31protocolversionusedbyclientfollowinginformationisavailableondebugbuildonlyDONOTUSEINMODSser_vers26serializationversionusedbyclientmajor0majorversionnumberminor4minorversionnumberpatch10patchversionnumbervers_string049gitfullversionstringstateActivecurrentclientstate" name="address127001IPaddressofclientip_version4IPv4IPv6min_rtt001minimumroundtriptimemax_rtt02maximumroundtriptimeavg_rtt002averageroundtriptimemin_jitter001minimumpackettimejittermax_jitter05maximumpackettimejitteravg_jitter003averagepackettimejitterconnection_uptime200secondssinceclientconnectedprot_vers31protocolversionusedbyclientfollowinginformationisavailableondebugbuildonlyDONOTUSEINMODSser_vers26serializationversionusedbyclientmajor0majorversionnumberminor4minorversionnumberpatch10patchversionnumbervers_string049gitfullversionstringstateActivecurrentclientstate">#</a>Returns a table containing information about a player. Example return value:<pre><code>{
|
||
address = "127.0.0.1", -- IP address of client
|
||
ip_version = 4, -- IPv4 / IPv6
|
||
min_rtt = 0.01, -- minimum round trip time
|
||
max_rtt = 0.2, -- maximum round trip time
|
||
avg_rtt = 0.02, -- average round trip time
|
||
min_jitter = 0.01, -- minimum packet time jitter
|
||
max_jitter = 0.5, -- maximum packet time jitter
|
||
avg_jitter = 0.03, -- average packet time jitter
|
||
connection_uptime = 200, -- seconds since client connected
|
||
prot_vers = 31, -- protocol version used by client
|
||
-- following information is available on debug build only!!!
|
||
-- DO NOT USE IN MODS
|
||
--ser_vers = 26, -- serialization version used by client
|
||
--major = 0, -- major version number
|
||
--minor = 4, -- minor version number
|
||
--patch = 10, -- patch version number
|
||
--vers_string = "0.4.9-git", -- full version string
|
||
--state = "Active" -- current client state
|
||
}
|
||
</code></pre>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestmkdirpath" name="minetestmkdirpath">#</a><code>minetest.mkdir(path)</code>: returns success.<ul>
|
||
<li><a class="anchor" href="#path" name="path">#</a>Creates a directory specified by <code>path</code>, creating parent directories
|
||
if they don't exist.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_dir_listpathis_dir" name="minetestget_dir_listpathis_dir">#</a><code>minetest.get_dir_list(path, [is_dir])</code>: returns list of entry names<ul>
|
||
<li>is_dir is one of:</li>
|
||
<li>nil: return all entries,</li>
|
||
<li>true: return only subdirectory names, or</li>
|
||
<li>false: return only file names.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_version" name="minetestget_version">#</a><code>minetest.get_version()</code>: returns a table containing components of the
|
||
engine version. Components:<ul>
|
||
<li><a class="anchor" href="#project" name="project">#</a><code>project</code>: Name of the project, eg, "Minetest"</li>
|
||
<li><a class="anchor" href="#string" name="string">#</a><code>string</code>: Simple version, eg, "1.2.3-dev"</li>
|
||
<li><a class="anchor" href="#hash" name="hash">#</a><code>hash</code>: Full git version (only set if available), eg, "1.2.3-dev-01234567-dirty"
|
||
Use this for informational purposes only. The information in the returned
|
||
table does not represent the capabilities of the engine, nor is it
|
||
reliable or verifyable. Compatible forks will have a different name and
|
||
version entirely. To check for the presence of engine features, test
|
||
whether the functions exported by the wanted features exist. For example:
|
||
<code>if minetest.nodeupdate then ... end</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="logging">Logging</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestdebug" name="minetestdebug">#</a><code>minetest.debug(...)</code><ul>
|
||
<li><a class="anchor" href="#minetestlogtableconcatt" name="minetestlogtableconcatt">#</a>Equivalent to <code>minetest.log(table.concat({...}, "\t"))</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestlogleveltext" name="minetestlogleveltext">#</a><code>minetest.log([level,] text)</code><ul>
|
||
<li><a class="anchor" href="#level_2" name="level_2">#</a><code>level</code> is one of <code>"none"</code>, <code>"error"</code>, <code>"warning"</code>, <code>"action"</code>,
|
||
<code>"info"</code>, or <code>"verbose"</code>. Default is <code>"none"</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="registration-functions">Registration functions</h3>
|
||
<p>Call these functions only at load time!</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregister_entitynameprototypetable_1" name="minetestregister_entitynameprototypetable_1">#</a><code>minetest.register_entity(name, prototype table)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_abmabmdefinition" name="minetestregister_abmabmdefinition">#</a><code>minetest.register_abm(abm definition)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_lbmlbmdefinition" name="minetestregister_lbmlbmdefinition">#</a><code>minetest.register_lbm(lbm definition)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_nodenamenodedefinition_1" name="minetestregister_nodenamenodedefinition_1">#</a><code>minetest.register_node(name, node definition)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_toolnameitemdefinition_1" name="minetestregister_toolnameitemdefinition_1">#</a><code>minetest.register_tool(name, item definition)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_craftitemnameitemdefinition_1" name="minetestregister_craftitemnameitemdefinition_1">#</a><code>minetest.register_craftitem(name, item definition)</code></li>
|
||
<li><a class="anchor" href="#minetestunregister_itemname_1" name="minetestunregister_itemname_1">#</a><code>minetest.unregister_item(name)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_aliasnameconvert_to" name="minetestregister_aliasnameconvert_to">#</a><code>minetest.register_alias(name, convert_to)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_alias_forcenameconvert_to" name="minetestregister_alias_forcenameconvert_to">#</a><code>minetest.register_alias_force(name, convert_to)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_craftrecipe" name="minetestregister_craftrecipe">#</a><code>minetest.register_craft(recipe)</code><ul>
|
||
<li>Check recipe table syntax for different types below.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclear_craftrecipe" name="minetestclear_craftrecipe">#</a><code>minetest.clear_craft(recipe)</code><ul>
|
||
<li>Will erase existing craft based either on output item or on input recipe.</li>
|
||
<li><a class="anchor" href="#minetestregister_craftrecipe_1" name="minetestregister_craftrecipe_1">#</a>Specify either output or input only. If you specify both, input will be ignored. For input use the same recipe table
|
||
syntax as for <code>minetest.register_craft(recipe)</code>. For output specify only the item, without a quantity.</li>
|
||
<li>If no erase candidate could be found, Lua exception will be thrown.</li>
|
||
<li><strong>Warning</strong>! The type field ("shaped","cooking" or any other) will be ignored if the recipe
|
||
contains output. Erasing is then done independently from the crafting method.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_oreoredefinition_1" name="minetestregister_oreoredefinition_1">#</a><code>minetest.register_ore(ore definition)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_biomebiomedefinition_1" name="minetestregister_biomebiomedefinition_1">#</a><code>minetest.register_biome(biome definition)</code></li>
|
||
<li><a class="anchor" href="#minetestregister_decorationdecorationdefinition_1" name="minetestregister_decorationdecorationdefinition_1">#</a><code>minetest.register_decoration(decoration definition)</code></li>
|
||
<li><a class="anchor" href="#minetestoverride_itemnameredefinition" name="minetestoverride_itemnameredefinition">#</a><code>minetest.override_item(name, redefinition)</code><ul>
|
||
<li>Overrides fields of an item registered with register_node/tool/craftitem.</li>
|
||
<li>Note: Item must already be defined, (opt)depend on the mod defining it.</li>
|
||
<li><a class="anchor" href="#minetestoverride_itemdefaultmeselight_sourceLIGHT_MAX" name="minetestoverride_itemdefaultmeselight_sourceLIGHT_MAX">#</a>Example: <code>minetest.override_item("default:mese", {light_source=LIGHT_MAX})</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclear_registered_ores_1" name="minetestclear_registered_ores_1">#</a><code>minetest.clear_registered_ores()</code></li>
|
||
<li><a class="anchor" href="#minetestclear_registered_biomes_1" name="minetestclear_registered_biomes_1">#</a><code>minetest.clear_registered_biomes()</code></li>
|
||
<li><a class="anchor" href="#minetestclear_registered_decorations_1" name="minetestclear_registered_decorations_1">#</a><code>minetest.clear_registered_decorations()</code></li>
|
||
</ul>
|
||
<h3 id="global-callback-registration-functions">Global callback registration functions</h3>
|
||
<p>Call these functions only at load time!</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregister_globalstepfuncdtime" name="minetestregister_globalstepfuncdtime">#</a><code>minetest.register_globalstep(func(dtime))</code><ul>
|
||
<li>Called every server step, usually interval of 0.1s</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_shutdownfunc" name="minetestregister_on_shutdownfunc">#</a><code>minetest.register_on_shutdown(func())</code><ul>
|
||
<li>Called before server shutdown</li>
|
||
<li><strong>Warning</strong>: If the server terminates abnormally (i.e. crashes), the registered
|
||
callbacks <strong>will likely not be run</strong>. Data should be saved at
|
||
semi-frequent intervals as well as on server shutdown.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_placenodefuncposnewnodeplaceroldnodeitemstackpointed_thing" name="minetestregister_on_placenodefuncposnewnodeplaceroldnodeitemstackpointed_thing">#</a><code>minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack, pointed_thing))</code><ul>
|
||
<li>Called when a node has been placed</li>
|
||
<li><a class="anchor" href="#true_4" name="true_4">#</a>If return <code>true</code> no item is taken from <code>itemstack</code></li>
|
||
<li><a class="anchor" href="#on_construct" name="on_construct">#</a><strong>Not recommended</strong>; use <code>on_construct</code> or <code>after_place_node</code> in node definition
|
||
whenever possible</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_dignodefuncposoldnodedigger" name="minetestregister_on_dignodefuncposoldnodedigger">#</a><code>minetest.register_on_dignode(func(pos, oldnode, digger))</code><ul>
|
||
<li>Called when a node has been dug.</li>
|
||
<li><a class="anchor" href="#on_destruct" name="on_destruct">#</a><strong>Not recommended</strong>; Use <code>on_destruct</code> or <code>after_dig_node</code> in node definition
|
||
whenever possible</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_punchnodefuncposnodepuncherpointed_thing" name="minetestregister_on_punchnodefuncposnodepuncherpointed_thing">#</a><code>minetest.register_on_punchnode(func(pos, node, puncher, pointed_thing))</code><ul>
|
||
<li>Called when a node is punched</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_generatedfuncminpmaxpblockseed" name="minetestregister_on_generatedfuncminpmaxpblockseed">#</a><code>minetest.register_on_generated(func(minp, maxp, blockseed))</code><ul>
|
||
<li>Called after generating a piece of world. Modifying nodes inside the area
|
||
is a bit faster than usually.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_newplayerfuncObjectRef" name="minetestregister_on_newplayerfuncObjectRef">#</a><code>minetest.register_on_newplayer(func(ObjectRef))</code><ul>
|
||
<li>Called after a new player has been created</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_dieplayerfuncObjectRef" name="minetestregister_on_dieplayerfuncObjectRef">#</a><code>minetest.register_on_dieplayer(func(ObjectRef))</code><ul>
|
||
<li>Called when a player dies</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_punchplayerfuncplayerhittertime_from_last_punchtool_capabilitiesdirdamage" name="minetestregister_on_punchplayerfuncplayerhittertime_from_last_punchtool_capabilitiesdirdamage">#</a><code>minetest.register_on_punchplayer(func(player, hitter, time_from_last_punch, tool_capabilities, dir, damage))</code><ul>
|
||
<li>Called when a player is punched</li>
|
||
<li><a class="anchor" href="#player" name="player">#</a><code>player</code> - ObjectRef - Player that was punched</li>
|
||
<li><a class="anchor" href="#hitter" name="hitter">#</a><code>hitter</code> - ObjectRef - Player that hit</li>
|
||
<li><a class="anchor" href="#time_from_last_punch_1" name="time_from_last_punch_1">#</a><code>time_from_last_punch</code>: Meant for disallowing spamming of clicks (can be nil)</li>
|
||
<li><a class="anchor" href="#tool_capabilities_1" name="tool_capabilities_1">#</a><code>tool_capabilities</code>: capability table of used tool (can be nil)</li>
|
||
<li><a class="anchor" href="#dir" name="dir">#</a><code>dir</code>: unit vector of direction of punch. Always defined. Points from
|
||
the puncher to the punched.</li>
|
||
<li><a class="anchor" href="#damage_1" name="damage_1">#</a><code>damage</code> - number that represents the damage calculated by the engine</li>
|
||
<li><a class="anchor" href="#true_5" name="true_5">#</a>should return <code>true</code> to prevent the default damage mechanism</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_player_hpchangefuncplayerhp_changemodifier" name="minetestregister_on_player_hpchangefuncplayerhp_changemodifier">#</a><code>minetest.register_on_player_hpchange(func(player, hp_change), modifier)</code><ul>
|
||
<li>Called when the player gets damaged or healed</li>
|
||
<li><a class="anchor" href="#player_1" name="player_1">#</a><code>player</code>: ObjectRef of the player</li>
|
||
<li><a class="anchor" href="#hp_change" name="hp_change">#</a><code>hp_change</code>: the amount of change. Negative when it is damage.</li>
|
||
<li><a class="anchor" href="#modifier" name="modifier">#</a><code>modifier</code>: when true, the function should return the actual <code>hp_change</code>.
|
||
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.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_respawnplayerfuncObjectRef" name="minetestregister_on_respawnplayerfuncObjectRef">#</a><code>minetest.register_on_respawnplayer(func(ObjectRef))</code><ul>
|
||
<li>Called when player is to be respawned</li>
|
||
<li>Called <em>before</em> repositioning of player occurs</li>
|
||
<li>return true in func to disable regular player placement</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_prejoinplayerfuncnameip" name="minetestregister_on_prejoinplayerfuncnameip">#</a><code>minetest.register_on_prejoinplayer(func(name, ip))</code><ul>
|
||
<li>Called before a player joins the game</li>
|
||
<li>If it returns a string, the player is disconnected with that string as reason</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_joinplayerfuncObjectRef" name="minetestregister_on_joinplayerfuncObjectRef">#</a><code>minetest.register_on_joinplayer(func(ObjectRef))</code><ul>
|
||
<li>Called when a player joins the game</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_leaveplayerfuncObjectReftimed_out" name="minetestregister_on_leaveplayerfuncObjectReftimed_out">#</a><code>minetest.register_on_leaveplayer(func(ObjectRef, timed_out))</code><ul>
|
||
<li>Called when a player leaves the game</li>
|
||
<li><a class="anchor" href="#timed_out" name="timed_out">#</a><code>timed_out</code>: True for timeout, false for other reasons.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_cheatfuncObjectRefcheat" name="minetestregister_on_cheatfuncObjectRefcheat">#</a><code>minetest.register_on_cheat(func(ObjectRef, cheat))</code><ul>
|
||
<li>Called when a player cheats</li>
|
||
<li><a class="anchor" href="#cheat" name="cheat">#</a><code>cheat</code>: <code>{type=<cheat_type>}</code>, where <code><cheat_type></code> is one of:<ul>
|
||
<li><a class="anchor" href="#moved_too_fast" name="moved_too_fast">#</a><code>moved_too_fast</code></li>
|
||
<li><a class="anchor" href="#interacted_too_far" name="interacted_too_far">#</a><code>interacted_too_far</code></li>
|
||
<li><a class="anchor" href="#interacted_while_dead" name="interacted_while_dead">#</a><code>interacted_while_dead</code></li>
|
||
<li><a class="anchor" href="#finished_unknown_dig" name="finished_unknown_dig">#</a><code>finished_unknown_dig</code></li>
|
||
<li><a class="anchor" href="#dug_unbreakable" name="dug_unbreakable">#</a><code>dug_unbreakable</code></li>
|
||
<li><a class="anchor" href="#dug_too_fast" name="dug_too_fast">#</a><code>dug_too_fast</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_chat_messagefuncnamemessage" name="minetestregister_on_chat_messagefuncnamemessage">#</a><code>minetest.register_on_chat_message(func(name, message))</code><ul>
|
||
<li>Called always when a player says something</li>
|
||
<li><a class="anchor" href="#true_6" name="true_6">#</a>Return <code>true</code> to mark the message as handled, which means that it will not be sent to other players</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_player_receive_fieldsfuncplayerformnamefields" name="minetestregister_on_player_receive_fieldsfuncplayerformnamefields">#</a><code>minetest.register_on_player_receive_fields(func(player, formname, fields))</code><ul>
|
||
<li>Called when a button is pressed in player's inventory form</li>
|
||
<li>Newest functions are called first</li>
|
||
<li><a class="anchor" href="#true_7" name="true_7">#</a>If function returns <code>true</code>, remaining functions are not called</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_craftfuncitemstackplayerold_craft_gridcraft_inv" name="minetestregister_on_craftfuncitemstackplayerold_craft_gridcraft_inv">#</a><code>minetest.register_on_craft(func(itemstack, player, old_craft_grid, craft_inv))</code><ul>
|
||
<li><a class="anchor" href="#player_2" name="player_2">#</a>Called when <code>player</code> crafts something</li>
|
||
<li><a class="anchor" href="#itemstack_2" name="itemstack_2">#</a><code>itemstack</code> is the output</li>
|
||
<li><a class="anchor" href="#old_craft_grid" name="old_craft_grid">#</a><code>old_craft_grid</code> contains the recipe (Note: the one in the inventory is cleared)</li>
|
||
<li><a class="anchor" href="#craft_inv" name="craft_inv">#</a><code>craft_inv</code> is the inventory with the crafting grid</li>
|
||
<li><a class="anchor" href="#ItemStack" name="ItemStack">#</a>Return either an <code>ItemStack</code>, to replace the output, or <code>nil</code>, to not modify it</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_craft_predictfuncitemstackplayerold_craft_gridcraft_inv" name="minetestregister_craft_predictfuncitemstackplayerold_craft_gridcraft_inv">#</a><code>minetest.register_craft_predict(func(itemstack, player, old_craft_grid, craft_inv))</code><ul>
|
||
<li>The same as before, except that it is called before the player crafts, to make
|
||
craft prediction, and it should not change anything.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_protection_violationfuncposname" name="minetestregister_on_protection_violationfuncposname">#</a><code>minetest.register_on_protection_violation(func(pos, name))</code><ul>
|
||
<li><a class="anchor" href="#builtin" name="builtin">#</a>Called by <code>builtin</code> and mods when a player violates protection at a position
|
||
(eg, digs a node or punches a protected entity).</li>
|
||
<li><a class="anchor" href="#minetestrecord_protection_violation" name="minetestrecord_protection_violation">#</a>The registered functions can be called using <code>minetest.record_protection_violation</code></li>
|
||
<li>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.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_on_item_eatfunchp_changereplace_with_itemitemstackuserpointed_thing" name="minetestregister_on_item_eatfunchp_changereplace_with_itemitemstackuserpointed_thing">#</a><code>minetest.register_on_item_eat(func(hp_change, replace_with_item, itemstack, user, pointed_thing))</code><ul>
|
||
<li><a class="anchor" href="#minetestitem_eat" name="minetestitem_eat">#</a>Called when an item is eaten, by <code>minetest.item_eat</code></li>
|
||
<li><a class="anchor" href="#true_8" name="true_8">#</a>Return <code>true</code> or <code>itemstack</code> to cancel the default item eat response (i.e.: hp increase)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="other-registration-functions">Other registration functions</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregister_chatcommandcmdchatcommanddefinition" name="minetestregister_chatcommandcmdchatcommanddefinition">#</a><code>minetest.register_chatcommand(cmd, chatcommand definition)</code><ul>
|
||
<li><a class="anchor" href="#minetestregistered_chatcommands" name="minetestregistered_chatcommands">#</a>Adds definition to <code>minetest.registered_chatcommands</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestoverride_chatcommandnameredefinition" name="minetestoverride_chatcommandnameredefinition">#</a><code>minetest.override_chatcommand(name, redefinition)</code><ul>
|
||
<li><a class="anchor" href="#register_chatcommand" name="register_chatcommand">#</a>Overrides fields of a chatcommand registered with <code>register_chatcommand</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestunregister_chatcommandname" name="minetestunregister_chatcommandname">#</a><code>minetest.unregister_chatcommand(name)</code><ul>
|
||
<li><a class="anchor" href="#register_chatcommand_1" name="register_chatcommand_1">#</a>Unregisters a chatcommands registered with <code>register_chatcommand</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_privilegenamedefinition" name="minetestregister_privilegenamedefinition">#</a><code>minetest.register_privilege(name, definition)</code><ul>
|
||
<li><a class="anchor" href="#definition" name="definition">#</a><code>definition</code>: <code>"description text"</code></li>
|
||
<li><a class="anchor" href="#definition_1" name="definition_1">#</a><code>definition</code>: <code>{ description = "description text", give_to_singleplayer = boolean}</code>
|
||
the default of <code>give_to_singleplayer</code> is true</li>
|
||
<li><a class="anchor" href="#basic_privs" name="basic_privs">#</a>To allow players with <code>basic_privs</code> to grant, see <code>basic_privs</code> minetest.conf setting.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregister_authentication_handlerhandler" name="minetestregister_authentication_handlerhandler">#</a><code>minetest.register_authentication_handler(handler)</code><ul>
|
||
<li><a class="anchor" href="#minetestbuiltin_auth_handler" name="minetestbuiltin_auth_handler">#</a>See <code>minetest.builtin_auth_handler</code> in <code>builtin.lua</code> for reference</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="setting-related">Setting-related</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestsettings" name="minetestsettings">#</a><code>minetest.settings</code>: Settings object containing all of the settings from the
|
||
main config file (<code>minetest.conf</code>).</li>
|
||
<li><a class="anchor" href="#minetestsetting_get_posname" name="minetestsetting_get_posname">#</a><code>minetest.setting_get_pos(name)</code>: Loads a setting from the main settings and
|
||
parses it as a position (in the format <code>(1,2,3)</code>). Returns a position or nil.</li>
|
||
</ul>
|
||
<h3 id="authentication">Authentication</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestnotify_authentication_modifiedname" name="minetestnotify_authentication_modifiedname">#</a><code>minetest.notify_authentication_modified(name)</code><ul>
|
||
<li>Should be called by the authentication handler if privileges changes.</li>
|
||
<li><a class="anchor" href="#namenil" name="namenil">#</a>To report everybody, set <code>name=nil</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestcheck_password_entrynameentrypassword" name="minetestcheck_password_entrynameentrypassword">#</a><code>minetest.check_password_entry(name, entry, password)</code><ul>
|
||
<li>Returns true if the "db entry" for a player with name matches given</li>
|
||
<li>password, false otherwise.</li>
|
||
<li>The "db entry" is the usually player-individual value that is derived</li>
|
||
<li>from the player's chosen password and stored on the server in order to allow</li>
|
||
<li>authentication whenever the player desires to log in.</li>
|
||
<li>Only use this function for making it possible to log in via the password from</li>
|
||
<li>via protocols like IRC, other uses for inside the game are frowned upon.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_password_hashnameraw_password" name="minetestget_password_hashnameraw_password">#</a><code>minetest.get_password_hash(name, raw_password)</code><ul>
|
||
<li>Convert a name-password pair to a password hash that Minetest can use.</li>
|
||
<li>The returned value alone is not a good basis for password checks based</li>
|
||
<li>on comparing the password hash in the database with the password hash</li>
|
||
<li>from the function, with an externally provided password, as the hash</li>
|
||
<li>in the db might use the new SRP verifier format.</li>
|
||
<li><a class="anchor" href="#minetestcheck_password_entry" name="minetestcheck_password_entry">#</a>For this purpose, use <code>minetest.check_password_entry</code> instead.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#mineteststring_to_privsstr" name="mineteststring_to_privsstr">#</a><code>minetest.string_to_privs(str)</code>: returns <code>{priv1=true,...}</code></li>
|
||
<li><a class="anchor" href="#minetestprivs_to_stringprivs" name="minetestprivs_to_stringprivs">#</a><code>minetest.privs_to_string(privs)</code>: returns <code>"priv1,priv2,..."</code><ul>
|
||
<li>Convert between two privilege representations</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestset_player_passwordnamepassword_hash" name="minetestset_player_passwordnamepassword_hash">#</a><code>minetest.set_player_password(name, password_hash)</code></li>
|
||
<li><a class="anchor" href="#minetestset_player_privsnamepriv1true" name="minetestset_player_privsnamepriv1true">#</a><code>minetest.set_player_privs(name, {priv1=true,...})</code></li>
|
||
<li><a class="anchor" href="#minetestget_player_privsnamepriv1true" name="minetestget_player_privsnamepriv1true">#</a><code>minetest.get_player_privs(name) -> {priv1=true,...}</code></li>
|
||
<li><a class="anchor" href="#minetestauth_reload" name="minetestauth_reload">#</a><code>minetest.auth_reload()</code></li>
|
||
<li><a class="anchor" href="#minetestcheck_player_privsplayer_or_name" name="minetestcheck_player_privsplayer_or_name">#</a><code>minetest.check_player_privs(player_or_name, ...)</code>: returns <code>bool, missing_privs</code><ul>
|
||
<li>A quickhand for checking privileges.</li>
|
||
<li><a class="anchor" href="#player_or_name" name="player_or_name">#</a><code>player_or_name</code>: Either a Player object or the name of a player.</li>
|
||
<li><code>...</code> is either a list of strings, e.g. <code>"priva", "privb"</code> or
|
||
a table, e.g. <code>{ priva = true, privb = true }</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_player_ipname" name="minetestget_player_ipname">#</a><code>minetest.get_player_ip(name)</code>: returns an IP address string</li>
|
||
</ul>
|
||
<p><code>minetest.set_player_password</code>, <code>minetest_set_player_privs</code>, <code>minetest_get_player_privs</code>
|
||
and <code>minetest.auth_reload</code> call the authetification handler.</p>
|
||
<h3 id="chat">Chat</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestchat_send_alltext" name="minetestchat_send_alltext">#</a><code>minetest.chat_send_all(text)</code></li>
|
||
<li><a class="anchor" href="#minetestchat_send_playernametext" name="minetestchat_send_playernametext">#</a><code>minetest.chat_send_player(name, text)</code></li>
|
||
</ul>
|
||
<h3 id="environment-access">Environment access</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestset_nodeposnode" name="minetestset_nodeposnode">#</a><code>minetest.set_node(pos, node)</code></li>
|
||
<li><a class="anchor" href="#minetestadd_nodeposnodealiasset_nodeposnode" name="minetestadd_nodeposnodealiasset_nodeposnode">#</a><code>minetest.add_node(pos, node): alias set_node(pos, node)</code><ul>
|
||
<li><a class="anchor" href="#nodenamefooparam10param20" name="nodenamefooparam10param20">#</a>Set node at position (<code>node = {name="foo", param1=0, param2=0}</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestswap_nodeposnode" name="minetestswap_nodeposnode">#</a><code>minetest.swap_node(pos, node)</code><ul>
|
||
<li>Set node at position, but don't remove metadata</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestremove_nodepos" name="minetestremove_nodepos">#</a><code>minetest.remove_node(pos)</code><ul>
|
||
<li><a class="anchor" href="#set_nodeposair" name="set_nodeposair">#</a>Equivalent to <code>set_node(pos, "air")</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_nodepos" name="minetestget_nodepos">#</a><code>minetest.get_node(pos)</code><ul>
|
||
<li><a class="anchor" href="#namenode_nameparam10param20" name="namenode_nameparam10param20">#</a>Returns the node at the given position as table in the format
|
||
<code>{name="node_name", param1=0, param2=0}</code>, returns <code>{name="ignore", param1=0, param2=0}</code>
|
||
for unloaded areas.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_node_or_nilpos" name="minetestget_node_or_nilpos">#</a><code>minetest.get_node_or_nil(pos)</code><ul>
|
||
<li><a class="anchor" href="#get_node" name="get_node">#</a>Same as <code>get_node</code> but returns <code>nil</code> for unloaded areas.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_node_lightpostimeofday" name="minetestget_node_lightpostimeofday">#</a><code>minetest.get_node_light(pos, timeofday)</code><ul>
|
||
<li>Gets the light value at the given position. Note that the light value
|
||
"inside" the node at the given position is returned, so you usually want
|
||
to get the light value of a neighbor.</li>
|
||
<li><a class="anchor" href="#pos" name="pos">#</a><code>pos</code>: The position where to measure the light.</li>
|
||
<li><a class="anchor" href="#timeofday" name="timeofday">#</a><code>timeofday</code>: <code>nil</code> for current time, <code>0</code> for night, <code>0.5</code> for day</li>
|
||
<li><a class="anchor" href="#0_8" name="0_8">#</a>Returns a number between <code>0</code> and <code>15</code> or <code>nil</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestplace_nodeposnode" name="minetestplace_nodeposnode">#</a><code>minetest.place_node(pos, node)</code><ul>
|
||
<li>Place node with the same effects that a player would cause</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdig_nodepos" name="minetestdig_nodepos">#</a><code>minetest.dig_node(pos)</code><ul>
|
||
<li>Dig node with the same effects that a player would cause</li>
|
||
<li><a class="anchor" href="#true_9" name="true_9">#</a>Returns <code>true</code> if successful, <code>false</code> on failure (e.g. protected location)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestpunch_nodepos" name="minetestpunch_nodepos">#</a><code>minetest.punch_node(pos)</code><ul>
|
||
<li>Punch node with the same effects that a player would cause</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestspawn_falling_nodepos" name="minetestspawn_falling_nodepos">#</a>
|
||
<p><code>minetest.spawn_falling_node(pos)</code></p>
|
||
<ul>
|
||
<li>Change node into falling node</li>
|
||
<li><a class="anchor" href="#true_10" name="true_10">#</a>Returns <code>true</code> if successful, <code>false</code> on failure</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestfind_nodes_with_metapos1pos2" name="minetestfind_nodes_with_metapos1pos2">#</a>
|
||
<p><code>minetest.find_nodes_with_meta(pos1, pos2)</code></p>
|
||
<ul>
|
||
<li>Get a table of positions of nodes that have metadata within a region {pos1, pos2}</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_metapos" name="minetestget_metapos">#</a><code>minetest.get_meta(pos)</code><ul>
|
||
<li><a class="anchor" href="#NodeMetaRef" name="NodeMetaRef">#</a>Get a <code>NodeMetaRef</code> at that position</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_node_timerpos" name="minetestget_node_timerpos">#</a>
|
||
<p><code>minetest.get_node_timer(pos)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#NodeTimerRef" name="NodeTimerRef">#</a>Get <code>NodeTimerRef</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestadd_entityposnamestaticdata" name="minetestadd_entityposnamestaticdata">#</a>
|
||
<p><code>minetest.add_entity(pos, name, [staticdata])</code>: Spawn Lua-defined entity at position</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#ObjectRef" name="ObjectRef">#</a>Returns <code>ObjectRef</code>, or <code>nil</code> if failed</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestadd_itempositem" name="minetestadd_itempositem">#</a><code>minetest.add_item(pos, item)</code>: Spawn item<ul>
|
||
<li><a class="anchor" href="#ObjectRef_1" name="ObjectRef_1">#</a>Returns <code>ObjectRef</code>, or <code>nil</code> if failed</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_player_by_namename" name="minetestget_player_by_namename">#</a><code>minetest.get_player_by_name(name)</code>: Get an <code>ObjectRef</code> to a player</li>
|
||
<li><a class="anchor" href="#minetestget_objects_inside_radiusposradius" name="minetestget_objects_inside_radiusposradius">#</a><code>minetest.get_objects_inside_radius(pos, radius)</code><ul>
|
||
<li><a class="anchor" href="#radius" name="radius">#</a><code>radius</code>: using an euclidean metric</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestset_timeofdayval" name="minetestset_timeofdayval">#</a><code>minetest.set_timeofday(val)</code><ul>
|
||
<li><a class="anchor" href="#val" name="val">#</a><code>val</code> is between <code>0</code> and <code>1</code>; <code>0</code> for midnight, <code>0.5</code> for midday</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_timeofday" name="minetestget_timeofday">#</a><code>minetest.get_timeofday()</code></li>
|
||
<li><a class="anchor" href="#minetestget_gametime" name="minetestget_gametime">#</a><code>minetest.get_gametime()</code>: returns the time, in seconds, since the world was created</li>
|
||
<li><a class="anchor" href="#minetestget_day_count" name="minetestget_day_count">#</a><code>minetest.get_day_count()</code>: returns number days elapsed since world was created,<ul>
|
||
<li>accounting for time changes.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestfind_node_nearposradiusnodenamessearch_center" name="minetestfind_node_nearposradiusnodenamessearch_center">#</a><code>minetest.find_node_near(pos, radius, nodenames, [search_center])</code>: returns pos or <code>nil</code><ul>
|
||
<li><a class="anchor" href="#radius_1" name="radius_1">#</a><code>radius</code>: using a maximum metric</li>
|
||
<li><a class="anchor" href="#nodenames" name="nodenames">#</a><code>nodenames</code>: e.g. <code>{"ignore", "group:tree"}</code> or <code>"default:dirt"</code></li>
|
||
<li><a class="anchor" href="#search_center" name="search_center">#</a><code>search_center</code> is an optional boolean (default: <code>false</code>)
|
||
If true <code>pos</code> is also checked for the nodes</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestfind_nodes_in_areapos1pos2nodenames" name="minetestfind_nodes_in_areapos1pos2nodenames">#</a><code>minetest.find_nodes_in_area(pos1, pos2, nodenames)</code>: returns a list of positions<ul>
|
||
<li><a class="anchor" href="#nodenames_1" name="nodenames_1">#</a><code>nodenames</code>: e.g. <code>{"ignore", "group:tree"}</code> or <code>"default:dirt"</code></li>
|
||
<li>First return value: Table with all node positions</li>
|
||
<li>Second return value: Table with the count of each node with the node name as index</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestfind_nodes_in_area_under_airpos1pos2nodenames" name="minetestfind_nodes_in_area_under_airpos1pos2nodenames">#</a><code>minetest.find_nodes_in_area_under_air(pos1, pos2, nodenames)</code>: returns a list of positions<ul>
|
||
<li><a class="anchor" href="#nodenames_2" name="nodenames_2">#</a><code>nodenames</code>: e.g. <code>{"ignore", "group:tree"}</code> or <code>"default:dirt"</code></li>
|
||
<li>Return value: Table with all node positions with a node air above</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_perlinnoiseparams" name="minetestget_perlinnoiseparams">#</a><code>minetest.get_perlin(noiseparams)</code></li>
|
||
<li><a class="anchor" href="#minetestget_perlinseeddiffoctavespersistencescale" name="minetestget_perlinseeddiffoctavespersistencescale">#</a><code>minetest.get_perlin(seeddiff, octaves, persistence, scale)</code><ul>
|
||
<li><a class="anchor" href="#intworldseedseeddiff" name="intworldseedseeddiff">#</a>Return world-specific perlin noise (<code>int(worldseed)+seeddiff</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_voxel_manippos1pos2" name="minetestget_voxel_manippos1pos2">#</a><code>minetest.get_voxel_manip([pos1, pos2])</code><ul>
|
||
<li>Return voxel manipulator object.</li>
|
||
<li>Loads the manipulator from the map if positions are passed.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestset_gen_notifyflagsdeco_ids" name="minetestset_gen_notifyflagsdeco_ids">#</a><code>minetest.set_gen_notify(flags, {deco_ids})</code><ul>
|
||
<li>Set the types of on-generate notifications that should be collected</li>
|
||
<li><a class="anchor" href="#flags_1" name="flags_1">#</a><code>flags</code> is a flag field with the available flags: <code>dungeon</code>, <code>temple</code>, <code>cave_begin</code>,
|
||
<code>cave_end</code>, <code>large_cave_begin</code>, <code>large_cave_end</code>, <code>decoration</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>The second parameter is a list of IDS of decorations which notification is requested for</li>
|
||
<li><a class="anchor" href="#get_gen_notify" name="get_gen_notify">#</a><code>get_gen_notify()</code>: returns a flagstring and a table with the <code>deco_id</code>s</li>
|
||
<li><a class="anchor" href="#minetestget_mapgen_objectobjectname" name="minetestget_mapgen_objectobjectname">#</a><code>minetest.get_mapgen_object(objectname)</code><ul>
|
||
<li>Return requested mapgen object if available (see "Mapgen objects")</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_biome_idbiome_name" name="minetestget_biome_idbiome_name">#</a><code>minetest.get_biome_id(biome_name)</code><ul>
|
||
<li>Returns the biome id, as used in the biomemap Mapgen object, for a
|
||
given biome_name string.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_mapgen_params" name="minetestget_mapgen_params">#</a><code>minetest.get_mapgen_params()</code> Returns mapgen parameters, a table containing
|
||
<code>mgname</code>, <code>seed</code>, <code>chunksize</code>, <code>water_level</code>, and <code>flags</code>.</li>
|
||
<li><a class="anchor" href="#minetestget_mapgen_settingname" name="minetestget_mapgen_settingname">#</a>Deprecated: use <code>minetest.get_mapgen_setting(name)</code> instead</li>
|
||
<li><a class="anchor" href="#minetestset_mapgen_paramsMapgenParams" name="minetestset_mapgen_paramsMapgenParams">#</a><code>minetest.set_mapgen_params(MapgenParams)</code><ul>
|
||
<li><a class="anchor" href="#minetestset_mapgen_settingnamevalueoverride" name="minetestset_mapgen_settingnamevalueoverride">#</a>Deprecated: use <code>minetest.set_mapgen_setting(name, value, override)</code> instead</li>
|
||
<li>Set map generation parameters</li>
|
||
<li><a class="anchor" href="#on_mapgen_init" name="on_mapgen_init">#</a>Function cannot be called after the registration period; only initialization
|
||
and <code>on_mapgen_init</code></li>
|
||
<li><a class="anchor" href="#mgname" name="mgname">#</a>Takes a table as an argument with the fields <code>mgname</code>, <code>seed</code>, <code>water_level</code>,
|
||
and <code>flags</code>.<ul>
|
||
<li>Leave field unset to leave that parameter unchanged</li>
|
||
<li><a class="anchor" href="#flags_2" name="flags_2">#</a><code>flags</code> contains a comma-delimited string of flags to set,
|
||
or if the prefix <code>"no"</code> is attached, clears instead.</li>
|
||
<li><a class="anchor" href="#flags_3" name="flags_3">#</a><code>flags</code> is in the same format and has the same options as <code>mg_flags</code> in <code>minetest.conf</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_mapgen_settingname_1" name="minetestget_mapgen_settingname_1">#</a><code>minetest.get_mapgen_setting(name)</code><ul>
|
||
<li>Gets the <em>active</em> mapgen setting (or nil if none exists) in string format with the following
|
||
order of precedence:
|
||
1) Settings loaded from map_meta.txt or overrides set during mod execution
|
||
2) Settings set by mods without a metafile override
|
||
3) Settings explicitly set in the user config file, minetest.conf
|
||
4) Settings set as the user config default</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_mapgen_setting_noiseparamsname" name="minetestget_mapgen_setting_noiseparamsname">#</a><code>minetest.get_mapgen_setting_noiseparams(name)</code><ul>
|
||
<li><a class="anchor" href="#name_10" name="name_10">#</a>Same as above, but returns the value as a NoiseParams table if the setting <code>name</code> exists
|
||
and is a valid NoiseParams</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestset_mapgen_settingnamevalueoverride_meta" name="minetestset_mapgen_settingnamevalueoverride_meta">#</a><code>minetest.set_mapgen_setting(name, value, [override_meta])</code></li>
|
||
<li><a class="anchor" href="#value" name="value">#</a>Sets a mapgen param to <code>value</code>, and will take effect if the corresponding mapgen setting
|
||
is not already present in map_meta.txt.</li>
|
||
<li><a class="anchor" href="#override_meta" name="override_meta">#</a><code>override_meta</code> is an optional boolean (default: <code>false</code>). If this is set to true,
|
||
the setting will become the active setting regardless of the map metafile contents.</li>
|
||
<li><a class="anchor" href="#seed_1" name="seed_1">#</a>Note: to set the seed, use <code>"seed"</code>, not <code>"fixed_map_seed"</code></li>
|
||
<li><a class="anchor" href="#minetestset_mapgen_setting_noiseparamsnamevalueoverride_meta" name="minetestset_mapgen_setting_noiseparamsnamevalueoverride_meta">#</a><code>minetest.set_mapgen_setting_noiseparams(name, value, [override_meta])</code></li>
|
||
<li>Same as above, except value is a NoiseParams table.</li>
|
||
<li><a class="anchor" href="#minetestset_noiseparamsnamenoiseparamsset_default" name="minetestset_noiseparamsnamenoiseparamsset_default">#</a><code>minetest.set_noiseparams(name, noiseparams, set_default)</code><ul>
|
||
<li><a class="anchor" href="#name_11" name="name_11">#</a>Sets the noiseparams setting of <code>name</code> to the noiseparams table specified in <code>noiseparams</code>.</li>
|
||
<li><a class="anchor" href="#set_default" name="set_default">#</a><code>set_default</code> is an optional boolean (default: <code>true</code>) that specifies whether the setting
|
||
should be applied to the default config or current active config</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_noiseparamsname" name="minetestget_noiseparamsname">#</a><code>minetest.get_noiseparams(name)</code>: returns a table of the noiseparams for name</li>
|
||
<li><a class="anchor" href="#minetestgenerate_oresvmpos1pos2" name="minetestgenerate_oresvmpos1pos2">#</a><code>minetest.generate_ores(vm, pos1, pos2)</code><ul>
|
||
<li><a class="anchor" href="#vm" name="vm">#</a>Generate all registered ores within the VoxelManip <code>vm</code> and in the area from <code>pos1</code> to <code>pos2</code>.</li>
|
||
<li><a class="anchor" href="#pos1" name="pos1">#</a><code>pos1</code> and <code>pos2</code> are optional and default to mapchunk minp and maxp.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestgenerate_decorationsvmpos1pos2" name="minetestgenerate_decorationsvmpos1pos2">#</a><code>minetest.generate_decorations(vm, pos1, pos2)</code><ul>
|
||
<li><a class="anchor" href="#vm_1" name="vm_1">#</a>Generate all registered decorations within the VoxelManip <code>vm</code> and in the area from <code>pos1</code> to <code>pos2</code>.</li>
|
||
<li><a class="anchor" href="#pos1_1" name="pos1_1">#</a><code>pos1</code> and <code>pos2</code> are optional and default to mapchunk minp and maxp.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclear_objectsoptions" name="minetestclear_objectsoptions">#</a><code>minetest.clear_objects([options])</code><ul>
|
||
<li>Clear all objects in the environment</li>
|
||
<li><a class="anchor" href="#mode" name="mode">#</a>Takes an optional table as an argument with the field <code>mode</code>.<ul>
|
||
<li><a class="anchor" href="#full" name="full">#</a>mode = <code>"full"</code>: Load and go through every mapblock, clearing objects (default).</li>
|
||
<li><a class="anchor" href="#quick" name="quick">#</a>mode = <code>"quick"</code>: Clear objects immediately in loaded mapblocks;
|
||
clear objects in unloaded mapblocks only when the mapblocks are next activated.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestemerge_areapos1pos2callbackparam" name="minetestemerge_areapos1pos2callbackparam">#</a><code>minetest.emerge_area(pos1, pos2, [callback], [param])</code><ul>
|
||
<li><a class="anchor" href="#pos1_2" name="pos1_2">#</a>Queue all blocks in the area from <code>pos1</code> to <code>pos2</code>, inclusive, to be asynchronously</li>
|
||
<li>fetched from memory, loaded from disk, or if inexistent, generates them.</li>
|
||
<li><a class="anchor" href="#callback" name="callback">#</a>If <code>callback</code> is a valid Lua function, this will be called for each block emerged.</li>
|
||
<li>The function signature of callback is:</li>
|
||
<li><a class="anchor" href="#functionEmergeAreaCallbackblockposactioncalls_remainingparam" name="functionEmergeAreaCallbackblockposactioncalls_remainingparam">#</a><code>function EmergeAreaCallback(blockpos, action, calls_remaining, param)</code></li>
|
||
<li><a class="anchor" href="#blockpos" name="blockpos">#</a>
|
||
<ul>
|
||
<li><a class="anchor" href="#blockpos_1" name="blockpos_1">#</a><code>blockpos</code> is the <em>block</em> coordinates of the block that had been emerged</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#action" name="action">#</a>
|
||
<ul>
|
||
<li><a class="anchor" href="#action_1" name="action_1">#</a><code>action</code> could be one of the following constant values:</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestEMERGE_CANCELLED" name="minetestEMERGE_CANCELLED">#</a><code>minetest.EMERGE_CANCELLED</code>, <code>minetest.EMERGE_ERRORED</code>, <code>minetest.EMERGE_FROM_MEMORY</code>,</li>
|
||
<li><a class="anchor" href="#minetestEMERGE_FROM_DISK" name="minetestEMERGE_FROM_DISK">#</a><code>minetest.EMERGE_FROM_DISK</code>, <code>minetest.EMERGE_GENERATED</code></li>
|
||
<li><a class="anchor" href="#calls_remaining" name="calls_remaining">#</a>
|
||
<ul>
|
||
<li><a class="anchor" href="#calls_remaining_1" name="calls_remaining_1">#</a><code>calls_remaining</code> is the number of callbacks to be expected after this one</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#param" name="param">#</a>
|
||
<ul>
|
||
<li><a class="anchor" href="#param_1" name="param_1">#</a><code>param</code> is the user-defined parameter passed to emerge_area (or nil if the</li>
|
||
</ul>
|
||
</li>
|
||
<li>parameter was absent)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdelete_areapos1pos2" name="minetestdelete_areapos1pos2">#</a><code>minetest.delete_area(pos1, pos2)</code><ul>
|
||
<li>delete all mapblocks in the area from pos1 to pos2, inclusive</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestline_of_sightpos1pos2stepsize" name="minetestline_of_sightpos1pos2stepsize">#</a><code>minetest.line_of_sight(pos1, pos2, stepsize)</code>: returns <code>boolean, pos</code><ul>
|
||
<li><a class="anchor" href="#pos1_3" name="pos1_3">#</a>Check if there is a direct line of sight between <code>pos1</code> and <code>pos2</code></li>
|
||
<li><a class="anchor" href="#false" name="false">#</a>Returns the position of the blocking node when <code>false</code></li>
|
||
<li><a class="anchor" href="#pos1_4" name="pos1_4">#</a><code>pos1</code>: First position</li>
|
||
<li><a class="anchor" href="#pos2" name="pos2">#</a><code>pos2</code>: Second position</li>
|
||
<li><a class="anchor" href="#stepsize" name="stepsize">#</a><code>stepsize</code>: smaller gives more accurate results but requires more computing
|
||
time. Default is <code>1</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestraycastpos1pos2objectsliquids" name="minetestraycastpos1pos2objectsliquids">#</a><code>minetest.raycast(pos1, pos2, objects, liquids)</code>: returns <code>Raycast</code><ul>
|
||
<li><a class="anchor" href="#Raycast" name="Raycast">#</a>Creates a <code>Raycast</code> object.</li>
|
||
<li><a class="anchor" href="#pos1_5" name="pos1_5">#</a><code>pos1</code>: start of the ray</li>
|
||
<li><a class="anchor" href="#pos2_1" name="pos2_1">#</a><code>pos2</code>: end of the ray</li>
|
||
<li><a class="anchor" href="#objects" name="objects">#</a><code>objects</code> : if false, only nodes will be returned. Default is <code>true</code>.</li>
|
||
<li><a class="anchor" href="#liquidsiffalseliquidnodeswontbereturnedDefaultis" name="liquidsiffalseliquidnodeswontbereturnedDefaultis">#</a><code>liquids' : if false, liquid nodes won't be returned. Default is</code>false`.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestfind_pathpos1pos2searchdistancemax_jumpmax_dropalgorithm" name="minetestfind_pathpos1pos2searchdistancemax_jumpmax_dropalgorithm">#</a><code>minetest.find_path(pos1,pos2,searchdistance,max_jump,max_drop,algorithm)</code><ul>
|
||
<li>returns table containing path</li>
|
||
<li><a class="anchor" href="#pos1_6" name="pos1_6">#</a>returns a table of 3D points representing a path from <code>pos1</code> to <code>pos2</code> or <code>nil</code></li>
|
||
<li><a class="anchor" href="#pos1_7" name="pos1_7">#</a><code>pos1</code>: start position</li>
|
||
<li><a class="anchor" href="#pos2_2" name="pos2_2">#</a><code>pos2</code>: end position</li>
|
||
<li><a class="anchor" href="#searchdistance" name="searchdistance">#</a><code>searchdistance</code>: number of blocks to search in each direction using a maximum metric</li>
|
||
<li><a class="anchor" href="#max_jump" name="max_jump">#</a><code>max_jump</code>: maximum height difference to consider walkable</li>
|
||
<li><a class="anchor" href="#max_drop" name="max_drop">#</a><code>max_drop</code>: maximum height difference to consider droppable</li>
|
||
<li><a class="anchor" href="#algorithm" name="algorithm">#</a><code>algorithm</code>: One of <code>"A*_noprefetch"</code> (default), <code>"A*"</code>, <code>"Dijkstra"</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestspawn_treepostreedef" name="minetestspawn_treepostreedef">#</a><code>minetest.spawn_tree (pos, {treedef})</code><ul>
|
||
<li><a class="anchor" href="#pos_1" name="pos_1">#</a>spawns L-system tree at given <code>pos</code> with definition in <code>treedef</code> table</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetesttransforming_liquid_addpos" name="minetesttransforming_liquid_addpos">#</a><code>minetest.transforming_liquid_add(pos)</code><ul>
|
||
<li>add node to liquid update queue</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_node_max_levelpos" name="minetestget_node_max_levelpos">#</a><code>minetest.get_node_max_level(pos)</code><ul>
|
||
<li>get max available level for leveled node</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_node_levelpos" name="minetestget_node_levelpos">#</a><code>minetest.get_node_level(pos)</code><ul>
|
||
<li>get level of leveled node (water, snow)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestset_node_levelposlevel" name="minetestset_node_levelposlevel">#</a><code>minetest.set_node_level(pos, level)</code><ul>
|
||
<li><a class="anchor" href="#level_3" name="level_3">#</a>set level of leveled node, default <code>level</code> equals <code>1</code></li>
|
||
<li><a class="anchor" href="#totallevelmaxlevel" name="totallevelmaxlevel">#</a>if <code>totallevel > maxlevel</code>, returns rest (<code>total-max</code>).</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestadd_node_levelposlevel" name="minetestadd_node_levelposlevel">#</a><code>minetest.add_node_level(pos, level)</code><ul>
|
||
<li><a class="anchor" href="#level_4" name="level_4">#</a>increase level of leveled node by level, default <code>level</code> equals <code>1</code></li>
|
||
<li><a class="anchor" href="#totallevelmaxlevel_1" name="totallevelmaxlevel_1">#</a>if <code>totallevel > maxlevel</code>, returns rest (<code>total-max</code>)</li>
|
||
<li>can be negative for decreasing</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestfix_lightpos1pos2" name="minetestfix_lightpos1pos2">#</a><code>minetest.fix_light(pos1, pos2)</code>: returns <code>true</code>/<code>false</code><ul>
|
||
<li>resets the light in a cuboid-shaped part of
|
||
the map and removes lighting bugs.</li>
|
||
<li>Loads the area if it is not loaded.</li>
|
||
<li><a class="anchor" href="#pos1_8" name="pos1_8">#</a><code>pos1</code> is the corner of the cuboid with the least coordinates
|
||
(in node coordinates), inclusive.</li>
|
||
<li><a class="anchor" href="#pos2_3" name="pos2_3">#</a><code>pos2</code> is the opposite corner of the cuboid, inclusive.</li>
|
||
<li>The actual updated cuboid might be larger than the specified one,
|
||
because only whole map blocks can be updated.
|
||
The actual updated area consists of those map blocks that intersect
|
||
with the given cuboid.</li>
|
||
<li>However, the neighborhood of the updated area might change
|
||
as well, as light can spread out of the cuboid, also light
|
||
might be removed.</li>
|
||
<li><a class="anchor" href="#false_1" name="false_1">#</a>returns <code>false</code> if the area is not fully generated,
|
||
<code>true</code> otherwise</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestcheck_single_for_fallingpos" name="minetestcheck_single_for_fallingpos">#</a><code>minetest.check_single_for_falling(pos)</code><ul>
|
||
<li><a class="anchor" href="#groupfalling_node" name="groupfalling_node">#</a>causes an unsupported <code>group:falling_node</code> node to fall and causes an
|
||
unattached <code>group:attached_node</code> node to fall.</li>
|
||
<li>does not spread these updates to neighbours.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestcheck_for_fallingpos" name="minetestcheck_for_fallingpos">#</a><code>minetest.check_for_falling(pos)</code><ul>
|
||
<li><a class="anchor" href="#groupfalling_node_1" name="groupfalling_node_1">#</a>causes an unsupported <code>group:falling_node</code> node to fall and causes an
|
||
unattached <code>group:attached_node</code> node to fall.</li>
|
||
<li>spread these updates to neighbours and can cause a cascade
|
||
of nodes to fall.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="inventory_1">Inventory</h3>
|
||
<p><code>minetest.get_inventory(location)</code>: returns an <code>InvRef</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#location" name="location">#</a><code>location</code> = e.g.<ul>
|
||
<li><a class="anchor" href="#typeplayernameceleron55" name="typeplayernameceleron55">#</a><code>{type="player", name="celeron55"}</code></li>
|
||
<li><a class="anchor" href="#typenodeposxyz" name="typenodeposxyz">#</a><code>{type="node", pos={x=, y=, z=}}</code></li>
|
||
<li><a class="anchor" href="#typedetachednamecreative" name="typedetachednamecreative">#</a><code>{type="detached", name="creative"}</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestcreate_detached_inventorynamecallbacksplayer_name" name="minetestcreate_detached_inventorynamecallbacksplayer_name">#</a><code>minetest.create_detached_inventory(name, callbacks, [player_name])</code>: returns an <code>InvRef</code><ul>
|
||
<li>callbacks: See "Detached inventory callbacks"</li>
|
||
<li><a class="anchor" href="#player_name" name="player_name">#</a><code>player_name</code>: 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.</li>
|
||
<li>Creates a detached inventory. If it already exists, it is cleared.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdo_item_eathp_changereplace_with_itemitemstackuserpointed_thing" name="minetestdo_item_eathp_changereplace_with_itemitemstackuserpointed_thing">#</a><code>minetest.do_item_eat(hp_change, replace_with_item, itemstack, user, pointed_thing)</code>:
|
||
returns left over ItemStack<ul>
|
||
<li><a class="anchor" href="#minetestitem_eat_1" name="minetestitem_eat_1">#</a>See <code>minetest.item_eat</code> and <code>minetest.register_on_item_eat</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="formspec_1">Formspec</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestshow_formspecplayernameformnameformspec" name="minetestshow_formspecplayernameformnameformspec">#</a><code>minetest.show_formspec(playername, formname, formspec)</code><ul>
|
||
<li><a class="anchor" href="#playername_1" name="playername_1">#</a><code>playername</code>: name of player to show formspec</li>
|
||
<li><a class="anchor" href="#formname" name="formname">#</a><code>formname</code>: name passed to <code>on_player_receive_fields</code> callbacks.
|
||
It should follow the <code>"modname:<whatever>"</code> naming convention</li>
|
||
<li><a class="anchor" href="#formspec_3" name="formspec_3">#</a><code>formspec</code>: formspec to display</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestclose_formspecplayernameformname" name="minetestclose_formspecplayernameformname">#</a><code>minetest.close_formspec(playername, formname)</code><ul>
|
||
<li><a class="anchor" href="#playername_2" name="playername_2">#</a><code>playername</code>: name of player to close formspec</li>
|
||
<li><a class="anchor" href="#formname_1" name="formname_1">#</a><code>formname</code>: has to exactly match the one given in <code>show_formspec</code>, or the formspec will
|
||
not close.</li>
|
||
<li><a class="anchor" href="#show_formspecplayernameformname" name="show_formspecplayernameformname">#</a>calling <code>show_formspec(playername, formname, "")</code> is equal to this expression</li>
|
||
<li><a class="anchor" href="#minetestclose_formspecplayername" name="minetestclose_formspecplayername">#</a>to close a formspec regardless of the formname, call
|
||
<code>minetest.close_formspec(playername, "")</code>. <strong>USE THIS ONLY WHEN ABSOLUTELY NECESSARY!</strong></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestformspec_escapestring_1" name="minetestformspec_escapestring_1">#</a><code>minetest.formspec_escape(string)</code>: returns a string<ul>
|
||
<li>escapes the characters "[", "]", "\", "," and ";", which can not be used in formspecs</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestexplode_table_eventstring" name="minetestexplode_table_eventstring">#</a><code>minetest.explode_table_event(string)</code>: returns a table<ul>
|
||
<li><a class="anchor" href="#typeCHGrow1column2" name="typeCHGrow1column2">#</a>returns e.g. <code>{type="CHG", row=1, column=2}</code></li>
|
||
<li><a class="anchor" href="#type" name="type">#</a><code>type</code> is one of:<ul>
|
||
<li><a class="anchor" href="#INV" name="INV">#</a><code>"INV"</code>: no row selected)</li>
|
||
<li><a class="anchor" href="#CHG" name="CHG">#</a><code>"CHG"</code>: selected)</li>
|
||
<li><a class="anchor" href="#DCL" name="DCL">#</a><code>"DCL"</code>: double-click</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestexplode_textlist_eventstring" name="minetestexplode_textlist_eventstring">#</a><code>minetest.explode_textlist_event(string)</code>: returns a table<ul>
|
||
<li><a class="anchor" href="#typeCHGindex1" name="typeCHGindex1">#</a>returns e.g. <code>{type="CHG", index=1}</code></li>
|
||
<li><a class="anchor" href="#type_1" name="type_1">#</a><code>type</code> is one of:<ul>
|
||
<li><a class="anchor" href="#INV_1" name="INV_1">#</a><code>"INV"</code>: no row selected)</li>
|
||
<li><a class="anchor" href="#CHG_1" name="CHG_1">#</a><code>"CHG"</code>: selected)</li>
|
||
<li><a class="anchor" href="#DCL_1" name="DCL_1">#</a><code>"DCL"</code>: double-click</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestexplode_scrollbar_eventstring" name="minetestexplode_scrollbar_eventstring">#</a><code>minetest.explode_scrollbar_event(string)</code>: returns a table<ul>
|
||
<li><a class="anchor" href="#typeCHGvalue500" name="typeCHGvalue500">#</a>returns e.g. <code>{type="CHG", value=500}</code></li>
|
||
<li><a class="anchor" href="#type_2" name="type_2">#</a><code>type</code> is one of:<ul>
|
||
<li><a class="anchor" href="#INV_2" name="INV_2">#</a><code>"INV"</code>: something failed</li>
|
||
<li><a class="anchor" href="#CHG_2" name="CHG_2">#</a><code>"CHG"</code>: has been changed</li>
|
||
<li><a class="anchor" href="#VAL" name="VAL">#</a><code>"VAL"</code>: not changed</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="item-handling">Item handling</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestinventorycubeimg1img2img3" name="minetestinventorycubeimg1img2img3">#</a><code>minetest.inventorycube(img1, img2, img3)</code><ul>
|
||
<li>Returns a string for making an image of a cube (useful as an item image)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_pointed_thing_positionpointed_thingabove" name="minetestget_pointed_thing_positionpointed_thingabove">#</a><code>minetest.get_pointed_thing_position(pointed_thing, above)</code><ul>
|
||
<li><a class="anchor" href="#pointed_thing_1" name="pointed_thing_1">#</a>Get position of a <code>pointed_thing</code> (that you can get from somewhere)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdir_to_facedirdiris6d" name="minetestdir_to_facedirdiris6d">#</a><code>minetest.dir_to_facedir(dir, is6d)</code><ul>
|
||
<li><a class="anchor" href="#param2_1" name="param2_1">#</a>Convert a vector to a facedir value, used in <code>param2</code> for <code>paramtype2="facedir"</code>;</li>
|
||
<li><a class="anchor" href="#nil_1" name="nil_1">#</a>passing something non-<code>nil</code>/<code>false</code> for the optional second parameter causes it to
|
||
take the y component into account</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestfacedir_to_dirfacedir" name="minetestfacedir_to_dirfacedir">#</a><code>minetest.facedir_to_dir(facedir)</code><ul>
|
||
<li>Convert a facedir back into a vector aimed directly out the "back" of a node</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdir_to_wallmounteddir" name="minetestdir_to_wallmounteddir">#</a><code>minetest.dir_to_wallmounted(dir)</code><ul>
|
||
<li><a class="anchor" href="#paramtype2wallmounted" name="paramtype2wallmounted">#</a>Convert a vector to a wallmounted value, used for <code>paramtype2="wallmounted"</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestwallmounted_to_dirwallmounted" name="minetestwallmounted_to_dirwallmounted">#</a><code>minetest.wallmounted_to_dir(wallmounted)</code><ul>
|
||
<li>Convert a wallmounted value back into a vector aimed directly out the "back" of a node</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdir_to_yawdir" name="minetestdir_to_yawdir">#</a><code>minetest.dir_to_yaw(dir)</code><ul>
|
||
<li>Convert a vector into a yaw (angle)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestyaw_to_diryaw" name="minetestyaw_to_diryaw">#</a><code>minetest.yaw_to_dir(yaw)</code><ul>
|
||
<li>Convert yaw (angle) to a vector</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_node_dropsnodenametoolname" name="minetestget_node_dropsnodenametoolname">#</a><code>minetest.get_node_drops(nodename, toolname)</code><ul>
|
||
<li>Returns list of item names.</li>
|
||
<li><strong>Note</strong>: This will be removed or modified in a future version.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_craft_resultinput" name="minetestget_craft_resultinput">#</a><code>minetest.get_craft_result(input)</code>: returns <code>output, decremented_input</code><ul>
|
||
<li><a class="anchor" href="#inputmethod" name="inputmethod">#</a><code>input.method</code> = <code>"normal"</code> or <code>"cooking"</code> or <code>"fuel"</code></li>
|
||
<li><a class="anchor" href="#inputwidth" name="inputwidth">#</a><code>input.width</code> = for example <code>3</code></li>
|
||
<li><a class="anchor" href="#inputitems" name="inputitems">#</a><code>input.items</code> = for example
|
||
<code>{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }</code></li>
|
||
<li><a class="anchor" href="#outputitem" name="outputitem">#</a><code>output.item</code> = <code>ItemStack</code>, if unsuccessful: empty <code>ItemStack</code></li>
|
||
<li><a class="anchor" href="#outputtime" name="outputtime">#</a><code>output.time</code> = a number, if unsuccessful: <code>0</code></li>
|
||
<li><a class="anchor" href="#outputreplacements" name="outputreplacements">#</a><code>output.replacements</code> = list of <code>ItemStack</code>s that couldn't be placed in
|
||
<code>decremented_input.items</code></li>
|
||
<li><a class="anchor" href="#decremented_input" name="decremented_input">#</a><code>decremented_input</code> = like <code>input</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_craft_recipeoutput" name="minetestget_craft_recipeoutput">#</a><code>minetest.get_craft_recipe(output)</code>: returns input<ul>
|
||
<li>returns last registered recipe for output item (node)</li>
|
||
<li><a class="anchor" href="#output" name="output">#</a><code>output</code> is a node or item type such as <code>"default:torch"</code></li>
|
||
<li><a class="anchor" href="#inputmethod_1" name="inputmethod_1">#</a><code>input.method</code> = <code>"normal"</code> or <code>"cooking"</code> or <code>"fuel"</code></li>
|
||
<li><a class="anchor" href="#inputwidth_1" name="inputwidth_1">#</a><code>input.width</code> = for example <code>3</code></li>
|
||
<li><a class="anchor" href="#inputitems_1" name="inputitems_1">#</a><code>input.items</code> = for example
|
||
<code>{ stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9 }</code></li>
|
||
<li><a class="anchor" href="#inputitems_2" name="inputitems_2">#</a><code>input.items</code> = <code>nil</code> if no recipe found</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_all_craft_recipesqueryitem" name="minetestget_all_craft_recipesqueryitem">#</a><code>minetest.get_all_craft_recipes(query item)</code>: returns a table or <code>nil</code><ul>
|
||
<li><a class="anchor" href="#nil_2" name="nil_2">#</a>returns indexed table with all registered recipes for query item (node)
|
||
or <code>nil</code> if no recipe was found</li>
|
||
<li><a class="anchor" href="#methodnormalorcookingorfuelwidth030meansshapelessrecipeitemsindexed19tablewithrecipeitemsoutputstringwithitemnameandquantityExamplequeryfordefaultgold_ingotwillreturntable1methodcookingwidth3outputdefaultgold_ingotitems1defaultgold_lump2methodnormalwidth1outputdefaultgold_ingot9items1defaultgoldblock" name="methodnormalorcookingorfuelwidth030meansshapelessrecipeitemsindexed19tablewithrecipeitemsoutputstringwithitemnameandquantityExamplequeryfordefaultgold_ingotwillreturntable1methodcookingwidth3outputdefaultgold_ingotitems1defaultgold_lump2methodnormalwidth1outputdefaultgold_ingot9items1defaultgoldblock">#</a>recipe entry table:<pre><code>{
|
||
method = 'normal' or 'cooking' or 'fuel'
|
||
width = 0-3, 0 means shapeless recipe
|
||
items = indexed [1-9] table with recipe items
|
||
output = string with item name and quantity
|
||
}
|
||
* Example query for `"default:gold_ingot"` will return table:
|
||
|
||
{
|
||
[1]={method = "cooking", width = 3, output = "default:gold_ingot",
|
||
items = {1 = "default:gold_lump"}},
|
||
[2]={method = "normal", width = 1, output = "default:gold_ingot 9",
|
||
items = {1 = "default:goldblock"}}
|
||
}
|
||
</code></pre>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetesthandle_node_dropsposdropsdigger" name="minetesthandle_node_dropsposdropsdigger">#</a><code>minetest.handle_node_drops(pos, drops, digger)</code><ul>
|
||
<li><a class="anchor" href="#drops" name="drops">#</a><code>drops</code>: list of itemstrings</li>
|
||
<li>Handles drops from nodes after digging: Default action is to put them into
|
||
digger's inventory</li>
|
||
<li>Can be overridden to get different functionality (e.g. dropping items on
|
||
ground)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestitemstring_with_paletteitempalette_index" name="minetestitemstring_with_paletteitempalette_index">#</a><code>minetest.itemstring_with_palette(item, palette_index)</code>: returns an item string<ul>
|
||
<li>Creates an item string which contains palette index information
|
||
for hardware colorization. You can use the returned string
|
||
as an output in a craft recipe.</li>
|
||
<li><a class="anchor" href="#item_1" name="item_1">#</a><code>item</code>: the item stack which becomes colored. Can be in string,
|
||
table and native form.</li>
|
||
<li><a class="anchor" href="#palette_index_1" name="palette_index_1">#</a><code>palette_index</code>: this index is added to the item stack</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestitemstring_with_coloritemcolorstring" name="minetestitemstring_with_coloritemcolorstring">#</a><code>minetest.itemstring_with_color(item, colorstring)</code>: returns an item string<ul>
|
||
<li>Creates an item string which contains static color information
|
||
for hardware colorization. Use this method if you wish to colorize
|
||
an item that does not own a palette. You can use the returned string
|
||
as an output in a craft recipe.</li>
|
||
<li><a class="anchor" href="#item_2" name="item_2">#</a><code>item</code>: the item stack which becomes colored. Can be in string,
|
||
table and native form.</li>
|
||
<li><a class="anchor" href="#colorstring_1" name="colorstring_1">#</a><code>colorstring</code>: the new color of the item stack</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="rollback">Rollback</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestrollback_get_node_actionsposrangesecondslimit" name="minetestrollback_get_node_actionsposrangesecondslimit">#</a><code>minetest.rollback_get_node_actions(pos, range, seconds, limit)</code>:
|
||
returns <code>{ {actor, pos, time, oldnode, newnode}, ...}</code><ul>
|
||
<li>Find who has done something to a node, or near a node</li>
|
||
<li><a class="anchor" href="#actor" name="actor">#</a><code>actor</code>: <code>"player:<name>"</code>, also <code>"liquid"</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestrollback_revert_actions_byactorseconds" name="minetestrollback_revert_actions_byactorseconds">#</a><code>minetest.rollback_revert_actions_by(actor, seconds)</code>: returns <code>boolean, log_messages</code><ul>
|
||
<li>Revert latest actions of someone</li>
|
||
<li><a class="anchor" href="#actor_1" name="actor_1">#</a><code>actor</code>: <code>"player:<name>"</code>, also <code>"liquid"</code>.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="defaults-for-the-on_-item-definition-functions">Defaults for the <code>on_*</code> item definition functions</h3>
|
||
<p>These functions return the leftover itemstack.</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestitem_place_nodeitemstackplacerpointed_thingparam2" name="minetestitem_place_nodeitemstackplacerpointed_thingparam2">#</a><code>minetest.item_place_node(itemstack, placer, pointed_thing, param2)</code><ul>
|
||
<li>Place item as a node</li>
|
||
<li><a class="anchor" href="#param2_2" name="param2_2">#</a><code>param2</code> overrides <code>facedir</code> and wallmounted <code>param2</code></li>
|
||
<li><a class="anchor" href="#itemstacksuccess" name="itemstacksuccess">#</a>returns <code>itemstack, success</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestitem_place_objectitemstackplacerpointed_thing" name="minetestitem_place_objectitemstackplacerpointed_thing">#</a><code>minetest.item_place_object(itemstack, placer, pointed_thing)</code><ul>
|
||
<li>Place item as-is</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestitem_placeitemstackplacerpointed_thingparam2" name="minetestitem_placeitemstackplacerpointed_thingparam2">#</a><code>minetest.item_place(itemstack, placer, pointed_thing, param2)</code><ul>
|
||
<li>Use one of the above based on what the item is.</li>
|
||
<li><a class="anchor" href="#on_rightclick" name="on_rightclick">#</a>Calls <code>on_rightclick</code> of <code>pointed_thing.under</code> if defined instead</li>
|
||
<li><a class="anchor" href="#on_place" name="on_place">#</a><strong>Note</strong>: is not called when wielded item overrides <code>on_place</code></li>
|
||
<li><a class="anchor" href="#param2_3" name="param2_3">#</a><code>param2</code> overrides <code>facedir</code> and wallmounted <code>param2</code></li>
|
||
<li><a class="anchor" href="#itemstacksuccess_1" name="itemstacksuccess_1">#</a>returns <code>itemstack, success</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestitem_dropitemstackdropperpos" name="minetestitem_dropitemstackdropperpos">#</a><code>minetest.item_drop(itemstack, dropper, pos)</code><ul>
|
||
<li>Drop the item</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestitem_eathp_changereplace_with_item" name="minetestitem_eathp_changereplace_with_item">#</a><code>minetest.item_eat(hp_change, replace_with_item)</code><ul>
|
||
<li>Eat the item.</li>
|
||
<li><a class="anchor" href="#replace_with_item" name="replace_with_item">#</a><code>replace_with_item</code> is the itemstring which is added to the inventory.
|
||
If the player is eating a stack, then replace_with_item goes to a
|
||
different spot. Can be <code>nil</code></li>
|
||
<li><a class="anchor" href="#minetestdo_item_eat" name="minetestdo_item_eat">#</a>See <code>minetest.do_item_eat</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="defaults-for-the-on_punch-and-on_dig-node-definition-callbacks">Defaults for the <code>on_punch</code> and <code>on_dig</code> node definition callbacks</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestnode_punchposnodepuncherpointed_thing" name="minetestnode_punchposnodepuncherpointed_thing">#</a><code>minetest.node_punch(pos, node, puncher, pointed_thing)</code><ul>
|
||
<li><a class="anchor" href="#minetestregister_on_punchnode" name="minetestregister_on_punchnode">#</a>Calls functions registered by <code>minetest.register_on_punchnode()</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestnode_digposnodedigger" name="minetestnode_digposnodedigger">#</a><code>minetest.node_dig(pos, node, digger)</code><ul>
|
||
<li>Checks if node can be dug, puts item into inventory, removes node</li>
|
||
<li><a class="anchor" href="#minetestregistered_on_dignodes" name="minetestregistered_on_dignodes">#</a>Calls functions registered by <code>minetest.registered_on_dignodes()</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="sounds_1">Sounds</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestsound_playspecparameters" name="minetestsound_playspecparameters">#</a><code>minetest.sound_play(spec, parameters)</code>: returns a handle<ul>
|
||
<li><a class="anchor" href="#spec" name="spec">#</a><code>spec</code> is a <code>SimpleSoundSpec</code></li>
|
||
<li><a class="anchor" href="#parameters" name="parameters">#</a><code>parameters</code> is a sound parameter table</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestsound_stophandle" name="minetestsound_stophandle">#</a><code>minetest.sound_stop(handle)</code></li>
|
||
<li><a class="anchor" href="#minetestsound_fadehandlestepgain" name="minetestsound_fadehandlestepgain">#</a><code>minetest.sound_fade(handle, step, gain)</code><ul>
|
||
<li><a class="anchor" href="#handle" name="handle">#</a><code>handle</code> is a handle returned by <code>minetest.sound_play</code></li>
|
||
<li><a class="anchor" href="#step" name="step">#</a><code>step</code> determines how fast a sound will fade.
|
||
Negative step will lower the sound volume, positive step will increase the sound volume</li>
|
||
<li><a class="anchor" href="#gain" name="gain">#</a><code>gain</code> the target gain for the fade.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="timing">Timing</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestaftertimefunc" name="minetestaftertimefunc">#</a><code>minetest.after(time, func, ...)</code><ul>
|
||
<li><a class="anchor" href="#func" name="func">#</a>Call the function <code>func</code> after <code>time</code> seconds, may be fractional</li>
|
||
<li><a class="anchor" href="#func_1" name="func_1">#</a>Optional: Variable number of arguments that are passed to <code>func</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="server">Server</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestrequest_shutdownmessagereconnectdelay" name="minetestrequest_shutdownmessagereconnectdelay">#</a><code>minetest.request_shutdown([message],[reconnect],[delay])</code>: request for server shutdown. Will display <code>message</code> to clients,
|
||
<code>reconnect</code> == true displays a reconnect button,
|
||
<code>delay</code> adds an optional delay (in seconds) before shutdown
|
||
negative delay cancels the current active shutdown
|
||
zero delay triggers an immediate shutdown.</li>
|
||
<li><a class="anchor" href="#minetestcancel_shutdown_requests" name="minetestcancel_shutdown_requests">#</a><code>minetest.cancel_shutdown_requests()</code>: cancel current delayed shutdown</li>
|
||
<li><a class="anchor" href="#minetestget_server_status" name="minetestget_server_status">#</a><code>minetest.get_server_status()</code>: returns server status string</li>
|
||
<li><a class="anchor" href="#minetestget_server_uptime" name="minetestget_server_uptime">#</a><code>minetest.get_server_uptime()</code>: returns the server uptime in seconds</li>
|
||
<li><a class="anchor" href="#minetestremove_playername" name="minetestremove_playername">#</a><code>minetest.remove_player(name)</code>: remove player from database (if he is not connected).<ul>
|
||
<li>Does not remove player authentication data, minetest.player_exists will continue to return true.</li>
|
||
<li>Returns a code (0: successful, 1: no such player, 2: player is connected)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="bans">Bans</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestget_ban_list" name="minetestget_ban_list">#</a><code>minetest.get_ban_list()</code>: returns the ban list (same as <code>minetest.get_ban_description("")</code>)</li>
|
||
<li><a class="anchor" href="#minetestget_ban_descriptionip_or_name" name="minetestget_ban_descriptionip_or_name">#</a><code>minetest.get_ban_description(ip_or_name)</code>: returns ban description (string)</li>
|
||
<li><a class="anchor" href="#minetestban_playername" name="minetestban_playername">#</a><code>minetest.ban_player(name)</code>: ban a player</li>
|
||
<li><a class="anchor" href="#minetestunban_player_or_ipname" name="minetestunban_player_or_ipname">#</a><code>minetest.unban_player_or_ip(name)</code>: unban player or IP address</li>
|
||
<li><a class="anchor" href="#minetestkick_playernamereason" name="minetestkick_playernamereason">#</a><code>minetest.kick_player(name, [reason])</code>: disconnect a player with a optional reason</li>
|
||
</ul>
|
||
<h3 id="particles">Particles</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestadd_particleparticledefinition" name="minetestadd_particleparticledefinition">#</a>
|
||
<p><code>minetest.add_particle(particle definition)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestadd_particleposvelocityaccelerationexpirationtimesizecollisiondetectiontextureplayername" name="minetestadd_particleposvelocityaccelerationexpirationtimesizecollisiondetectiontextureplayername">#</a>Deprecated: <code>minetest.add_particle(pos, velocity, acceleration, expirationtime,
|
||
size, collisiondetection, texture, playername)</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestadd_particlespawnerparticlespawnerdefinition" name="minetestadd_particlespawnerparticlespawnerdefinition">#</a>
|
||
<p><code>minetest.add_particlespawner(particlespawner definition)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#ParticleSpawner" name="ParticleSpawner">#</a>Add a <code>ParticleSpawner</code>, an object that spawns an amount of particles over <code>time</code> seconds</li>
|
||
<li><a class="anchor" href="#id" name="id">#</a>Returns an <code>id</code>, and -1 if adding didn't succeed</li>
|
||
<li><a class="anchor" href="#Deprecatedminetestadd_particlespawneramounttimeminposmaxposminvelmaxvelminaccmaxaccminexptimemaxexptimeminsizemaxsizecollisiondetectiontextureplayername" name="Deprecatedminetestadd_particlespawneramounttimeminposmaxposminvelmaxvelminaccmaxaccminexptimemaxexptimeminsizemaxsizecollisiondetectiontextureplayername">#</a><code>Deprecated: minetest.add_particlespawner(amount, time,
|
||
minpos, maxpos,
|
||
minvel, maxvel,
|
||
minacc, maxacc,
|
||
minexptime, maxexptime,
|
||
minsize, maxsize,
|
||
collisiondetection, texture, playername)</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdelete_particlespawneridplayer" name="minetestdelete_particlespawneridplayer">#</a>
|
||
<p><code>minetest.delete_particlespawner(id, player)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#ParticleSpawner_1" name="ParticleSpawner_1">#</a>Delete <code>ParticleSpawner</code> with <code>id</code> (return value from <code>minetest.add_particlespawner</code>)</li>
|
||
<li>If playername is specified, only deletes on the player's client,</li>
|
||
<li>otherwise on all clients</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="schematics">Schematics</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestcreate_schematicp1p2probability_listfilenameslice_prob_list" name="minetestcreate_schematicp1p2probability_listfilenameslice_prob_list">#</a>
|
||
<p><code>minetest.create_schematic(p1, p2, probability_list, filename, slice_prob_list)</code></p>
|
||
<ul>
|
||
<li>Create a schematic from the volume of map specified by the box formed by p1 and p2.</li>
|
||
<li><a class="anchor" href="#probability_list" name="probability_list">#</a>Apply the specified probability and per-node force-place to the specified nodes
|
||
according to the <code>probability_list</code>.<ul>
|
||
<li><a class="anchor" href="#probability_list_1" name="probability_list_1">#</a><code>probability_list</code> is an array of tables containing two fields, <code>pos</code> and <code>prob</code>.<ul>
|
||
<li><a class="anchor" href="#pos_2" name="pos_2">#</a><code>pos</code> is the 3D vector specifying the absolute coordinates of the
|
||
node being modified,</li>
|
||
<li><a class="anchor" href="#prob_1" name="prob_1">#</a><code>prob</code> is an integer value from <code>0</code> to <code>255</code> that encodes probability and
|
||
per-node force-place. Probability has levels 0-127, then 128 is added to
|
||
encode per-node force-place.
|
||
For probability stated as 0-255, divide by 2 and round down to get values
|
||
0-127, then add 128 to apply per-node force-place.</li>
|
||
<li>If there are two or more entries with the same pos value, the
|
||
last entry is used.</li>
|
||
<li><a class="anchor" href="#pos_3" name="pos_3">#</a>If <code>pos</code> is not inside the box formed by <code>p1</code> and <code>p2</code>, it is ignored.</li>
|
||
<li><a class="anchor" href="#probability_list_2" name="probability_list_2">#</a>If <code>probability_list</code> equals <code>nil</code>, no probabilities are applied.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#slice_prob_list" name="slice_prob_list">#</a>Apply the specified probability to the specified horizontal slices according to the
|
||
<code>slice_prob_list</code>.<ul>
|
||
<li><a class="anchor" href="#slice_prob_list_1" name="slice_prob_list_1">#</a><code>slice_prob_list</code> is an array of tables containing two fields, <code>ypos</code> and <code>prob</code>.<ul>
|
||
<li><a class="anchor" href="#ypos" name="ypos">#</a><code>ypos</code> indicates the y position of the slice with a probability applied,
|
||
the lowest slice being <code>ypos = 0</code>.</li>
|
||
<li><a class="anchor" href="#nil_3" name="nil_3">#</a>If slice probability list equals <code>nil</code>, no slice probabilities are applied.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>Saves schematic in the Minetest Schematic format to filename.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestplace_schematicposschematicrotationreplacementsforce_placement" name="minetestplace_schematicposschematicrotationreplacementsforce_placement">#</a>
|
||
<p><code>minetest.place_schematic(pos, schematic, rotation, replacements, force_placement)</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#pos_4" name="pos_4">#</a>Place the schematic specified by schematic (see: Schematic specifier) at <code>pos</code>.</li>
|
||
<li><a class="anchor" href="#rotation" name="rotation">#</a><code>rotation</code> can equal <code>"0"</code>, <code>"90"</code>, <code>"180"</code>, <code>"270"</code>, or <code>"random"</code>.</li>
|
||
<li><a class="anchor" href="#rotation_1" name="rotation_1">#</a>If the <code>rotation</code> parameter is omitted, the schematic is not rotated.</li>
|
||
<li><a class="anchor" href="#replacements" name="replacements">#</a><code>replacements</code> = <code>{["old_name"] = "convert_to", ...}</code></li>
|
||
<li><a class="anchor" href="#force_placement_1" name="force_placement_1">#</a><code>force_placement</code> is a boolean indicating whether nodes other than <code>air</code> and
|
||
<code>ignore</code> are replaced by the schematic</li>
|
||
<li>Returns nil if the schematic could not be loaded.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestplace_schematic_on_vmanipvmanipposschematicrotationreplacementforce_placement" name="minetestplace_schematic_on_vmanipvmanipposschematicrotationreplacementforce_placement">#</a>
|
||
<p><code>minetest.place_schematic_on_vmanip(vmanip, pos, schematic, rotation, replacement, force_placement)</code>:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#vmanip" name="vmanip">#</a>This function is analagous to minetest.place_schematic, but places a schematic onto the
|
||
specified VoxelManip object <code>vmanip</code> instead of the whole map.</li>
|
||
<li>Returns false if any part of the schematic was cut-off due to the VoxelManip not
|
||
containing the full area required, and true if the whole schematic was able to fit.</li>
|
||
<li>Returns nil if the schematic could not be loaded.</li>
|
||
<li>After execution, any external copies of the VoxelManip contents are invalidated.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestserialize_schematicschematicformatoptions" name="minetestserialize_schematicschematicformatoptions">#</a>
|
||
<p><code>minetest.serialize_schematic(schematic, format, options)</code></p>
|
||
<ul>
|
||
<li>Return the serialized schematic specified by schematic (see: Schematic specifier)</li>
|
||
<li><a class="anchor" href="#format" name="format">#</a>in the <code>format</code> of either "mts" or "lua".</li>
|
||
<li>"mts" - a string containing the binary MTS data used in the MTS file format</li>
|
||
<li>"lua" - a string containing Lua code representing the schematic in table format</li>
|
||
<li><a class="anchor" href="#options" name="options">#</a><code>options</code> is a table containing the following optional parameters:</li>
|
||
<li><a class="anchor" href="#lua_use_comments" name="lua_use_comments">#</a>If <code>lua_use_comments</code> is true and <code>format</code> is "lua", the Lua code generated will have (X, Z)</li>
|
||
<li>position comments for every X row generated in the schematic data for easier reading.</li>
|
||
<li><a class="anchor" href="#lua_num_indent_spaces" name="lua_num_indent_spaces">#</a>If <code>lua_num_indent_spaces</code> is a nonzero number and <code>format</code> is "lua", the Lua code generated</li>
|
||
<li>will use that number of spaces as indentation instead of a tab character.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="http-requests">HTTP Requests:</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestrequest_http_api" name="minetestrequest_http_api">#</a><code>minetest.request_http_api()</code>:<ul>
|
||
<li><a class="anchor" href="#HTTPApiTable" name="HTTPApiTable">#</a>returns <code>HTTPApiTable</code> containing http functions if the calling mod has been granted
|
||
access by being listed in the <code>secure.http_mods</code> or <code>secure.trusted_mods</code> setting,
|
||
otherwise returns <code>nil</code>.</li>
|
||
<li><a class="anchor" href="#fetch" name="fetch">#</a>The returned table contains the functions <code>fetch</code>, <code>fetch_async</code> and <code>fetch_async_get</code>
|
||
described below.</li>
|
||
<li>Only works at init time and must be called from the mod's main scope (not from a function).</li>
|
||
<li>Function only exists if minetest server was built with cURL support.</li>
|
||
<li><strong>DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED TABLE, STORE IT IN
|
||
A LOCAL VARIABLE!</strong></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#HTTPApiTablefetchHTTPRequestreqcallback" name="HTTPApiTablefetchHTTPRequestreqcallback">#</a><code>HTTPApiTable.fetch(HTTPRequest req, callback)</code><ul>
|
||
<li>Performs given request asynchronously and calls callback upon completion</li>
|
||
<li><a class="anchor" href="#functionHTTPRequestResultres" name="functionHTTPRequestResultres">#</a>callback: <code>function(HTTPRequestResult res)</code></li>
|
||
<li>Use this HTTP function if you are unsure, the others are for advanced use.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#HTTPApiTablefetch_asyncHTTPRequestreq" name="HTTPApiTablefetch_asyncHTTPRequestreq">#</a><code>HTTPApiTable.fetch_async(HTTPRequest req)</code>: returns handle<ul>
|
||
<li><a class="anchor" href="#HTTPApiTablefetch_async_get" name="HTTPApiTablefetch_async_get">#</a>Performs given request asynchronously and returns handle for <code>HTTPApiTable.fetch_async_get</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#HTTPApiTablefetch_async_gethandle" name="HTTPApiTablefetch_async_gethandle">#</a><code>HTTPApiTable.fetch_async_get(handle)</code>: returns HTTPRequestResult<ul>
|
||
<li>Return response data for given asynchronous HTTP request</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="storage-api">Storage API:</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestget_mod_storage" name="minetestget_mod_storage">#</a><code>minetest.get_mod_storage()</code>:<ul>
|
||
<li><a class="anchor" href="#StorageRef" name="StorageRef">#</a>returns reference to mod private <code>StorageRef</code></li>
|
||
<li>must be called during mod load time</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="misc">Misc.</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestget_connected_players" name="minetestget_connected_players">#</a><code>minetest.get_connected_players()</code>: returns list of <code>ObjectRefs</code></li>
|
||
<li><a class="anchor" href="#minetestplayer_existsname" name="minetestplayer_existsname">#</a><code>minetest.player_exists(name)</code>: boolean, whether player exists (regardless of online status)</li>
|
||
<li><a class="anchor" href="#minetesthud_replace_builtinnamehud_definition" name="minetesthud_replace_builtinnamehud_definition">#</a><code>minetest.hud_replace_builtin(name, hud_definition)</code><ul>
|
||
<li>Replaces definition of a builtin hud element</li>
|
||
<li><a class="anchor" href="#name_12" name="name_12">#</a><code>name</code>: <code>"breath"</code> or <code>"health"</code></li>
|
||
<li><a class="anchor" href="#hud_definition" name="hud_definition">#</a><code>hud_definition</code>: definition to replace builtin definition</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetesthash_node_positionxyz" name="minetesthash_node_positionxyz">#</a><code>minetest.hash_node_position({x=,y=,z=})</code>: returns an 48-bit integer<ul>
|
||
<li>Gives a unique hash number for a node position (16+16+16=48bit)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_position_from_hashhash" name="minetestget_position_from_hashhash">#</a><code>minetest.get_position_from_hash(hash)</code>: returns a position<ul>
|
||
<li><a class="anchor" href="#minetesthash_node_position" name="minetesthash_node_position">#</a>Inverse transform of <code>minetest.hash_node_position</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_item_groupnamegroup" name="minetestget_item_groupnamegroup">#</a><code>minetest.get_item_group(name, group)</code>: returns a rating<ul>
|
||
<li><a class="anchor" href="#0_9" name="0_9">#</a>Get rating of a group of an item. (<code>0</code> means: not in group)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_node_groupnamegroup" name="minetestget_node_groupnamegroup">#</a><code>minetest.get_node_group(name, group)</code>: returns a rating<ul>
|
||
<li>Deprecated: An alias for the former.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestraillike_groupname" name="minetestraillike_groupname">#</a><code>minetest.raillike_group(name)</code>: returns a rating<ul>
|
||
<li>Returns rating of the connect_to_raillike group corresponding to name</li>
|
||
<li>If name is not yet the name of a connect_to_raillike group, a new group id</li>
|
||
<li>is created, with that name</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_content_idname" name="minetestget_content_idname">#</a><code>minetest.get_content_id(name)</code>: returns an integer<ul>
|
||
<li><a class="anchor" href="#name_13" name="name_13">#</a>Gets the internal content ID of <code>name</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestget_name_from_content_idcontent_id" name="minetestget_name_from_content_idcontent_id">#</a><code>minetest.get_name_from_content_id(content_id)</code>: returns a string<ul>
|
||
<li>Gets the name of the content with that content ID</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestparse_jsonstringnullvalue" name="minetestparse_jsonstringnullvalue">#</a><code>minetest.parse_json(string[, nullvalue])</code>: returns something<ul>
|
||
<li>Convert a string containing JSON data into the Lua equivalent</li>
|
||
<li><a class="anchor" href="#nullvalue" name="nullvalue">#</a><code>nullvalue</code>: returned in place of the JSON null; defaults to <code>nil</code></li>
|
||
<li><a class="anchor" href="#nullvalue_1" name="nullvalue_1">#</a>On success returns a table, a string, a number, a boolean or <code>nullvalue</code></li>
|
||
<li><a class="anchor" href="#nil_4" name="nil_4">#</a>On failure outputs an error message and returns <code>nil</code></li>
|
||
<li><a class="anchor" href="#parse_json10afalse" name="parse_json10afalse">#</a>Example: <code>parse_json("[10, {\"a\":false}]")</code>, returns <code>{10, {a = false}}</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestwrite_jsondatastyled" name="minetestwrite_jsondatastyled">#</a><code>minetest.write_json(data[, styled])</code>: returns a string or <code>nil</code> and an error message<ul>
|
||
<li>Convert a Lua table into a JSON string</li>
|
||
<li>styled: Outputs in a human-readable format if this is set, defaults to false</li>
|
||
<li>Unserializable things like functions and userdata will cause an error.</li>
|
||
<li><strong>Warning</strong>: JSON is more strict than the Lua table format.<ol>
|
||
<li>You can only use strings and positive integers of at least one as keys.</li>
|
||
<li>You can not mix string and integer keys.
|
||
This is due to the fact that JSON has two distinct array and object values.</li>
|
||
</ol>
|
||
</li>
|
||
<li><a class="anchor" href="#write_json10afalse" name="write_json10afalse">#</a>Example: <code>write_json({10, {a = false}})</code>, returns <code>"[10, {\"a\": false}]"</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestserializetable" name="minetestserializetable">#</a><code>minetest.serialize(table)</code>: returns a string<ul>
|
||
<li><a class="anchor" href="#nil_5" name="nil_5">#</a>Convert a table containing tables, strings, numbers, booleans and <code>nil</code>s
|
||
into string form readable by <code>minetest.deserialize</code></li>
|
||
<li><a class="anchor" href="#serializefoobar" name="serializefoobar">#</a>Example: <code>serialize({foo='bar'})</code>, returns <code>'return { ["foo"] = "bar" }'</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdeserializestring" name="minetestdeserializestring">#</a><code>minetest.deserialize(string)</code>: returns a table<ul>
|
||
<li><a class="anchor" href="#minetestdeserialize" name="minetestdeserialize">#</a>Convert a string returned by <code>minetest.deserialize</code> into a table</li>
|
||
<li><a class="anchor" href="#string_1" name="string_1">#</a><code>string</code> is loaded in an empty sandbox environment.</li>
|
||
<li>Will load functions, but they cannot access the global environment.</li>
|
||
<li><a class="anchor" href="#deserializereturnfoobar" name="deserializereturnfoobar">#</a>Example: <code>deserialize('return { ["foo"] = "bar" }')</code>, returns <code>{foo='bar'}</code></li>
|
||
<li><a class="anchor" href="#deserializeprintfoo" name="deserializeprintfoo">#</a>Example: <code>deserialize('print("foo")')</code>, returns <code>nil</code> (function call fails)<ul>
|
||
<li><a class="anchor" href="#errorstringprintfoo1attempttocallglobalprintanilvalue" name="errorstringprintfoo1attempttocallglobalprintanilvalue">#</a><code>error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestcompressdatamethod" name="minetestcompressdatamethod">#</a><code>minetest.compress(data, method, ...)</code>: returns <code>compressed_data</code><ul>
|
||
<li>Compress a string of data.</li>
|
||
<li><a class="anchor" href="#method" name="method">#</a><code>method</code> is a string identifying the compression method to be used.</li>
|
||
<li>Supported compression methods:</li>
|
||
<li><a class="anchor" href="#deflate" name="deflate">#</a>Deflate (zlib): <code>"deflate"</code></li>
|
||
<li><code>...</code> indicates method-specific arguments. Currently defined arguments are:</li>
|
||
<li><a class="anchor" href="#level_5" name="level_5">#</a>Deflate: <code>level</code> - Compression level, <code>0</code>-<code>9</code> or <code>nil</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdecompresscompressed_datamethod" name="minetestdecompresscompressed_datamethod">#</a><code>minetest.decompress(compressed_data, method, ...)</code>: returns data<ul>
|
||
<li>Decompress a string of data (using ZLib).</li>
|
||
<li><a class="anchor" href="#minetestcompress" name="minetestcompress">#</a>See documentation on <code>minetest.compress()</code> for supported compression methods.</li>
|
||
<li>currently supported.</li>
|
||
<li><code>...</code> indicates method-specific arguments. Currently, no methods use this.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestrgbaredgreenbluealpha" name="minetestrgbaredgreenbluealpha">#</a><code>minetest.rgba(red, green, blue[, alpha])</code>: returns a string<ul>
|
||
<li>Each argument is a 8 Bit unsigned integer</li>
|
||
<li>Returns the ColorString from rgb or rgba values</li>
|
||
<li><a class="anchor" href="#minetestrgba10203040" name="minetestrgba10203040">#</a>Example: <code>minetest.rgba(10, 20, 30, 40)</code>, returns <code>"#0A141E28"</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestencode_base64string" name="minetestencode_base64string">#</a><code>minetest.encode_base64(string)</code>: returns string encoded in base64<ul>
|
||
<li>Encodes a string in base64.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestdecode_base64string" name="minetestdecode_base64string">#</a><code>minetest.decode_base64(string)</code>: returns string<ul>
|
||
<li>Decodes a string encoded in base64.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestis_protectedposname" name="minetestis_protectedposname">#</a>
|
||
<p><code>minetest.is_protected(pos, name)</code>: returns boolean</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#name_14" name="name_14">#</a>Returns true, if player <code>name</code> shouldn't be abled to dig at <code>pos</code> or do other
|
||
actions, defineable by mods, due to some mod-defined ownership-like concept.
|
||
Returns false or nil, if the player is allowed to do such actions.</li>
|
||
<li>This function should be overridden by protection mods and should be used to
|
||
check if a player can interact at a position.</li>
|
||
<li>This function should call the old version of itself if the position is not
|
||
protected by the mod.</li>
|
||
<li><a class="anchor" href="#localold_is_protectedminetestis_protectedfunctionminetestis_protectedposnameifmymodposition_protected_fromposnamethenreturntrueendreturnold_is_protectedposnameend" name="localold_is_protectedminetestis_protectedfunctionminetestis_protectedposnameifmymodposition_protected_fromposnamethenreturntrueendreturnold_is_protectedposnameend">#</a>Example:<pre><code>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
|
||
</code></pre>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestrecord_protection_violationposname" name="minetestrecord_protection_violationposname">#</a><code>minetest.record_protection_violation(pos, name)</code><ul>
|
||
<li><a class="anchor" href="#minetestregister_on_protection_violation" name="minetestregister_on_protection_violation">#</a>This function calls functions registered with
|
||
<code>minetest.register_on_protection_violation</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestrotate_and_placeitemstackplacerpointed_thinginfinitestacksorient_flags" name="minetestrotate_and_placeitemstackplacerpointed_thinginfinitestacksorient_flags">#</a><code>minetest.rotate_and_place(itemstack, placer, pointed_thing, infinitestacks, orient_flags)</code><ul>
|
||
<li><a class="anchor" href="#itemstack_3" name="itemstack_3">#</a>Attempt to predict the desired orientation of the facedir-capable node
|
||
defined by <code>itemstack</code>, and place it accordingly (on-wall, on the floor, or
|
||
hanging from the ceiling). Stacks are handled normally if the <code>infinitestacks</code>
|
||
field is false or omitted (else, the itemstack is not changed). <code>orient_flags</code>
|
||
is an optional table containing extra tweaks to the placement code:</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#invert_wall" name="invert_wall">#</a><code>invert_wall</code>: if <code>true</code>, place wall-orientation on the ground and ground-
|
||
orientation on the wall.</li>
|
||
<li><a class="anchor" href="#force_wall" name="force_wall">#</a><code>force_wall</code> : if <code>true</code>, always place the node in wall orientation.</li>
|
||
<li><a class="anchor" href="#force_ceiling" name="force_ceiling">#</a><code>force_ceiling</code>: if <code>true</code>, always place on the ceiling.</li>
|
||
<li><a class="anchor" href="#force_floor" name="force_floor">#</a><code>force_floor</code>: if <code>true</code>, always place the node on the floor.</li>
|
||
<li><a class="anchor" href="#force_facedir" name="force_facedir">#</a><code>force_facedir</code>: if <code>true</code>, forcefully reset the facedir to north when placing on
|
||
the floor or ceiling</li>
|
||
<li>The first four options are mutually-exclusive; the last in the list takes
|
||
precedence over the first.</li>
|
||
<li><a class="anchor" href="#minetestrotate_nodeitemstackplacerpointed_thing" name="minetestrotate_nodeitemstackplacerpointed_thing">#</a><code>minetest.rotate_node(itemstack, placer, pointed_thing)</code><ul>
|
||
<li><a class="anchor" href="#rotate_and_place" name="rotate_and_place">#</a>calls <code>rotate_and_place()</code> with infinitestacks set according to the state of
|
||
the creative mode setting, and checks for "sneak" to set the <code>invert_wall</code>
|
||
parameter.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestforceload_blockpostransient" name="minetestforceload_blockpostransient">#</a>
|
||
<p><code>minetest.forceload_block(pos[, transient])</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#pos_5" name="pos_5">#</a>forceloads the position <code>pos</code>.</li>
|
||
<li><a class="anchor" href="#true_11" name="true_11">#</a>returns <code>true</code> if area could be forceloaded</li>
|
||
<li><a class="anchor" href="#transient" name="transient">#</a>If <code>transient</code> is <code>false</code> or absent, the forceload will be persistent
|
||
(saved between server runs). If <code>true</code>, the forceload will be transient
|
||
(not saved between server runs).</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestforceload_free_blockpostransient" name="minetestforceload_free_blockpostransient">#</a>
|
||
<p><code>minetest.forceload_free_block(pos[, transient])</code></p>
|
||
<ul>
|
||
<li><a class="anchor" href="#pos_6" name="pos_6">#</a>stops forceloading the position <code>pos</code></li>
|
||
<li><a class="anchor" href="#transient_1" name="transient_1">#</a>If <code>transient</code> is <code>false</code> or absent, frees a persistent forceload.
|
||
If <code>true</code>, frees a transient forceload.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestrequest_insecure_environment" name="minetestrequest_insecure_environment">#</a>
|
||
<p><code>minetest.request_insecure_environment()</code>: returns an environment containing
|
||
insecure functions if the calling mod has been listed as trusted in the
|
||
<code>secure.trusted_mods</code> setting or security is disabled, otherwise returns <code>nil</code>.</p>
|
||
<ul>
|
||
<li>Only works at init time and must be called from the mod's main scope (not from a function).</li>
|
||
<li><strong>DO NOT ALLOW ANY OTHER MODS TO ACCESS THE RETURNED ENVIRONMENT, STORE IT IN
|
||
A LOCAL VARIABLE!</strong></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestglobal_existsname" name="minetestglobal_existsname">#</a>
|
||
<p><code>minetest.global_exists(name)</code></p>
|
||
<ul>
|
||
<li>Checks if a global variable has been set, without triggering a warning.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="global-objects">Global objects</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestenv" name="minetestenv">#</a><code>minetest.env</code>: <code>EnvRef</code> of the server environment and world.<ul>
|
||
<li><a class="anchor" href="#minetestenvsomefunctionsomearguments" name="minetestenvsomefunctionsomearguments">#</a>Any function in the minetest namespace can be called using the syntax
|
||
<code>minetest.env:somefunction(somearguments)</code>
|
||
instead of <code>minetest.somefunction(somearguments)</code></li>
|
||
<li>Deprecated, but support is not to be dropped soon</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="global-tables">Global tables</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestregistered_items" name="minetestregistered_items">#</a><code>minetest.registered_items</code><ul>
|
||
<li>Map of registered items, indexed by name</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_nodes_1" name="minetestregistered_nodes_1">#</a><code>minetest.registered_nodes</code><ul>
|
||
<li>Map of registered node definitions, indexed by name</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_craftitems" name="minetestregistered_craftitems">#</a><code>minetest.registered_craftitems</code><ul>
|
||
<li>Map of registered craft item definitions, indexed by name</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_tools" name="minetestregistered_tools">#</a><code>minetest.registered_tools</code><ul>
|
||
<li>Map of registered tool definitions, indexed by name</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_entities" name="minetestregistered_entities">#</a><code>minetest.registered_entities</code><ul>
|
||
<li>Map of registered entity prototypes, indexed by name</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestobject_refs" name="minetestobject_refs">#</a><code>minetest.object_refs</code><ul>
|
||
<li>Map of object references, indexed by active object id</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestluaentities" name="minetestluaentities">#</a><code>minetest.luaentities</code><ul>
|
||
<li>Map of Lua entities, indexed by active object id</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_chatcommands_1" name="minetestregistered_chatcommands_1">#</a><code>minetest.registered_chatcommands</code><ul>
|
||
<li>Map of registered chat command definitions, indexed by name</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_ores_1" name="minetestregistered_ores_1">#</a><code>minetest.registered_ores</code><ul>
|
||
<li>List of registered ore definitions.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_biomes" name="minetestregistered_biomes">#</a><code>minetest.registered_biomes</code><ul>
|
||
<li>List of registered biome definitions.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#minetestregistered_decorations_1" name="minetestregistered_decorations_1">#</a><code>minetest.registered_decorations</code><ul>
|
||
<li>List of registered decoration definitions.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h2 id="class-reference">Class reference</h2>
|
||
<h3 id="metadataref"><code>MetaDataRef</code></h3>
|
||
<p>See <code>StorageRef</code>, <code>NodeMetaRef</code> and <code>ItemStackMetaRef</code>.</p>
|
||
<h4 id="methods">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#set_stringnamevalue" name="set_stringnamevalue">#</a><code>set_string(name, value)</code></li>
|
||
<li><a class="anchor" href="#get_stringname" name="get_stringname">#</a><code>get_string(name)</code></li>
|
||
<li><a class="anchor" href="#set_intnamevalue" name="set_intnamevalue">#</a><code>set_int(name, value)</code></li>
|
||
<li><a class="anchor" href="#get_intname" name="get_intname">#</a><code>get_int(name)</code></li>
|
||
<li><a class="anchor" href="#set_floatnamevalue" name="set_floatnamevalue">#</a><code>set_float(name, value)</code></li>
|
||
<li><a class="anchor" href="#get_floatname" name="get_floatname">#</a><code>get_float(name)</code></li>
|
||
<li><a class="anchor" href="#to_table" name="to_table">#</a><code>to_table()</code>: returns <code>nil</code> or a table with keys:<ul>
|
||
<li><a class="anchor" href="#fields" name="fields">#</a><code>fields</code>: key-value storage</li>
|
||
<li><a class="anchor" href="#inventory_2" name="inventory_2">#</a><code>inventory</code>: <code>{list1 = {}, ...}}</code> (NodeMetaRef only)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#from_tablenilor" name="from_tablenilor">#</a><code>from_table(nil or {})</code><ul>
|
||
<li>Any non-table value will clear the metadata</li>
|
||
<li>See "Node Metadata" for an example</li>
|
||
<li><a class="anchor" href="#true_12" name="true_12">#</a>returns <code>true</code> on success</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#equalsother" name="equalsother">#</a><code>equals(other)</code><ul>
|
||
<li><a class="anchor" href="#true_13" name="true_13">#</a>returns <code>true</code> if this metadata has the same key-value pairs as <code>other</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="nodemetaref"><code>NodeMetaRef</code></h3>
|
||
<p>Node metadata: reference extra data and functionality stored in a node.
|
||
Can be obtained via <code>minetest.get_meta(pos)</code>.</p>
|
||
<h4 id="methods_1">Methods</h4>
|
||
<ul>
|
||
<li>All methods in MetaDataRef</li>
|
||
<li><a class="anchor" href="#get_inventory" name="get_inventory">#</a><code>get_inventory()</code>: returns <code>InvRef</code></li>
|
||
<li><a class="anchor" href="#mark_as_privatenameorname1name2" name="mark_as_privatenameorname1name2">#</a><code>mark_as_private(name or {name1, name2, ...})</code>: Mark specific vars as private
|
||
This will prevent them from being sent to the client. Note that the "private"
|
||
status will only be remembered if an associated key-value pair exists, meaning
|
||
it's best to call this when initializing all other meta (e.g. <code>on_construct</code>).</li>
|
||
</ul>
|
||
<h3 id="itemstackmetaref"><code>ItemStackMetaRef</code></h3>
|
||
<p>ItemStack metadata: reference extra data and functionality stored in a stack.
|
||
Can be obtained via <code>item:get_meta()</code>.</p>
|
||
<h4 id="methods_2">Methods</h4>
|
||
<ul>
|
||
<li>All methods in MetaDataRef</li>
|
||
</ul>
|
||
<h3 id="storageref"><code>StorageRef</code></h3>
|
||
<p>Mod metadata: per mod metadata, saved automatically.
|
||
Can be obtained via <code>minetest.get_mod_storage()</code> during load time.</p>
|
||
<h4 id="methods_3">Methods</h4>
|
||
<ul>
|
||
<li>All methods in MetaDataRef</li>
|
||
</ul>
|
||
<h3 id="nodetimerref"><code>NodeTimerRef</code></h3>
|
||
<p>Node Timers: a high resolution persistent per-node timer.
|
||
Can be gotten via <code>minetest.get_node_timer(pos)</code>.</p>
|
||
<h4 id="methods_4">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#settimeoutelapsed" name="settimeoutelapsed">#</a><code>set(timeout,elapsed)</code><ul>
|
||
<li>set a timer's state</li>
|
||
<li><a class="anchor" href="#timeout" name="timeout">#</a><code>timeout</code> is in seconds, and supports fractional values (0.1 etc)</li>
|
||
<li><a class="anchor" href="#elapsed" name="elapsed">#</a><code>elapsed</code> is in seconds, and supports fractional values (0.1 etc)</li>
|
||
<li><a class="anchor" href="#on_timer" name="on_timer">#</a>will trigger the node's <code>on_timer</code> function after <code>(timeout - elapsed)</code> seconds</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#starttimeout" name="starttimeout">#</a><code>start(timeout)</code><ul>
|
||
<li>start a timer</li>
|
||
<li><a class="anchor" href="#settimeout0" name="settimeout0">#</a>equivalent to <code>set(timeout,0)</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#stop" name="stop">#</a><code>stop()</code><ul>
|
||
<li>stops the timer</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_timeout" name="get_timeout">#</a><code>get_timeout()</code>: returns current timeout in seconds<ul>
|
||
<li><a class="anchor" href="#timeout_1" name="timeout_1">#</a>if <code>timeout</code> equals <code>0</code>, timer is inactive</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_elapsed" name="get_elapsed">#</a><code>get_elapsed()</code>: returns current elapsed time in seconds<ul>
|
||
<li><a class="anchor" href="#on_timer_1" name="on_timer_1">#</a>the node's <code>on_timer</code> function will be called after <code>(timeout - elapsed)</code> seconds</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#is_started" name="is_started">#</a><code>is_started()</code>: returns boolean state of timer<ul>
|
||
<li><a class="anchor" href="#true_14" name="true_14">#</a>returns <code>true</code> if timer is started, otherwise <code>false</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="objectref"><code>ObjectRef</code></h3>
|
||
<p>Moving things in the game are generally these.</p>
|
||
<p>This is basically a reference to a C++ <code>ServerActiveObject</code></p>
|
||
<h4 id="methods_5">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#remove" name="remove">#</a><code>remove()</code>: remove object (after returning from Lua)<ul>
|
||
<li><a class="anchor" href="#minetestkick_player" name="minetestkick_player">#</a>Note: Doesn't work on players, use <code>minetest.kick_player</code> instead</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_pos" name="get_pos">#</a><code>get_pos()</code>: returns <code>{x=num, y=num, z=num}</code></li>
|
||
<li><a class="anchor" href="#set_pospos" name="set_pospos">#</a><code>set_pos(pos)</code>; <code>pos</code>=<code>{x=num, y=num, z=num}</code></li>
|
||
<li><a class="anchor" href="#move_toposcontinuousfalse" name="move_toposcontinuousfalse">#</a><code>move_to(pos, continuous=false)</code>: interpolated move</li>
|
||
<li><a class="anchor" href="#punchpunchertime_from_last_punchtool_capabilitiesdirection" name="punchpunchertime_from_last_punchtool_capabilitiesdirection">#</a><code>punch(puncher, time_from_last_punch, tool_capabilities, direction)</code><ul>
|
||
<li><a class="anchor" href="#puncher_1" name="puncher_1">#</a><code>puncher</code> = another <code>ObjectRef</code>,</li>
|
||
<li><a class="anchor" href="#time_from_last_punch_2" name="time_from_last_punch_2">#</a><code>time_from_last_punch</code> = time since last punch action of the puncher</li>
|
||
<li><a class="anchor" href="#direction_4" name="direction_4">#</a><code>direction</code>: can be <code>nil</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#right_clickclicker" name="right_clickclicker">#</a><code>right_click(clicker)</code>; <code>clicker</code> is another <code>ObjectRef</code></li>
|
||
<li><a class="anchor" href="#get_hp" name="get_hp">#</a><code>get_hp()</code>: returns number of hitpoints (2 * number of hearts)</li>
|
||
<li><a class="anchor" href="#set_hphp" name="set_hphp">#</a><code>set_hp(hp)</code>: set number of hitpoints (2 * number of hearts)</li>
|
||
<li><a class="anchor" href="#get_inventory_1" name="get_inventory_1">#</a><code>get_inventory()</code>: returns an <code>InvRef</code></li>
|
||
<li><a class="anchor" href="#get_wield_list" name="get_wield_list">#</a><code>get_wield_list()</code>: returns the name of the inventory list the wielded item is in</li>
|
||
<li><a class="anchor" href="#get_wield_index" name="get_wield_index">#</a><code>get_wield_index()</code>: returns the index of the wielded item</li>
|
||
<li><a class="anchor" href="#get_wielded_item" name="get_wielded_item">#</a><code>get_wielded_item()</code>: returns an <code>ItemStack</code></li>
|
||
<li><a class="anchor" href="#set_wielded_itemitem" name="set_wielded_itemitem">#</a><code>set_wielded_item(item)</code>: replaces the wielded item, returns <code>true</code> if successful</li>
|
||
<li><a class="anchor" href="#set_armor_groupsgroup1ratinggroup2rating" name="set_armor_groupsgroup1ratinggroup2rating">#</a><code>set_armor_groups({group1=rating, group2=rating, ...})</code></li>
|
||
<li><a class="anchor" href="#get_armor_groups" name="get_armor_groups">#</a><code>get_armor_groups()</code>: returns a table with the armor group ratings</li>
|
||
<li><a class="anchor" href="#set_animationx1y1frame_speed15frame_blend0frame_looptrue" name="set_animationx1y1frame_speed15frame_blend0frame_looptrue">#</a><code>set_animation({x=1,y=1}, frame_speed=15, frame_blend=0, frame_loop=true)</code></li>
|
||
<li><a class="anchor" href="#get_animation" name="get_animation">#</a><code>get_animation()</code>: returns <code>range</code>, <code>frame_speed</code>, <code>frame_blend</code> and <code>frame_loop</code></li>
|
||
<li><a class="anchor" href="#set_attachparentbonepositionrotation" name="set_attachparentbonepositionrotation">#</a><code>set_attach(parent, bone, position, rotation)</code><ul>
|
||
<li><a class="anchor" href="#bone" name="bone">#</a><code>bone</code>: string</li>
|
||
<li><a class="anchor" href="#position" name="position">#</a><code>position</code>: <code>{x=num, y=num, z=num}</code> (relative)</li>
|
||
<li><a class="anchor" href="#rotation_2" name="rotation_2">#</a><code>rotation</code>: <code>{x=num, y=num, z=num}</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_attach" name="get_attach">#</a><code>get_attach()</code>: returns parent, bone, position, rotation or nil if it isn't attached</li>
|
||
<li><a class="anchor" href="#set_detach" name="set_detach">#</a><code>set_detach()</code></li>
|
||
<li><a class="anchor" href="#set_bone_positionbonepositionrotation" name="set_bone_positionbonepositionrotation">#</a><code>set_bone_position(bone, position, rotation)</code><ul>
|
||
<li><a class="anchor" href="#bone_1" name="bone_1">#</a><code>bone</code>: string</li>
|
||
<li><a class="anchor" href="#position_1" name="position_1">#</a><code>position</code>: <code>{x=num, y=num, z=num}</code> (relative)</li>
|
||
<li><a class="anchor" href="#rotation_3" name="rotation_3">#</a><code>rotation</code>: <code>{x=num, y=num, z=num}</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_bone_positionbone" name="get_bone_positionbone">#</a><code>get_bone_position(bone)</code>: returns position and rotation of the bone</li>
|
||
<li><a class="anchor" href="#set_propertiesobjectpropertytable" name="set_propertiesobjectpropertytable">#</a><code>set_properties(object property table)</code></li>
|
||
<li><a class="anchor" href="#get_properties" name="get_properties">#</a><code>get_properties()</code>: returns object property table</li>
|
||
<li><a class="anchor" href="#is_player" name="is_player">#</a><code>is_player()</code>: returns true for players, false otherwise</li>
|
||
<li><a class="anchor" href="#get_nametag_attributes" name="get_nametag_attributes">#</a><code>get_nametag_attributes()</code><ul>
|
||
<li>returns a table with the attributes of the nametag of an object</li>
|
||
<li>{
|
||
color = {a=0..255, r=0..255, g=0..255, b=0..255},
|
||
text = "",
|
||
}</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_nametag_attributesattributes" name="set_nametag_attributesattributes">#</a><code>set_nametag_attributes(attributes)</code><ul>
|
||
<li>sets the attributes of the nametag of an object</li>
|
||
<li><a class="anchor" href="#attributes" name="attributes">#</a><code>attributes</code>:
|
||
{
|
||
color = ColorSpec,
|
||
text = "My Nametag",
|
||
}</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h5 id="luaentitysao-only-no-op-for-other-objects">LuaEntitySAO-only (no-op for other objects)</h5>
|
||
<ul>
|
||
<li><a class="anchor" href="#set_velocityxnumynumznum" name="set_velocityxnumynumznum">#</a><code>set_velocity({x=num, y=num, z=num})</code></li>
|
||
<li><a class="anchor" href="#get_velocity" name="get_velocity">#</a><code>get_velocity()</code>: returns <code>{x=num, y=num, z=num}</code></li>
|
||
<li><a class="anchor" href="#set_accelerationxnumynumznum" name="set_accelerationxnumynumznum">#</a><code>set_acceleration({x=num, y=num, z=num})</code></li>
|
||
<li><a class="anchor" href="#get_acceleration" name="get_acceleration">#</a><code>get_acceleration()</code>: returns <code>{x=num, y=num, z=num}</code></li>
|
||
<li><a class="anchor" href="#set_yawradians" name="set_yawradians">#</a><code>set_yaw(radians)</code></li>
|
||
<li><a class="anchor" href="#get_yaw" name="get_yaw">#</a><code>get_yaw()</code>: returns number in radians</li>
|
||
<li><a class="anchor" href="#set_texture_modmod" name="set_texture_modmod">#</a><code>set_texture_mod(mod)</code></li>
|
||
<li><a class="anchor" href="#get_texture_mod" name="get_texture_mod">#</a><code>get_texture_mod()</code> returns current texture modifier</li>
|
||
<li><a class="anchor" href="#set_spritepx0y0num_frames1framelength02select_horiz_by_yawpitchfalse" name="set_spritepx0y0num_frames1framelength02select_horiz_by_yawpitchfalse">#</a><code>set_sprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
|
||
select_horiz_by_yawpitch=false)</code><ul>
|
||
<li>Select sprite from spritesheet with optional animation and DM-style
|
||
texture selection based on yaw relative to camera</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_entity_name" name="get_entity_name">#</a><code>get_entity_name()</code> (<strong>Deprecated</strong>: Will be removed in a future version)</li>
|
||
<li><a class="anchor" href="#get_luaentity" name="get_luaentity">#</a><code>get_luaentity()</code></li>
|
||
</ul>
|
||
<h5 id="player-only-no-op-for-other-objects">Player-only (no-op for other objects)</h5>
|
||
<ul>
|
||
<li><a class="anchor" href="#get_player_name" name="get_player_name">#</a><code>get_player_name()</code>: returns <code>""</code> if is not a player</li>
|
||
<li><a class="anchor" href="#get_player_velocity" name="get_player_velocity">#</a><code>get_player_velocity()</code>: returns <code>nil</code> if is not a player, otherwise a
|
||
table {x, y, z} representing the player's instantaneous velocity in nodes/s</li>
|
||
<li><a class="anchor" href="#get_look_dir" name="get_look_dir">#</a><code>get_look_dir()</code>: get camera direction as a unit vector</li>
|
||
<li><a class="anchor" href="#get_look_vertical" name="get_look_vertical">#</a><code>get_look_vertical()</code>: pitch in radians<ul>
|
||
<li>Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_look_horizontal" name="get_look_horizontal">#</a><code>get_look_horizontal()</code>: yaw in radians<ul>
|
||
<li>Angle is counter-clockwise from the +z direction.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_look_verticalradians" name="set_look_verticalradians">#</a><code>set_look_vertical(radians)</code>: sets look pitch<ul>
|
||
<li>radians - Angle from looking forward, where positive is downwards.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_look_horizontalradians" name="set_look_horizontalradians">#</a><code>set_look_horizontal(radians)</code>: sets look yaw<ul>
|
||
<li>radians - Angle from the +z direction, where positive is counter-clockwise.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_look_pitch" name="get_look_pitch">#</a><code>get_look_pitch()</code>: pitch in radians - Deprecated as broken. Use <code>get_look_vertical</code>.<ul>
|
||
<li>Angle ranges between -pi/2 and pi/2, which are straight down and up respectively.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_look_yaw" name="get_look_yaw">#</a><code>get_look_yaw()</code>: yaw in radians - Deprecated as broken. Use <code>get_look_horizontal</code>.<ul>
|
||
<li>Angle is counter-clockwise from the +x direction.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_look_pitchradians" name="set_look_pitchradians">#</a><code>set_look_pitch(radians)</code>: sets look pitch - Deprecated. Use <code>set_look_vertical</code>.</li>
|
||
<li><a class="anchor" href="#set_look_yawradians" name="set_look_yawradians">#</a><code>set_look_yaw(radians)</code>: sets look yaw - Deprecated. Use <code>set_look_horizontal</code>.</li>
|
||
<li><a class="anchor" href="#get_breath" name="get_breath">#</a><code>get_breath()</code>: returns players breath</li>
|
||
<li><a class="anchor" href="#set_breathvalue" name="set_breathvalue">#</a><code>set_breath(value)</code>: sets players breath<ul>
|
||
<li><a class="anchor" href="#0_10" name="0_10">#</a>values:<ul>
|
||
<li><a class="anchor" href="#0_11" name="0_11">#</a><code>0</code>: player is drowning,</li>
|
||
<li><a class="anchor" href="#1" name="1">#</a><code>1</code>-<code>10</code>: remaining number of bubbles</li>
|
||
<li><a class="anchor" href="#11" name="11">#</a><code>11</code>: bubbles bar is not shown</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_attributeattributevalue" name="set_attributeattributevalue">#</a><code>set_attribute(attribute, value)</code>:<ul>
|
||
<li>Sets an extra attribute with value on player.</li>
|
||
<li><a class="anchor" href="#value_1" name="value_1">#</a><code>value</code> must be a string.</li>
|
||
<li><a class="anchor" href="#value_2" name="value_2">#</a>If <code>value</code> is <code>nil</code>, remove attribute from player.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_attributeattribute" name="get_attributeattribute">#</a><code>get_attribute(attribute)</code>:<ul>
|
||
<li>Returns value (a string) for extra attribute.</li>
|
||
<li><a class="anchor" href="#nil_6" name="nil_6">#</a>Returns <code>nil</code> if no attribute found.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_inventory_formspecformspec" name="set_inventory_formspecformspec">#</a><code>set_inventory_formspec(formspec)</code><ul>
|
||
<li>Redefine player's inventory form</li>
|
||
<li><a class="anchor" href="#on_joinplayer" name="on_joinplayer">#</a>Should usually be called in <code>on_joinplayer</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_inventory_formspec" name="get_inventory_formspec">#</a><code>get_inventory_formspec()</code>: returns a formspec string</li>
|
||
<li><a class="anchor" href="#get_player_control" name="get_player_control">#</a><code>get_player_control()</code>: returns table with player pressed keys<ul>
|
||
<li><a class="anchor" href="#jumpboolrightboolleftboolLMBboolRMBboolsneakboolaux1booldownboolupbool" name="jumpboolrightboolleftboolLMBboolRMBboolsneakboolaux1booldownboolupbool">#</a><code>{jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_player_control_bits" name="get_player_control_bits">#</a><code>get_player_control_bits()</code>: returns integer with bit packed player pressed keys<ul>
|
||
<li>bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_physics_overrideoverride_table" name="set_physics_overrideoverride_table">#</a><code>set_physics_override(override_table)</code><ul>
|
||
<li><a class="anchor" href="#override_table" name="override_table">#</a><code>override_table</code> is a table with the following fields:<ul>
|
||
<li><a class="anchor" href="#speed" name="speed">#</a><code>speed</code>: multiplier to default walking speed value (default: <code>1</code>)</li>
|
||
<li><a class="anchor" href="#jump" name="jump">#</a><code>jump</code>: multiplier to default jump value (default: <code>1</code>)</li>
|
||
<li><a class="anchor" href="#gravity" name="gravity">#</a><code>gravity</code>: multiplier to default gravity value (default: <code>1</code>)</li>
|
||
<li><a class="anchor" href="#sneak" name="sneak">#</a><code>sneak</code>: whether player can sneak (default: <code>true</code>)</li>
|
||
<li><a class="anchor" href="#sneak_glitch" name="sneak_glitch">#</a><code>sneak_glitch</code>: whether player can use the new move code replications
|
||
of the old sneak side-effects: sneak ladders and 2 node sneak jump
|
||
(default: <code>false</code>)</li>
|
||
<li><a class="anchor" href="#new_move" name="new_move">#</a><code>new_move</code>: use new move/sneak code. When <code>false</code> the exact old code
|
||
is used for the specific old sneak behaviour (default: <code>true</code>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_physics_override" name="get_physics_override">#</a><code>get_physics_override()</code>: returns the table given to <code>set_physics_override</code></li>
|
||
<li><a class="anchor" href="#hud_addhuddefinition" name="hud_addhuddefinition">#</a><code>hud_add(hud definition)</code>: add a HUD element described by HUD def, returns ID
|
||
number on success</li>
|
||
<li><a class="anchor" href="#hud_removeid" name="hud_removeid">#</a><code>hud_remove(id)</code>: remove the HUD element of the specified id</li>
|
||
<li><a class="anchor" href="#hud_changeidstatvalue" name="hud_changeidstatvalue">#</a><code>hud_change(id, stat, value)</code>: change a value of a previously added HUD element<ul>
|
||
<li><a class="anchor" href="#stat" name="stat">#</a>element <code>stat</code> values: <code>position</code>, <code>name</code>, <code>scale</code>, <code>text</code>, <code>number</code>, <code>item</code>, <code>dir</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#hud_getid" name="hud_getid">#</a><code>hud_get(id)</code>: gets the HUD element definition structure of the specified ID</li>
|
||
<li><a class="anchor" href="#hud_set_flagsflags" name="hud_set_flagsflags">#</a><code>hud_set_flags(flags)</code>: sets specified HUD flags to <code>true</code>/<code>false</code><ul>
|
||
<li><a class="anchor" href="#flags_4" name="flags_4">#</a><code>flags</code>: (is visible) <code>hotbar</code>, <code>healthbar</code>, <code>crosshair</code>, <code>wielditem</code>, <code>minimap</code></li>
|
||
<li><a class="anchor" href="#true_15" name="true_15">#</a>pass a table containing a <code>true</code>/<code>false</code> value of each flag to be set or unset</li>
|
||
<li><a class="anchor" href="#nil_7" name="nil_7">#</a>if a flag equals <code>nil</code>, the flag is not modified</li>
|
||
<li><a class="anchor" href="#minimap" name="minimap">#</a>note that setting <code>minimap</code> modifies the client's permission to view the minimap -</li>
|
||
<li>the client may locally elect to not view the minimap</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#hud_get_flags" name="hud_get_flags">#</a><code>hud_get_flags()</code>: returns a table containing status of hud flags<ul>
|
||
<li><a class="anchor" href="#hotbartruehealthbartruecrosshairtruewielditemtruebreathbartrueminimaptrue" name="hotbartruehealthbartruecrosshairtruewielditemtruebreathbartrueminimaptrue">#</a>returns <code>{ hotbar=true, healthbar=true, crosshair=true, wielditem=true, breathbar=true, minimap=true }</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#hud_set_hotbar_itemcountcount" name="hud_set_hotbar_itemcountcount">#</a><code>hud_set_hotbar_itemcount(count)</code>: sets number of items in builtin hotbar<ul>
|
||
<li><a class="anchor" href="#count" name="count">#</a><code>count</code>: number of items, must be between <code>1</code> and <code>23</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#hud_get_hotbar_itemcount" name="hud_get_hotbar_itemcount">#</a><code>hud_get_hotbar_itemcount</code>: returns number of visible items</li>
|
||
<li><a class="anchor" href="#hud_set_hotbar_imagetexturename" name="hud_set_hotbar_imagetexturename">#</a><code>hud_set_hotbar_image(texturename)</code><ul>
|
||
<li>sets background image for hotbar</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#hud_get_hotbar_image" name="hud_get_hotbar_image">#</a><code>hud_get_hotbar_image</code>: returns texturename</li>
|
||
<li><a class="anchor" href="#hud_set_hotbar_selected_imagetexturename" name="hud_set_hotbar_selected_imagetexturename">#</a><code>hud_set_hotbar_selected_image(texturename)</code><ul>
|
||
<li>sets image for selected item of hotbar</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#hud_get_hotbar_selected_image" name="hud_get_hotbar_selected_image">#</a><code>hud_get_hotbar_selected_image</code>: returns texturename</li>
|
||
<li><a class="anchor" href="#set_skybgcolortypetexturenamesclouds" name="set_skybgcolortypetexturenamesclouds">#</a><code>set_sky(bgcolor, type, {texture names}, clouds)</code><ul>
|
||
<li><a class="anchor" href="#bgcolor_1" name="bgcolor_1">#</a><code>bgcolor</code>: ColorSpec, defaults to white</li>
|
||
<li><a class="anchor" href="#type_3" name="type_3">#</a><code>type</code>: Available types:<ul>
|
||
<li><a class="anchor" href="#regular" name="regular">#</a><code>"regular"</code>: Uses 0 textures, <code>bgcolor</code> ignored</li>
|
||
<li><a class="anchor" href="#skybox" name="skybox">#</a><code>"skybox"</code>: Uses 6 textures, <code>bgcolor</code> used</li>
|
||
<li><a class="anchor" href="#plain" name="plain">#</a><code>"plain"</code>: Uses 0 textures, <code>bgcolor</code> used</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#clouds" name="clouds">#</a><code>clouds</code>: Boolean for whether clouds appear in front of <code>"skybox"</code> or
|
||
<code>"plain"</code> custom skyboxes (default: <code>true</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_sky" name="get_sky">#</a><code>get_sky()</code>: returns bgcolor, type, table of textures, clouds</li>
|
||
<li><a class="anchor" href="#set_cloudsparameters" name="set_cloudsparameters">#</a><code>set_clouds(parameters)</code>: set cloud parameters<ul>
|
||
<li><a class="anchor" href="#parameters_1" name="parameters_1">#</a><code>parameters</code> is a table with the following optional fields:<ul>
|
||
<li><a class="anchor" href="#density" name="density">#</a><code>density</code>: from <code>0</code> (no clouds) to <code>1</code> (full clouds) (default <code>0.4</code>)</li>
|
||
<li><a class="anchor" href="#color_8" name="color_8">#</a><code>color</code>: basic cloud color with alpha channel, ColorSpec (default <code>#fff0f0e5</code>)</li>
|
||
<li><a class="anchor" href="#ambient" name="ambient">#</a><code>ambient</code>: cloud color lower bound, use for a "glow at night" effect.
|
||
ColorSpec (alpha ignored, default <code>#000000</code>)</li>
|
||
<li><a class="anchor" href="#height" name="height">#</a><code>height</code>: cloud height, i.e. y of cloud base (default per conf, usually <code>120</code>)</li>
|
||
<li><a class="anchor" href="#thickness" name="thickness">#</a><code>thickness</code>: cloud thickness in nodes (default <code>16</code>)</li>
|
||
<li><a class="anchor" href="#speed_1" name="speed_1">#</a><code>speed</code>: 2D cloud speed + direction in nodes per second (default <code>{x=0, z=-2}</code>)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_clouds" name="get_clouds">#</a><code>get_clouds()</code>: returns a table with the current cloud parameters as in <code>set_clouds</code></li>
|
||
<li><a class="anchor" href="#override_day_night_ratioratioornil" name="override_day_night_ratioratioornil">#</a><code>override_day_night_ratio(ratio or nil)</code><ul>
|
||
<li><a class="anchor" href="#0_12" name="0_12">#</a><code>0</code>...<code>1</code>: Overrides day-night ratio, controlling sunlight to a specific amount</li>
|
||
<li><a class="anchor" href="#nil_8" name="nil_8">#</a><code>nil</code>: Disables override, defaulting to sunlight based on day-night cycle</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_day_night_ratio" name="get_day_night_ratio">#</a><code>get_day_night_ratio()</code>: returns the ratio or nil if it isn't overridden</li>
|
||
<li><a class="anchor" href="#set_local_animationstandidlewalkdigwalkdigframe_speedframe_speed" name="set_local_animationstandidlewalkdigwalkdigframe_speedframe_speed">#</a>
|
||
<p><code>set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed)</code></p>
|
||
<p>set animation for player model in third person view</p>
|
||
<pre><code>set_local_animation({x=0, y=79}, -- < stand/idle animation key frames
|
||
{x=168, y=187}, -- < walk animation key frames
|
||
{x=189, y=198}, -- < dig animation key frames
|
||
{x=200, y=219}, -- < walk+dig animation key frames
|
||
frame_speed=30): -- < animation frame speed
|
||
</code></pre>
|
||
<ul>
|
||
<li><a class="anchor" href="#get_local_animation" name="get_local_animation">#</a><code>get_local_animation()</code>: returns stand, walk, dig, dig+walk tables and <code>frame_speed</code></li>
|
||
<li><a class="anchor" href="#set_eye_offsetx0y0z0x0y0z0" name="set_eye_offsetx0y0z0x0y0z0">#</a><code>set_eye_offset({x=0,y=0,z=0},{x=0,y=0,z=0})</code>: defines offset value for camera per player</li>
|
||
<li>in first person view</li>
|
||
<li><a class="anchor" href="#x1010y1015z55" name="x1010y1015z55">#</a>in third person view (max. values <code>{x=-10/10,y=-10,15,z=-5/5}</code>)</li>
|
||
<li><a class="anchor" href="#get_eye_offset" name="get_eye_offset">#</a><code>get_eye_offset()</code>: returns <code>offset_first</code> and <code>offset_third</code></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="invref"><code>InvRef</code></h3>
|
||
<p>An <code>InvRef</code> is a reference to an inventory.</p>
|
||
<h4 id="methods_6">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#is_emptylistname" name="is_emptylistname">#</a><code>is_empty(listname)</code>: return <code>true</code> if list is empty</li>
|
||
<li><a class="anchor" href="#get_sizelistname" name="get_sizelistname">#</a><code>get_size(listname)</code>: get size of a list</li>
|
||
<li><a class="anchor" href="#set_sizelistnamesize" name="set_sizelistnamesize">#</a><code>set_size(listname, size)</code>: set size of a list<ul>
|
||
<li><a class="anchor" href="#false_2" name="false_2">#</a>returns <code>false</code> on error (e.g. invalid <code>listname</code> or <code>size</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_widthlistname" name="get_widthlistname">#</a><code>get_width(listname)</code>: get width of a list</li>
|
||
<li><a class="anchor" href="#set_widthlistnamewidth" name="set_widthlistnamewidth">#</a><code>set_width(listname, width)</code>: set width of list; currently used for crafting</li>
|
||
<li><a class="anchor" href="#get_stacklistnamei" name="get_stacklistnamei">#</a><code>get_stack(listname, i)</code>: get a copy of stack index <code>i</code> in list</li>
|
||
<li><a class="anchor" href="#set_stacklistnameistack" name="set_stacklistnameistack">#</a><code>set_stack(listname, i, stack)</code>: copy <code>stack</code> to index <code>i</code> in list</li>
|
||
<li><a class="anchor" href="#get_listlistname" name="get_listlistname">#</a><code>get_list(listname)</code>: return full list</li>
|
||
<li><a class="anchor" href="#set_listlistnamelist" name="set_listlistnamelist">#</a><code>set_list(listname, list)</code>: set full list (size will not change)</li>
|
||
<li><a class="anchor" href="#get_lists" name="get_lists">#</a><code>get_lists()</code>: returns list of inventory lists</li>
|
||
<li><a class="anchor" href="#set_listslists" name="set_listslists">#</a><code>set_lists(lists)</code>: sets inventory lists (size will not change)</li>
|
||
<li><a class="anchor" href="#add_itemlistnamestack" name="add_itemlistnamestack">#</a><code>add_item(listname, stack)</code>: add item somewhere in list, returns leftover <code>ItemStack</code></li>
|
||
<li><a class="anchor" href="#room_for_itemlistnamestack" name="room_for_itemlistnamestack">#</a><code>room_for_item(listname, stack):</code> returns <code>true</code> if the stack of items
|
||
can be fully added to the list</li>
|
||
<li><a class="anchor" href="#contains_itemlistnamestackmatch_meta" name="contains_itemlistnamestackmatch_meta">#</a><code>contains_item(listname, stack, [match_meta])</code>: returns <code>true</code> if
|
||
the stack of items can be fully taken from the list.
|
||
If <code>match_meta</code> is false, only the items' names are compared (default: <code>false</code>).</li>
|
||
<li><a class="anchor" href="#remove_itemlistnamestack" name="remove_itemlistnamestack">#</a><code>remove_item(listname, stack)</code>: take as many items as specified from the list,
|
||
returns the items that were actually removed (as an <code>ItemStack</code>) -- note that
|
||
any item metadata is ignored, so attempting to remove a specific unique
|
||
item this way will likely remove the wrong one -- to do that use <code>set_stack</code>
|
||
with an empty <code>ItemStack</code></li>
|
||
<li><a class="anchor" href="#get_location" name="get_location">#</a><code>get_location()</code>: returns a location compatible to <code>minetest.get_inventory(location)</code><ul>
|
||
<li><a class="anchor" href="#typeundefined" name="typeundefined">#</a>returns <code>{type="undefined"}</code> in case location is not known</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="areastore"><code>AreaStore</code></h3>
|
||
<p>A fast access data structure to store areas, and find areas near a given position or area.
|
||
Every area has a <code>data</code> string attribute to store additional information.
|
||
You can create an empty <code>AreaStore</code> by calling <code>AreaStore()</code>, or <code>AreaStore(type_name)</code>.
|
||
If you chose the parameter-less constructor, a fast implementation will be automatically
|
||
chosen for you.</p>
|
||
<h4 id="methods_7">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#get_areaidinclude_bordersinclude_data" name="get_areaidinclude_bordersinclude_data">#</a><code>get_area(id, include_borders, include_data)</code>: returns the area with the id <code>id</code>.
|
||
(optional) Boolean values <code>include_borders</code> and <code>include_data</code> control what's copied.
|
||
Returns nil if specified area id does not exist.</li>
|
||
<li><a class="anchor" href="#get_areas_for_posposinclude_bordersinclude_data" name="get_areas_for_posposinclude_bordersinclude_data">#</a><code>get_areas_for_pos(pos, include_borders, include_data)</code>: returns all areas that contain
|
||
the position <code>pos</code>. (optional) Boolean values <code>include_borders</code> and <code>include_data</code> control
|
||
what's copied.</li>
|
||
<li><a class="anchor" href="#get_areas_in_areaedge1edge2accept_overlapinclude_bordersinclude_data" name="get_areas_in_areaedge1edge2accept_overlapinclude_bordersinclude_data">#</a><code>get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)</code>:
|
||
returns all areas that contain all nodes inside the area specified by <code>edge1</code> and <code>edge2</code> (inclusive).
|
||
If <code>accept_overlap</code> is true, also areas are returned that have nodes in common with the specified area.
|
||
(optional) Boolean values <code>include_borders</code> and <code>include_data</code> control what's copied.</li>
|
||
<li><a class="anchor" href="#insert_areaedge1edge2dataid" name="insert_areaedge1edge2dataid">#</a><code>insert_area(edge1, edge2, data, [id])</code>: inserts an area into the store. Returns the new area's ID,
|
||
or nil if the insertion failed. The (inclusive) positions <code>edge1</code> and <code>edge2</code> describe the area.
|
||
<code>data</code> is a string stored with the area. If passed, <code>id</code> will be used as the internal area ID,
|
||
it must be a unique number between 0 and 2^32-2. If you use the <code>id</code> parameter you must always use it,
|
||
or insertions are likely to fail due to conflicts.</li>
|
||
<li><a class="anchor" href="#reservecount" name="reservecount">#</a><code>reserve(count)</code>: reserves resources for at most <code>count</code> many contained areas.
|
||
Only needed for efficiency, and only some implementations profit.</li>
|
||
<li><a class="anchor" href="#remove_areaid" name="remove_areaid">#</a><code>remove_area(id)</code>: removes the area with the given id from the store, returns success.</li>
|
||
<li><a class="anchor" href="#set_cache_paramsparams" name="set_cache_paramsparams">#</a><code>set_cache_params(params)</code>: sets params for the included prefiltering cache.
|
||
Calling invalidates the cache, so that its elements have to be newly generated.<ul>
|
||
<li><a class="anchor" href="#params" name="params">#</a><code>params</code>:
|
||
{
|
||
enabled = boolean, -- whether to enable, default true
|
||
block_radius = number, -- the radius (in nodes) of the areas the cache generates
|
||
prefiltered lists for, minimum 16, default 64
|
||
limit = number, -- the cache's size, minimum 20, default 1000
|
||
}</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#to_string" name="to_string">#</a><code>to_string()</code>: Experimental. Returns area store serialized as a (binary) string.</li>
|
||
<li><a class="anchor" href="#to_filefilename" name="to_filefilename">#</a><code>to_file(filename)</code>: Experimental. Like <code>to_string()</code>, but writes the data to a file.</li>
|
||
<li><a class="anchor" href="#from_stringstr" name="from_stringstr">#</a><code>from_string(str)</code>: Experimental. Deserializes string and loads it into the AreaStore.
|
||
Returns success and, optionally, an error message.</li>
|
||
<li><a class="anchor" href="#from_filefilename" name="from_filefilename">#</a><code>from_file(filename)</code>: Experimental. Like <code>from_string()</code>, but reads the data from a file.</li>
|
||
</ul>
|
||
<h3 id="itemstack_1"><code>ItemStack</code></h3>
|
||
<p>An <code>ItemStack</code> is a stack of items.</p>
|
||
<p>It can be created via <code>ItemStack(x)</code>, where x is an <code>ItemStack</code>,
|
||
an itemstring, a table or <code>nil</code>.</p>
|
||
<h4 id="methods_8">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#is_empty" name="is_empty">#</a><code>is_empty()</code>: Returns <code>true</code> if stack is empty.</li>
|
||
<li><a class="anchor" href="#get_name" name="get_name">#</a><code>get_name()</code>: Returns item name (e.g. <code>"default:stone"</code>).</li>
|
||
<li><a class="anchor" href="#set_nameitem_name" name="set_nameitem_name">#</a><code>set_name(item_name)</code>: Returns boolean whether item was cleared</li>
|
||
<li><a class="anchor" href="#get_count" name="get_count">#</a><code>get_count()</code>: Returns number of items on the stack.</li>
|
||
<li><a class="anchor" href="#set_countcount" name="set_countcount">#</a><code>set_count(count)</code>: Returns boolean whether item was cleared</li>
|
||
<li><a class="anchor" href="#get_wear" name="get_wear">#</a><code>get_wear()</code>: Returns tool wear (<code>0</code>-<code>65535</code>), <code>0</code> for non-tools.</li>
|
||
<li><a class="anchor" href="#set_wearwear" name="set_wearwear">#</a><code>set_wear(wear)</code>: Returns boolean whether item was cleared</li>
|
||
<li><a class="anchor" href="#get_meta" name="get_meta">#</a><code>get_meta()</code>: Returns ItemStackMetaRef. See section for more details</li>
|
||
<li><a class="anchor" href="#get_metadata" name="get_metadata">#</a><code>get_metadata()</code>: (DEPRECATED) Returns metadata (a string attached to an item stack).</li>
|
||
<li><a class="anchor" href="#set_metadatametadata" name="set_metadatametadata">#</a><code>set_metadata(metadata)</code>: (DEPRECATED) Returns true.</li>
|
||
<li><a class="anchor" href="#clear" name="clear">#</a><code>clear()</code>: removes all items from the stack, making it empty.</li>
|
||
<li><a class="anchor" href="#replaceitem" name="replaceitem">#</a><code>replace(item)</code>: replace the contents of this stack.<ul>
|
||
<li><a class="anchor" href="#item_3" name="item_3">#</a><code>item</code> can also be an itemstring or table.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#to_string_1" name="to_string_1">#</a><code>to_string()</code>: Returns the stack in itemstring form.</li>
|
||
<li><a class="anchor" href="#to_table_1" name="to_table_1">#</a><code>to_table()</code>: Returns the stack in Lua table form.</li>
|
||
<li><a class="anchor" href="#get_stack_max" name="get_stack_max">#</a><code>get_stack_max()</code>: Returns the maximum size of the stack (depends on the item).</li>
|
||
<li><a class="anchor" href="#get_free_space" name="get_free_space">#</a><code>get_free_space()</code>: Returns <code>get_stack_max() - get_count()</code>.</li>
|
||
<li><a class="anchor" href="#is_known" name="is_known">#</a><code>is_known()</code>: Returns <code>true</code> if the item name refers to a defined item type.</li>
|
||
<li><a class="anchor" href="#get_definition" name="get_definition">#</a><code>get_definition()</code>: Returns the item definition table.</li>
|
||
<li><a class="anchor" href="#get_tool_capabilities" name="get_tool_capabilities">#</a><code>get_tool_capabilities()</code>: Returns the digging properties of the item,
|
||
or those of the hand if none are defined for this item type</li>
|
||
<li><a class="anchor" href="#add_wearamount" name="add_wearamount">#</a><code>add_wear(amount)</code>: Increases wear by <code>amount</code> if the item is a tool.</li>
|
||
<li><a class="anchor" href="#add_itemitem" name="add_itemitem">#</a><code>add_item(item)</code>: Put some item or stack onto this stack.
|
||
Returns leftover <code>ItemStack</code>.</li>
|
||
<li><a class="anchor" href="#item_fitsitem" name="item_fitsitem">#</a><code>item_fits(item)</code>: Returns <code>true</code> if item or stack can be fully added to
|
||
this one.</li>
|
||
<li><a class="anchor" href="#take_itemn1" name="take_itemn1">#</a><code>take_item(n=1)</code>: Take (and remove) up to <code>n</code> items from this stack.
|
||
Returns taken <code>ItemStack</code>.</li>
|
||
<li><a class="anchor" href="#peek_itemn1" name="peek_itemn1">#</a><code>peek_item(n=1)</code>: copy (don't remove) up to <code>n</code> items from this stack.
|
||
Returns taken <code>ItemStack</code>.</li>
|
||
</ul>
|
||
<h3 id="pseudorandom"><code>PseudoRandom</code></h3>
|
||
<p>A 16-bit pseudorandom number generator.
|
||
Uses a well-known LCG algorithm introduced by K&R.</p>
|
||
<p>It can be created via <code>PseudoRandom(seed)</code>.</p>
|
||
<h4 id="methods_9">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#next" name="next">#</a><code>next()</code>: return next integer random number [<code>0</code>...<code>32767</code>]</li>
|
||
<li><a class="anchor" href="#nextminmax" name="nextminmax">#</a><code>next(min, max)</code>: return next integer random number [<code>min</code>...<code>max</code>]<ul>
|
||
<li><a class="anchor" href="#maxmin32767ormaxmin6553" name="maxmin32767ormaxmin6553">#</a><code>((max - min) == 32767) or ((max-min) <= 6553))</code> must be true
|
||
due to the simple implementation making bad distribution otherwise.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="pcgrandom"><code>PcgRandom</code></h3>
|
||
<p>A 32-bit pseudorandom number generator.
|
||
Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness.</p>
|
||
<p>It can be created via <code>PcgRandom(seed)</code> or <code>PcgRandom(seed, sequence)</code>.</p>
|
||
<h4 id="methods_10">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#next_1" name="next_1">#</a><code>next()</code>: return next integer random number [<code>-2147483648</code>...<code>2147483647</code>]</li>
|
||
<li><a class="anchor" href="#nextminmax_1" name="nextminmax_1">#</a><code>next(min, max)</code>: return next integer random number [<code>min</code>...<code>max</code>]</li>
|
||
<li><a class="anchor" href="#rand_normal_distminmaxnum_trials6" name="rand_normal_distminmaxnum_trials6">#</a><code>rand_normal_dist(min, max, num_trials=6)</code>: return normally distributed random number [<code>min</code>...<code>max</code>]<ul>
|
||
<li>This is only a rough approximation of a normal distribution with:</li>
|
||
<li><a class="anchor" href="#meanmaxmin2" name="meanmaxmin2">#</a><code>mean = (max - min) / 2</code>, and</li>
|
||
<li><a class="anchor" href="#variancemaxmin12112num_trials" name="variancemaxmin12112num_trials">#</a><code>variance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)</code></li>
|
||
<li><a class="anchor" href="#num_trials" name="num_trials">#</a>Increasing <code>num_trials</code> improves accuracy of the approximation</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="securerandom"><code>SecureRandom</code></h3>
|
||
<p>Interface for the operating system's crypto-secure PRNG.</p>
|
||
<p>It can be created via <code>SecureRandom()</code>. The constructor returns nil if a secure random device cannot be
|
||
be found on the system.</p>
|
||
<h4 id="methods_11">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#next_bytescount" name="next_bytescount">#</a><code>next_bytes([count])</code>: return next <code>count</code> (default 1, capped at 2048) many random bytes, as a string.</li>
|
||
</ul>
|
||
<h3 id="perlinnoise"><code>PerlinNoise</code></h3>
|
||
<p>A perlin noise generator.
|
||
It can be created via <code>PerlinNoise(seed, octaves, persistence, scale)</code>
|
||
or <code>PerlinNoise(noiseparams)</code>.
|
||
Alternatively with <code>minetest.get_perlin(seeddiff, octaves, persistence, scale)</code>
|
||
or <code>minetest.get_perlin(noiseparams)</code>.</p>
|
||
<h4 id="methods_12">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#get2dpos" name="get2dpos">#</a><code>get2d(pos)</code>: returns 2D noise value at <code>pos={x=,y=}</code></li>
|
||
<li><a class="anchor" href="#get3dpos" name="get3dpos">#</a><code>get3d(pos)</code>: returns 3D noise value at <code>pos={x=,y=,z=}</code></li>
|
||
</ul>
|
||
<h3 id="perlinnoisemap"><code>PerlinNoiseMap</code></h3>
|
||
<p>A fast, bulk perlin noise generator.</p>
|
||
<p>It can be created via <code>PerlinNoiseMap(noiseparams, size)</code> or
|
||
<code>minetest.get_perlin_map(noiseparams, size)</code>.</p>
|
||
<p>Format of <code>size</code> is <code>{x=dimx, y=dimy, z=dimz}</code>. The <code>z</code> conponent is ommitted
|
||
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
|
||
<code>nil</code> is returned).</p>
|
||
<p>For each of the functions with an optional <code>buffer</code> parameter: If <code>buffer</code> is not
|
||
nil, this table will be used to store the result instead of creating a new table.</p>
|
||
<h4 id="methods_13">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#get2dMappos" name="get2dMappos">#</a><code>get2dMap(pos)</code>: returns a <code><size.x></code> times <code><size.y></code> 2D array of 2D noise
|
||
with values starting at <code>pos={x=,y=}</code></li>
|
||
<li><a class="anchor" href="#get3dMappos" name="get3dMappos">#</a><code>get3dMap(pos)</code>: returns a <code><size.x></code> times <code><size.y></code> times <code><size.z></code> 3D array
|
||
of 3D noise with values starting at <code>pos={x=,y=,z=}</code></li>
|
||
<li><a class="anchor" href="#get2dMap_flatposbuffer" name="get2dMap_flatposbuffer">#</a><code>get2dMap_flat(pos, buffer)</code>: returns a flat <code><size.x * size.y></code> element array of 2D noise
|
||
with values starting at <code>pos={x=,y=}</code></li>
|
||
<li><a class="anchor" href="#get3dMap_flatposbuffer" name="get3dMap_flatposbuffer">#</a><code>get3dMap_flat(pos, buffer)</code>: Same as <code>get2dMap_flat</code>, but 3D noise</li>
|
||
<li><a class="anchor" href="#calc2dMappos" name="calc2dMappos">#</a><code>calc2dMap(pos)</code>: Calculates the 2d noise map starting at <code>pos</code>. The result is stored internally.</li>
|
||
<li><a class="anchor" href="#calc3dMappos" name="calc3dMappos">#</a><code>calc3dMap(pos)</code>: Calculates the 3d noise map starting at <code>pos</code>. The result is stored internally.</li>
|
||
<li><a class="anchor" href="#getMapSliceslice_offsetslice_sizebuffer" name="getMapSliceslice_offsetslice_sizebuffer">#</a><code>getMapSlice(slice_offset, slice_size, buffer)</code>: In the form of an array, returns a slice of the
|
||
most recently computed noise results. The result slice begins at coordinates <code>slice_offset</code> and
|
||
takes a chunk of <code>slice_size</code>.
|
||
E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20:
|
||
<code>noisevals = noise:getMapSlice({y=20}, {y=2})</code>
|
||
It is important to note that <code>slice_offset</code> offset coordinates begin at 1, and are relative to
|
||
the starting position of the most recently calculated noise.
|
||
To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000:
|
||
<code>noise:calc3dMap({x=1000, y=1000, z=1000})</code>
|
||
<code>noisevals = noise:getMapSlice({x=24, z=1}, {x=1, z=1})</code></li>
|
||
</ul>
|
||
<h3 id="voxelmanip"><code>VoxelManip</code></h3>
|
||
<h4 id="about-voxelmanip">About VoxelManip</h4>
|
||
<p>VoxelManip is a scripting interface to the internal 'Map Voxel Manipulator' facility. The purpose of
|
||
this object is for fast, low-level, bulk access to reading and writing Map content. As such, setting
|
||
map nodes through VoxelManip will lack many of the higher level features and concepts you may be used
|
||
to with other methods of setting nodes. For example, nodes will not have their construction and
|
||
destruction callbacks run, and no rollback information is logged.</p>
|
||
<p>It is important to note that VoxelManip is designed for speed, and <em>not</em> ease of use or flexibility.
|
||
If your mod requires a map manipulation facility that will handle 100% of all edge cases, or the use
|
||
of high level node placement features, perhaps <code>minetest.set_node()</code> is better suited for the job.</p>
|
||
<p>In addition, VoxelManip might not be faster, or could even be slower, for your specific use case.
|
||
VoxelManip is most effective when setting very large areas of map at once - for example, if only
|
||
setting a 5x5x5 node area, a <code>minetest.set_node()</code> loop may be more optimal. Always profile code
|
||
using both methods of map manipulation to determine which is most appropriate for your usage.</p>
|
||
<h4 id="using-voxelmanip">Using VoxelManip</h4>
|
||
<p>A VoxelManip object can be created any time using either:
|
||
<code>VoxelManip([p1, p2])</code>, or <code>minetest.get_voxel_manip([p1, p2])</code>.</p>
|
||
<p>If the optional position parameters are present for either of these routines, the specified region
|
||
will be pre-loaded into the VoxelManip object on creation. Otherwise, the area of map you wish to
|
||
manipulate must first be loaded into the VoxelManip object using <code>VoxelManip:read_from_map()</code>.</p>
|
||
<p>Note that <code>VoxelManip:read_from_map()</code> returns two position vectors. The region formed by these
|
||
positions indicate the minimum and maximum (respectively) positions of the area actually loaded in
|
||
the VoxelManip, which may be larger than the area requested. For convenience, the loaded area
|
||
coordinates can also be queried any time after loading map data with <code>VoxelManip:get_emerged_area()</code>.</p>
|
||
<p>Now that the VoxelManip object is populated with map data, your mod can fetch a copy of this data
|
||
using either of two methods. <code>VoxelManip:get_node_at()</code>, which retrieves an individual node in a
|
||
MapNode formatted table at the position requested is the simplest method to use, but also the slowest.</p>
|
||
<p>Nodes in a VoxelManip object may also be read in bulk to a flat array table using:
|
||
<code>VoxelManip:get_data()</code> for node content (in Content ID form, see section 'Content IDs'),
|
||
<code>VoxelManip:get_light_data()</code> for node light levels, and
|
||
<code>VoxelManip:get_param2_data()</code> for the node type-dependent "param2" values.</p>
|
||
<p>See section 'Flat array format' for more details.</p>
|
||
<p>It is very important to understand that the tables returned by any of the above three functions
|
||
represent a snapshot of the VoxelManip's internal state at the time of the call. This copy of the
|
||
data will <em>not</em> magically update itself if another function modifies the internal VoxelManip state.
|
||
Any functions that modify a VoxelManip's contents work on the VoxelManip's internal state unless
|
||
otherwise explicitly stated.</p>
|
||
<p>Once the bulk data has been edited to your liking, the internal VoxelManip state can be set using:
|
||
<code>VoxelManip:set_data()</code> for node content (in Content ID form, see section 'Content IDs'),
|
||
<code>VoxelManip:set_light_data()</code> for node light levels, and
|
||
<code>VoxelManip:set_param2_data()</code> for the node type-dependent <code>param2</code> values.</p>
|
||
<p>The parameter to each of the above three functions can use any table at all in the same flat array
|
||
format as produced by <code>get_data()</code> et al. and is <em>not required</em> to be a table retrieved from <code>get_data()</code>.</p>
|
||
<p>Once the internal VoxelManip state has been modified to your liking, the changes can be committed back
|
||
to the map by calling <code>VoxelManip:write_to_map()</code>.</p>
|
||
<h5 id="flat-array-format">Flat array format</h5>
|
||
<p>Let
|
||
<code>Nx = p2.X - p1.X + 1</code>,
|
||
<code>Ny = p2.Y - p1.Y + 1</code>, and
|
||
<code>Nz = p2.Z - p1.Z + 1</code>.</p>
|
||
<p>Then, for a loaded region of p1..p2, this array ranges from <code>1</code> up to and including the value of
|
||
the expression <code>Nx * Ny * Nz</code>.</p>
|
||
<p>Positions offset from p1 are present in the array with the format of:</p>
|
||
<p><code>[
|
||
(0, 0, 0), (1, 0, 0), (2, 0, 0), ... (Nx, 0, 0),
|
||
(0, 1, 0), (1, 1, 0), (2, 1, 0), ... (Nx, 1, 0),
|
||
...
|
||
(0, Ny, 0), (1, Ny, 0), (2, Ny, 0), ... (Nx, Ny, 0),
|
||
(0, 0, 1), (1, 0, 1), (2, 0, 1), ... (Nx, 0, 1),
|
||
...
|
||
(0, Ny, 2), (1, Ny, 2), (2, Ny, 2), ... (Nx, Ny, 2),
|
||
...
|
||
(0, Ny, Nz), (1, Ny, Nz), (2, Ny, Nz), ... (Nx, Ny, Nz)
|
||
]</code></p>
|
||
<p>and the array index for a position p contained completely in p1..p2 is:</p>
|
||
<p><code>(p.Z - p1.Z) * Ny * Nx + (p.Y - p1.Y) * Nx + (p.X - p1.X) + 1</code></p>
|
||
<p>Note that this is the same "flat 3D array" format as <code>PerlinNoiseMap:get3dMap_flat()</code>.
|
||
VoxelArea objects (see section 'VoxelArea') can be used to simplify calculation of the index
|
||
for a single point in a flat VoxelManip array.</p>
|
||
<h5 id="content-ids">Content IDs</h5>
|
||
<p>A Content ID is a unique integer identifier for a specific node type. These IDs are used by VoxelManip
|
||
in place of the node name string for <code>VoxelManip:get_data()</code> and <code>VoxelManip:set_data()</code>. You can use
|
||
<code>minetest.get_content_id()</code> to look up the Content ID for the specified node name, and
|
||
<code>minetest.get_name_from_content_id()</code> to look up the node name string for a given Content ID.
|
||
After registration of a node, its Content ID will remain the same throughout execution of the mod.
|
||
Note that the node being queried needs to have already been been registered.</p>
|
||
<p>The following builtin node types have their Content IDs defined as constants:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestCONTENT_UNKNOWN" name="minetestCONTENT_UNKNOWN">#</a><code>minetest.CONTENT_UNKNOWN</code>: ID for "unknown" nodes</li>
|
||
<li><a class="anchor" href="#minetestCONTENT_AIR" name="minetestCONTENT_AIR">#</a><code>minetest.CONTENT_AIR</code>: ID for "air" nodes</li>
|
||
<li><a class="anchor" href="#minetestCONTENT_IGNORE" name="minetestCONTENT_IGNORE">#</a><code>minetest.CONTENT_IGNORE</code>: ID for "ignore" nodes</li>
|
||
</ul>
|
||
<h5 id="mapgen-voxelmanip-objects">Mapgen VoxelManip objects</h5>
|
||
<p>Inside of <code>on_generated()</code> callbacks, it is possible to retrieve the same VoxelManip object used by the
|
||
core's Map Generator (commonly abbreviated Mapgen). Most of the rules previously described still apply
|
||
but with a few differences:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#minetestget_mapgen_objectvoxelmanip" name="minetestget_mapgen_objectvoxelmanip">#</a>The Mapgen VoxelManip object is retrieved using: <code>minetest.get_mapgen_object("voxelmanip")</code></li>
|
||
<li><a class="anchor" href="#VoxelManipread_from_map" name="VoxelManipread_from_map">#</a>This VoxelManip object already has the region of map just generated loaded into it; it's not necessary
|
||
to call <code>VoxelManip:read_from_map()</code> before using a Mapgen VoxelManip.</li>
|
||
<li><a class="anchor" href="#on_generated" name="on_generated">#</a>The <code>on_generated()</code> callbacks of some mods may place individual nodes in the generated area using
|
||
non-VoxelManip map modification methods. Because the same Mapgen VoxelManip object is passed through
|
||
each <code>on_generated()</code> callback, it becomes necessary for the Mapgen VoxelManip object to maintain
|
||
consistency with the current map state. For this reason, calling any of the following functions:
|
||
<code>minetest.add_node()</code>, <code>minetest.set_node()</code>, or <code>minetest.swap_node()</code>
|
||
will also update the Mapgen VoxelManip object's internal state active on the current thread.</li>
|
||
<li><a class="anchor" href="#VoxelManipcalc_lighting" name="VoxelManipcalc_lighting">#</a>After modifying the Mapgen VoxelManip object's internal buffer, it may be necessary to update lighting
|
||
information using either: <code>VoxelManip:calc_lighting()</code> or <code>VoxelManip:set_lighting()</code>.</li>
|
||
</ul>
|
||
<h5 id="other-api-functions-operating-on-a-voxelmanip">Other API functions operating on a VoxelManip</h5>
|
||
<p>If any VoxelManip contents were set to a liquid node, <code>VoxelManip:update_liquids()</code> must be called
|
||
for these liquid nodes to begin flowing. It is recommended to call this function only after having
|
||
written all buffered data back to the VoxelManip object, save for special situations where the modder
|
||
desires to only have certain liquid nodes begin flowing.</p>
|
||
<p>The functions <code>minetest.generate_ores()</code> and <code>minetest.generate_decorations()</code> will generate all
|
||
registered decorations and ores throughout the full area inside of the specified VoxelManip object.</p>
|
||
<p><code>minetest.place_schematic_on_vmanip()</code> is otherwise identical to <code>minetest.place_schematic()</code>,
|
||
except instead of placing the specified schematic directly on the map at the specified position, it
|
||
will place the schematic inside of the VoxelManip.</p>
|
||
<h5 id="notes">Notes</h5>
|
||
<ul>
|
||
<li><a class="anchor" href="#VoxelManipget_data" name="VoxelManipget_data">#</a>Attempting to read data from a VoxelManip object before map is read will result in a zero-length
|
||
array table for <code>VoxelManip:get_data()</code>, and an "ignore" node at any position for
|
||
<code>VoxelManip:get_node_at()</code>.</li>
|
||
<li>If either a region of map has not yet been generated or is out-of-bounds of the map, that region is
|
||
filled with "ignore" nodes.</li>
|
||
<li>Other mods, or the core itself, could possibly modify the area of map currently loaded into a VoxelManip
|
||
object. With the exception of Mapgen VoxelManips (see above section), the internal buffers are not
|
||
updated. For this reason, it is strongly encouraged to complete the usage of a particular VoxelManip
|
||
object in the same callback it had been created.</li>
|
||
<li><a class="anchor" href="#on_generated_1" name="on_generated_1">#</a>If a VoxelManip object will be used often, such as in an <code>on_generated()</code> callback, consider passing
|
||
a file-scoped table as the optional parameter to <code>VoxelManip:get_data()</code>, which serves as a static
|
||
buffer the function can use to write map data to instead of returning a new table each call. This
|
||
greatly enhances performance by avoiding unnecessary memory allocations.</li>
|
||
</ul>
|
||
<h4 id="methods_14">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#read_from_mapp1p2" name="read_from_mapp1p2">#</a><code>read_from_map(p1, p2)</code>: Loads a chunk of map into the VoxelManip object containing
|
||
the region formed by <code>p1</code> and <code>p2</code>.<ul>
|
||
<li><a class="anchor" href="#pmin" name="pmin">#</a>returns actual emerged <code>pmin</code>, actual emerged <code>pmax</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#write_to_maplight" name="write_to_maplight">#</a><code>write_to_map([light])</code>: Writes the data loaded from the <code>VoxelManip</code> back to the map.<ul>
|
||
<li><a class="anchor" href="#VoxelManipset_data" name="VoxelManipset_data">#</a><strong>important</strong>: data must be set using <code>VoxelManip:set_data()</code> before calling this</li>
|
||
<li><a class="anchor" href="#light" name="light">#</a>if <code>light</code> is true, then lighting is automatically recalculated.
|
||
The default value is true.
|
||
If <code>light</code> is false, no light calculations happen, and you should correct
|
||
all modified blocks with <code>minetest.fix_light()</code> as soon as possible.
|
||
Keep in mind that modifying the map where light is incorrect can cause
|
||
more lighting bugs.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_node_atpos" name="get_node_atpos">#</a><code>get_node_at(pos)</code>: Returns a <code>MapNode</code> table of the node currently loaded in
|
||
the <code>VoxelManip</code> at that position</li>
|
||
<li><a class="anchor" href="#set_node_atposnode" name="set_node_atposnode">#</a><code>set_node_at(pos, node)</code>: Sets a specific <code>MapNode</code> in the <code>VoxelManip</code> at that position</li>
|
||
<li><a class="anchor" href="#get_databuffer" name="get_databuffer">#</a><code>get_data([buffer])</code>: Retrieves the node content data loaded into the <code>VoxelManip</code> object<ul>
|
||
<li>returns raw node data in the form of an array of node content IDs</li>
|
||
<li><a class="anchor" href="#buffer" name="buffer">#</a>if the param <code>buffer</code> is present, this table will be used to store the result instead</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_datadata" name="set_datadata">#</a><code>set_data(data)</code>: Sets the data contents of the <code>VoxelManip</code> object</li>
|
||
<li><a class="anchor" href="#update_map" name="update_map">#</a><code>update_map()</code>: Does nothing, kept for compatibility.</li>
|
||
<li><a class="anchor" href="#set_lightinglightp1p2" name="set_lightinglightp1p2">#</a><code>set_lighting(light, [p1, p2])</code>: Set the lighting within the <code>VoxelManip</code> to a uniform value<ul>
|
||
<li><a class="anchor" href="#light_1" name="light_1">#</a><code>light</code> is a table, <code>{day=<0...15>, night=<0...15>}</code></li>
|
||
<li><a class="anchor" href="#VoxelManip" name="VoxelManip">#</a>To be used only by a <code>VoxelManip</code> object from <code>minetest.get_mapgen_object</code></li>
|
||
<li><a class="anchor" href="#p1" name="p1">#</a>(<code>p1</code>, <code>p2</code>) is the area in which lighting is set;
|
||
defaults to the whole area if left out</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_light_data" name="get_light_data">#</a><code>get_light_data()</code>: Gets the light data read into the <code>VoxelManip</code> object<ul>
|
||
<li><a class="anchor" href="#0_13" name="0_13">#</a>Returns an array (indices 1 to volume) of integers ranging from <code>0</code> to <code>255</code></li>
|
||
<li><a class="anchor" href="#0_14" name="0_14">#</a>Each value is the bitwise combination of day and night light values (<code>0</code> to <code>15</code> each)</li>
|
||
<li><a class="anchor" href="#lightdaynight16" name="lightdaynight16">#</a><code>light = day + (night * 16)</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_light_datalight_data" name="set_light_datalight_data">#</a><code>set_light_data(light_data)</code>: Sets the <code>param1</code> (light) contents of each node
|
||
in the <code>VoxelManip</code><ul>
|
||
<li><a class="anchor" href="#get_light_data_1" name="get_light_data_1">#</a>expects lighting data in the same format that <code>get_light_data()</code> returns</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#get_param2_databuffer" name="get_param2_databuffer">#</a><code>get_param2_data([buffer])</code>: Gets the raw <code>param2</code> data read into the <code>VoxelManip</code> object<ul>
|
||
<li><a class="anchor" href="#0_15" name="0_15">#</a>Returns an array (indices 1 to volume) of integers ranging from <code>0</code> to <code>255</code></li>
|
||
<li><a class="anchor" href="#buffer_1" name="buffer_1">#</a>If the param <code>buffer</code> is present, this table will be used to store the result instead</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_param2_dataparam2_data" name="set_param2_dataparam2_data">#</a><code>set_param2_data(param2_data)</code>: Sets the <code>param2</code> contents of each node in the <code>VoxelManip</code></li>
|
||
<li><a class="anchor" href="#calc_lightingp1p2propagate_shadow" name="calc_lightingp1p2propagate_shadow">#</a><code>calc_lighting([p1, p2], [propagate_shadow])</code>: Calculate lighting within the <code>VoxelManip</code><ul>
|
||
<li><a class="anchor" href="#VoxelManip_1" name="VoxelManip_1">#</a>To be used only by a <code>VoxelManip</code> object from <code>minetest.get_mapgen_object</code></li>
|
||
<li><a class="anchor" href="#p1_1" name="p1_1">#</a>(<code>p1</code>, <code>p2</code>) is the area in which lighting is set; defaults to the whole area
|
||
if left out or nil</li>
|
||
<li><a class="anchor" href="#propagate_shadow" name="propagate_shadow">#</a><code>propagate_shadow</code> is an optional boolean deciding whether shadows in a generated
|
||
mapchunk above are propagated down into the mapchunk; defaults to <code>true</code> if left out</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#update_liquids" name="update_liquids">#</a><code>update_liquids()</code>: Update liquid flow</li>
|
||
<li><a class="anchor" href="#was_modified" name="was_modified">#</a><code>was_modified()</code>: Returns <code>true</code> or <code>false</code> if the data in the voxel manipulator
|
||
had been modified since the last read from map, due to a call to
|
||
<code>minetest.set_data()</code> on the loaded area elsewhere</li>
|
||
<li><a class="anchor" href="#get_emerged_area" name="get_emerged_area">#</a><code>get_emerged_area()</code>: Returns actual emerged minimum and maximum positions.</li>
|
||
</ul>
|
||
<h3 id="voxelarea"><code>VoxelArea</code></h3>
|
||
<p>A helper class for voxel areas.
|
||
It can be created via <code>VoxelArea:new{MinEdge=pmin, MaxEdge=pmax}</code>.
|
||
The coordinates are <em>inclusive</em>, like most other things in Minetest.</p>
|
||
<h4 id="methods_15">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#getExtent" name="getExtent">#</a><code>getExtent()</code>: returns a 3D vector containing the size of the area formed by
|
||
<code>MinEdge</code> and <code>MaxEdge</code></li>
|
||
<li><a class="anchor" href="#getVolume" name="getVolume">#</a><code>getVolume()</code>: returns the volume of the area formed by <code>MinEdge</code> and <code>MaxEdge</code></li>
|
||
<li><a class="anchor" href="#indexxyz" name="indexxyz">#</a><code>index(x, y, z)</code>: returns the index of an absolute position in a flat array starting at <code>1</code><ul>
|
||
<li><a class="anchor" href="#VoxelManip_2" name="VoxelManip_2">#</a>useful for things like <code>VoxelManip</code>, raw Schematic specifiers,
|
||
<code>PerlinNoiseMap:get2d</code>/<code>3dMap</code>, and so on</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#indexpp" name="indexpp">#</a><code>indexp(p)</code>: same as above, except takes a vector</li>
|
||
<li><a class="anchor" href="#positioni" name="positioni">#</a><code>position(i)</code>: returns the absolute position vector corresponding to index <code>i</code></li>
|
||
<li><a class="anchor" href="#containsxyz" name="containsxyz">#</a><code>contains(x, y, z)</code>: check if (<code>x</code>,<code>y</code>,<code>z</code>) is inside area formed by <code>MinEdge</code> and <code>MaxEdge</code></li>
|
||
<li><a class="anchor" href="#containspp" name="containspp">#</a><code>containsp(p)</code>: same as above, except takes a vector</li>
|
||
<li><a class="anchor" href="#containsii" name="containsii">#</a><code>containsi(i)</code>: same as above, except takes an index <code>i</code></li>
|
||
<li><a class="anchor" href="#iterminxminyminzmaxxmaxymaxz" name="iterminxminyminzmaxxmaxymaxz">#</a><code>iter(minx, miny, minz, maxx, maxy, maxz)</code>: returns an iterator that returns indices<ul>
|
||
<li><a class="anchor" href="#minx" name="minx">#</a>from (<code>minx</code>,<code>miny</code>,<code>minz</code>) to (<code>maxx</code>,<code>maxy</code>,<code>maxz</code>) in the order of <code>[z [y [x]]]</code></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#iterpminpmaxp" name="iterpminpmaxp">#</a><code>iterp(minp, maxp)</code>: same as above, except takes a vector</li>
|
||
</ul>
|
||
<h3 id="settings"><code>Settings</code></h3>
|
||
<p>An interface to read config files in the format of <code>minetest.conf</code>.</p>
|
||
<p>It can be created via <code>Settings(filename)</code>.</p>
|
||
<h4 id="methods_16">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#getkey" name="getkey">#</a><code>get(key)</code>: returns a value</li>
|
||
<li><a class="anchor" href="#get_boolkey" name="get_boolkey">#</a><code>get_bool(key)</code>: returns a boolean</li>
|
||
<li><a class="anchor" href="#setkeyvalue" name="setkeyvalue">#</a><code>set(key, value)</code><ul>
|
||
<li>Setting names can't contain whitespace or any of <code>="{}#</code>.</li>
|
||
<li><a class="anchor" href="#n_2" name="n_2">#</a>Setting values can't contain the sequence <code>\n"""</code>.</li>
|
||
<li><a class="anchor" href="#minetestsettings_1" name="minetestsettings_1">#</a>Setting names starting with "secure." can't be set on the main settings object (<code>minetest.settings</code>).</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#set_boolkeyvalue" name="set_boolkeyvalue">#</a><code>set_bool(key, value)</code><ul>
|
||
<li>See documentation for set() above.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#removekey" name="removekey">#</a><code>remove(key)</code>: returns a boolean (<code>true</code> for success)</li>
|
||
<li><a class="anchor" href="#get_names" name="get_names">#</a><code>get_names()</code>: returns <code>{key1,...}</code></li>
|
||
<li><a class="anchor" href="#write" name="write">#</a><code>write()</code>: returns a boolean (<code>true</code> for success)<ul>
|
||
<li>Writes changes to file.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#to_table_2" name="to_table_2">#</a><code>to_table()</code>: returns <code>{[key1]=value1,...}</code></li>
|
||
</ul>
|
||
<h3 id="raycast"><code>Raycast</code></h3>
|
||
<p>A raycast on the map. It works with selection boxes.
|
||
Can be used as an iterator in a for loop.</p>
|
||
<p>The map is loaded as the ray advances. If the
|
||
map is modified after the <code>Raycast</code> is created,
|
||
the changes may or may not have an effect on
|
||
the object.</p>
|
||
<p>It can be created via <code>Raycast(pos1, pos2, objects, liquids)</code> or
|
||
<code>minetest.raycast(pos1, pos2, objects, liquids)</code> where:
|
||
* <code>pos1</code>: start of the ray
|
||
* <code>pos2</code>: end of the ray
|
||
* <code>objects</code> : if false, only nodes will be returned. Default is true.
|
||
* `liquids' : if false, liquid nodes won't be returned. Default is false.</p>
|
||
<h4 id="methods_17">Methods</h4>
|
||
<ul>
|
||
<li><a class="anchor" href="#next_2" name="next_2">#</a><code>next()</code>: returns a <code>pointed_thing</code><ul>
|
||
<li>Returns the next thing pointed by the ray or nil.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h2 id="mapgen-objects">Mapgen objects</h2>
|
||
<p>A mapgen object is a construct used in map generation. Mapgen objects can be used
|
||
by an <code>on_generate</code> callback to speed up operations by avoiding unnecessary
|
||
recalculations; these can be retrieved using the <code>minetest.get_mapgen_object()</code>
|
||
function. If the requested Mapgen object is unavailable, or <code>get_mapgen_object()</code>
|
||
was called outside of an <code>on_generate()</code> callback, <code>nil</code> is returned.</p>
|
||
<p>The following Mapgen objects are currently available:</p>
|
||
<h3 id="voxelmanip_1"><code>voxelmanip</code></h3>
|
||
<p>This returns three values; the <code>VoxelManip</code> object to be used, minimum and maximum
|
||
emerged position, in that order. All mapgens support this object.</p>
|
||
<h3 id="heightmap"><code>heightmap</code></h3>
|
||
<p>Returns an array containing the y coordinates of the ground levels of nodes in
|
||
the most recently generated chunk by the current mapgen.</p>
|
||
<h3 id="biomemap"><code>biomemap</code></h3>
|
||
<p>Returns an array containing the biome IDs of nodes in the most recently
|
||
generated chunk by the current mapgen.</p>
|
||
<h3 id="heatmap"><code>heatmap</code></h3>
|
||
<p>Returns an array containing the temperature values of nodes in the most
|
||
recently generated chunk by the current mapgen.</p>
|
||
<h3 id="humiditymap"><code>humiditymap</code></h3>
|
||
<p>Returns an array containing the humidity values of nodes in the most recently
|
||
generated chunk by the current mapgen.</p>
|
||
<h3 id="gennotify"><code>gennotify</code></h3>
|
||
<p>Returns a table mapping requested generation notification types to arrays of
|
||
positions at which the corresponding generated structures are located at within
|
||
the current chunk. To set the capture of positions of interest to be recorded
|
||
on generate, use <code>minetest.set_gen_notify()</code>.</p>
|
||
<p>Possible fields of the table returned are:</p>
|
||
<ul>
|
||
<li><a class="anchor" href="#dungeon" name="dungeon">#</a><code>dungeon</code></li>
|
||
<li><a class="anchor" href="#temple" name="temple">#</a><code>temple</code></li>
|
||
<li><a class="anchor" href="#cave_begin" name="cave_begin">#</a><code>cave_begin</code></li>
|
||
<li><a class="anchor" href="#cave_end" name="cave_end">#</a><code>cave_end</code></li>
|
||
<li><a class="anchor" href="#large_cave_begin" name="large_cave_begin">#</a><code>large_cave_begin</code></li>
|
||
<li><a class="anchor" href="#large_cave_end" name="large_cave_end">#</a><code>large_cave_end</code></li>
|
||
<li><a class="anchor" href="#decoration" name="decoration">#</a><code>decoration</code></li>
|
||
</ul>
|
||
<p>Decorations have a key in the format of <code>"decoration#id"</code>, where <code>id</code> is the
|
||
numeric unique decoration ID.</p>
|
||
<h2 id="registered-entities">Registered entities</h2>
|
||
<ul>
|
||
<li><a class="anchor" href="#self" name="self">#</a>Functions receive a "luaentity" as <code>self</code>:<ul>
|
||
<li><a class="anchor" href="#name_15" name="name_15">#</a>It has the member <code>.name</code>, which is the registered name <code>("mod:thing")</code></li>
|
||
<li><a class="anchor" href="#object" name="object">#</a>It has the member <code>.object</code>, which is an <code>ObjectRef</code> pointing to the object</li>
|
||
<li>The original prototype stuff is visible directly via a metatable</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#on_activateselfstaticdatadtime_s" name="on_activateselfstaticdatadtime_s">#</a>Callbacks:<ul>
|
||
<li><a class="anchor" href="#on_activateselfstaticdatadtime_s_1" name="on_activateselfstaticdatadtime_s_1">#</a><code>on_activate(self, staticdata, dtime_s)</code><ul>
|
||
<li>Called when the object is instantiated.</li>
|
||
<li><a class="anchor" href="#dtime_s" name="dtime_s">#</a><code>dtime_s</code> is the time passed since the object was unloaded, which can
|
||
be used for updating the entity state.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#on_stepselfdtime" name="on_stepselfdtime">#</a><code>on_step(self, dtime)</code><ul>
|
||
<li><a class="anchor" href="#dtime" name="dtime">#</a>Called on every server tick, after movement and collision processing.
|
||
<code>dtime</code> is usually 0.1 seconds, as per the <code>dedicated_server_step</code> setting
|
||
<code>in minetest.conf</code>.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#on_punchselfpunchertime_from_last_punchtool_capabilitiesdir" name="on_punchselfpunchertime_from_last_punchtool_capabilitiesdir">#</a><code>on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)</code><ul>
|
||
<li>Called when somebody punches the object.</li>
|
||
<li>Note that you probably want to handle most punches using the
|
||
automatic armor group system.</li>
|
||
<li><a class="anchor" href="#puncher_2" name="puncher_2">#</a><code>puncher</code>: an <code>ObjectRef</code> (can be <code>nil</code>)</li>
|
||
<li><a class="anchor" href="#time_from_last_punch_3" name="time_from_last_punch_3">#</a><code>time_from_last_punch</code>: Meant for disallowing spamming of clicks (can be <code>nil</code>)</li>
|
||
<li><a class="anchor" href="#tool_capabilities_2" name="tool_capabilities_2">#</a><code>tool_capabilities</code>: capability table of used tool (can be <code>nil</code>)</li>
|
||
<li><a class="anchor" href="#dir_1" name="dir_1">#</a><code>dir</code>: unit vector of direction of punch. Always defined. Points from
|
||
the puncher to the punched.
|
||
<code>on_death(self, killer)</code></li>
|
||
<li>Called when the object dies.</li>
|
||
<li><a class="anchor" href="#killer" name="killer">#</a><code>killer</code>: an <code>ObjectRef</code> (can be <code>nil</code>)</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#on_rightclickselfclicker" name="on_rightclickselfclicker">#</a><code>on_rightclick(self, clicker)</code></li>
|
||
<li><a class="anchor" href="#get_staticdataself" name="get_staticdataself">#</a><code>get_staticdata(self)</code><ul>
|
||
<li><a class="anchor" href="#on_activate" name="on_activate">#</a>Should return a string that will be passed to <code>on_activate</code> when
|
||
the object is instantiated the next time.</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h2 id="l-system-trees">L-system trees</h2>
|
||
<p><strong>Warning</strong>
|
||
L-system generation currently creates lighting bugs in the form of mapblock-sized shadows.
|
||
Often these bugs appear as subtle shadows in water.</p>
|
||
<h3 id="tree-definition">Tree definition</h3>
|
||
<pre><code>treedef={
|
||
axiom, --string initial tree axiom
|
||
rules_a, --string rules set A
|
||
rules_b, --string rules set B
|
||
rules_c, --string rules set C
|
||
rules_d, --string rules set D
|
||
trunk, --string trunk node name
|
||
leaves, --string leaves node name
|
||
leaves2, --string secondary leaves node name
|
||
leaves2_chance,--num chance (0-100) to replace leaves with leaves2
|
||
angle, --num angle in deg
|
||
iterations, --num max # of iterations, usually 2 -5
|
||
random_level, --num factor to lower nr of iterations, usually 0 - 3
|
||
trunk_type, --string single/double/crossed) type of trunk: 1 node,
|
||
-- 2x2 nodes or 3x3 in cross shape
|
||
thin_branches, --boolean true -> use thin (1 node) branches
|
||
fruit, --string fruit node name
|
||
fruit_chance, --num chance (0-100) to replace leaves with fruit node
|
||
seed, --num random seed; if no seed is provided, the engine will create one
|
||
}
|
||
</code></pre>
|
||
<h3 id="key-for-special-l-system-symbols-used-in-axioms">Key for Special L-System Symbols used in Axioms</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#G" name="G">#</a><code>G</code>: move forward one unit with the pen up</li>
|
||
<li><a class="anchor" href="#F" name="F">#</a><code>F</code>: move forward one unit with the pen down drawing trunks and branches</li>
|
||
<li><a class="anchor" href="#f" name="f">#</a><code>f</code>: move forward one unit with the pen down drawing leaves (100% chance)</li>
|
||
<li><a class="anchor" href="#T" name="T">#</a><code>T</code>: move forward one unit with the pen down drawing trunks only</li>
|
||
<li><a class="anchor" href="#R" name="R">#</a><code>R</code>: move forward one unit with the pen down placing fruit</li>
|
||
<li><a class="anchor" href="#A" name="A">#</a><code>A</code>: replace with rules set A</li>
|
||
<li><a class="anchor" href="#B" name="B">#</a><code>B</code>: replace with rules set B</li>
|
||
<li><a class="anchor" href="#C" name="C">#</a><code>C</code>: replace with rules set C</li>
|
||
<li><a class="anchor" href="#D" name="D">#</a><code>D</code>: replace with rules set D</li>
|
||
<li><a class="anchor" href="#a_1" name="a_1">#</a><code>a</code>: replace with rules set A, chance 90%</li>
|
||
<li><a class="anchor" href="#b" name="b">#</a><code>b</code>: replace with rules set B, chance 80%</li>
|
||
<li><a class="anchor" href="#c" name="c">#</a><code>c</code>: replace with rules set C, chance 70%</li>
|
||
<li><a class="anchor" href="#d" name="d">#</a><code>d</code>: replace with rules set D, chance 60%</li>
|
||
<li><code>+</code>: yaw the turtle right by <code>angle</code> parameter</li>
|
||
<li><code>-</code>: yaw the turtle left by <code>angle</code> parameter</li>
|
||
<li><code>&</code>: pitch the turtle down by <code>angle</code> parameter</li>
|
||
<li><code>^</code>: pitch the turtle up by <code>angle</code> parameter</li>
|
||
<li><code>/</code>: roll the turtle to the right by <code>angle</code> parameter</li>
|
||
<li><code>*</code>: roll the turtle to the left by <code>angle</code> parameter</li>
|
||
<li><code>[</code>: save in stack current state info</li>
|
||
<li><code>]</code>: recover from stack state info</li>
|
||
</ul>
|
||
<h3 id="example_1">Example</h3>
|
||
<p>Spawn a small apple tree:</p>
|
||
<pre><code>pos = {x=230,y=20,z=4}
|
||
apple_tree={
|
||
axiom="FFFFFAFFBF",
|
||
rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
|
||
rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
|
||
trunk="default:tree",
|
||
leaves="default:leaves",
|
||
angle=30,
|
||
iterations=2,
|
||
random_level=0,
|
||
trunk_type="single",
|
||
thin_branches=true,
|
||
fruit_chance=10,
|
||
fruit="default:apple"
|
||
}
|
||
minetest.spawn_tree(pos,apple_tree)
|
||
</code></pre>
|
||
<h2 id="definition-tables">Definition tables</h2>
|
||
<h3 id="object-properties">Object Properties</h3>
|
||
<pre><code>{
|
||
hp_max = 1,
|
||
physical = true,
|
||
collide_with_objects = true, -- collide with other objects if physical = true
|
||
weight = 5,
|
||
collisionbox = {-0.5, 0.0, -0.5, 0.5, 1.0, 0.5},
|
||
visual = "cube" / "sprite" / "upright_sprite" / "mesh" / "wielditem",
|
||
visual_size = {x = 1, y = 1},
|
||
mesh = "model",
|
||
textures = {}, -- number of required textures depends on visual
|
||
colors = {}, -- number of required colors depends on visual
|
||
spritediv = {x = 1, y = 1},
|
||
initial_sprite_basepos = {x = 0, y = 0},
|
||
is_visible = true,
|
||
makes_footstep_sound = false,
|
||
automatic_rotate = false,
|
||
stepheight = 0,
|
||
automatic_face_movement_dir = 0.0,
|
||
-- ^ Automatically set yaw to movement direction, offset in degrees,
|
||
-- 'false' to disable.
|
||
automatic_face_movement_max_rotation_per_sec = -1,
|
||
-- ^ Limit automatic rotation to this value in degrees per second,
|
||
-- value < 0 no limit.
|
||
backface_culling = true, -- false to disable backface_culling for model
|
||
nametag = "", -- by default empty, for players their name is shown if empty
|
||
nametag_color = <color>, -- sets color of nametag as ColorSpec
|
||
infotext = "", -- by default empty, text to be shown when pointed at object
|
||
}
|
||
</code></pre>
|
||
<h3 id="entity-definition-register_entity">Entity definition (<code>register_entity</code>)</h3>
|
||
<pre><code>{
|
||
-- Deprecated: Everything in object properties is read directly from here
|
||
|
||
initial_properties = --[[<initial object properties>]],
|
||
|
||
on_activate = function(self, staticdata, dtime_s),
|
||
on_step = function(self, dtime),
|
||
on_punch = function(self, puncher, time_from_last_punch, tool_capabilities, dir),
|
||
on_rightclick = function(self, clicker),
|
||
get_staticdata = function(self),
|
||
-- ^ 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 (see item definition for
|
||
-- more info)
|
||
_custom_field = whatever,
|
||
}
|
||
</code></pre>
|
||
<h3 id="abm-activeblockmodifier-definition-register_abm">ABM (ActiveBlockModifier) definition (<code>register_abm</code>)</h3>
|
||
<pre><code>{
|
||
label = "Lava cooling",
|
||
-- ^ Descriptive label for profiling purposes (optional).
|
||
-- Definitions with identical labels will be listed as one.
|
||
-- In the following two fields, also group:groupname will work.
|
||
nodenames = {"default:lava_source"},
|
||
neighbors = {"default:water_source", "default:water_flowing"}, -- Any of these --[[
|
||
^ If left out or empty, any neighbor will do ]]
|
||
interval = 1.0, -- Operation interval in seconds
|
||
chance = 1, -- Chance of trigger per-node per-interval is 1.0 / this
|
||
catch_up = true, -- If true, catch-up behaviour is enabled --[[
|
||
^ The chance value is temporarily reduced when returning to
|
||
an area to simulate time lost by the area being unattended.
|
||
^ Note chance value can often be reduced to 1 ]]
|
||
action = func(pos, node, active_object_count, active_object_count_wider),
|
||
}
|
||
</code></pre>
|
||
<h3 id="lbm-loadingblockmodifier-definition-register_lbm">LBM (LoadingBlockModifier) definition (<code>register_lbm</code>)</h3>
|
||
<pre><code>{
|
||
label = "Upgrade legacy doors",
|
||
-- ^ Descriptive label for profiling purposes (optional).
|
||
-- Definitions with identical labels will be listed as one.
|
||
name = "modname:replace_legacy_door",
|
||
nodenames = {"default:lava_source"},
|
||
-- ^ List of node names to trigger the LBM on.
|
||
-- Also non-registered nodes will work.
|
||
-- Groups (as of group:groupname) will work as well.
|
||
run_at_every_load = false,
|
||
-- ^ Whether to run the LBM's action every time a block gets loaded,
|
||
-- and not just for blocks that were saved last time before LBMs were
|
||
-- introduced to the world.
|
||
action = func(pos, node),
|
||
}
|
||
</code></pre>
|
||
<h3 id="item-definition-register_node-register_craftitem-register_tool">Item definition (<code>register_node</code>, <code>register_craftitem</code>, <code>register_tool</code>)</h3>
|
||
<pre><code>{
|
||
description = "Steel Axe",
|
||
groups = {}, -- key = name, value = rating; rating = 1..3.
|
||
if rating not applicable, use 1.
|
||
e.g. {wool = 1, fluffy = 3}
|
||
{soil = 2, outerspace = 1, crumbly = 1}
|
||
{bendy = 2, snappy = 1},
|
||
{hard = 1, metal = 1, spikes = 1}
|
||
inventory_image = "default_tool_steelaxe.png",
|
||
wield_image = "",
|
||
palette = "",
|
||
--[[
|
||
^ An image file containing the palette of a node.
|
||
^ You can set the currently used color as the
|
||
^ "palette_index" field of the item stack metadata.
|
||
^ The palette is always stretched to fit indices
|
||
^ between 0 and 255, to ensure compatibility with
|
||
^ "colorfacedir" and "colorwallmounted" nodes.
|
||
]]
|
||
color = "0xFFFFFFFF",
|
||
--[[
|
||
^ The color of the item. The palette overrides this.
|
||
]]
|
||
wield_scale = {x = 1, y = 1, z = 1},
|
||
stack_max = 99,
|
||
range = 4.0,
|
||
liquids_pointable = false,
|
||
tool_capabilities = {
|
||
full_punch_interval = 1.0,
|
||
max_drop_level = 0,
|
||
groupcaps = {
|
||
-- For example:
|
||
choppy = {times = {[1] = 2.50, [2] = 1.40, [3] = 1.00}, uses = 20, maxlevel = 2},
|
||
},
|
||
damage_groups = {groupname = damage},
|
||
},
|
||
node_placement_prediction = nil,
|
||
--[[
|
||
^ If nil and item is node, prediction is made automatically
|
||
^ If nil and item is not a node, no prediction is made
|
||
^ If "" and item is anything, no prediction is made
|
||
^ Otherwise should be name of node which the client immediately places
|
||
on ground when the player places the item. Server will always update
|
||
actual result to client in a short moment.
|
||
]]
|
||
sound = {
|
||
breaks = "default_tool_break", -- tools only
|
||
place = --[[<SimpleSoundSpec>]],
|
||
},
|
||
|
||
on_place = func(itemstack, placer, pointed_thing),
|
||
--[[
|
||
^ Shall place item and return the leftover itemstack
|
||
^ The placer may be any ObjectRef or nil.
|
||
^ default: minetest.item_place ]]
|
||
on_secondary_use = func(itemstack, user, pointed_thing),
|
||
--[[
|
||
^ Same as on_place but called when pointing at nothing.
|
||
^ The user may be any ObjectRef or nil.
|
||
^ pointed_thing : always { type = "nothing" }
|
||
]]
|
||
on_drop = func(itemstack, dropper, pos),
|
||
--[[
|
||
^ Shall drop item and return the leftover itemstack
|
||
^ The dropper may be any ObjectRef or nil.
|
||
^ default: minetest.item_drop ]]
|
||
on_use = func(itemstack, user, pointed_thing),
|
||
--[[
|
||
^ default: nil
|
||
^ Function must return either nil if no item shall be removed from
|
||
inventory, or an itemstack to replace the original itemstack.
|
||
e.g. itemstack:take_item(); return itemstack
|
||
^ Otherwise, the function is free to do what it wants.
|
||
^ The user may be any ObjectRef or nil.
|
||
^ 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
|
||
^ 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.
|
||
]]
|
||
}
|
||
</code></pre>
|
||
<h3 id="tile-definition">Tile definition</h3>
|
||
<ul>
|
||
<li><a class="anchor" href="#imagepng" name="imagepng">#</a><code>"image.png"</code></li>
|
||
<li><a class="anchor" href="#nameimagepnganimationTileAnimationdefinition" name="nameimagepnganimationTileAnimationdefinition">#</a><code>{name="image.png", animation={Tile Animation definition}}</code></li>
|
||
<li><a class="anchor" href="#nameimagepngbackface_cullingbooltileable_verticalbooltileable_horizontalbool" name="nameimagepngbackface_cullingbooltileable_verticalbooltileable_horizontalbool">#</a><code>{name="image.png", backface_culling=bool, tileable_vertical=bool,
|
||
tileable_horizontal=bool}</code><ul>
|
||
<li>backface culling enabled by default for most nodes</li>
|
||
<li>tileable flags are info for shaders, how they should treat texture
|
||
when displacement mapping is used
|
||
Directions are from the point of view of the tile texture,
|
||
not the node it's on</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#nameimagepngcolorColorSpec" name="nameimagepngcolorColorSpec">#</a><code>{name="image.png", color=ColorSpec}</code><ul>
|
||
<li>the texture's color will be multiplied with this color.</li>
|
||
<li>the tile's color overrides the owning node's color in all cases.</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="anchor" href="#image_3" name="image_3">#</a>deprecated, yet still supported field names:<ul>
|
||
<li><a class="anchor" href="#image_4" name="image_4">#</a><code>image</code> (name)</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3 id="tile-animation-definition">Tile animation definition</h3>
|
||
<pre><code>{
|
||
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
|
||
}
|
||
</code></pre>
|
||
<h3 id="node-definition-register_node">Node definition (<code>register_node</code>)</h3>
|
||
<pre><code>{
|
||
-- <all fields allowed in item definitions>,
|
||
|
||
drawtype = "normal", -- See "Node drawtypes"
|
||
visual_scale = 1.0, --[[
|
||
^ Supported for drawtypes "plantlike", "signlike", "torchlike",
|
||
^ "firelike", "mesh".
|
||
^ For plantlike and firelike, 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 ]]
|
||
overlay_tiles = {tile definition 1, def2, def3, def4, def5, def6}, --[[
|
||
^ Same as `tiles`, but these textures are drawn on top of the
|
||
^ base tiles. You can use this to colorize only specific parts of
|
||
^ your texture. If the texture name is an empty string, that
|
||
^ overlay is not drawn. Since such tiles are drawn twice, it
|
||
^ is not recommended to use overlays on very common nodes.
|
||
special_tiles = {tile definition 1, Tile definition 2}, --[[
|
||
^ Special textures of node; used rarely (old field name: special_materials)
|
||
^ List can be shortened to needed length ]]
|
||
color = ColorSpec, --[[
|
||
^ The node's original color will be multiplied with this color.
|
||
^ If the node has a palette, then this setting only has an effect
|
||
^ in the inventory and on the wield item. ]]
|
||
use_texture_alpha = false, -- Use texture's alpha channel
|
||
palette = "palette.png", --[[
|
||
^ The node's `param2` is used to select a pixel from the image
|
||
^ (pixels are arranged from left to right and from top to bottom).
|
||
^ The node's color will be multiplied with the selected pixel's
|
||
^ color. Tiles can override this behavior.
|
||
^ Only when `paramtype2` supports palettes. ]]
|
||
post_effect_color = "green#0F", -- If player is inside node, see "ColorSpec"
|
||
paramtype = "none", -- See "Nodes" --[[
|
||
^ paramtype = "light" allows light to propagate from or through the node with light value
|
||
^ falling by 1 per node. This line is essential for a light source node to spread its light. ]]
|
||
paramtype2 = "none", -- See "Nodes"
|
||
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
|
||
sunlight_propagates = false, -- If true, sunlight will go infinitely through this
|
||
walkable = true, -- If true, objects collide with node
|
||
pointable = true, -- If true, can be pointed at
|
||
diggable = true, -- If false, can never be dug
|
||
climbable = false, -- If true, can be climbed on (ladder)
|
||
buildable_to = false, -- If true, placed nodes can replace this node
|
||
floodable = false, --[[
|
||
^ If true, liquids flow into and replace this node.
|
||
^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]]
|
||
liquidtype = "none", -- "none"/"source"/"flowing"
|
||
liquid_alternative_flowing = "", -- Flowing version of source liquid
|
||
liquid_alternative_source = "", -- Source version of flowing liquid
|
||
liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
|
||
liquid_renewable = true, --[[
|
||
^ If true, a new liquid source can be created by placing two or more sources nearby ]]
|
||
leveled = 0, --[[
|
||
^ Block contains level in param2. Value is default level, used for snow.
|
||
^ Don't forget to use "leveled" type nodebox. ]]
|
||
liquid_range = 8, -- number of flowing nodes around source (max. 8)
|
||
drowning = 0, -- Player will take this amount of damage if no bubbles are left
|
||
light_source = 0, --[[
|
||
^ Amount of light emitted by node.
|
||
^ To set the maximum (currently 14), use the value 'minetest.LIGHT_MAX'.
|
||
^ A value outside the range 0 to minetest.LIGHT_MAX causes undefined behavior.]]
|
||
damage_per_second = 0, -- If player is inside node, this damage is caused
|
||
node_box = {type="regular"}, -- See "Node boxes"
|
||
connects_to = nodenames, --[[
|
||
* Used for nodebox nodes with the type == "connected"
|
||
* Specifies to what neighboring nodes connections will be drawn
|
||
* e.g. `{"group:fence", "default:wood"}` or `"default:stone"` ]]
|
||
connect_sides = { "top", "bottom", "front", "left", "back", "right" }, --[[
|
||
^ Tells connected nodebox nodes to connect only to these sides of this node. ]]
|
||
mesh = "model",
|
||
selection_box = {type="regular"}, -- See "Node boxes" --[[
|
||
^ If drawtype "nodebox" is used and selection_box is nil, then node_box is used. ]]
|
||
legacy_facedir_simple = false, -- Support maps made in and before January 2012
|
||
legacy_wallmounted = false, -- Support maps made in and before January 2012
|
||
waving = 0, --[[ valid for mesh, nodebox, plantlike, allfaces_optional nodes
|
||
^ 1 - wave node like plants (top of node moves, bottom is fixed)
|
||
^ 2 - wave node like leaves (whole node moves side-to-side synchronously)
|
||
^ caveats: not all models will properly wave
|
||
^ plantlike drawtype nodes can only wave like plants
|
||
^ allfaces_optional drawtype nodes can only wave like leaves --]]
|
||
sounds = {
|
||
footstep = <SimpleSoundSpec>,
|
||
dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
|
||
dug = <SimpleSoundSpec>,
|
||
place = <SimpleSoundSpec>,
|
||
place_failed = <SimpleSoundSpec>,
|
||
},
|
||
drop = "", -- Name of dropped node when dug. Default is the node itself.
|
||
-- Alternatively:
|
||
drop = {
|
||
max_items = 1, -- Maximum number of items to drop.
|
||
items = { -- Choose max_items randomly from this list.
|
||
{
|
||
items = {"foo:bar", "baz:frob"}, -- Items to drop.
|
||
rarity = 1, -- Probability of dropping is 1 / rarity.
|
||
},
|
||
},
|
||
},
|
||
|
||
on_construct = func(pos), --[[
|
||
^ Node constructor; called after adding node
|
||
^ Can set up metadata and stuff like that
|
||
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
|
||
^ default: nil ]]
|
||
on_destruct = func(pos), --[[
|
||
^ Node destructor; called before removing node
|
||
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
|
||
^ default: nil ]]
|
||
after_destruct = func(pos, oldnode), --[[
|
||
^ Node destructor; called after removing node
|
||
^ Not called for bulk node placement (i.e. schematics and VoxelManip)
|
||
^ default: nil ]]
|
||
on_flood = func(pos, oldnode, newnode), --[[
|
||
^ Called when a liquid (newnode) is about to flood oldnode, if
|
||
^ it has `floodable = true` in the nodedef. Not called for bulk
|
||
^ node placement (i.e. schematics and VoxelManip) or air nodes. If
|
||
^ return true the node is not flooded, but on_flood callback will
|
||
^ most likely be called over and over again every liquid update
|
||
^ interval. Default: nil.
|
||
^ Warning: making a liquid node 'floodable' does not work and may cause problems. ]]
|
||
|
||
after_place_node = func(pos, placer, itemstack, pointed_thing) --[[
|
||
^ Called after constructing node when node was placed using
|
||
minetest.item_place_node / minetest.place_node
|
||
^ If return true no item is taken from itemstack
|
||
^ default: nil ]]
|
||
after_dig_node = func(pos, oldnode, oldmetadata, digger), --[[
|
||
^ oldmetadata is in table format
|
||
^ Called after destructing node when node was dug using
|
||
minetest.node_dig / minetest.dig_node
|
||
^ default: nil ]]
|
||
can_dig = function(pos, [player]) --[[
|
||
^ returns true if node can be dug, or false if not
|
||
^ default: nil ]]
|
||
|
||
on_punch = func(pos, node, puncher, pointed_thing), --[[
|
||
^ default: minetest.node_punch
|
||
^ By default: Calls minetest.register_on_punchnode callbacks ]]
|
||
on_rightclick = func(pos, node, clicker, itemstack, pointed_thing), --[[
|
||
^ default: nil
|
||
^ if defined, itemstack will hold clicker's wielded item
|
||
^ Shall return the leftover itemstack
|
||
^ Note: pointed_thing can be nil, if a mod calls this function ]]
|
||
|
||
on_dig = func(pos, node, digger), --[[
|
||
^ default: minetest.node_dig
|
||
^ By default: checks privileges, wears out tool and removes node ]]
|
||
|
||
on_timer = function(pos,elapsed), --[[
|
||
^ default: nil
|
||
^ called by NodeTimers, see minetest.get_node_timer and NodeTimerRef
|
||
^ elapsed is the total time passed since the timer was started
|
||
^ return true to run the timer for another cycle with the same timeout value ]]
|
||
|
||
on_receive_fields = func(pos, formname, fields, sender), --[[
|
||
^ fields = {name1 = value1, name2 = value2, ...}
|
||
^ Called when an UI form (e.g. sign text input) returns data
|
||
^ default: nil ]]
|
||
|
||
allow_metadata_inventory_move = func(pos, from_list, from_index,
|
||
to_list, to_index, count, player), --[[
|
||
^ Called when a player wants to move items inside the inventory
|
||
^ Return value: number of items allowed to move ]]
|
||
|
||
allow_metadata_inventory_put = func(pos, listname, index, stack, player), --[[
|
||
^ Called when a player wants to put something into the inventory
|
||
^ Return value: number of items allowed to put
|
||
^ Return value: -1: Allow and don't modify item count in inventory ]]
|
||
|
||
allow_metadata_inventory_take = func(pos, listname, index, stack, player), --[[
|
||
^ Called when a player wants to take something out of the inventory
|
||
^ Return value: number of items allowed to take
|
||
^ Return value: -1: Allow and don't modify item count in inventory ]]
|
||
|
||
on_metadata_inventory_move = func(pos, from_list, from_index,
|
||
to_list, to_index, count, player),
|
||
on_metadata_inventory_put = func(pos, listname, index, stack, player),
|
||
on_metadata_inventory_take = func(pos, listname, index, stack, player), --[[
|
||
^ Called after the actual action has happened, according to what was allowed.
|
||
^ No return value ]]
|
||
|
||
on_blast = func(pos, intensity), --[[
|
||
^ intensity: 1.0 = mid range of regular TNT
|
||
^ If defined, called when an explosion touches the node, instead of
|
||
removing the node ]]
|
||
}
|
||
</code></pre>
|
||
<h3 id="recipe-for-register_craft-shaped">Recipe for <code>register_craft</code> (shaped)</h3>
|
||
<pre><code>{
|
||
output = 'default:pick_stone',
|
||
recipe = {
|
||
{'default:cobble', 'default:cobble', 'default:cobble'},
|
||
{'', 'default:stick', ''},
|
||
{'', 'default:stick', ''}, -- Also groups; e.g. 'group:crumbly'
|
||
},
|
||
replacements = --[[<optional list of item pairs,
|
||
replace one input item with another item on crafting>]]
|
||
}
|
||
</code></pre>
|
||
<h3 id="recipe-for-register_craft-shapeless">Recipe for <code>register_craft</code> (shapeless)</h3>
|
||
<pre><code>{
|
||
type = "shapeless",
|
||
output = 'mushrooms:mushroom_stew',
|
||
recipe = {
|
||
"mushrooms:bowl",
|
||
"mushrooms:mushroom_brown",
|
||
"mushrooms:mushroom_red",
|
||
},
|
||
replacements = --[[<optional list of item pairs,
|
||
replace one input item with another item on crafting>]]
|
||
</code></pre>
|
||
<p>}</p>
|
||
<h3 id="recipe-for-register_craft-tool-repair">Recipe for <code>register_craft</code> (tool repair)</h3>
|
||
<pre><code>{
|
||
type = "toolrepair",
|
||
additional_wear = -0.02,
|
||
}
|
||
</code></pre>
|
||
<h3 id="recipe-for-register_craft-cooking">Recipe for <code>register_craft</code> (cooking)</h3>
|
||
<pre><code>{
|
||
type = "cooking",
|
||
output = "default:glass",
|
||
recipe = "default:sand",
|
||
cooktime = 3,
|
||
}
|
||
</code></pre>
|
||
<h3 id="recipe-for-register_craft-furnace-fuel">Recipe for <code>register_craft</code> (furnace fuel)</h3>
|
||
<pre><code>{
|
||
type = "fuel",
|
||
recipe = "default:leaves",
|
||
burntime = 1,
|
||
}
|
||
</code></pre>
|
||
<h3 id="ore-definition-register_ore">Ore definition (<code>register_ore</code>)</h3>
|
||
<pre><code>{
|
||
ore_type = "scatter", -- See "Ore types"
|
||
ore = "default:stone_with_coal",
|
||
wherein = "default:stone",
|
||
-- ^ a list of nodenames is supported too
|
||
clust_scarcity = 8*8*8,
|
||
-- ^ Ore has a 1 out of clust_scarcity chance of spawning in a node
|
||
-- ^ This value should be *MUCH* higher than your intuition might tell you!
|
||
clust_num_ores = 8,
|
||
-- ^ Number of ores in a cluster
|
||
clust_size = 3,
|
||
-- ^ Size of the bounding box of the cluster
|
||
-- ^ In this example, there is a 3x3x3 cluster where 8 out of the 27 nodes are coal ore
|
||
y_min = -31000,
|
||
y_max = 64,
|
||
-- ^ Lower and upper limits for ore.
|
||
-- ^ Limits are relative to y = water_level - 1 for core mapgen, or
|
||
-- ^ relative to y = 0 for minetest.generate_ores().
|
||
flags = "",
|
||
-- ^ Attributes for this ore generation
|
||
noise_threshold = 0.5,
|
||
-- ^ If noise is above this threshold, ore is placed. Not needed for a uniform distribution
|
||
noise_params = {offset=0, scale=1, spread={x=100, y=100, z=100}, seed=23, octaves=3, persist=0.70}
|
||
-- ^ NoiseParams structure describing the perlin noise used for ore distribution.
|
||
-- ^ Needed for sheet ore_type. Omit from scatter ore_type for a uniform ore distribution
|
||
random_factor = 1.0,
|
||
-- ^ Multiplier of the randomness contribution to the noise value at any
|
||
-- ^ given point to decide if ore should be placed. Set to 0 for solid veins.
|
||
-- ^ This parameter is only valid for ore_type == "vein".
|
||
biomes = {"desert", "rainforest"}
|
||
-- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted,
|
||
-- ^ and ignored if the Mapgen being used does not support biomes.
|
||
-- ^ Can be a list of (or a single) biome names, IDs, or definitions.
|
||
}
|
||
</code></pre>
|
||
<h3 id="biome-definition-register_biome">Biome definition (<code>register_biome</code>)</h3>
|
||
<p><strong>Note</strong>
|
||
The Biome API is still in an experimental phase and subject to change.</p>
|
||
<pre><code>{
|
||
name = "tundra",
|
||
node_dust = "default:snow",
|
||
-- ^ Node dropped onto upper surface after all else is generated.
|
||
node_top = "default:dirt_with_snow",
|
||
depth_top = 1,
|
||
-- ^ Node forming surface layer of biome and thickness of this layer.
|
||
node_filler = "default:permafrost",
|
||
depth_filler = 3,
|
||
-- ^ Node forming lower layer of biome and thickness of this layer.
|
||
node_stone = "default:bluestone",
|
||
-- ^ Node that replaces all stone nodes between roughly y_min and y_max.
|
||
node_water_top = "default:ice",
|
||
depth_water_top = 10,
|
||
-- ^ Node forming a surface layer in seawater with the defined thickness.
|
||
node_water = "",
|
||
-- ^ Node that replaces all seawater nodes not in the defined surface layer.
|
||
node_river_water = "default:ice",
|
||
-- ^ Node that replaces river water in mapgens that use default:river_water.
|
||
node_riverbed = "default:gravel",
|
||
depth_riverbed = 2,
|
||
-- ^ Node placed under river water and thickness of this layer.
|
||
y_min = 1,
|
||
y_max = 31000,
|
||
-- ^ Lower and upper limits for biome.
|
||
-- ^ Limits are relative to y = water_level - 1.
|
||
-- ^ Because biome is not recalculated for every node in a node column
|
||
-- ^ some biome materials can exceed their limits, especially stone.
|
||
-- ^ For each node column in a mapchunk, biome is only recalculated at column
|
||
-- ^ top and at each of these surfaces:
|
||
-- ^ Ground below air, water below air, ground below water.
|
||
-- ^ The selected biome then stays in effect for all nodes below until
|
||
-- ^ column base or the next biome recalculation.
|
||
heat_point = 0,
|
||
humidity_point = 50,
|
||
-- ^ Characteristic average temperature and humidity for the biome.
|
||
-- ^ These values create 'biome points' on a voronoi diagram that has heat
|
||
-- ^ and humidity as axes. The resulting voronoi cells determine which
|
||
-- ^ heat/humidity points belong to which biome, and therefore determine
|
||
-- ^ the area and location of each biome in the world.
|
||
-- ^ The biome points need to be carefully and evenly spaced on the voronoi
|
||
-- ^ diagram to result in roughly equal size biomes.
|
||
-- ^ Heat and humidity have average values of 50, vary mostly between
|
||
-- ^ 0 and 100 but also often exceed these values.
|
||
-- ^ Heat is not in degrees celcius, both values are abstract.
|
||
}
|
||
</code></pre>
|
||
<h3 id="decoration-definition-register_decoration">Decoration definition (<code>register_decoration</code>)</h3>
|
||
<pre><code>{
|
||
deco_type = "simple", -- See "Decoration types"
|
||
place_on = "default:dirt_with_grass",
|
||
-- ^ Node (or list of nodes) that the decoration can be placed on
|
||
sidelen = 8,
|
||
-- ^ Size of divisions made in the chunk being generated.
|
||
-- ^ If the chunk size is not evenly divisible by sidelen, sidelen is made equal to the chunk size.
|
||
fill_ratio = 0.02,
|
||
-- ^ Ratio of the area to be uniformly filled by the decoration.
|
||
-- ^ Used only if noise_params is not specified.
|
||
noise_params = {offset=0, scale=.45, spread={x=100, y=100, z=100}, seed=354, octaves=3, persist=0.7},
|
||
-- ^ NoiseParams structure describing the perlin noise used for decoration distribution.
|
||
-- ^ The result of this is multiplied by the 2d area of the division being decorated.
|
||
biomes = {"Oceanside", "Hills", "Plains"},
|
||
-- ^ List of biomes in which this decoration occurs. Occurs in all biomes if this is omitted,
|
||
-- ^ and ignored if the Mapgen being used does not support biomes.
|
||
-- ^ Can be a list of (or a single) biome names, IDs, or definitions.
|
||
y_min = -31000
|
||
y_max = 31000
|
||
-- ^ Lower and upper limits for decoration.
|
||
-- ^ Limits are relative to y = water_level - 1 for core mapgen, or
|
||
-- ^ relative to y = 0 for minetest.generate_decorations().
|
||
-- ^ This parameter refers to the `y` position of the decoration base, so
|
||
-- the actual maximum height would be `height_max + size.Y`.
|
||
spawn_by = "default:water",
|
||
-- ^ Node (or list of nodes) that the decoration only spawns next to.
|
||
-- ^ Checks two horizontal planes of neighbouring nodes (including diagonal neighbours),
|
||
-- ^ one plane at Y = surface and one plane at Y = surface = + 1.
|
||
num_spawn_by = 1,
|
||
-- ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
|
||
-- ^ If absent or -1, decorations occur next to any nodes.
|
||
flags = "liquid_surface, force_placement",
|
||
-- ^ Flags for all decoration types.
|
||
-- ^ "liquid_surface": Instead of placement on the highest solid surface
|
||
-- ^ in a mapchunk column, placement is on the highest liquid surface.
|
||
-- ^ Placement is disabled if solid nodes are found above the liquid surface.
|
||
-- ^ "force_placement": Nodes other than "air" and "ignore" are replaced by the decoration.
|
||
|
||
----- Simple-type parameters
|
||
decoration = "default:grass",
|
||
-- ^ The node name used as the decoration.
|
||
-- ^ If instead a list of strings, a randomly selected node from the list is placed as the decoration.
|
||
height = 1,
|
||
-- ^ 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.
|
||
-- ^ If absent, the parameter 'height' is used as a constant.
|
||
param2 = 0,
|
||
-- ^ Param2 value of placed decoration node.
|
||
|
||
----- Schematic-type parameters
|
||
schematic = "foobar.mts",
|
||
-- ^ If schematic is a string, it is the filepath relative to the current working directory of the
|
||
-- ^ specified Minetest schematic file.
|
||
-- ^ - OR -, could be the ID of a previously registered schematic
|
||
-- ^ - OR -, could instead be a table containing two mandatory fields, size and data,
|
||
-- ^ and an optional table yslice_prob:
|
||
schematic = {
|
||
size = {x=4, y=6, z=4},
|
||
data = {
|
||
{name="default:cobble", param1=255, param2=0},
|
||
{name="default:dirt_with_grass", param1=255, param2=0},
|
||
{name="ignore", param1=255, param2=0},
|
||
{name="air", param1=255, param2=0},
|
||
...
|
||
},
|
||
yslice_prob = {
|
||
{ypos=2, prob=128},
|
||
{ypos=5, prob=64},
|
||
...
|
||
},
|
||
},
|
||
-- ^ See 'Schematic specifier' for details.
|
||
replacements = {["oldname"] = "convert_to", ...},
|
||
flags = "place_center_x, place_center_y, place_center_z",
|
||
-- ^ Flags for schematic decorations. See 'Schematic attributes'.
|
||
rotation = "90" -- rotate schematic 90 degrees on placement
|
||
-- ^ Rotation can be "0", "90", "180", "270", or "random".
|
||
}
|
||
</code></pre>
|
||
<h3 id="chat-command-definition-register_chatcommand">Chat command definition (<code>register_chatcommand</code>)</h3>
|
||
<pre><code>{
|
||
params = "<name> <privilege>", -- Short parameter description
|
||
description = "Remove privilege from player", -- Full description
|
||
privs = {privs=true}, -- Require the "privs" privilege to run
|
||
func = function(name, param), -- Called when command is run.
|
||
-- Returns boolean success and text output.
|
||
}
|
||
</code></pre>
|
||
<h3 id="detached-inventory-callbacks">Detached inventory callbacks</h3>
|
||
<pre><code>{
|
||
allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
|
||
-- ^ Called when a player wants to move items inside the inventory
|
||
-- ^ Return value: number of items allowed to move
|
||
|
||
allow_put = func(inv, listname, index, stack, player),
|
||
-- ^ Called when a player wants to put something into the inventory
|
||
-- ^ Return value: number of items allowed to put
|
||
-- ^ Return value: -1: Allow and don't modify item count in inventory
|
||
|
||
allow_take = func(inv, listname, index, stack, player),
|
||
-- ^ Called when a player wants to take something out of the inventory
|
||
-- ^ Return value: number of items allowed to take
|
||
-- ^ Return value: -1: Allow and don't modify item count in inventory
|
||
|
||
on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
|
||
on_put = func(inv, listname, index, stack, player),
|
||
on_take = func(inv, listname, index, stack, player),
|
||
-- ^ Called after the actual action has happened, according to what was allowed.
|
||
-- ^ No return value
|
||
}
|
||
</code></pre>
|
||
<h3 id="hud-definition-hud_add-hud_get">HUD Definition (<code>hud_add</code>, <code>hud_get</code>)</h3>
|
||
<pre><code>{
|
||
hud_elem_type = "image", -- see HUD element types
|
||
-- ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
|
||
position = {x=0.5, y=0.5},
|
||
-- ^ Left corner position of element
|
||
name = "<name>",
|
||
scale = {x=2, y=2},
|
||
text = "<text>",
|
||
number = 2,
|
||
item = 3,
|
||
-- ^ Selected item in inventory. 0 for no item selected.
|
||
direction = 0,
|
||
-- ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
|
||
alignment = {x=0, y=0},
|
||
-- ^ See "HUD Element Types"
|
||
offset = {x=0, y=0},
|
||
-- ^ See "HUD Element Types"
|
||
size = { x=100, y=100 },
|
||
-- ^ Size of element in pixels
|
||
}
|
||
</code></pre>
|
||
<h3 id="particle-definition-add_particle">Particle definition (<code>add_particle</code>)</h3>
|
||
<pre><code>{
|
||
pos = {x=0, y=0, z=0},
|
||
velocity = {x=0, y=0, z=0},
|
||
acceleration = {x=0, y=0, z=0},
|
||
-- ^ Spawn particle at pos with velocity and acceleration
|
||
expirationtime = 1,
|
||
-- ^ Disappears after expirationtime seconds
|
||
size = 1,
|
||
collisiondetection = false,
|
||
-- ^ collisiondetection: if true collides with physical objects
|
||
collision_removal = false,
|
||
-- ^ collision_removal: if true then particle is removed when it collides,
|
||
-- ^ requires collisiondetection = true to have any effect
|
||
vertical = false,
|
||
-- ^ vertical: if true faces player using y axis only
|
||
texture = "image.png",
|
||
-- ^ Uses texture (string)
|
||
playername = "singleplayer",
|
||
-- ^ optional, if specified spawns particle only on the player's client
|
||
animation = {Tile Animation definition},
|
||
-- ^ optional, specifies how to animate the particle texture
|
||
glow = 0
|
||
-- ^ optional, specify particle self-luminescence in darkness
|
||
}
|
||
</code></pre>
|
||
<h3 id="particlespawner-definition-add_particlespawner"><code>ParticleSpawner</code> definition (<code>add_particlespawner</code>)</h3>
|
||
<pre><code>{
|
||
amount = 1,
|
||
time = 1,
|
||
-- ^ If time is 0 has infinite lifespan and spawns the amount on a per-second base
|
||
minpos = {x=0, y=0, z=0},
|
||
maxpos = {x=0, y=0, z=0},
|
||
minvel = {x=0, y=0, z=0},
|
||
maxvel = {x=0, y=0, z=0},
|
||
minacc = {x=0, y=0, z=0},
|
||
maxacc = {x=0, y=0, z=0},
|
||
minexptime = 1,
|
||
maxexptime = 1,
|
||
minsize = 1,
|
||
maxsize = 1,
|
||
-- ^ The particle's properties are random values in between the bounds:
|
||
-- ^ minpos/maxpos, minvel/maxvel (velocity), minacc/maxacc (acceleration),
|
||
-- ^ minsize/maxsize, minexptime/maxexptime (expirationtime)
|
||
collisiondetection = false,
|
||
-- ^ collisiondetection: if true uses collision detection
|
||
collision_removal = false,
|
||
-- ^ collision_removal: if true then particle is removed when it collides,
|
||
-- ^ requires collisiondetection = true to have any effect
|
||
attached = ObjectRef,
|
||
-- ^ 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
|
||
}
|
||
</code></pre>
|
||
<h3 id="httprequest-definition-httpapitablefetch_async-httpapitablefetch_async"><code>HTTPRequest</code> definition (<code>HTTPApiTable.fetch_async</code>, <code>HTTPApiTable.fetch_async</code>)</h3>
|
||
<pre><code>{
|
||
url = "http://example.org",
|
||
timeout = 10,
|
||
-- ^ Timeout for connection in seconds. Default is 3 seconds.
|
||
post_data = "Raw POST request data string" OR { field1 = "data1", field2 = "data2" },
|
||
-- ^ Optional, if specified a POST request with post_data is performed.
|
||
-- ^ Accepts both a string and a table. If a table is specified, encodes table
|
||
-- ^ as x-www-form-urlencoded key-value pairs.
|
||
-- ^ If post_data ist not specified, a GET request is performed instead.
|
||
user_agent = "ExampleUserAgent",
|
||
-- ^ Optional, if specified replaces the default minetest user agent with given string
|
||
extra_headers = { "Accept-Language: en-us", "Accept-Charset: utf-8" },
|
||
-- ^ Optional, if specified adds additional headers to the HTTP request. You must make sure
|
||
-- ^ that the header strings follow HTTP specification ("Key: Value").
|
||
multipart = boolean
|
||
-- ^ Optional, if true performs a multipart HTTP request. Default is false.
|
||
}
|
||
</code></pre>
|
||
<h3 id="httprequestresult-definition-httpapitablefetch-callback-httpapitablefetch_async_get"><code>HTTPRequestResult</code> definition (<code>HTTPApiTable.fetch</code> callback, <code>HTTPApiTable.fetch_async_get</code>)</h3>
|
||
<pre><code>{
|
||
completed = true,
|
||
-- ^ If true, the request has finished (either succeeded, failed or timed out)
|
||
succeeded = true,
|
||
-- ^ If true, the request was succesful
|
||
timeout = false,
|
||
-- ^ If true, the request timed out
|
||
code = 200,
|
||
-- ^ HTTP status code
|
||
data = "response"
|
||
}
|
||
</code></pre> |