Module spawnusher
Spawn usher is a system that allows to correct the spawn position of players without knowing anything about the mapgen.
The system will register callbacks for newplayer and respawnplayer and will try to find an air bubble, either upwards or downwards, which the player can fit into. If an air bubble is found, the player will be moved there. If the block is not loaded, it will be tried again after a certain amount of time.
The only function that should be called from clients is activate.
Functions
| activate (random_placement_radius, required_bubble_size, retry_time) | Activates the spawn usher system. |
| is_air_bubble (start_pos) | Tests if the given position is an air bubble big enough. |
| move_later (player, current_pos) | Schedules the player to be moved later. |
| move_random (player) | Moves the player randomly on the x and z plane. |
| move_player (player) | Moves the player to a safe location. |
| move_players () | Move all players that could not be placed so far. |
| on_spawn_player (player) | Callback for if a player spawns. |
| register_after_spawn_callback (callback) | Allows to register callbacks after a player has been spawned by spawn usher. |
| register_spawnpoint_provider (provider) | Allows to register providers that are called after the final position of the player has been determined. |
Functions
- activate (random_placement_radius, required_bubble_size, retry_time)
-
Activates the spawn usher system.
Parameters:
- random_placement_radius Optional. The player will be respawned in the given radius around the spawn point.
- required_bubble_size Optional. The size/height of the bubble of air that is required for the player to spawn. Defaults to 2.
- retry_time Optional. This is the time that passes between tries to place to the player.
- is_air_bubble (start_pos)
-
Tests if the given position is an air bubble big enough.
Parameters:
- start_pos The position at which to check.
Returns:
-
true if at the given position is an air bubble big enough.
- move_later (player, current_pos)
-
Schedules the player to be moved later. Also moves the player to the given
position.
Parameters:
- player The player object.
- current_pos The current position to which the player will be moved.
- move_random (player)
-
Moves the player randomly on the x and z plane.
Parameters:
- player The Player object to move.
- move_player (player)
-
Moves the player to a safe location.
Parameters:
- player The player object.
- move_players ()
- Move all players that could not be placed so far.
- on_spawn_player (player)
-
Callback for if a player spawns.
Parameters:
- player The Player that spawned.
Returns:
-
true, to disable default placement.
- register_after_spawn_callback (callback)
-
Allows to register callbacks after a player has been spawned by spawn usher.
Parameters:
- callback The callback to invoke, a function that accepts the player object as single parameter.
- register_spawnpoint_provider (provider)
-
Allows to register providers that are called after the final position of
the player has been determined. The provider can return a different position,
or nil if it is happy with the given position.
Parameters:
- provider The provider. A function that accepts two parameters, the Player object and the spawn position that the system calculated. It can return a new position, a table with x y z values, or nil if the position should not be changed.