forked from minetest-mods/nether
266 lines
12 KiB
Plaintext
266 lines
12 KiB
Plaintext
Portal API Reference
|
|
====================
|
|
|
|
The portal system used to get to the Nether can be used to create portals
|
|
to other realms.
|
|
|
|
Pick a node type to have your portals built from, a shape in which the
|
|
portals must be built, and provide 3 functions for portals to find their
|
|
destination with:
|
|
* `find_realm_anchorPos(surface_anchorPos)`
|
|
* `find_surface_anchorPos(realm_anchorPos)`
|
|
* `is_within_realm(pos)`
|
|
|
|
Optionally decorate by choosing portal colors, particles, media etc.
|
|
|
|
See `init.lua` and `portal_examples.lua` for examples of 3 different portals.
|
|
|
|
Portal code is more efficient when each type of portal uses a different type
|
|
of node to build its frame out of - consider creating your own node for
|
|
players to build portals from. However it is possible to register more than
|
|
one kind of portal with the same frame material — such as obsidian — provided
|
|
the size of the PortalShape is distinct from any other type of portal that is
|
|
using the same node for its frame, and portal sizes remain small.
|
|
|
|
The Nether provides three variants of Nether basalt to ensure there are
|
|
alternatives to obsidian for other mods to use as portalstones.
|
|
|
|
|
|
Realms
|
|
------
|
|
|
|
This API uses the concept of a realm for each type of portal. If a portal is
|
|
outside its realm then it links to a portal inside the realm, if a portal is
|
|
inside its realm then it links to the outside.
|
|
|
|
You get to decide what constitutes your realm by implementing the function
|
|
`is_within_realm(position)`.
|
|
|
|
For example, the Nether realm is defined as existing at a certain depth and
|
|
anything above that depth is considered outside the Realm.
|
|
|
|
In contrast, the "Surface portal" - an example in portal_examples.lua, only
|
|
uses one realm. Its `is_within_realm()` function always returns true so that
|
|
any time a portal is opened it will use `find_surface_anchorPos()`.
|
|
|
|
Note that the name "find_surface_anchorPos" is a Nether-centric misnomer, as
|
|
different types of portals are free to use different definitions of a realm
|
|
such that leaving the realm might not be synonymous with travelling to the
|
|
surface.
|
|
|
|
|
|
Helper functions
|
|
----------------
|
|
|
|
* `nether.volume_is_natural_and_unprotected(minp, maxp, player_name)`: 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.
|
|
Water will fail this test, unless it is unemerged.
|
|
* player_name is optional, providing it allows the player's own protected
|
|
areas to be treated as unprotected.
|
|
|
|
* `nether.find_surface_target_y(target_x, target_z, portal_name, player_name)`:
|
|
returns a suitable anchorPos
|
|
* Can be used when implementing custom find_surface_anchorPos() functions
|
|
* portal_name is optional, providing it allows existing portals on the
|
|
surface to be reused.
|
|
* player_name is optional, providing it prevents the exclusion of surface
|
|
target areas which are protected by the player.
|
|
* May return nil in extreme circumstances, such as the surface being
|
|
protected down to a great depth.
|
|
|
|
* `nether.find_nearest_working_portal(portal_name, anchorPos, distance_limit, y_factor)`: returns
|
|
(anchorPos, orientation), or nil if no portal was found within 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.
|
|
A false return value should be handled, you could:
|
|
* Fall back to using a secondary material for portals to be built with.
|
|
* Use error() to exit lua with a message explaining how two mods are
|
|
clashing and how it can be resolved.
|
|
* Continue without a portal (the reason will be logged for the user).
|
|
* `nether.register_portal_ignition_item(name, ignition_failure_sound)`
|
|
* ignition_failure_sound is optional, it plays any time an attempt to use
|
|
the item occurs if a portal is not ignited.
|
|
* `nether.register_wormhole_node(name, nodedef_overrides)`
|
|
* Can be used to register wormhole nodes with a different post_effect_color
|
|
from the "nether:portal" node. "Post effect color" is the tint the world
|
|
takes on when you are standing inside a portal. `post_effect_color` is the
|
|
only key/value that is needed in the nodedef_overrides table to achieve that,
|
|
but the function allows any nodedef key/value to be specified/overridden.
|
|
* After `register_wormhole_node()`, invoke `register_portal()` and include
|
|
`wormhole_node_name` in the portal_definition, assigning it the name of the
|
|
new wormhole node.
|
|
* `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
|
|
* You will probably never need to call this, it exists only for completeness.
|
|
|
|
|
|
Portal definition
|
|
-----------------
|
|
|
|
Used by `nether.register_portal`.
|
|
|
|
{
|
|
frame_node_name = "default:obsidian",
|
|
-- Required. For best results, have your portal constructed of a
|
|
-- material nobody else is using.
|
|
|
|
frame_node_color = 0,
|
|
-- Optional.
|
|
-- A value from 0 to 7. Only used if the frame node's paramtype2 is
|
|
-- "colorfacedir", in which case this color will be used when a remote
|
|
-- portal is created.
|
|
|
|
shape = nether.PortalShape_Traditional,
|
|
-- Optional.
|
|
-- Shapes available are:
|
|
-- nether.PortalShape_Traditional (default)
|
|
-- nether.PortalShape_Circular
|
|
-- nether.PortalShape_Platform
|
|
-- New shapes can be created, but are beyond the scope of this guide.
|
|
|
|
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.
|
|
-- The Nether mod provides:
|
|
-- "nether:portal" (default)
|
|
-- "nether:portal_alt"
|
|
|
|
wormhole_node_color = 0,
|
|
-- Optional. Defaults to 0/magenta.
|
|
-- A value from 0 to 7 corresponding to the color of pixels in
|
|
-- nether_portals_palette.png:
|
|
-- 0 traditional/magenta
|
|
-- 1 black
|
|
-- 2 blue
|
|
-- 3 green
|
|
-- 4 cyan
|
|
-- 5 red
|
|
-- 6 yellow
|
|
-- 7 white
|
|
|
|
particle_color = "#808",
|
|
-- Optional. Will default to a colour matching the wormhole_node_color
|
|
-- if not specified.
|
|
|
|
particle_texture = "image.png",
|
|
-- Optional. Hardware colouring (i.e. particle_color) is applied to
|
|
-- this texture, use particle_texture_colored instead if you want to
|
|
-- use the colors of the image.
|
|
-- Animation and particle scale may also be specified, e.g:
|
|
-- particle_texture = {
|
|
-- name = "nether_particle_anim1.png",
|
|
-- animation = {
|
|
-- type = "vertical_frames",
|
|
-- aspect_w = 7,
|
|
-- aspect_h = 7,
|
|
-- length = 1,
|
|
-- },
|
|
-- scale = 1.5
|
|
-- },
|
|
-- See lua_api.txt for Tile Animation definition
|
|
-- Some animated and non-animated textures are provided by this mod:
|
|
-- nether_particle.png (original)
|
|
-- nether_particle_anim1.png (stars)
|
|
-- nether_particle_anim2.png (bubbles)
|
|
-- nether_particle_anim3.png (sparks)
|
|
-- nether_particle_anim4.png (particles)
|
|
|
|
title = "Gateway to Moria",
|
|
-- Optional. Provides a title for the portal.
|
|
-- Used in the Book of Portals or Help modpack.
|
|
|
|
book_of_portals_pagetext = "Everything I need the player to know",
|
|
-- Optional. Provides the text for the portal in the Book of Portals
|
|
-- and Help modpack.
|
|
-- The Book of Portals is a book that can be found in chests, and
|
|
-- provides players with instructions on how to build and use the
|
|
-- portal, so be sure to mention the node type the frame must be built
|
|
-- from.
|
|
-- This can also provide flavortext or details about where the portal
|
|
-- will take the player.
|
|
|
|
sounds = {
|
|
ambient = <SimpleSoundSpec>,
|
|
-- if the ambient SimpleSoundSpec is a table it can also contain a
|
|
-- "length" int, which is the number of seconds to wait before
|
|
-- repeating the ambient sound. Default is 3.
|
|
ignite = <SimpleSoundSpec>,
|
|
extinguish = <SimpleSoundSpec>,
|
|
teleport = <SimpleSoundSpec>,
|
|
}
|
|
-- sounds is optional
|
|
|
|
within_realm = function(pos),
|
|
-- Required. Return true if a portal at pos is in the realm, rather
|
|
-- than the surface world.
|
|
-- Ideally implementations are fast, as this function can be used to
|
|
-- sift through a list of portals.
|
|
|
|
find_realm_anchorPos = function(surface_anchorPos, player_name),
|
|
-- 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.
|
|
-- If the location of an existing portal is returned then include the
|
|
-- orientation, otherwise the existing portal could be overwritten by
|
|
-- a new one with the orientation of the surface portal.
|
|
-- Return nil, or a position with a nil y component, to prevent the
|
|
-- portal from igniting.
|
|
-- player_name may be "", e.g. if the portal was ignited by a mesecon,
|
|
-- and is provided for use with volume_is_natural_and_unprotected() etc.
|
|
|
|
find_surface_anchorPos = function(realm_anchorPos, player_name),
|
|
-- Optional. If you don't implement this then a position near the
|
|
-- surface will be picked.
|
|
-- Return an anchorPos or (anchorPos, orientation)
|
|
-- The name of this function is a Nether-centric misnomer. It should
|
|
-- return a position outside the realm, and different types of portals
|
|
-- are free to use different definitions of a realm such that leaving
|
|
-- the realm might not be synonymous with travelling to the surface.
|
|
-- If orientation is not specified then the orientation of the realm
|
|
-- portal will be used.
|
|
-- If the location of an existing portal is returned then include the
|
|
-- orientation, otherwise the existing portal could be overwritten by
|
|
-- a new one with the orientation of the realm portal.
|
|
-- Return nil, or a position with a nil y component, to prevent the
|
|
-- portal from igniting.
|
|
-- player_name may be "", e.g. if the portal was ignited by a mesecon,
|
|
-- and is provided for use with volume_is_natural_and_unprotected() etc.
|
|
|
|
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.
|
|
on_player_teleported = function(portalDef, player, oldPos, newPos),
|
|
-- invoked immediately after a player is teleported
|
|
on_ignite = function(portalDef, anochorPos, orientation)
|
|
-- invoked when a player or mesecon ignites a portal
|
|
on_created = function(portalDef, anochorPos, orientation)
|
|
-- invoked when a portal creates a remote twin, this is usually when
|
|
-- a player travels through a portal for the first time.
|
|
}
|