nether/portal_api.txt

109 lines
4.1 KiB
Plaintext
Raw Normal View History

2019-07-05 15:22:22 +02:00
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
2019-07-05 15:22:22 +02:00
* 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
2019-07-05 15:22:22 +02:00
* 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.
2019-07-05 15:22:22 +02:00
* `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
2019-07-05 15:22:22 +02:00
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
2019-07-05 15:22:22 +02:00
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.
2019-07-05 15:22:22 +02:00
sound_ambient = "nether_portal_hum",
2019-07-05 15:22:22 +02:00
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.
2019-07-05 15:22:22 +02:00
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.
2019-07-05 15:22:22 +02:00
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.
2019-07-05 15:22:22 +02:00
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)
2019-07-05 15:22:22 +02:00
}