minetest-australopithecus-spawn-usher/README

minetest-australopithecus-spawn-usher
=====================================

A simple system that corrects the spawn of players without knowing anything
about the mapgen that is used.


Usage
=====

The system activates itself, you just need to add the mod to the subgame.


Configuration
=============

The system can be configured by adding settings to the `minetest.conf`:

    # The radius around the spawnpoint in which the players will be randomly
    # placed, defaults to 40.
    spawnusher_placement_radius = 40.
    
    # The size of the air bubble that is required for the player to be placed.
    # Note that this is only the vertical size, defaults to 2.
    # If you want to avoid spawns in caves, this value needs to be increased
    # to a sensible value.
    spawnusher_bubble_size = 2
    
    # If the player can not be placed because the block is currently not loaded,
    # this amount of time will be waited before it is retried to place
    # place the player, defaults to 0.5.
    # In seconds.
    spawnusher_retry_time = 0.5


Providers
=========

You can register providers which allow to customize the spawn point of
the players. The provider is a callback that is able to provide a different
spawn point. As second return value it can return a boolean determining if
the system should look for an air bubble above or below the given location.
The signature is:

    function(
        player,    -- The Player object of the player that is going to respawn.
        spawn_pos) -- The current spawn position of the player.
    
    returns
        spawn_pos, -- The position at which the player should ge respawned.
                   -- nil to use the current one.
        exact_spot -- true if the given position is the exact position to be
                   -- used. nil to keep the current value.

And a usage example:

    -- Fixes the spawn point of the player named "hero" at some position.
    spawnusher.register_spawnpoint_provider(function(player, spawn_pos)
        if player:get_player_name() == "hero" then
            return {
                x = 0,
                y = 125,
                z = 50
            },
            true
        end
    end)
    
    -- We want to move all players further out.
    spawnusher.register_spawnpoint_provider(function(player, spawn_pos)
        return {
            x = spawn_pos.x + 150,
            y = spawn_pos.y,
            z = spawn_pos.z + 150
        }
    end)


After Spawn Callbacks
=====================

You can register a callback that will be invoked after the player has been
respawned. This callback can't modify the spawn point anymore and is only
to get informed about the actual spawn point of the player. The signature is:

    function(
        player,      -- The Player object of the player that has respawned.
        spawn_point) -- The spawn point of the player.

Usage example:

    spawnusher.register_after_spawn_callback(function(player, spawn_point)
        -- Do something with this information.
    end)


Caveats
=======

There is a good chance that the player is placed inside a cave if
the `required_bubble_size` is small, like 2. If you want to prevent that, just
pick a `required_bubble_size` that is large enough to avoid caves, 10 should
work for the most part, for example.