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,
		on_ignite,
		on_extinguish,
		on_player_teleported,
		on_created
	}