Introduction

This plugin brings hide and seek to Minecraft servers running Spigot/PaperMC or Fabric. Its focus is to bring a full hide and seek experience with lots of customization options.

Expand the sidebar to view installation instructions and a guide for using Kenshin’s Hide and Seek.

Installation

To install Kenshin’s Hide and Seek (KHS), first get a working Minecraft server that is supported by the plugin. The following server softwares are suported.

Spigot/Paper

Only the official JARs distributed by Spiggot or Paper are supported. Any forks of either of these server softwares are not expection to have perfect functionality.

Download the plugin from Spigot or Modrinth and place the JAR inside the servers plugins/ folder.

Configuration files will be found in plugins/KenshinsHideAndSeek.

Dependencies

The only required dependency for bukkit server software is PacketEvents.

bStats

KHS on bukkit server software uses bStats for metrics. You can disable bStats on the server to not have this information collected. See bStats privacy policy.

Fabric

Warning

Fabric support is currently marked as experimental. Expect to find bugs or other issues.

Download the mod from Modrinth and place the JAR into the servers mods/ folder.

Configuration files will be found in config/khs.

Dependencies

The following mods are required for KHS to function: PacketEvents, Fabric Langauge Kotlin, Fabric API, and Architectury.

Setup

Before players are able to even join the plugin’s game lobby, a map must first be created and setup.

Creating a map

A map is a space in which the game is played in. To create a map run /hs map add <name> <world>.

Spawn points

Each map needs its own lobby, seeker spawn, and hider spawn. To set these run the following commands at the location of the spawn point.

/hs map set lobby <name> - is where players wait for the round to start for that map
/hs map set seekerlobby <name> - is where seekers wait to join or during death cooldown till they spawn/respawn into the game
/hs map set spawn <name> - is where everyone spawns into the map.

Because the seeker lobby is where seekers wait, it’s important to make it a closed off space and not have a view to the map itself. Otherwise, seekers could start attacking early, or watch where the hiders go hide.

Bounds

Map bounds are a square bounding box that must contain the map, global spawn, and seeker lobby. This is used to contain all players and spectators in the game. To set the bounds run /hs map set bounds <name> in two opposite corners of the map. You will see that the bounds is set to (1/2), then (2/2). If the bounds are set to the wrong positions, running the command again will repeat the (1/2), and (2/2) steps.

Map save

The plugin saves a copy of the map to play on so that original doesn’t get modified. Otherwise, a player can open the doors, mess with redstone, or other actions that would stay persistant.

Map saves may be disabled with the mapsvae option in the config if rollback functionality is not wanted. If disabled, this section should be ignored.

To start a map save, make sure spawn points and bounds are already set, then run /hs map save <name> and the map will be saved.

Warning

Commands cannot be run while a map save is in progress.

Warning

The map save must be re-run every time changes are made to the source map.

Finally

To check if a map passes all checks run /hs map status <map>, and it will state if all checks pass or what checks failed. Only maps that pass all checks will be added into the map pool.

If this is the first map made, a global exit must be set before any gameplay can begin. This is where all players go when they leave the game. This can be set by running /hs setexit at the wished exit position.

Run /hs join to join the lobby. /hs start to start the game. /hs leave to leave the game!

Types

The following are the types used within the configuation files of the plugin.

Primitives

type	description	example
int	An integer number.	-3
uint	An positive integer number.	7
long	A large integer number.	-2147483649
ulong	A large positive integer number.	4294967326
bool	Either `true` or `false`.	true
decimal	A decimal floating point number.	1.2
string	A string of text.	“example”
list	A list of a type, if not specified it will be a list of strings.	[“example”]

Some types will be marked as optional. This just means that they don’t need to be specified. Setting these values as null is the same as not specifying them. When not set, they may be removed from the configuation file upon plugin reload.

Map

A map is a mapping from a key to a value. A map has a type for its key, and a type for its value. These docs will show map as map<key,value> where key and value are the types.

An eample map is shown below. This map is from string to uint. Note the two space indentation.

enchantments:
  knockback: 7
  sharpness: 3

Item

An item type represents a physical item given to players that is held in their inventory.

name	description	type	default
name	The name of the item.	optional string	null
material	The material/type of the item. If invalid the item will not be given to the player.	string	“BLOCK”
lore	Lore to be shown when hovering over the item.	list	[]
enchantments	Map of enchantment names to their level.	map<string, int>	{}
unbreakable	If the item has unlimited durabality.	optional bool	null
modelData	The block data field used in minecraft versions prior to 1.13.	optional uint	null
owner	The owner of skull given the item is a skull.	optional string	null
effect	The potion effect given the item is a potion.	optional string	null
slot	The inventory slot this item will always be put in. If not set it will be put in the net availiable slot.	optional uint	null

Effect

A potion effect that will be applied to players depending on the situation.

name	description	type	default
type	The type of potion effect.	string	“NONE”
duration	The length in seconds that the effect will last.	uint	60
amplifier	The amplifier of the potion effect.	uint	1
ambient	Marks the surrounding particles as semitransparent and less visually intrusive.	bool	true
particles	Hides the surrounding particles.	bool	true

Config

This section is for the config.yml file.

The config.yml file contains all the general settings for the plugin, ranging from player count to active game mode. Each option is listed below along with its default value, type, and description for that setting. Information for all of these settings will also be stated in the config.yml file.

General

name	description	type	default
checkForUpdates	Check for updates on server startup, and notify players with the `hs.admin` permission.	bool	true
dropItems	Allow players to drop their items mid-game.	bool	false
countdownDisplay	Where the plugin will state the length of time in seconds left to hide. Allowed values are CHAT, ACTIONBAR, or TITLE.	enum	CHAT
nametagsVisible	Allow hiders’ to see everyone’s nametags. Seekers’ can never see nametags.	bool	false
permmissionsRequired	Require players to have permissions to run commands.	bool	true
startingSeekerCount	Amount of initial seekers when teh game starts, minimum of 1.	uint	1
respawnAsSpectator	Respawn dead hiders as spectators instead of seekers.	bool	false
gameOverTitle	Display a title describing the game over along with the chat message.	bool	true
blockHuntNotify	Notify a seeker when the undisguise a hider in block hunt.	bool	true
debug	Show plugin debug output in the server console.	bool	false

Spectator items

Part of sub-section spectatorItems.

name	description	type	default
flight	The item a spectator can use to toggle flight.	item
teleport	The item a spectator can use to teleport to other hiders or seekers.	item

Seeker ping

Part of sub-section seekerPing.

name	description	type	default
enabled	Play a ping sound when seekers’ get too close to a hider.	bool	true
distances.level1	Seekers this distance from the hider cause a low-intensity ping noise.	uint	30
distances.level1	Seekers this distance from the hider cause a medium-intensity ping noise.	uint	20
distances.level1	Seekers this distance from the hider cause a high-intensity ping noise.	uint	10
sounds.heartbeatNoise	The heartbeat noise that speeds up the closer seekers get.	sound	basedrum
sounds.ringingNoise	The ringing noise that plays when a seeker is very close (level3).	sound	pling
sounds.leadingVolume	The volume used for the first note of the ping noise.	decimal	0.5
sounds.volume	The volume used for the rest of the ping noise.	decimal	0.3
sounds.pitch	The pitch of the ping noise.	decimal	1.0

Timing

name	description	type	default
gameLength	How long in seconds wil the game last, set to 0 to make the game length infinite.	ulong	1200
hidingLength	How long in seconds will the initial hiding period last, minimum is 10 seconds.	ulong	30
endGameDelay	How long in seconds the game will wait until the it teleports players to the lobby after a game over is triggered.	ulong	5

Delayed respawn

Part of sub-section delayedRespawn.

name	description	type	default
enabled	Seekers will have to wait [delay] seconds until they respawn after death.	bool	true
delay	How long in secodns dp player shave to wait in seconds before respawning.	uint	5

Database

The database is used to save persistant game information such as player names, and how many wins/losses a player has.

There are three supported database types: SQLITE, MYSQL, and POSTGRES. When using SQLITE which is the default, all other arguments besides type should be ignored as SQLITE is not a remote databse. Remote database arguments only matter for MYSQL or POSTGRES.

It is recommended to stick with SQLITE for most setups as no work is needed to be done by the server admins. But given a multi-server setup, a remote database is recommended to have shared data between the servers.

Database

Part of sub-section database.

name	description	type	default
type	The type of database to store user data in.	enum	SQLITE
host	The hostname of the remote database server.	string	localhost
port	The port of the remote database server.	optional ulong	null
username	The username to connect with to the remote database server.	string	postgres
password	The password to connect with to the remote database server.	string	postgres
database	The name of the database to connect to on the remote database server.	string	postgres

Game mode

There currently are two supported game modes: HIDE_AND_SEEK and TAG.

When playng HIDE_AND_SEEK, the two available scoring modes are: ALL_HIDERS_FOUND, or LAST_HIDER_WINS.

name	description	type	default
gameMode	The game mode that the plugin will operate under.	enum	HIDE_AND_SEEK
scoringMode	The scoring mode decides the hider win condition for the HIDE_AND_SEEK game moed only.	enum	ALL_HIDERS_FOUND
dontRewardQuit	End the game abruptly without updating any scores if a player leaving the game causes a game over.	bool	true

PvP

name	description	type	default
pvp	Seekers must kill hiders to “find” them. Hiders are able to attack seekers to protect themselves.	bool	true
regenHealth	Allow players to regenate health.	bool	false
allowNaturalCauses	Hiders and Seekers can no longer take damage from natural causes such as fall damage or projectiles.	bool	false

Lobby

name	description	type	default
autoJoin	Players will auto join the game lobby upon joining the server.	bool	false
teleportStraysToExit	Players will be teleported to the plugin’s exit position if they join the server and are located in a game world.	bool	false
leaveType	`EXIT` will teleport players to the plugin’s exit position upon leaving the game. `PROXY` will instead teleport them to the `leaveOnEnd` server.	enum	EXIT
leaveServer	The bungeecord/velocity server players will teleport to upon a leave when leaveType is set to `PROXY`.	string	“lobby”
leaveOnEnd	All players will always leave the game upon a game over.	bool	false
saveInventory	Restore the players previously cleared inventory after leaving the game.	bool	false
saveScoreBoard	Restore the players previously active score board after leaving the game.	bool	true

Lobby

Part of sub-section lobby.

name	description	type	default
countdown	Time in seconds the lobby waits until the game starts. Set to 0 to disable.	ulong	60
chagneCountdown	Player threshold to speed up the countdown to 10 seconds. Set to 0 to disable.
min	Minimum amount of players required to start the countdown.	uint	3
max	Maximum amount of players allowed in the lobby.	uint	10
leaveItem	Item used by players to leave the lobby.	item
startItem	Item used by admins to manually start the game.	item

Events

Taunt

Part of sub-section taunt.

name	description	type	default
enabled	If the taunt event is enabled.	bool	true
delay	Time in esconds between taunts, minimum is 60 seconds.	ulong	360
disableForLastHider	Don’t taunt when there is only one hider left.	bool	false
showCountdown	Allow seekers to see the time till next taunt, not just hiders.	bool	true

Power-ups

Glow

Part of sub-section glow.

name	description	type	default
enabled	If the glow power-up is to be given to hiders.	bool	true
time	The length in seconds that the power-up lasts.	ulong	30
stackable	Allows multiple uses of the power-up to stack the duration instead of resetting the timer.	bool	true
item	The item hiders use to activate the power-up.	item

Protections

name	description	type	default
mapSaveEnabled	Duplicate copes of maps to their own world to protect the original from changes during the game. The plugin will rollback the map save after gameplay.	bool	true
blockedCommands	Commands players are not allowed to run during gameplay.	list
blockedInteracts	Blocks players are not allowed to interact with during gameplay.	list

Command hooks

Trigger custom commands after game events.

Command hooks

Part of sub-section commandHooks.

name	description	type	default
enable	The plugin will eecute the hook commands for each player.	bool	false
onGameStart	List of commands to execute for each player upon starting the game.	list	[]
onGameEndWin	List of commands to execute for each winning player.	list	[]
onGameEndLoose	List of commands to execute for each loosing player.	list	[]

Items

Items and potion effects given to hiders and seekers when they spawn into the game.

Hider items

name	description	type	default
hiderItems	A list of items given to hiders upon spawning in.	list<item>
hiderHelmet	The helmet given to hiders.	optional item	null
hiderChestplate	The helmet chestplate to hiders.	optional item	null
hiderLeggings	The helmet leggings to hiders.	optional item	null
hiderBoots	The helmet boots to hiders.	optional item	null

Seeker items

name	description	type	default
seekerItems	A list of items given to seekers upon spawning in.	list<item>
seekerHelmet	The helmet given to seekers.	optional item	leather helmet
seekerChestplate	The helmet chestplate to seekers.	optional item	leather chestplate
seekerLeggings	The helmet leggings to seekers.	optional item	leather leggings
seekerBoots	The helmet boots to seekers.	optional item	leather boots

Hider effects

name	description	type	default
hiderEffects	Effects hiders are given at the start of the round.	list<effect>

Seeker effects

name	description	type	default
seekerEffects	Effects seekers are given at the start of the round and when the respawn.	list<effect>

Board

Lobby

Part of sub-section lobby.

The following values can be used within the template. Values can be used within the template by typing {NAME} where NAME is the name of the template value.

name	description
COUNTDOWN	Time left until game start, or a message that there is not enough players.
COUNT	Number of players currently in the lobby.
SEEKER%	Percentage change that the player will be a seeker next game.
HIDER%	Percentage change that the player will be a hider next game.
MAP	The current map the lobby is in.

Change what is displayed on the scoreboard/leaderboard while in the lobby.

name	description	type
title	The title of the scoreboard.	string
content	The template to generate the scoreboard from.	string

Game

Part of sub-section game.

The following values can be used within the template. Values can be used within the template by typing {NAME} where NAME is the name of the template value. If a template value is toggable, any lines with that value will be removed from the scoreboard if the action/event associated with that value is disabled.

name	description	toggable
TIME	Time left in seconds until the game ends.	false
TEAM	The team the player is currently on.	false
BORDER	The current status of the world border event.	true
TAUNT	The current status of the taunt event.	true
GLOW	The current status of the glow power-up.	true
#SEEKER	The current number of seekers in the game.	false
#HIDER	The current number of hiders in the game.	false
MAP	The current map the lobby is in.	false

Chant what is displayed on the scoreboard/leaderboard while playing the game.

name	description	type
title	The title of the scoreboard.	string
content	The template to generate the scoreboard from.	string

Countdown

Part of sub-section countdown.

name	description	type
waiting	Text displayed when the lobby is waiting for more players.	string
startingIn	Text displayed when the lobby is starting in some seconds.	string
timer	How many minutes and seconds until game end.	string

Taunt

Part of sub-section taunt.

name	description	type
timer	How many minutes and seconds until the next taunt.	string
active	Text shown when a player is about to be taunted.	string

Glow

Part of sub-section glow.

name	description	type
active	Text shown when the glow poer-up is active.	string
disabled	Text shown when the glow poer-up is inactive.	string

Border

Part of sub-section border.

name	description	type
timer	How many minutes and seconds until the world border shrinks.	string
shrinking	Text shown when the world border is shrinking.	string

Locale

The locale.yml file contains all the locale strings used for player messages, titles, or other ways of communicating to the player. KHS does not support any given language, instead it provides the locale configuration file to allow players to change the language strings to fit their play style, or language if required.

Localization strings may be automatically reset upon plugin updates due to changes in the default language string.

Hide and Seek

Hide and seek is the default and original game mode of the plugin. Hiders have some amount of time to hide, then seekers must spend the remaning game time to go find them. Any hiders found will become seekers and are tasked to find the remaning hiders.

All hiders found

When this is set as the scoring mode, the game will not end until the timer runs out, or every last hider has been found by the seekers. Either the remaning hiders get a win, or the initial seekers.

Last hider wins

When this is set as the scoring mode, the game will not end until the timer runs out, or there is a single hider left. On game end, the initial seekers and last hider are the winners.

Tag

Tag is the newest game mode added to KHS version v2.3.0. Instead of hiders becoming seekers joining the team to find other hiders, instead players swap teams. When a seeker “finds” a hider, the hider swaps to a seeker andis respawned while the seeker swaps to being a hider.

Winning

A player wins at the tag gamemode when they are still a hider once the game timer ends. Only players who joined at the start of the game will be considered.

Block hunt

Note

Block hunt is not supported on Minecraft 1.8.

Block hunt is not necessarily a game mode itself, but an extension of the other game modes. When enabled on a map, hiders will be prompted to disguise as a block. If hit or moved, the block will become undisguised and will be visible to other hiders or seekers. If stationey for a period of time, the block will solidify and will blend in with the environment. The rest of the game runs as it normally would.

Spiggot/PaperMC servers use falling sand as the undisguised block while Fabric uses display entities. This doesn’t matter for gameplay, but it’s to be noted.

Note

Players disguised can see their own player character but other players will not be able to.

Setup

Block hunt is enabled on a per-map basis, and is disabled by default. To enable or disable block hunt on a map, run /hs map blockhunt enabled <map> <true/false>.

For a map to pass all checks, it must have at least one block in its blockhunt selection. To add or remove blocks run, /hs map blockhunt block <add/remove> <map> <block>. To list a map’s blocks run /hs map blockhunt block list <map>.

Glow power-up

Note

Glow is not supported on Minecraft 1.8.

Warning

The glow effect is only visiable as far as the servers entity distance allows. Make sure to increase the servers entity distance for best effects.

Hiders each game will automatically be given a power-up orb that they can use to activate the glow power-up for all hiders. When active, all seekers will have a glow effect displayed around them that all hiders can see, Seekers cannot see the glow effect when hiders use the power-up. The power-up can be used once, per hider, per game.

Taunt

A taunt is a firework rocket spawned at the position of a random hider at a configured interval. The firework “taunts” the seekers to the hiders position. Since the taunt is a firework, it can damage the hider.

Once the configured taunt interval is reached, a notice will be sent out to all players that a random hider will be taunted in 30 seconds. The random hider will also be notified that they will soon be taunt. A hider cannot be taunted twice in a row.

Border

Warning

The border event uses the maps global world border. There should not be anything else going on in the world the game is in with the border event enabled or it will affect players not in the game.

The border is shrinking field of play that gets smaller and smaller as the game progresses.

The border is enabled on a per-map basis. To enable to border on a map run. /hs map set border <map> <size> <delay> <move>. To disable the border run /hs map unset border <map>.

The position of the world border will be set to the position of the player that run /hs map set border.

Values

These are the values that are passed in to the /hs map set border command.

Note

The delay in seconds does not include the 30 seconds the border takes to shrink each interval.

name	description	type
map	The name of the map to enable the border on.	string
size	The size that the world border starts at in block radius.	uint
delay	The length on seconds the border spends between shrinking.	uint
move	The amount of blocks the border shrinks each interval.	uint

Commands

This is a reference of all commands in the plugin.

Command arguments that start with an * are optional.

Permissions

All commands have auto generated permissions based on their command string. For example command /hs map set border has the permission hs.map.set.border.

`/hs confirm`

Confirm an action that the plugin required confirmation for.

`/hs debug`

Opens up a debug menu for the plugin.

`/hs help`

Arguments: *page.

Messages the player a page of the help menu.

`/hs join`

Arguments: *map.

Join the game lobby. If map is specified and the game lobby is empty, start the game lobby at that map.

`/hs lastgame`

Show win/loose information from the last game played.

`/hs leave`

Leave the game lobby.

`/hs map add`

Arguments: name, world.

Create a map with a given name that will be located in a given world.

`/hs map blockhunt block add`

Arguments: map, block.

Add a block to the pool that hiders can disguise themselves as in a blockhunt enabled map.

`/hs map blockhunt block list`

Arguments: map.

List blocks that hiders can disguise themselves as in a given map.

`/hs map blockhunt block remove`

Arguments: map, block.

Remove a block from the pool that hiders can disguise themselves as in a blockhunt enabled map.

`/hs map blockhunt debug`

Arguments: map.

Open up the blockhunt picker for a given map.

`/hs map blockhunt enabled`

Arguments: map, enabled.

Enable or disable blockhunt on a given map.

`/hs map goto`

Arguments: map, spawn.

Goto the lobby, seekerlobby, or spawn of a given map.

Warning

If map save are enabled, spawn or seekerlobby will be located in the map save copy of the map, not the source map.

`/hs map list`

List the maps available to the plugin and if each map is setup.

`/hs map remove`

Arguments: map.

Remove the given map from the plugin.

`/hs map save`

Arguments: map.

Initiate a map-save for a given map.

Warning

Commands cannot be run while a map save is in progress.

`/hs set border`

Arguments: map, size, delay, move.

Set the maps world border to the command executors current position, with a given size. The border will shrink every delay seconds by move blocks.

`/hs map set bounds`

Arguments: map.

Sets one of the two opposite corners of the maps bounds.

`/hs map set lobby`

Arguments: map.

Sets the position of the maps lobby spawn.

`/hs map set seekerlobby`

Arguments: map.

Sets the position of the maps seeker lobby spawn.

`/hs map set spawn`

Arguments: map.

Sets the position of the maps game spawn.

`/hs map status`

Arguments: map.

Run checks to see if a map is fully setup.

`/hs map unset border`

Arguments: map.

Disable the border for a given map.

`/hs reload`

Reload the plugins configuration.

`/hs send`

Arguments: map.

Send the games lobby to a different map.

`/hs setexit`

Sets the plugins global exit position.

`/hs start`

Arguments: *player…

Manually starts the game. An optional list of players may be specified to be the initial seekers.

`/hs stop`

Manually stop the game.

`/hs top`

View the global win leaderboard for the plugin.

`/hs wins`

Arguments: *player.

View the win and gameplay information for a given player. If the player argument is not set, the command instead shows the information for the player running the command.

`/hs world create`

Arguments: name, type, isFlat.

Create a new miencraft world on the server with a given type and if the world is flat.

`/hs world delete`

Arguments: name.

Delete a custom map from the minecraft server.

`/hs world list`

List all available worlds to the minecraft server.

`/hs world tp`

Arguments: name.

Teleport to the spawn point of a given world.

Placeholders

This plugin supports software such as PlaceholderAPI.

A placeholder is a string such as %hs_team%, which in this case returns what team the player is on.

Teams

The following teams: hiders, seekers, and spectators can be used in %hs_<team>% to get the number of players currently in that team.

Also %hs_team% returns the players current team.

Rankings

The valid player statistics are:

wins, hiderWins, seekerWins
losses, hiderLosses, seekerLosses
games, hiderGames, seekerGames
kills, hiderKills, seekerKills
deaths, hiderDeaths, seekerDeaths

To get the RANK of a statistic for a target use:

%hs_rank_<stat>_<target>%

When target is not set, it returns the subject players integer rank
When target is a player name/uuid, it returns the targets integer rank
When target is an integer rank, it returns the player name at that rank

Examples:

%hs_rank_wins%
%hs_rank_deaths_KenshinEto$
%hs_rank_games_1%

Stats

To get the VALUE of a statistic for a target use:

%hs_stat_<stat>_<target>%

When target is not set, it returns the subject players stat value
When target is a player name/uuid, it returns the stat value for that player
When target is an integer rank, it returns the stat value at that ranking place (1st/2nd/3rd/…)

Examples:

%hs_stat_wins%
%hs_stat_deaths_KenshinEto$
%hs_stat_games_1%

Last Winners

The following placeholders return information about the last game played.

%hs_win_<team>_<index>% - Returns list of winners %hs_loose_<team>_<index>% - Returns liust of loosers

When team is set, it will only return players in that list that are in the given team
When index is setm it will return the player at the list at the given index. The index starts at zero.

Examples:

%hs_last_win%
%hs_last_win_seeker%
%hs_last_win_hider%
%hs_last_win_hider_0%
%hs_last_loose%
%hs_last_loose_hider_2%

Keyboard shortcuts

Kenshin's Hide and Seek