Add callback parameter for core.emerge_area()

1 files changed, 13 insertions, 3 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 5ad88b121..57940a5dd 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -2039,9 +2039,19 @@ and `minetest.auth_reload` call the authetification handler.
     * `pos1` and `pos2` are optional and default to mapchunk minp and maxp.
 * `minetest.clear_objects()`
     * clear all objects in the environments
-* `minetest.emerge_area(pos1, pos2)`
-    * queues all mapblocks in the area from pos1 to pos2, inclusive, for emerge
-    * i.e. asynchronously loads blocks from disk, or if inexistent, generates them
+* `minetest.emerge_area(pos1, pos2, [callback], [param])`
+    * Queue all blocks in the area from `pos1` to `pos2`, inclusive, to be asynchronously
+    * fetched from memory, loaded from disk, or if inexistent, generates them.
+    * If `callback` is a valid Lua function, this will be called for each block emerged.
+    * The function signature of callback is:
+    *   `function EmergeAreaCallback(blockpos, action, calls_remaining, param)`
+    * - `blockpos` is the *block* coordinates of the block that had been emerged
+    * - `action` could be one of the following constant values:
+    *   `core.EMERGE_CANCELLED`, `core.EMERGE_ERRORED`, `core.EMERGE_FROM_MEMORY`,
+    *   `core.EMERGE_FROM_DISK`, `core.EMERGE_GENERATED`
+    * - `calls_remaining` is the number of callbacks to be expected after this one
+    * - `param` is the user-defined parameter passed to emerge_area (or nil if the
+    *   parameter was absent)
 * `minetest.delete_area(pos1, pos2)`
     * delete all mapblocks in the area from pos1 to pos2, inclusive
 * `minetest.line_of_sight(pos1, pos2, stepsize)`: returns `boolean, pos`