provide Portal API

.luacheckrc

@@ -1,6 +1,10 @@
 unused_args = false
 allow_defined_top = true
 
+globals = {
+	"nether"
+}
+
 read_globals = {
 	"core",
 	"default",

mapgen.lua

@@ -0,0 +1,225 @@
+--[[
+
+  Nether mod for minetest
+
+  Copyright (C) 2013 PilzAdam
+
+  Permission to use, copy, modify, and/or distribute this software for
+  any purpose with or without fee is hereby granted, provided that the
+  above copyright notice and this permission notice appear in all copies.
+
+  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
+  WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
+  WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR
+  BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES
+  OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+  WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+  ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+  SOFTWARE.
+
+]]--
+
+
+-- Parameters
+
+local NETHER_DEPTH = nether.DEPTH
+local TCAVE = 0.6
+local BLEND = 128
+
+
+-- 3D noise
+
+local np_cave = {
+	offset = 0,
+	scale = 1,
+	spread = {x = 384, y = 128, z = 384}, -- squashed 3:1
+	seed = 59033,
+	octaves = 5,
+	persist = 0.7,
+	lacunarity = 2.0,
+	--flags = ""
+}
+
+
+-- Stuff
+
+local yblmax = NETHER_DEPTH - BLEND * 2
+
+
+
+
+-- Mapgen
+
+-- Initialize noise object, localise noise and data buffers
+
+local nobj_cave = nil
+local nbuf_cave = nil
+local dbuf = nil
+
+
+-- Content ids
+
+local c_air = minetest.get_content_id("air")
+
+--local c_stone_with_coal = minetest.get_content_id("default:stone_with_coal")
+--local c_stone_with_iron = minetest.get_content_id("default:stone_with_iron")
+local c_stone_with_mese = minetest.get_content_id("default:stone_with_mese")
+local c_stone_with_diamond = minetest.get_content_id("default:stone_with_diamond")
+local c_stone_with_gold = minetest.get_content_id("default:stone_with_gold")
+--local c_stone_with_copper = minetest.get_content_id("default:stone_with_copper")
+local c_mese = minetest.get_content_id("default:mese")
+
+local c_gravel = minetest.get_content_id("default:gravel")
+local c_dirt = minetest.get_content_id("default:dirt")
+local c_sand = minetest.get_content_id("default:sand")
+
+local c_cobble = minetest.get_content_id("default:cobble")
+local c_mossycobble = minetest.get_content_id("default:mossycobble")
+local c_stair_cobble = minetest.get_content_id("stairs:stair_cobble")
+
+local c_lava_source = minetest.get_content_id("default:lava_source")
+local c_lava_flowing = minetest.get_content_id("default:lava_flowing")
+local c_water_source = minetest.get_content_id("default:water_source")
+local c_water_flowing = minetest.get_content_id("default:water_flowing")
+
+local c_glowstone = minetest.get_content_id("nether:glowstone")
+local c_nethersand = minetest.get_content_id("nether:sand")
+local c_netherbrick = minetest.get_content_id("nether:brick")
+local c_netherrack = minetest.get_content_id("nether:rack")
+
+
+-- On-generated function
+
+minetest.register_on_generated(function(minp, maxp, seed)
+	if minp.y > NETHER_DEPTH then
+		return
+	end
+
+	local x1 = maxp.x
+	local y1 = maxp.y
+	local z1 = maxp.z
+	local x0 = minp.x
+	local y0 = minp.y
+	local z0 = minp.z
+
+	local vm, emin, emax = minetest.get_mapgen_object("voxelmanip")
+	local area = VoxelArea:new{MinEdge = emin, MaxEdge = emax}
+	local data = vm:get_data(dbuf)
+
+	local x11 = emax.x -- Limits of mapchunk plus mapblock shell
+	local y11 = emax.y
+	local z11 = emax.z
+	local x00 = emin.x
+	local y00 = emin.y
+	local z00 = emin.z
+
+	local ystride = x1 - x0 + 1
+	local zstride = ystride * ystride
+	local chulens = {x = ystride, y = ystride, z = ystride}
+	local minposxyz = {x = x0, y = y0, z = z0}
+
+	nobj_cave = nobj_cave or minetest.get_perlin_map(np_cave, chulens)
+	local nvals_cave = nobj_cave:get3dMap_flat(minposxyz, nbuf_cave)
+
+	for y = y00, y11 do -- Y loop first to minimise tcave calculations
+		local tcave
+		local in_chunk_y = false
+		if y >= y0 and y <= y1 then
+			if y > yblmax then
+				tcave = TCAVE + ((y - yblmax) / BLEND) ^ 2
+			else
+				tcave = TCAVE
+			end
+			in_chunk_y = true
+		end
+
+		for z = z00, z11 do
+			local vi = area:index(x00, y, z) -- Initial voxelmanip index
+			local ni
+			local in_chunk_yz = in_chunk_y and z >= z0 and z <= z1
+
+			for x = x00, x11 do
+				if in_chunk_yz and x == x0 then
+					-- Initial noisemap index
+					ni = (z - z0) * zstride + (y - y0) * ystride + 1
+				end
+				local in_chunk_yzx = in_chunk_yz and x >= x0 and x <= x1 -- In mapchunk
+
+				local id = data[vi] -- Existing node
+				-- Cave air, cave liquids and dungeons are overgenerated,
+				-- convert these throughout mapchunk plus shell
+				if id == c_air or -- Air and liquids to air
+						id == c_lava_source or
+						id == c_lava_flowing or
+						id == c_water_source or
+						id == c_water_flowing then
+					data[vi] = c_air
+				-- Dungeons are preserved so we don't need
+				-- to check for cavern in the shell
+				elseif id == c_cobble or -- Dungeons (preserved) to netherbrick
+						id == c_mossycobble or
+						id == c_stair_cobble then
+					data[vi] = c_netherbrick
+				end
+
+				if in_chunk_yzx then -- In mapchunk
+					if nvals_cave[ni] > tcave then -- Only excavate cavern in mapchunk
+						data[vi] = c_air
+					elseif id == c_mese then -- Mese block to lava
+						data[vi] = c_lava_source
+					elseif id == c_stone_with_gold or -- Precious ores to glowstone
+							id == c_stone_with_mese or
+							id == c_stone_with_diamond then
+						data[vi] = c_glowstone
+					elseif id == c_gravel or -- Blob ore to nethersand
+							id == c_dirt or
+							id == c_sand then
+						data[vi] = c_nethersand
+					else -- All else to netherstone
+						data[vi] = c_netherrack
+					end
+
+					ni = ni + 1 -- Only increment noise index in mapchunk
+				end
+
+				vi = vi + 1
+			end
+		end
+	end
+
+	vm:set_data(data)
+	vm:set_lighting({day = 0, night = 0})
+	vm:calc_lighting()
+	vm:update_liquids()
+	vm:write_to_map()
+end)
+
+
+-- use knowledge of the nether mapgen algorithm to return a suitable ground level for placing a portal.
+function nether.find_nether_ground_y(target_x, target_z, start_y)
+	local nobj_cave_point = minetest.get_perlin(np_cave)
+	local air = 0 -- Consecutive air nodes found
+
+	for y = start_y, start_y - 4096, -1 do
+		local nval_cave = nobj_cave_point:get3d({x = target_x, y = y, z = target_z})
+
+		if nval_cave > TCAVE then -- Cavern
+			air = air + 1
+		else -- Not cavern, check if 4 nodes of space above
+			if air >= 4 then
+				-- Check volume for non-natural nodes
+				local minp = {x = target_x - 1, y = y    , z = target_z - 2}
+				local maxp = {x = target_x + 2, y = y + 4, z = target_z + 2}
+				if nether.volume_is_natural(minp, maxp) then
+					return y + 1
+				else -- Restart search a little lower
+					nether.find_nether_ground_y(target_x, target_z, y - 16)
+				end
+			else -- Not enough space, reset air to zero
+				air = 0
+			end
+		end
+	end
+
+	return start_y -- Fallback
+end

nodes.lua

@@ -0,0 +1,165 @@
+-- Portal node
+
+minetest.register_node("nether:portal", {
+	description = "Nether Portal",
+	tiles = {
+		"nether_transparent.png",
+		"nether_transparent.png",
+		"nether_transparent.png",
+		"nether_transparent.png",
+		{
+			name = "nether_portal.png",
+			animation = {
+				type = "vertical_frames",
+				aspect_w = 16,
+				aspect_h = 16,
+				length = 0.5,
+			},
+		},
+		{
+			name = "nether_portal.png",
+			animation = {
+				type = "vertical_frames",
+				aspect_w = 16,
+				aspect_h = 16,
+				length = 0.5,
+			},
+		},
+	},
+	drawtype = "nodebox",
+	paramtype = "light",
+	paramtype2 = "colorfacedir",
+	palette = "nether_portals_palette.png",
+	post_effect_color = {
+		-- post_effect_color can't be changed dynamically in Minetest like the portal colour is.
+		-- If you need a different post_effect_color then create a custom node and set it as the
+		-- wormhole_node_name in your portaldef.
+		-- Hopefully this colour is close enough to magenta to work with the traditional magenta
+		-- portals, close enough to red to work for a red portal, and also close enough to red to
+		-- work with blue & cyan portals - since blue portals are sometimes portrayed as being red
+		-- from the opposite side / from the inside.
+		a = 160, r = 128, g = 0, b = 80
+	},
+	sunlight_propagates = true,
+	use_texture_alpha = true,
+	walkable = false,
+	diggable = false,
+	pointable = false,
+	buildable_to = false,
+	is_ground_content = false,
+	drop = "",
+	light_source = 5,
+	alpha = 192,
+	node_box = {
+		type = "fixed",
+		fixed = {
+			{-0.5, -0.5, -0.1,  0.5, 0.5, 0.1},
+		},
+	},
+	groups = {not_in_creative_inventory = 1}
+})
+
+
+-- Nether nodes
+
+minetest.register_node("nether:rack", {
+	description = "Netherrack",
+	tiles = {"nether_rack.png"},
+	is_ground_content = true,
+	groups = {cracky = 3, level = 2},
+	sounds = default.node_sound_stone_defaults(),
+})
+
+minetest.register_node("nether:sand", {
+	description = "Nethersand",
+	tiles = {"nether_sand.png"},
+	is_ground_content = true,
+	groups = {crumbly = 3, level = 2, falling_node = 1},
+	sounds = default.node_sound_gravel_defaults({
+		footstep = {name = "default_gravel_footstep", gain = 0.45},
+	}),
+})
+
+minetest.register_node("nether:glowstone", {
+	description = "Glowstone",
+	tiles = {"nether_glowstone.png"},
+	is_ground_content = true,
+	light_source = 14,
+	paramtype = "light",
+	groups = {cracky = 3, oddly_breakable_by_hand = 3},
+	sounds = default.node_sound_glass_defaults(),
+})
+
+minetest.register_node("nether:brick", {
+	description = "Nether Brick",
+	tiles = {"nether_brick.png"},
+	is_ground_content = false,
+	groups = {cracky = 2, level = 2},
+	sounds = default.node_sound_stone_defaults(),
+})
+
+local fence_texture =
+	"default_fence_overlay.png^nether_brick.png^default_fence_overlay.png^[makealpha:255,126,126"
+
+minetest.register_node("nether:fence_nether_brick", {
+	description = "Nether Brick Fence",
+	drawtype = "fencelike",
+	tiles = {"nether_brick.png"},
+	inventory_image = fence_texture,
+	wield_image = fence_texture,
+	paramtype = "light",
+	sunlight_propagates = true,
+	is_ground_content = false,
+	selection_box = {
+		type = "fixed",
+		fixed = {-1/7, -1/2, -1/7, 1/7, 1/2, 1/7},
+	},
+	groups = {cracky = 2, level = 2},
+	sounds = default.node_sound_stone_defaults(),
+})
+
+
+-- Register stair and slab
+
+stairs.register_stair_and_slab(
+	"nether_brick",
+	"nether:brick",
+	{cracky = 2, level = 2},
+	{"nether_brick.png"},
+	"nether stair",
+	"nether slab",
+	default.node_sound_stone_defaults()
+)
+
+-- StairsPlus
+
+if minetest.get_modpath("moreblocks") then
+	stairsplus:register_all(
+		"nether", "brick", "nether:brick", {
+			description = "Nether Brick",
+			groups = {cracky = 2, level = 2},
+			tiles = {"nether_brick.png"},
+			sounds = default.node_sound_stone_defaults(),
+	})
+end
+
+
+-- Crafting
+
+minetest.register_craft({
+	output = "nether:brick 4",
+	recipe = {
+		{"nether:rack", "nether:rack"},
+		{"nether:rack", "nether:rack"},
+	}
+})
+
+minetest.register_craft({
+	output = "nether:fence_nether_brick 6",
+	recipe = {
+		{"nether:brick", "nether:brick", "nether:brick"},
+		{"nether:brick", "nether:brick", "nether:brick"},
+	},
+})
+
+

portal_api.txt

@@ -0,0 +1,84 @@
+Portal API Reference
+====================
+
+The portal system used to get to the Nether can be used to create portals
+to other realms.
+
+
+
+Helper functions
+----------------
+
+* `nether.volume_is_natural(minp, maxp)`
+    * use this when determining where to spawn a portal, to avoid overwriting 
+      player builds. It checks the area for any nodes that aren't ground or 
+      trees.
+
+* `nether.find_surface_target_y(target_x, target_z, portal_name)`
+    * Can be used to implement custom find_surface_anchorPos() functions
+    * Providing the portal_name allows existing portals on the surface to be reused.
+
+
+
+
+API functions
+-------------
+
+Call these functions only at load time!
+
+* `nether.register_portal(name, portal definition)`
+    * Returns true on success. Can return false if the portal definition 
+      clashes with a portal already registered by another mod, e.g. if the size
+      and frame node is not unique.
+* `nether.unregister_portal(name)`
+    * Unregisters the portal from the engine, and deletes the entry with key
+      `name` from `nether.registered_portals` and associated internal tables.
+    * Returns true on success
+* register_portal_ignition_item(name)
+
+
+
+Portal definition
+-----------------
+
+Used by `nether.register_portal`.
+
+    {
+		shape = PortalShape_Traditional, 
+        -- optional. 
+
+		wormhole_node_name  = "nether:portal",
+        -- optional. Allows a custom wormhole node to be specified.
+        -- Useful if you want the portals to have a different post_effect_color
+        -- or texture.
+
+		wormhole_node_color = 0,
+
+		particle_color      = "#808",
+        -- Optional. Will default to the same colour as wormhole_node_color if
+        -- not specified.
+
+		frame_node_name     = "default:obsidian",
+        -- required 
+
+
+		sound_ambient       = "portal_hum",
+		sound_ignite        = "",
+		sound_extinguish    = "",
+		sound_teleport      = "",
+
+        within_realm = function(pos)
+        end,
+
+		find_realm_anchorPos = function(pos)
+		end,
+
+		find_surface_anchorPos = function(pos)
+		end,
+
+		on_run_wormhole,
+		on_ignite,
+		on_extinguish,
+		on_player_teleported,
+		on_created
+	}