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, 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 as its frame, and portal sizes remain small.

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 consitutes your realm by implementing the function
`is_within_realm(position)`.

The Nether realm, for example, is defined as existing at a certain depth.


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 when implementing custom find_surface_anchorPos() functions
    * portal_name is optional, 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.
      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.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, 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.



Portal definition
-----------------

Used by `nether.register_portal`.

    {
        shape = PortalShape_Traditional, 
        -- Optional. Defaults to PortalShape_Traditional

        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,
        -- 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

        frame_node_name     = "default:obsidian",
        -- Required. For best results, have your portal constructed of a 
        -- material nobody else is using.

        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.

        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.
        -- 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.

        find_surface_anchorPos = function(realm_anchorPos),
        -- Optional. If you don't implement 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. 
        -- 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.

        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, usually when a
        -- player travels through a portal for the first time.
    }