net.risingworld.api

Interface Server

public interface Server

Represents the server object. This is basically the "core element", it will be used to control everything related to the game context.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Server.Type The server type

Method Summary

Modifier and Type	Method and Description
void	addArea(Area area) Adds an Area to the server.
void	banPlayer(long playerUID, java.lang.String reason, int duration) Bans the player with the specified UID for a given amount of time.
void	broadcastTextMessage(java.lang.String message) Broadcasts a text message, i.e. send it to all players.
void	broadcastYellMessage(java.lang.String message) Broadcasts a yell message, i.e. send it to all players.
Player	findNearestPlayer(Vector3f position) Gets the player who has the shortest distance to a world position.
java.util.Collection<Area>	getAllAreas() Gets a collection containing all Areas that are currently registered with the server.
java.util.Collection<CustomImage>	getAllCustomImages() Gets a list containing all custom images (creates a new list).
java.util.Collection<CustomImage>	getAllCustomImages(long playerUID) Gets a list containing all custom images which were uploaded by a particular player.
java.util.Collection<java.lang.String>	getAllPermissionGroups() Gets all available permission group names.
java.util.Collection<Player>	getAllPlayers() Gets a collection containing all players that are currently connected to the server.
int	getBuild() Gets the current build of the game as an int (e.g. 201807210).
Weather	getCurrentWeather() Gets the current weather.
CustomImage	getCustomImage(int id) Gets a custom image.
CustomItem	getCustomItem(java.lang.String uuid) Gets the registered custom item with the specified UUID.
CustomRecipe	getCustomRecipe(java.lang.String targetUUID, int targetVariation) Gets the custom recipe which corresponds to the provided item UUID and variation.
Inventory	getDefaultSpawnInventory() Gets the default spawn inventory (i.e. the items you always spawn with).
Vector3f	getDefaultSpawnPosition() Gets the global default spawn position.
Quaternion	getDefaultSpawnRotation() Gets the default spawn rotation.
Time	getGameTime() Gets the internal time object which manages the ingame time and date.
int	getGameTime(Time.Unit unit) Gets the current ingame time.
float	getGameTimeSpeed() Gets the game time speed.
java.lang.String	getIP() Gets the server ip.
int	getMaxPlayerCount() Gets the maximum amount of players allowed on this server.
java.lang.String	getName() Gets the server name.
Weather	getNextWeather() Gets the next weather type.
java.lang.String	getOption(java.lang.String key) Gets a server option from the "server.properties" file.
Player	getPlayer(int playerid) Gets a player object representing the player with the provided playerid.
Player	getPlayer(long playerUID) Gets a player object representing the player with the provided unique ID (for Steam users, this is the SteamID64).
Player	getPlayer(java.lang.String playername) Gets a player object representing the player with the provided playername.
int	getPlayerCount() Gets the amount of players that are currently connected to this server.
int	getPort() Gets the server port.
float	getRunningTime() Gets the amount of seconds that have passed since serverstart.
long	getSteamID() Gets the SteamID64 of the server.
Server.Type	getType() Gets the current type of the server.
java.lang.String	getVersion() Gets the current game version as a String (e.g. "0.9.1.5").
float	getWeatherTransition() Gets the transition between the current weather type (0.0) and the next weather type (1.0).
boolean	isPassworded() Gets whether or not this server is password protected.
boolean	isPlayerAdmin(long playerUID) Gets whether the particular player is an admin or not.
boolean	isPlayerBanned(long playerUID) Gets whether the particular player (who has the provided UID) is banned or not.
boolean	isPlayerConnected(int playerid) Gets whether or not this player is connected to the server.
boolean	isPlayerConnected(java.lang.String playername) Gets whether or not this player is connected to the server.
boolean	isSteam() Gets whether or not this is a Steam server.
boolean	isWeatherEnabled() Gets whether or not the weather is enabled.
void	registerCustomItem(CustomItem item) Registers a new custom item.
void	registerCustomRecipe(CustomRecipe recipe) Registers a new custom crafting recipe.
void	removeArea(Area area) Removes an Area that has been added to the server previously.
void	removeCustomImage(int id) Deletes a custom image (and also removes all placed instances in the world).
void	saveAll() Forces the server to save all pending changes (world, players, npcs, storages etc).
void	saveNpcs() Forces the server to save all npcs.
void	savePlayers() Forces the server to save all players and inventories.
void	saveStorages() Forces the server to save all storages (chests etc).
void	sendInputCommand(java.lang.String input) Sends an input command to the InputStream (System.in) of the server.
void	setDefaultSpawnInventory(Inventory inventory) Sets the default spawn inventory (i.e. the items you always spawn with).
void	setDefaultSpawnPosition(float x, float y, float z) Sets the global default spawn position.
void	setDefaultSpawnPosition(Vector3f position) Sets the global default spawn position.
void	setDefaultSpawnRotation(float pitch, float yaw, float roll) Sets the default spawn rotation.
void	setDefaultSpawnRotation(Quaternion quaternion) Sets the default spawn rotation.
void	setGameTime(int hour, int min) Sets the ingame time.
void	setGameTimeSpeed(float value) Changes the game time speed.
void	setWeather(Weather newWeather, boolean instant) Sets the weather.
void	setWeatherEnabled(boolean enabled) Enables or disables the weather.
void	shutdown() Forces the server to shutdown gracefully.
void	unbanPlayer(long playerUID) Unbans the player with the specified name (i.e. removes him from the ban list).

Method Detail

getType

Server.Type getType()

Gets the current type of the server. Sometimes it's useful to find out if this server is currently a singleplayer server or a dedicated server (more precisely, it indicates if this plugin is executed in a singleplayer or multiplayer environment).

Returns:

the current server type.

isSteam

boolean isSteam()

Gets whether or not this is a Steam server. In most cases this returns true, unless this is a LAN or singleplayer session of the standalone version of the game.

Returns:

true if this is a Steam server, false if not.

See Also:

getSteamID()

getSteamID

long getSteamID()

Gets the SteamID64 of the server. This only works if this is a Steam server, otherwise this method returns -1. If this is an integrated Steam servers (e.g. singleplayer, P2P or LAN), the SteamID of the host user is returned.

Returns:

the SteamID64 of the server, or -1 if this isn't a Steam server.

See Also:

isSteam()

getName

java.lang.String getName()

Gets the server name.

Returns:

the name of the server.

getIP

java.lang.String getIP()

Gets the server ip.

Returns:

the ip of the server.

getPort

int getPort()

Gets the server port.

Returns:

the port of the server.

isPassworded

boolean isPassworded()

Gets whether or not this server is password protected.

Returns:

true if players have to enter a password to enter the server, false if not (default).

getRunningTime

float getRunningTime()

Gets the amount of seconds that have passed since serverstart.

Returns:

the running time of the server (in seconds).

Example: Shutdown server when it's running for more than 24 hours

1	//Global flag somewhere in order to make sure that the shutdown
2	//procedure is only triggered once
3	public boolean shuttingdown = false;
4
5	//Somewhere in the code (e.g. inside an update method)...
6	Server server = getServer();
7
8	//24 hours == 86400 seconds
9	float runningtime = server.getRunningTime();
10
11	//Make sure "shuttingdown" hasn't been set yet
12	if(!shuttingdown && runningtime > 86400){
13	shuttingdown = true;
14
15	//Send a shutdown text and yell notification to all players
16	server.broadcastTextMessage("[#FF0000]WARNING: Server will shutdown in 1 minute!");
17	server.broadcastYellMessage("WARNING\nServer will shutdown in 1 minute");
18
19	//Create a timer which only triggers once after 1 minute (60 seconds)
20	Timer timer = new Timer(0, 60f, 0, () -> {
21	//Save all
22	server.saveAll();
23
24	//Shutdown server (this does not restart the server!)
25	server.shutdown();
26	});
27
28	//Start the timer (simply creating a timer does not start it automatically)
29	timer.start();
30	}

getOption

java.lang.String getOption(java.lang.String key)

Gets a server option from the "server.properties" file.
Note: This method cannot be used to retrieve passwords or login names.

Parameters:

key - the name of the option key.

Returns:

a string representing the value, or null if the key was not found.

Example: Determine if pvp is enabled (setting "settings_pvp_enabled")

1	Server server = getServer();
2	String pvp = server.getOption("settings_pvp_enabled");
3	if(pvp.equals("true")){
4	System.out.println("PVP is enabled");
5	}
6	else{
7	System.out.println("PVP is disabled");
8	}

getAllPermissionGroups

java.util.Collection<java.lang.String> getAllPermissionGroups()

Gets all available permission group names.

Returns:

a collection containing all permission group names.

getVersion

java.lang.String getVersion()

Gets the current game version as a String (e.g. "0.9.1.5").

Returns:

the current game version.

getBuild

int getBuild()

Gets the current build of the game as an int (e.g. 201807210). The build number always contains the year, month and day as well as an incrementing number.

Returns:

the current build of the game.

See Also:

getVersion()

saveAll

void saveAll()

Forces the server to save all pending changes (world, players, npcs, storages etc).

savePlayers

void savePlayers()

Forces the server to save all players and inventories.

saveStorages

void saveStorages()

Forces the server to save all storages (chests etc).

saveNpcs

void saveNpcs()

Forces the server to save all npcs.

sendInputCommand

void sendInputCommand(java.lang.String input)

Sends an input command to the InputStream (System.in) of the server. This only works for the dedicated server.

Parameters:

input - the input command.

Example: Send chat message

1	server.sendInputCommand("say Hello World!");

shutdown

void shutdown()

Forces the server to shutdown gracefully. This takes ~ 10 seconds. If you want to shutdown the server immediately (without removing all connections gracefully), you can use System.exit(0); instead.

setDefaultSpawnPosition

void setDefaultSpawnPosition(Vector3f position)

Sets the global default spawn position.

Parameters:

position - the new spawn position.

setDefaultSpawnPosition

void setDefaultSpawnPosition(float x,
                             float y,
                             float z)

Sets the global default spawn position.

Parameters:

x - the new x coordinate.

y - the new y coordinate.

z - the new z coordinate.

getDefaultSpawnPosition

Vector3f getDefaultSpawnPosition()

Gets the global default spawn position.

Returns:

the spawn position as a Vector3f.

setDefaultSpawnRotation

void setDefaultSpawnRotation(Quaternion quaternion)

Sets the default spawn rotation. Provide Quaternion.IDENTITY if the spawn rotation should face towards north.

Parameters:

quaternion - the spawn rotation as a Quaternion.

setDefaultSpawnRotation

void setDefaultSpawnRotation(float pitch,
                             float yaw,
                             float roll)

Sets the default spawn rotation. Builds the rotation from euler angles.

Parameters:

pitch - pitch (euler x)

yaw - yaw (euler y)

roll - roll (euler z)

getDefaultSpawnRotation

Quaternion getDefaultSpawnRotation()

Gets the default spawn rotation.

Returns:

the default spawn rotation as a Quaternion.

setDefaultSpawnInventory

void setDefaultSpawnInventory(Inventory inventory)

Sets the default spawn inventory (i.e. the items you always spawn with).

Parameters:

inventory - the default spawn inventory.

getDefaultSpawnInventory

Inventory getDefaultSpawnInventory()

Gets the default spawn inventory (i.e. the items you always spawn with).

Returns:

the default spawn inventory.

setGameTime

void setGameTime(int hour,
                 int min)

Sets the ingame time.

Parameters:

hour - hours (0-23)

min - minutes (0-59)

Example: Set ingame time to 3:30 p.m. (15:30)

1	getServer().setGameTime(15, 30);

getGameTime

int getGameTime(Time.Unit unit)

Gets the current ingame time.

Parameters:

unit - the time unit you want to get (e.g. hours, minutes, days etc)

Returns:

the current ingame time.

Example:

1	//Get current minutes (0-59)
2	int minutes = server.getGameTime(Time.Minute);
3
4	//Get current hours (0-23)
5	int minutes = server.getGameTime(Time.Hour);

getGameTime

Time getGameTime()

Gets the internal time object which manages the ingame time and date.

Returns:

the internal time object.

setGameTimeSpeed

void setGameTimeSpeed(float value)

Changes the game time speed. The value represents the amount of realtime seconds one ingame minute should take (e.g. a value of 60 indicates that one ingame minute takes 60 realtime seconds).

Parameters:

value - the amount of realtime seconds one ingame minute should take.

Example: Plugin which sets realtime time speed (1 ingame min == 60 realtime seconds)

1	public class ExamplePlugin extends Plugin{
2
3	public void onEnable(){
4	Server server = getServer();
5	server.setGameTimeSpeed(60);
6	}
7
8	public void onDisable(){
9	//...
10	}
11
12	}

getGameTimeSpeed

float getGameTimeSpeed()

Gets the game time speed. Or more precisely, the amount of realtime seconds one ingame minute takes (e.g. a value of 60 indicates that one ingame minute takes 60 realtime seconds).

Returns:

the game time speed (realtime seconds -> ingame minutes)

setWeather

void setWeather(Weather newWeather,
                boolean instant)

Sets the weather.

Parameters:

newWeather - the new weather type.

instant - if set to true, the weather will change instantly. Otherwise, there will be a smooth transition between the current weather type and the new weather type.

Example: Set sunny weather forever

1	Server server = getServer();
2
3	//Disable weather (so it doesn't change automatically)
4	server.setWeatherEnabled(false);
5
6	//Change the weather to "clear" (sunny) with smooth transition
7	server.setWeather(Weather.Clear);

getCurrentWeather

Weather getCurrentWeather()

Gets the current weather.

Returns:

the current weather type.

getNextWeather

Weather getNextWeather()

Gets the next weather type. In other words, if the weather is changing, this function returns the next weather type. Otherwise, null will be returned.

Returns:

the next weather type, or null if the weather is currently not changing.

setWeatherEnabled

void setWeatherEnabled(boolean enabled)

Enables or disables the weather. If the weather is disabled, the current weather stays active until it will be changed manually. Note that if the weather is currently changing while calling this method, the transition will still be completed.

Parameters:

enabled - true to enable weather, false to disable it.

isWeatherEnabled

boolean isWeatherEnabled()

Gets whether or not the weather is enabled.

Returns:

true if the weather is enabled, false if not.

getWeatherTransition

float getWeatherTransition()

Gets the transition between the current weather type (0.0) and the next weather type (1.0). If the weather is currently not changing, this function always returns 0.0, otherwise a value between 0.0 and 1.0 will be returned.

Returns:

the transition interpolation value between the current and the next weather type. If the weather is currently not changing, this function always returns 0.0

getPlayerCount

int getPlayerCount()

Gets the amount of players that are currently connected to this server.

Returns:

the current amount of players.

getMaxPlayerCount

int getMaxPlayerCount()

Gets the maximum amount of players allowed on this server.

Returns:

the max amount of players that can play on this server simultaneously.

isPlayerConnected

boolean isPlayerConnected(int playerid)

Gets whether or not this player is connected to the server.

Parameters:

playerid - the player ID (not the database ID).

Returns:

true if the player is online, false if not.

isPlayerConnected

boolean isPlayerConnected(java.lang.String playername)

Gets whether or not this player is connected to the server.

Parameters:

playername - the name of the player.

Returns:

true if the player is online, false if not.

getPlayer

Player getPlayer(int playerid)

Gets a player object representing the player with the provided playerid. This function only works for players who are currently connected to the server.

Parameters:

playerid - the player ID (neither the database ID nor the unique ID)

Returns:

the player, or null if no player with the given ID was found.

getPlayer

Player getPlayer(long playerUID)

Gets a player object representing the player with the provided unique ID (for Steam users, this is the SteamID64). This ID never changes for this player. This function only works for players who are currently connected to the server.

Parameters:

playerUID - the unique player ID.

Returns:

the player, or null if no player with the given UID was found.

getPlayer

Player getPlayer(java.lang.String playername)

Gets a player object representing the player with the provided playername. This function only works for players who are currently connected to the server.

Parameters:

playername - the name of the player.

Returns:

the player, or null if no player was found.

getAllPlayers

java.util.Collection<Player> getAllPlayers()

Gets a collection containing all players that are currently connected to the server.
Do not modify the collection!

Returns:

a collection containing all players.

Example: Heal all broken bones

1	Server server = getServer();
2	//Iterate through all players
3	for(Player player : server.getAllPlayers()){
4	//Check if player has broken bones and heal it accordingly
5	if(player.hasBrokenBones()){
6	player.setBrokenBones(false);
7	}
8	}

isPlayerBanned

boolean isPlayerBanned(long playerUID)

Gets whether the particular player (who has the provided UID) is banned or not.

Parameters:

playerUID - the unique id of the player (for Steam users, it's the SteamID64).

Returns:

true if the player is banned, false if not.

isPlayerAdmin

boolean isPlayerAdmin(long playerUID)

Gets whether the particular player is an admin or not.

Parameters:

playerUID - the unique id of the player (for Steam users, it's the SteamID64).

Returns:

true if the player is an admin, false if not.

banPlayer

void banPlayer(long playerUID,
               java.lang.String reason,
               int duration)

Bans the player with the specified UID for a given amount of time.

Parameters:

playerUID - the unique id of the player you want to ban (for Steam users, it's the SteamID64).

reason - a string containing the reason why the player was banned.

duration - the duration (in minutes) how long the player will be banned. Use '-1' to ban the player permanently.

unbanPlayer

void unbanPlayer(long playerUID)

Unbans the player with the specified name (i.e. removes him from the ban list).

Parameters:

playerUID - the unique id of the player you want to unban (for Steam users, it's the SteamID64).

findNearestPlayer

Player findNearestPlayer(Vector3f position)

Gets the player who has the shortest distance to a world position.

Parameters:

position - the world position.

Returns:

the closest player, or null if no player is on the server.

addArea

void addArea(Area area)

Adds an Area to the server. Once an area is added to the server, PlayerEnterAreaEvent and PlayerLeaveAreaEvent events will be triggered when a player enters/leaves an area.

Parameters:

area - the Area you want to add to the server.

See Also:

removeArea(net.risingworld.api.utils.Area)

removeArea

void removeArea(Area area)

Removes an Area that has been added to the server previously. Once an area is removed, events like PlayerEnterAreaEvent or PlayerLeaveAreaEvent will no longer be triggered for this area.

Parameters:

area - the Area you want to remove from the server. Note: you can still re-add the area to the server at any time.

See Also:

addArea(net.risingworld.api.utils.Area)

getAllAreas

java.util.Collection<Area> getAllAreas()

Gets a collection containing all Areas that are currently registered with the server.
Do not modify the collection!

Returns:

a collection containing all registered areas.

getCustomImage

CustomImage getCustomImage(int id)

Gets a custom image.

Parameters:

id - the image id.

Returns:

the custom image, or null if the image does not exist.

removeCustomImage

void removeCustomImage(int id)

Deletes a custom image (and also removes all placed instances in the world). If the image does not exist, nothing happens.

Parameters:

id - the image id.

getAllCustomImages

java.util.Collection<CustomImage> getAllCustomImages()

Gets a list containing all custom images (creates a new list).

Returns:

a new list containing all images.

getAllCustomImages

java.util.Collection<CustomImage> getAllCustomImages(long playerUID)

Gets a list containing all custom images which were uploaded by a particular player. This function creates a new list.

Parameters:

playerUID - the player UID (see Player.getUID()).

Returns:

a list containing all images uploaded by a particular player.

registerCustomItem

void registerCustomItem(CustomItem item)

Registers a new custom item. It's necessary to call this method only once, preferably when the plugin is initialized (onEnable() method). If a custom item is added to the player inventory, it will be treated like a regular item, i.e it's stored in the database automatically. This means the player is also able to store it in chests, for example. Internally, a custom item is treated as an abstract "API item", with a reference to the item UUID.

Parameters:

item - the custom item you want to register.

getCustomItem

CustomItem getCustomItem(java.lang.String uuid)

Gets the registered custom item with the specified UUID. If no such item is registered, null will be returned.

Parameters:

uuid - the UUID of the custom item.

Returns:

the custom item, or null if no such item is registered.

registerCustomRecipe

void registerCustomRecipe(CustomRecipe recipe)

Registers a new custom crafting recipe. It's necessary to call this method only once, preferably when the plugin is initialized (onEnable() method).
Make sure to register the corresponding item first before adding the custom recipe!

Parameters:

recipe - the custom recipe you want to register.

getCustomRecipe

CustomRecipe getCustomRecipe(java.lang.String targetUUID,
                             int targetVariation)

Gets the custom recipe which corresponds to the provided item UUID and variation. If no such item is registered, null will be returned.

Parameters:

targetUUID - the UUID of the target item.

targetVariation - the variation of the target item (by default 0)

Returns:

the corresponding custom item, or null if no item was found.

broadcastTextMessage

void broadcastTextMessage(java.lang.String message)

Broadcasts a text message, i.e. send it to all players. This is exactly the same as calling Player.sendTextMessage(java.lang.String) for every player.

Parameters:

message - the message you want to broadcast.

See Also:

Player.sendTextMessage(java.lang.String)

Example:

1	Server server = getServer();
2	server.broadcastTextMessage("[#FF0000]Server will shutdown in 5 minutes!");

broadcastYellMessage

void broadcastYellMessage(java.lang.String message)

Broadcasts a yell message, i.e. send it to all players. This is exactly the same as calling Player.sendYellMessage(java.lang.String) for every player.

Parameters:

message - the yell message you want to broadcast.

See Also:

Player.sendYellMessage(java.lang.String)