Updated map warps (markdown)

map-warps.md

@@ -1,4 +1,6 @@
-## Warping across maps, using [[WARP nodes|nodes]]
+# Warping via [[nodes]]
+
+## Warping across maps, using WARP nodes
 
 Let's say we have 3 maps, **map1**, **map2** and **map3**, and we want to put "doors" to warp from one map to another:
 
@@ -23,22 +25,79 @@ warpnode map2 myNode r
 
 Just place a _myNode_ node somewhere on the map and you will warp to it. The node name should be unique on that map.
 
+The warp destination is always the center of the target node.
+
+Optionally, after the target node name you can specify whether you will be facing left (**l**) or right (**r**) upon map load.
+
 ## Local Warping on a single maps, using WARPLOCALNODE nodes
 
 This is used for houses or entrances to small caves, where the warp target lies on the same map.
 
+To warp into a cave (place a node called **1in** next to the out-warp inside of the cave:
+
 ```
 warplocalnode 1in in
+```
+
+To wrap out of the cave, same thing in reverse (place a node called **1out** near the entrance warp:
+
+```
 warplocalnode 1out out
 ```
 
-A picture says more than 1000 words:
+A picture explains this much better:
 
 ![Local warps explanation](http://fg.wzff.de/pub/aquaria/wikidata/localwarps.png)
 
-Here, **1in** and **1out** are (arbitrarily chosen) names of warp target nodes, and the last word (**in**/**out**) specifies whether the warp goes inside a cave or back out into the open world.
+Here, **1in** and **1out** are (arbitrarily chosen) names of warp target nodes, and the last parameter (**in**/**out**) specifies whether the warp goes inside a cave or back out into the open world.
 
-While inside a local cave, the game enters a special mode where your world map position does not change, you'll still be displayed as if you were at the entrance location of the cave. This is because local caves are typically omitted from the world map, and it makes sense to lock your location this way.
+While inside a local cave, the game enters a special mode where your world map position does not change, you'll still be displayed as if you were at the entrance location of the cave. This is because local caves are typically omitted from the world map, and it makes sense to lock your apparent location this way.
 
 If you don't need the distinction between inside and outside, use "out".
 
+
+## Warping via tube flowers
+
+![A tube flower](http://fg.wzff.de/pub/aquaria/wikidata/warp-tubeflower.jpg)
+
+This warp type is a bit special. If you want any customized behavior in your mod you need to copy & modify the script file to your needs (see [scripts/entities/sporechildflowerportal.lua](https://github.com/AquariaOSE/Aquaria/blob/master/files/scripts/entities/sporechildflowerportal.lua)).
+
+The vanilla behavior can be summed up as follows:
+
+* If we're on a specially handled map (and those maps are built to have only one tube flower) then warp to whatever special target. Look at the code.
+* Otherwise try to find another tube flower on the same map, and warp to it.
+  * This implies that you can only have two tube flowers per map to ensure a reliable two-way connection, as it's undefined which tube flower it finds first if there are more than two.
+
+# Lua functions for warping
+
+If the above warp types are not sufficient, you can also initiate warping from scripts.
+
+***
+
+`warpAvatar(mapname, x, y)`
+
+Warp to position (x, y) on map _mapname_.
+
+***
+
+`warpNaijaToSceneNode(mapname, nodename, facing)`
+
+Warp to map _mapname_, node _nodename_, facing left or right (use "l" or "r" as parameter).
+
+***
+
+[Deprecated] `warpNaijaToEntity(entityname, xoffs, yoffs)`
+
+Find an entity named _entityname_ on the current map, fade out, put Naija where the entity is plus an optional offset, then fade back in. Nothing happens if the entity isn't found.
+
+***
+
+`loadMap(mapname, nodename)`
+
+Disable input, then warp to map _mapname_, node _nodename_. Very similar to warpNaijaToSceneNode() except you can't set the facing direction.
+
+***
+
+[OSE only] `setCanWarp(bool)`
+
+If false, warp/warpnode/warplocalnode nodes are ignored.