Package com.smartfoxserver.mmo

Class MMORoom

java.lang.Object

com.smartfoxserver.entities.SFSRoom

com.smartfoxserver.mmo.MMORoom

All Implemented Interfaces:

Room

public class MMORoom
extends SFSRoom

Overview

The MMORoom extends the functionalities of a regular Room by adding an Area Of Interest (AOI) to determine the range of the events that should be received by Users. The AOI parameter represents the area within which Users will affect each other, for example when sending public messages, updating User Variables etc...

By default the MMORoom does not trigger any USER_ENTER or USER_EXIT events when other users enter or leave the Room, instead the client's user list is updated via the PROXIMITY_LIST_UPDATE event which provides a delta of the current user list, within the AOI.

In other words the 'proximity list' replaces the regular user list on the client side, optimizing the number of updates that the User will receive. On the server side, however, the full Room's user list is always available.

Intended use

As suggested by the name of the class, MMORoom objects are useful to create very large, virtually unlimited, areas that are able to host thousands of players without overloading the clients with massive amounts of updates. The MMORoom can be configured to throttle the PROXIMITY_LIST_UPDATE events in order to optimize the network traffic.

Joining and Setting a User position

In contrast to regular Rooms, the MMORoom needs to know where each user is located in 2D or 3D space. The Room uses a generic coordinate system that allows to use any type of units (pixels, inches, meters, miles etc...) represented as either integers or floating point values (32bit).

When a User joins an MMORoom its position in the world is still undefined and therefore it will be in a state of limbo until the first SetUserPosition request is received. In order to avoid Users spending too much time in this invisible state each MMORoom can be configured to allow a timeout value after which the User is removed from the Room.

As mentioned in the overview there are no USER_ENTER/EXIT events triggered like in regular Rooms. The way in which players are notified about other Users in their proximity is via the PROXIMITY_LIST_UPDATE. All other Room events work similarly, including the USER_COUNT_CHANGE which keeps Users in the same Room group updated about the total number of clients in each Room.

User Variables and Room Variables

UserVariables work normally, affecting only those Users who are in the AOI of the sender. RoomVariables instead need to be used with parsimony to avoid generating heavy traffic towards the clients. Since RoomVariables contain data that interest all users in the MMORoom, updating them very often will generate large updates and thus consume significant network resources. the server bandwidth. What is critical here is the rate at which they are updated more than the number of variables used.

Map limits

The MMORoom accepts a pair of Vec3D parameters that represent the limits of the virtual map on the three axis (x, y, z). It is highly recommended to set these limits to restrain the User movement within the range of your virtual world. This way illegal movements can be detected on the server side and denied by the system. Without setting map limits there's a potential risk that malicious Users could exhaust the system memory by trying to fill very large number of spaces for extreme coordinate values.

Obtain the entry point of other Users

It is usually helpful to know at which coordinates a new User has entered the Player's AOI. Typically the client code will need to know this position to render a sprite/avatar in that spot. By default the MMORoom always sends the entry position of each new User. If this bit of information is not necessary in your application it can be turned off to save extra traffic.

MMOItems

MMOitems are an extra feature available in MMORooms to add non-player entities in the virtual map. MMOItems can be defined with custom variables (MMOItemVariables) to represent all sorts of objects such as collectible bonuses, triggers, bullets, non-player entities etc...

Tutorial

For more info see the tutorials in our online documentation

See Also:

• CreateMMORoomSettings
• Vec3D
• MMOItem
• SFSMMOApi

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MMORoom.PreviousMMORoomState

Field Summary

Fields inherited from class com.smartfoxserver.entities.SFSRoom

logger

Constructor Summary

Constructors

Constructor	Description
MMORoom(String name, Vec3D aoi, int updateMillis)

Method Summary

Modifier and Type	Method	Description
void	addUser(User user, boolean asSpectator)
boolean	containsMMOItem(int id)	Check if the provided MMOItem id is managed by this Room
boolean	containsMMOItem(BaseMMOItem item)	Check if the provided MMOItem is managed by this Room
void	destroy()
void	enableAudioManager()
com.smartfoxserver.mmo.P3D	findItemLocation(BaseMMOItem item)
com.smartfoxserver.mmo.P3D	findUserLocation(User user)
List<BaseMMOItem>	getAllMMOItems()	Obtain a list of all MMOItems managed by this Room
Vec3D	getDefaultAOI()	Obtain the default Area Of Interest (AOI) of this room.
com.smartfoxserver.mmo.IMMOItemManager	getItemsManager()
Vec3D	getMapHigherLimit()	Get the map higher limit
Vec3D	getMapLowerLimit()	Get the map lower limit
BaseMMOItem	getMMOItemById(int itemId)	Obtain an MMOItem managed by this Room via its id
List<User>	getPlayersList()	For Game Rooms: get all Players in the Room (same as all User without the Spectators)
List<BaseMMOItem>	getProximityItems(User target)	Get the list of MMOItems falling within the User's AoI
List<BaseMMOItem>	getProximityItems(User target, Vec3D aoi)	Get the list of MMOItems falling within a custom AoI
List<BaseMMOItem>	getProximityItems(Vec3D pos)	Get the list of MMOItems falling within the MMORoom's AoI at a specific location
List<BaseMMOItem>	getProximityItems(Vec3D pos, Vec3D aoi)	Get the list of MMOItems at a specific location, falling within a custom AoI
List<User>	getProximityList(User target)	Returns the List of Users falling within the target's AOI
List<User>	getProximityList(User target, Vec3D aoi)	Returns the List of Users falling within the a custom AOI around the target
List<User>	getProximityList(Vec3D position)	Returns the List of Users falling within the AOI of the target position
List<User>	getProximityList(Vec3D position, Vec3D aoi)	Returns the List of Users falling within the custom AOI around the target position
int	getProximityListUpdateMillis()
com.smartfoxserver.mmo.IProximityManager	getProximityManager()
Vec3D	getSectorSize()
List<User>	getSpectatorsList()	For Game Rooms: get all Spectators in the Room (same as all User without the Players)
User	getUserByPlayerId(int playerId)	Get the User currently having the specified playerId (Game Room only)
int	getUserLimboMaxSeconds()
boolean	isGame()	Checks if this is a Game Room
boolean	isSendAOIEntryPoint()
boolean	isSuppressUserList()
void	removeMMOItem(BaseMMOItem item)
void	removeUser(User user)
void	setGame(boolean game)
void	setGame(boolean game, Class<? extends IPlayerIdGenerator> customPlayerIdGeneratorClass)
void	setMapLimits(Vec3D lowLimit, Vec3D highLimit)
void	setSendAOIEntryPoint(boolean sendAOIEntryPoint)
void	setSuppressUserList(boolean value)
void	setUserLimboMaxSeconds(int userLimboMaxSeconds)
ISFSArray	toSFSArray(boolean globalRoomVarsOnly)
String	toString()
void	updateItem(BaseMMOItem item, Vec3D pos)
void	updateUser(User user)

Methods inherited from class com.smartfoxserver.entities.SFSRoom

addUser, banUser, containsProperty, containsUser, containsUser, containsVariable, equals, getAdminHelper, getAudioManager, getAutoRemoveMode, getBannedUserIds, getCapacity, getDump, getExtension, getGroupId, getId, getLifeTime, getMaxRoomVariablesAllowed, getMaxSpectators, getMaxUsers, getName, getOwner, getOwnerName, getPassword, getPlayerIdGeneratorClassName, getProperties, getProperty, getRoomVariablesData, getSessionList, getSize, getUserById, getUserByName, getUserBySession, getUserList, getUserListData, getUserManager, getVariable, getVariables, getVariablesCount, getVariablesCreatedByUser, getZone, isActive, isAllowOwnerInvitations, isAudioStreamingAllowed, isDynamic, isEmpty, isFlagSet, isFull, isHidden, isJoinAllowed, isOwnedBy, isPasswordProtected, isPublic, isUseWordsFilter, removeProperty, removeVariable, removeVariablesCreatedByUser, removeVariablesCreatedByUser, setActive, setAdminHelper, setAllowOwnerInvitations, setAutoRemoveMode, setCapacity, setDynamic, setExtension, setFlag, setFlags, setGroupId, setHidden, setMaxRoomVariablesAllowed, setMaxSpectators, setMaxUsers, setName, setOwner, setPassword, setProperties, setProperty, setUserManager, setUseWordsFilter, setVariable, setVariable, setVariables, setVariables, setZone, switchPlayerToSpectator, switchSpectatorToPlayer, unbanUser

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

MMORoom

public MMORoom(String name,
 Vec3D aoi,
 int updateMillis)

Internal

Instead use SFSApi.createRoom(com.smartfoxserver.entities.Zone, com.smartfoxserver.api.CreateRoomSettings, User)

Method Details

addUser

public void addUser(User user,
 boolean asSpectator)
             throws SFSJoinRoomException

Description copied from class: SFSRoom

Specified by:

addUser in interface Room

Overrides:

addUser in class SFSRoom

Throws:

SFSJoinRoomException

Internal

Instead use SFSApi.joinRoom(User, com.smartfoxserver.entities.Room)

removeUser

public void removeUser(User user)

Description copied from class: SFSRoom

Specified by:

removeUser in interface Room

Overrides:

removeUser in class SFSRoom

Internal

Instead use SFSApi.leaveRoom(User, com.smartfoxserver.entities.Room)

isSuppressUserList

public boolean isSuppressUserList()

Specified by:

isSuppressUserList in interface Room

Overrides:

isSuppressUserList in class SFSRoom

Internal

setSuppressUserList

public void setSuppressUserList(boolean value)

Specified by:

setSuppressUserList in interface Room

Overrides:

setSuppressUserList in class SFSRoom

Internal

enableAudioManager

public void enableAudioManager()

Specified by:

enableAudioManager in interface Room

Overrides:

enableAudioManager in class SFSRoom

Internal

removeMMOItem

public void removeMMOItem(BaseMMOItem item)

Internal

getDefaultAOI

public Vec3D getDefaultAOI()

Obtain the default Area Of Interest (AOI) of this room.

Returns:

the default Area Of Interest (AOI) of this room

getProximityList

public List<User> getProximityList(User target)

Returns the List of Users falling within the target's AOI

Parameters:

target - the target user

Returns:

the list of users within the target's AOI, returns null if the target User is not present in the Room

getProximityList

public List<User> getProximityList(User target,
 Vec3D aoi)

Returns the List of Users falling within the a custom AOI around the target

Parameters:

target - the target user

aoi - a custom AOI which must less than or equal the default Room's AOI

Returns:

the list of users within the requested target's AOI, returns null if the target User is not present in the Room

getProximityList

public List<User> getProximityList(Vec3D position)

Returns the List of Users falling within the AOI of the target position

Parameters:

position - a 2D/3D position in the virtual world

Returns:

the list of users within the target position AOI

getProximityList

public List<User> getProximityList(Vec3D position,
 Vec3D aoi)

Returns the List of Users falling within the custom AOI around the target position

Parameters:

position - a 2D/3D position in the virtual world

aoi - a custom AOI which must be less than or equal the default Room's AOI

Returns:

the list of users within the requested target's AOI

getMMOItemById

public BaseMMOItem getMMOItemById(int itemId)

Obtain an MMOItem managed by this Room via its id

Parameters:

itemId - the id of the MMOItem

Returns:

the MMOItem or null if no MMOItem is managed by this Room with the provided Id

getAllMMOItems

public List<BaseMMOItem> getAllMMOItems()

Obtain a list of all MMOItems managed by this Room

Returns:

the list of all MMOItems managed by this Room

containsMMOItem

public boolean containsMMOItem(int id)

Check if the provided MMOItem id is managed by this Room

Parameters:

id - the MMOItem id

Returns:

true if the MMOItem is managed by this Room, false otherwise

containsMMOItem

public boolean containsMMOItem(BaseMMOItem item)

Check if the provided MMOItem is managed by this Room

Parameters:

item - the MMOItem

Returns:

true if the MMOItem is managed by this Room, false otherwise

getProximityItems

public List<BaseMMOItem> getProximityItems(User target)

Get the list of MMOItems falling within the User's AoI

Parameters:

target - A user joined in the same Room

Returns:

The list of MMOItems. Null if the User is not present in the Room.

getProximityItems

public List<BaseMMOItem> getProximityItems(User target,
 Vec3D aoi)

Get the list of MMOItems falling within a custom AoI

Parameters:

target - A user joined in the same Room

aoi - A custom AoI, must be less than or equal than the default MMORoom AoI

Returns:

The list of MMOItems. Null if the User is not present in the Room.

getProximityItems

public List<BaseMMOItem> getProximityItems(Vec3D pos)

Get the list of MMOItems falling within the MMORoom's AoI at a specific location

Parameters:

pos - The location in the MMORoom's "map"

Returns:

The list of MMOItems.

getProximityItems

public List<BaseMMOItem> getProximityItems(Vec3D pos,
 Vec3D aoi)

Get the list of MMOItems at a specific location, falling within a custom AoI

Parameters:

pos - The location in the MMORoom's "map"

aoi - A custom AoI, must be less than or equal than the default MMORoom AoI

Returns:

The list of MMOItems.

getSectorSize

public Vec3D getSectorSize()

Internal

getProximityManager

public com.smartfoxserver.mmo.IProximityManager getProximityManager()

Internal

getItemsManager

public com.smartfoxserver.mmo.IMMOItemManager getItemsManager()

Internal

findUserLocation

public com.smartfoxserver.mmo.P3D findUserLocation(User user)

Internal

findItemLocation

public com.smartfoxserver.mmo.P3D findItemLocation(BaseMMOItem item)

Internal

updateUser

public void updateUser(User user)

Internal

updateItem

public void updateItem(BaseMMOItem item,
 Vec3D pos)

Internal

getMapLowerLimit

public Vec3D getMapLowerLimit()

Get the map lower limit

Returns:

get the map lower limit

getMapHigherLimit

public Vec3D getMapHigherLimit()

Get the map higher limit

Returns:

get the map higher limit

setMapLimits

public void setMapLimits(Vec3D lowLimit,
 Vec3D highLimit)

Internal

getUserLimboMaxSeconds

public int getUserLimboMaxSeconds()

Internal

setUserLimboMaxSeconds

public void setUserLimboMaxSeconds(int userLimboMaxSeconds)

Internal

destroy

public void destroy()

Specified by:

destroy in interface Room

Overrides:

destroy in class SFSRoom

Internal

isSendAOIEntryPoint

public boolean isSendAOIEntryPoint()

Internal

setSendAOIEntryPoint

public void setSendAOIEntryPoint(boolean sendAOIEntryPoint)

Internal

getProximityListUpdateMillis

public int getProximityListUpdateMillis()

Internal

getUserByPlayerId

public User getUserByPlayerId(int playerId)

Description copied from class: SFSRoom

Get the User currently having the specified playerId (Game Room only)

Specified by:

getUserByPlayerId in interface Room

Overrides:

getUserByPlayerId in class SFSRoom

Parameters:

playerId - the player id

Returns:

the User, null if no User exists with that player id

isGame

public boolean isGame()

Description copied from class: SFSRoom

Checks if this is a Game Room

Specified by:

isGame in interface Room

Overrides:

isGame in class SFSRoom

Returns:

true if this is a Game Room

toString

public String toString()

Overrides:

toString in class SFSRoom

getPlayersList

public List<User> getPlayersList()

Description copied from class: SFSRoom

For Game Rooms: get all Players in the Room (same as all User without the Spectators)

Specified by:

getPlayersList in interface Room

Overrides:

getPlayersList in class SFSRoom

Returns:

all Players in the Room

getSpectatorsList

public List<User> getSpectatorsList()

Description copied from class: SFSRoom

For Game Rooms: get all Spectators in the Room (same as all User without the Players)

Specified by:

getSpectatorsList in interface Room

Overrides:

getSpectatorsList in class SFSRoom

Returns:

all Spectators in the Room

setGame

public void setGame(boolean game)

Description copied from class: SFSRoom

Specified by:

setGame in interface Room

Overrides:

setGame in class SFSRoom

Internal

setGame

public void setGame(boolean game,
 Class<? extends IPlayerIdGenerator> customPlayerIdGeneratorClass)

Description copied from class: SFSRoom

Specified by:

setGame in interface Room

Overrides:

setGame in class SFSRoom

Internal

toSFSArray

public ISFSArray toSFSArray(boolean globalRoomVarsOnly)

Specified by:

toSFSArray in interface Room

Overrides:

toSFSArray in class SFSRoom

Internal