forked from minetest-mods/nether
52b20925d5
This is effectively a missing part to the change that made locate_or_build_portal() enforce that portals only link together in mutual pairs. As target portals that didn't need to be located or built we not being updated to link back to where the player travelled from. Also * implements events: on_run_wormhole, on_extinguish * adds a lot of debug info
109 lines
4.1 KiB
Plaintext
109 lines
4.1 KiB
Plaintext
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)`: returns a boolean
|
|
* 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)`: returns a
|
|
suitable anchorPos
|
|
* Can be used to implement custom find_surface_anchorPos() functions
|
|
* portal_name is optional, and providing it allows existing portals on the
|
|
surface to be reused.
|
|
|
|
* `nether.find_nearest_working_portal(portal_name, anchorPos, distance_limit, y_factor)`: returns
|
|
an anchorPos, or nil if no portal was found within the the distance_limit.
|
|
* A y_factor of 0 means y does not affect the distance_limit, a y_factor
|
|
of 1 means y is included (the default if y_factor is nil), and a y_factor
|
|
of 2 would squash the search-sphere by a factor of 2 on the y-axis, etc.
|
|
* Only portals in the same realm as the anchorPos will be returned, even if
|
|
y_factor is 0.
|
|
* Pass a nil (or negative) distance_limit to indicate no distance limit
|
|
|
|
|
|
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,
|
|
-- A value from 0 to 7 corresponding to the color of pixels in
|
|
-- nether_portals_palette.png
|
|
|
|
particle_color = "#808",
|
|
-- Optional. Will default to the same colour as wormhole_node_color if
|
|
-- not specified.
|
|
|
|
frame_node_name = "default:obsidian",
|
|
-- Required. For best results, have your portal constructed of a
|
|
-- material nobody else is using.
|
|
|
|
sound_ambient = "nether_portal_hum",
|
|
sound_ignite = "",
|
|
sound_extinguish = "",
|
|
sound_teleport = "",
|
|
|
|
within_realm = function(pos),
|
|
-- Required. Return true if a portal at pos is in the realm, rather
|
|
than the surface world.
|
|
|
|
find_realm_anchorPos = function(surface_anchorPos),
|
|
-- Required. Return a position in the realm that a portal created at
|
|
-- surface_anchorPos will link to.
|
|
-- Return an anchorPos or anchorPos, orientation
|
|
-- If orientation is not specified then the orientation of the surface
|
|
-- portal will be used.
|
|
|
|
find_surface_anchorPos = function(realm_anchorPos),
|
|
-- Optional. If you don't use this then a position near the surface
|
|
-- will be picked.
|
|
-- Return an anchorPos or anchorPos, orientation
|
|
-- If orientation is not specified then the orientation of the realm
|
|
-- portal will be used.
|
|
|
|
on_run_wormhole = function(portalDef, anochorPos, orientation)
|
|
-- invoked once per second per portal
|
|
on_extinguish = function(portalDef, anochorPos, orientation)
|
|
-- invoked when a portal is extinguished, including when the portal
|
|
-- it connected to was extinguished.
|
|
|
|
todo: on_ignite = function(portalDef, anochorPos, orientation)
|
|
todo: on_player_teleported = function(portalDef, oldPos, newPos)
|
|
todo: on_created = function(portalDef, anochorPos, orientation)
|
|
}
|