Nether mod for Minetest
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

263 lines
12KB

  1. Portal API Reference
  2. ====================
  3. The portal system used to get to the Nether can be used to create portals
  4. to other realms.
  5. Pick a node type to have your portals built from, a shape in which the
  6. portals must be built, and provide 3 functions for portals to find their
  7. destination with:
  8. * `find_realm_anchorPos(surface_anchorPos)`
  9. * `find_surface_anchorPos(realm_anchorPos)`
  10. * `is_within_realm(pos)`
  11. Optionally decorate by choosing portal colors, particles, media etc.
  12. See `init.lua` and `portal_examples.lua` for examples of 3 different portals.
  13. Portal code is more efficient when each type of portal uses a different type
  14. of node to build its frame out of - consider creating your own node for
  15. players to build portals from. However it is possible to register more than
  16. one kind of portal with the same frame material — such as obsidian — provided
  17. the size of the PortalShape is distinct from any other type of portal that is
  18. using the same node for its frame, and portal sizes remain small.
  19. Realms
  20. ------
  21. This API uses the concept of a realm for each type of portal. If a portal is
  22. outside its realm then it links to a portal inside the realm, if a portal is
  23. inside its realm then it links to the outside.
  24. You get to decide what constitutes your realm by implementing the function
  25. `is_within_realm(position)`.
  26. For example, the Nether realm is defined as existing at a certain depth and
  27. anything above that depth is considered outside the Realm.
  28. In contrast, the "Surface portal" - an example in portal_examples.lua, only
  29. uses one realm. Its `is_within_realm()` function always returns true so that
  30. any time a portal is opened it will use `find_surface_anchorPos()`.
  31. Note that the name "find_surface_anchorPos" is a Nether-centric misnomer, as
  32. different types of portals are free to use different definitions of a realm
  33. such that leaving the realm might not be synonymous with travelling to the
  34. surface.
  35. Helper functions
  36. ----------------
  37. * `nether.volume_is_natural_and_unprotected(minp, maxp, player_name)`: returns
  38. a boolean.
  39. * use this when determining where to spawn a portal, to avoid overwriting
  40. player builds. It checks the area for any nodes that aren't ground or
  41. trees.
  42. Water will fail this test, unless it is unemerged.
  43. * player_name is optional, providing it allows the player's own protected
  44. areas to be treated as unprotected.
  45. * `nether.find_surface_target_y(target_x, target_z, portal_name, player_name)`:
  46. returns a suitable anchorPos
  47. * Can be used when implementing custom find_surface_anchorPos() functions
  48. * portal_name is optional, providing it allows existing portals on the
  49. surface to be reused.
  50. * player_name is optional, providing it prevents the exclusion of surface
  51. target areas which are protected by the player.
  52. * May return nil in extreme circumstances, such as the surface being
  53. protected down to a great depth.
  54. * `nether.find_nearest_working_portal(portal_name, anchorPos, distance_limit, y_factor)`: returns
  55. (anchorPos, orientation), or nil if no portal was found within the
  56. distance_limit.
  57. * A y_factor of 0 means y does not affect the distance_limit, a y_factor
  58. of 1 means y is included (the default if y_factor is nil), and a y_factor
  59. of 2 would squash the search-sphere by a factor of 2 on the y-axis, etc.
  60. * Only portals in the same realm as the anchorPos will be returned, even if
  61. y_factor is 0.
  62. * Pass a nil (or negative) distance_limit to indicate no distance limit
  63. API functions
  64. -------------
  65. Call these functions only at load time:
  66. * `nether.register_portal(name, portal_definition)`
  67. * Returns true on success. Can return false if the portal definition
  68. clashes with a portal already registered by another mod, e.g. if the size
  69. and frame node is not unique.
  70. A false return value should be handled, you could:
  71. * Fall back to using a secondary material for portals to be built with.
  72. * Use error() to exit lua with a message explaining how two mods are
  73. clashing and how it can be resolved.
  74. * Continue without a portal (the reason will be logged for the user).
  75. * `nether.register_portal_ignition_item(name, ignition_failure_sound)`
  76. * ignition_failure_sound is optional, it plays any time an attempt to use
  77. the item occurs if a portal is not ignited.
  78. * `nether.register_wormhole_node(name, nodedef_overrides)`
  79. * Can be used to register wormhole nodes with a different post_effect_color
  80. from the "nether:portal" node. "Post effect color" is the tint the world
  81. takes on when you are standing inside a portal. `post_effect_color` is the
  82. only key/value that is needed in the nodedef_overrides table to achieve that,
  83. but the function allows any nodedef key/value to be specified/overridden.
  84. * After `register_wormhole_node()`, invoke `register_portal()` and include
  85. `wormhole_node_name` in the portal_definition, assigning it the name of the
  86. new wormhole node.
  87. * `nether.unregister_portal(name)`
  88. * Unregisters the portal from the engine, and deletes the entry with key
  89. `name` from `nether.registered_portals` and associated internal tables.
  90. * Returns true on success
  91. * You will probably never need to call this, it exists only for completeness.
  92. Portal definition
  93. -----------------
  94. Used by `nether.register_portal`.
  95. {
  96. frame_node_name = "default:obsidian",
  97. -- Required. For best results, have your portal constructed of a
  98. -- material nobody else is using.
  99. frame_node_color = 0,
  100. -- Optional.
  101. -- A value from 0 to 7. Only used if the frame node's paramtype2 is
  102. -- "colorfacedir", in which case this color will be used when a remote
  103. -- portal is created.
  104. shape = nether.PortalShape_Traditional,
  105. -- Optional.
  106. -- Shapes available are:
  107. -- nether.PortalShape_Traditional (default)
  108. -- nether.PortalShape_Circular
  109. -- nether.PortalShape_Platform
  110. -- New shapes can be created, but are beyond the scope of this guide.
  111. wormhole_node_name = "nether:portal",
  112. -- Optional. Allows a custom wormhole node to be specified.
  113. -- Useful if you want the portals to have a different post_effect_color
  114. -- or texture.
  115. -- The Nether mod provides:
  116. -- "nether:portal" (default)
  117. -- "nether:portal_alt"
  118. wormhole_node_color = 0,
  119. -- Optional. Defaults to 0/magenta.
  120. -- A value from 0 to 7 corresponding to the color of pixels in
  121. -- nether_portals_palette.png:
  122. -- 0 traditional/magenta
  123. -- 1 black
  124. -- 2 blue
  125. -- 3 green
  126. -- 4 cyan
  127. -- 5 red
  128. -- 6 yellow
  129. -- 7 white
  130. particle_color = "#808",
  131. -- Optional. Will default to a colour matching the wormhole_node_color
  132. -- if not specified.
  133. particle_texture = "image.png",
  134. -- Optional. Hardware colouring (i.e. particle_color) is applied to
  135. -- this texture, use particle_texture_colored instead if you want to
  136. -- use the colors of the image.
  137. -- Animation and particle scale may also be specified, e.g:
  138. -- particle_texture = {
  139. -- name = "nether_particle_anim1.png",
  140. -- animation = {
  141. -- type = "vertical_frames",
  142. -- aspect_w = 7,
  143. -- aspect_h = 7,
  144. -- length = 1,
  145. -- },
  146. -- scale = 1.5
  147. -- },
  148. -- See lua_api.txt for Tile Animation definition
  149. -- Some animated and non-animated textures are provided by this mod:
  150. -- nether_particle.png (original)
  151. -- nether_particle_anim1.png (stars)
  152. -- nether_particle_anim2.png (bubbles)
  153. -- nether_particle_anim3.png (sparks)
  154. -- nether_particle_anim4.png (particles)
  155. title = "Gateway to Moria",
  156. -- Optional. Provides a title for the portal.
  157. -- Used in the Book of Portals or Help modpack.
  158. book_of_portals_pagetext = "Everything I need the player to know",
  159. -- Optional. Provides the text for the portal in the Book of Portals
  160. -- and Help modpack.
  161. -- The Book of Portals is a book that can be found in chests, and
  162. -- provides players with instructions on how to build and use the
  163. -- portal, so be sure to mention the node type the frame must be built
  164. -- from.
  165. -- This can also provide flavortext or details about where the portal
  166. -- will take the player.
  167. sounds = {
  168. ambient = <SimpleSoundSpec>,
  169. -- if the ambient SimpleSoundSpec is a table it can also contain a
  170. -- "length" int, which is the number of seconds to wait before
  171. -- repeating the ambient sound. Default is 3.
  172. ignite = <SimpleSoundSpec>,
  173. extinguish = <SimpleSoundSpec>,
  174. teleport = <SimpleSoundSpec>,
  175. }
  176. -- sounds is optional
  177. within_realm = function(pos),
  178. -- Required. Return true if a portal at pos is in the realm, rather
  179. -- than the surface world.
  180. -- Ideally implementations are fast, as this function can be used to
  181. -- sift through a list of portals.
  182. find_realm_anchorPos = function(surface_anchorPos, player_name),
  183. -- Required. Return a position in the realm that a portal created at
  184. -- surface_anchorPos will link to.
  185. -- Return an anchorPos or (anchorPos, orientation)
  186. -- If orientation is not specified then the orientation of the surface
  187. -- portal will be used.
  188. -- If the location of an existing portal is returned then include the
  189. -- orientation, otherwise the existing portal could be overwritten by
  190. -- a new one with the orientation of the surface portal.
  191. -- Return nil, or a position with a nil y component, to prevent the
  192. -- portal from igniting.
  193. -- player_name may be "", e.g. if the portal was ignited by a mesecon,
  194. -- and is provided for use with volume_is_natural_and_unprotected() etc.
  195. find_surface_anchorPos = function(realm_anchorPos, player_name),
  196. -- Optional. If you don't implement this then a position near the
  197. -- surface will be picked.
  198. -- Return an anchorPos or (anchorPos, orientation)
  199. -- The name of this function is a Nether-centric misnomer. It should
  200. -- return a position outside the realm, and different types of portals
  201. -- are free to use different definitions of a realm such that leaving
  202. -- the realm might not be synonymous with travelling to the surface.
  203. -- If orientation is not specified then the orientation of the realm
  204. -- portal will be used.
  205. -- If the location of an existing portal is returned then include the
  206. -- orientation, otherwise the existing portal could be overwritten by
  207. -- a new one with the orientation of the realm portal.
  208. -- Return nil, or a position with a nil y component, to prevent the
  209. -- portal from igniting.
  210. -- player_name may be "", e.g. if the portal was ignited by a mesecon,
  211. -- and is provided for use with volume_is_natural_and_unprotected() etc.
  212. on_run_wormhole = function(portalDef, anochorPos, orientation),
  213. -- invoked once per second per portal
  214. on_extinguish = function(portalDef, anochorPos, orientation),
  215. -- invoked when a portal is extinguished, including when the portal
  216. -- it connected to was extinguished.
  217. on_player_teleported = function(portalDef, player, oldPos, newPos),
  218. -- invoked immediately after a player is teleported
  219. on_ignite = function(portalDef, anochorPos, orientation)
  220. -- invoked when a player or mesecon ignites a portal
  221. on_created = function(portalDef, anochorPos, orientation)
  222. -- invoked when a portal creates a remote twin, this is usually when
  223. -- a player travels through a portal for the first time.
  224. }