API documentation for mcl_fences

mods/ITEMS/mcl_fences/API.md

@@ -0,0 +1,62 @@
+# API for adding MineClone 2 fences
+This API allows you to add fences and fence gates.
+The recommended function is `mcl_fences.register_fence_and_fence_gate`.
+
+## ` mcl_fences.register_fence = function(id, fence_name, texture, fence_image, groups, connects_to, sounds)`
+Adds a fence without crafting recipe. A single node is created.
+
+### Parameter
+* `id`: A part of the itemstring of the node to create. The node name will be “`<modname>:<id>`”
+* `fence_name`: User-visible name (`description`)
+* `texture`: Texture to apply on the fence (all sides)
+* `fence_image`: Inventory image
+* `groups`: Table of groups to which the fence belongs to
+* `connects_to`: Table of nodes (itemstrings) to which the fence will connect to. Use `group:<groupname>` for all members of the group `<groupname>`
+* `sounds`: Node sound table for the fence
+
+### Return value
+The full itemstring of the new fence node.
+
+Notes: Fences will always have the group `fence=1`. They will always connect to solid nodes (group `solid=1`).
+
+## `mcl_fences.register_fence_gate = function(id, fence_gate_name, texture, gate_image, groups, connects_to, sounds)`
+Adds a fence gate without crafting recipe. This will create 2 nodes.
+
+### Parameters
+* `id`: A part of the itemstring of the nodes to create. The node names will be “`<modname>:<id>_gate`” and “`<modname>:<id>_gate_open`”
+* `fence_gate_name`: User-visible name (`description`)
+* `texture`: Texture to apply on the fence gate (all sides)
+* `gate_image`: Inventory image
+* `groups`: Table of groups to which the fence gate belongs to
+* `connects_to`: Table of nodes (itemstrings) to which the fence will connect to. Use `group:<groupname>` for all members of the group `<groupname>`
+* `sounds`: Node sound table for the fence gate
+
+Notes: Fence gates will always have the group `fence_gate=1`. The open fence gate will always have the group `not_in_creative_inventory=1`.
+
+### Return value
+This function returns 2 values, in the following order:
+
+1. Itemstring of the closed fence gate
+2. Itemstring of the open fence gate
+
+## `mcl_fences.register_fence_and_fence_gate = function(id, fence_name, fence_gate_name, texture, fence_image, gate_image, groups, connects_to, sounds)`
+Registers a fence and fence gate. This is basically a combination of the two functions above. This is the recommended way to add a fence / fence gate pair.
+This will register 3 nodes in total without crafting recipes.
+
+* `id`: A part of the itemstring of the nodes to create.
+* `fence_name`: User-visible name (`description`) of the fence
+* `fence_gate_name`: User-visible name (`description`) of the fence gate
+* `texture`: Texture to apply on the fence and fence gate (all sides)
+* `fence_image`: Inventory image of the fence
+* `gate_image`: Inventory image of the fence gate
+* `groups`: Table of groups to which the fence and fence gate belong to
+* `connects_to`: Table of nodes (itemstrings) to which the fence and fence gate will connect to. Use `group:<groupname>` for all members of the group `<groupname>`
+* `sounds`: Node sound table for the fence and the fence gate
+
+### Return value
+This function returns 3 values, in this order:
+
+1. Itemstring of the fence
+2. Itemstring of the closed fence gate
+3. Itemstring of the open fence gate
+

mods/ITEMS/mcl_fences/init.lua

@@ -60,6 +60,8 @@ mcl_fences.register_fence = function(id, fence_name, texture, fence_image, group
 		},
 		sounds = sounds,
 	})
+
+	return fence_id
 end
 
 mcl_fences.register_fence_gate = function(id, fence_gate_name, texture, gate_image, groups, connects_to, sounds)
@@ -71,6 +73,7 @@ mcl_fences.register_fence_gate = function(id, fence_gate_name, texture, gate_ima
 	end
 
 	local gate_id = minetest.get_current_modname()..":"..id.."_gate"
+	local open_gate_id = gate_id .. "_open"
 	local function punch_gate(pos, node)
 		meta2 = minetest.get_meta(pos)
 		state2 = meta2:get_int("state")
@@ -82,7 +85,7 @@ mcl_fences.register_fence_gate = function(id, fence_gate_name, texture, gate_ima
 		else
 			state2 = 1
 			minetest.sound_play("doors_fencegate_open", {gain = 0.3, max_hear_distance = 10})
-			tmp_node2 = {name=gate_id.."_open", param1=node.param1, param2=node.param2}
+			tmp_node2 = {name=open_gate_id, param1=node.param1, param2=node.param2}
 		end
 		update_gate(pos, tmp_node2)
 		meta2:set_int("state", state2)
@@ -98,7 +101,7 @@ mcl_fences.register_fence_gate = function(id, fence_gate_name, texture, gate_ima
 
 	groups.mesecon_effector_on = 1
 	groups.fence_gate = 1
-	minetest.register_node(gate_id.."_open", {
+	minetest.register_node(open_gate_id, {
 		tiles = {texture},
 		paramtype = "light",
 		paramtype2 = "facedir",
@@ -196,11 +199,13 @@ mcl_fences.register_fence_gate = function(id, fence_gate_name, texture, gate_ima
 		sounds = sounds,
 	})
 
+	return gate_id, open_gate_id
 end
 
 mcl_fences.register_fence_and_fence_gate = function(id, fence_name, fence_gate_name, texture, fence_image, gate_image, groups, connects_to, sounds)
-	mcl_fences.register_fence(id, fence_name, texture, fence_image, groups, connects_to, sounds)
+	local fence_id = mcl_fences.register_fence(id, fence_name, texture, fence_image, groups, connects_to, sounds)
-	mcl_fences.register_fence_gate(id, fence_gate_name, texture, gate_image, groups, connects_to, sounds)
+	local gate_id, open_gate_id = mcl_fences.register_fence_gate(id, fence_gate_name, texture, gate_image, groups, connects_to, sounds)
+	return fence_id, gate_id, open_gate_id
 end
 
 local wood_groups = {snappy=1,choppy=2,oddly_breakable_by_hand=2,flammable=2,fence_wood=1}