Bukkit

Spawn strategies

Spawn strategies determine what happens during various spawn/command events on your server, giving you full control over exactly what you want to have happen and when. Spawn strategies are defined in the config.yml and if you make any changes, you can reload them live in-game by just running "/hsp rc" (short for reloadconfig). For defining world or permission-specific strategies, please see this example.

Events

These are the events for which you can define spawn strategies:

• onJoin - this controls spawn behavior when a player logs into the server
• onNewPlayer (v1.7) - this event chain is only invoked when a new player logs in. If you don't define this event or it doesn't return a location, then HSP will fall through to onJoin instead
• onDeath - this controls spawn behavior when a player respawns after dying
• onSpawnCommand - this controls spawn behavior when a player types "/spawn" with no other arguments
• onHomeCommand - this controls spawn behavior when a player types "/home" with no other arguments
• onGroupSpawnCommand - this controls the spawn behavior when a player types "/groupspawn".
• onNamedHomeCommand - this controls home behavior when a player types "/home" with a name argument. The default strategy is "homeNamedHome" which will find the home of the argument passed by the player, but you can use this event chain to also apply modes (such as "modeHomeNoBed", for example) to affect how named homes work
• onNamedSpawnCommand - this controls home behavior when a player types "/spawn" with a name argument. The default strategy is "spawnNamedSpawn" which will find the spawn of the argument passed by the player.
• crossWorldTeleport (v1.7) - invoked when a player teleports crossWorld. This gives you opportunity to apply HSP event chain as a person enters a world. Note that if you have MultiVerse installed and the player teleports due to a MultiVerse event (such as a Portal or /mvtp command), this event is not invoked.
• multiverseCrossWorldTeleport (v1.7) - this is invoked when a player teleports crossWorld using Multiverse (such as a portal or /mvtp command). This is special because extra data might be available on this event, such as the source portal which you could use with the ModeMultiverseSourcePortal strategy, for example.
• multiverseTeleport (v1.7) - this is invoked when a player uses multiverse to teleport, but stays on the same world.
• onRegionEnter;<region> (v1.7) - this is an integration with WorldGuard, which can be used to do something special when a player enters a region. Please look at Example7 for more detail.
• onRegionExit;<region> (v1.7) - just like onRegionEnter but for region exits instead.

Custom commands and events

As of 1.7, HSP additionally lets you define your own event types which you can bind to a custom command. For example, HSP does not have a "/randomspawn" command, but maybe you want one; go right ahead and make it yourself! Since this is an advanced topic, it has it's own page describing how you can go about defining your own commands and events.

Spawn/Home strategies

These are the strategies that you can define for any of the events above. The strategies are defined in the appropriate section of the config.yml as a YML list, just look at the default settings for an example. The strategies are evaluated in the order they are listed, so if you list a strategy that is guaranteed to always return a location, such as "spawnDefaultWorld", then none of the other strategies listed after that one will ever get used for that event type.

Not all strategies make sense for all events, for example "homeDefaultWorld" doesn't make a lot of sense for "onSpawnCommand". There are no restrictions on where you can use strategies, so you could use it if you want but it'll just confuse your players.

To make strategies a little less overwhelming, they have been broken down into the simple options and the more advanced options. Additionally, home-related strategies are colored green while spawn-related strategies are colored yellow.

Simple

• homeLocalWorld: find the player's default home on whatever world they are on
• homeDefaultWorld: find the player's default home on the default world
• homeMultiWorld: convenience strategy combining Local and DefaultWorld; searches for default home on local world first, then on the default world

• spawnNewPlayer: this strategy only has an effect on the very first join of a new player, it will send them to the spawn set by "/setfirstspawn"
• spawnLocalWorld: send the player to the spawn point defined for the local world (this does nothing if /setspawn has never been used in that world)
• spawnDefaultWorld: send the player to default spawn in the default world. This strategy ALWAYS works, so if you use this, make sure it is at the end of your strategy list.

• default: this is the logical assumed end of every strategy chain, this will basically not do ANYTHING and let Bukkit do whatever is the default for the given action. This aborts any further strategy processing when it fires.

Advanced

• homeAnyWorld: find ANY home on ANY world. This does NOT guarantee any order (ie. no guarantee it will find Local or Default world first) and is meant primarily as an option for admins to provide a "last ditch" strategy (if local world is "A", default world is "B" and a third world is "C" and a player has only one home defined on "C" when they die on world "A", this strategy would find and return the home on world "C")
• homeSpecificWorld:myworld: send player to their default home on myworld
• homeNearest: search for nearest home on local world
• nearestHomeOrSpawn (v1.6.1): search for the nearest home or spawn on the local world; this could send them to a home or a spawn, depending on which is closer.

• spawnGroup: send the player to the spawn for their primary group, as set by "/setgroupspawn" command. Please note this feature works best with Vault installed and you should use the /groupquery command to check what group HSP thinks a given player is in. ALSO NOTE this only applies to the LOCAL WORLD the player is on when this strategy fires. If you want the player to go to a groupSpawn on a specific world, use the spawnGroupSpecificWorld strategy.
• spawnGroupSpecificWorld:myworld: send the player to the spawn defined by their Perm2-group on the specific world "myworld", as defined by "/setgroupspawn" command
• spawnNearest: send player to nearest spawn in local world
• spawnSpecificWorld:myworld: send player to default spawn in myworld
• spawnNamedSpawn:myspawn: send player to the spawn named myspawn
• spawnWGregion: if using WorldGuard "spawn" flag (dev 5.4+ only), send the player to the spawn for any region they are in. If they are not in a WorldGuard region or there is no spawn flag defined for the one they are in, this strategy does nothing
• spawnLocalRandom: choose a spawn at random in the player's local world to spawn the player. This chooses based only on spawns you've set using /setspawn, so you could use this to spawn a player randomly at any of four spawns you've set, for example. If you want to choose a completely random location, use the spawnWorldRandom strategy instead.
• spawnRandomNamed:name1,name2,name3 (v1.6): choose a random spawn out of the named spawns listed
• spawnRegionRandom:region1 (v1.6): choose a random location somewhere in the WorldGuard region named "region1" on whatever world the player is on. Since WorldGuard regions are defined per-world, this strategy will do nothing if the region doesn't exist. You can specify a specific world/region combo using the notation "world;region1".
• spawnWorldRandom:world (v1.6): the argument is not required, if no argument is given it will spawn the player at a completely random location in their current world. If the arg is given, it will spawn them at a completely random location in the world given. HSP automatically ties into WorldBorder to keep the spawned location within the border. If WorldBorder is not installed, HSP just defaults to +/- 1000 x/z.
• spawnLocalPlayerSpawn (v1.7): HSP can be instructed to remember where a player spawned using the modeRememberSpawn or modeRememberLocation modes. For example, if you have new players randomly assigned 1 of 4 spawns, modeRememberSpawn will remember it and then you can use this strategy to send a player to their remembered spawn. There can be one remembered spawn per player per world.
• spawnLastLocation (v1.7): HSP always remembers the lastLocation a person was at when they leave a world (one location per world). This strategy can be used to send a player to that location. This could be useful for crossWorld events, or even a custom "/lastloc" command. See custom commands for an example.

Advanced mode modifiers

These modes will change the way other strategies work. Modes are exclusive in that when you turn it on, it deletes any other active modes. Modes that do not behave like this (and therefore work in combination with modes already set) are listed as ADDITIVE. Note that if you are trying to use an additive mode (such as modeRequiresBed) along with an exclusive mode (such as modeHomeBedOnly), list the exclusive mode first otherwise it will reset the additive mode when it fires.

• modeDefault: (previously "modeHomeNormal", which also still works) this is the "default" mode in which the meaning of rules in not changed at all. This is provided so that an admin can switch back to default Mode after first trying some rules under a different mode.
• modeEffect:effect (v2.0): This mode can be used to display effects when players teleport. Since there are more options than can fit in this short description, this mode has it's own documentation page.

• modeHomeBedOnly: all subsequent rules [until the next mode rule] will only consider a home set by bed clicking
• modeHomeNoBed: all subsequent rules [until the next mode rule] will NOT select a home set by a bed
• modeHomeDefaultOnly: all subsequent rules [until the next mode rule] will only consider the default home
• modeHomeAny: all subsequent rules [until the next mode rule] will function for ANY home. For example, 'homeLocalWorld' normally only finds the "default" home on the local world, with this mode applied, it would find ANY home on the local world.
• modeRequiresBed: (ADDITIVE mode) This mode requires that a bed be within 5 blocks of any home in order for that home to be used.
• modeDistanceLimits:min;max (v1.7.3): This mode requires the target location be within the distance specified in order to be allowed. This can be used to only let players spawn if their home is within 0-100 blocks away, for example. Ticket #138. This was primarily targeted and tested to work with Home-related strategies, but should generically work with other strategies as well.

• modeRememberSpawn (v1.7): (ADDITIVE mode) This mode will "remember" any following Spawn-related event for this player. The remembered spawn can be used by spawnLocalPlayerSpawn later to send the player back to this location. This remembers the spawn by name, so if you move the spawn later (such as changing faction spawns), the "remembered" spawn will move with.
• modeRememberLocation (v1.7): (ADDITIVE mode) This mode will "remember" ANY location from this event chain. This is different from modeRememberSpawn in 2 ways. First, it can be used to remember non-spawn locations, such as a spawnWorldRandom strategy. Second, unlike modeRememberSpawn which remembers the spawn NAME and will move if you move that named spawn, this mode remembers the exact location and will never move. Both modes have their uses, so pick the one that matches what you want to do.
• modeYBounds:minY;maxY (v1.6.1): (ADDITIVE mode) This mode affects safe teleport (if you have enabled it) and random spawn behavior by controlling the min and max Y bounds. If you just specify one number, it is taken as minY. This could allow you to keep random spawns at or above water level, for example.
• modeNoWater (v1.6.1): (ADDITIVE mode) This mode affects safe teleport behavior (if you have enabled it) to not allow teleporting over water. Random spawns also work hard to avoid spawning over water if this mode is enabled.
• modeNoLilyPad (v1.6.1): (ADDITIVE mode) This mode affects safe teleport/random spawn behavior to not allow spawning over lilipads.
• modeNoIce (v1.6.1): (ADDITIVE mode) This mode affects safe teleport/random spawn behavior to not allow spawning over ice.
• modeNoLeaves (v1.6.1): (ADDITIVE mode) This mode affects safe teleport/random spawn behavior to not allow spawning over leaves. Helpful for keeping random spawns out of trees.
• modeSourceWorld:myworld (v1.7): This mode can be used in crossWorldTeleport events and it will prevent any strategies from running unless the source world of the teleport was myworld. This can be used to do something when a player leaves a specific world, or even combined with per-world strategies to do something specific when a player goes from one world to another.

Multiverse-specific strategies

• modeMultiverseSourcePortal:portalName (v1.7): This mode will not let any other strategies fire unless the source portal was portalName. See Example7 for a detailed example.
• modeMultiverseDestinationPortal:portalName (v1.7): This mode will not let any other strategies fire unless the destination portal is portalName. See Example7 for a detailed example.

WorldGuard-specific strategies

• modeInRegion:myregion (v1.7): This mode will not let any other strategies fire unless the player location is in WorldGuard region myregion. See Example7 for a detailed example.