Package com.smartfoxserver.v2.mmo

Class 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 fire any USER_ENTER or USER_EXIT events when other users enter or leave the Room, instead the client 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 substitutes 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 will always be accessible.

    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 contain thousands of players without overloading each client with useless updates. The MMORoom can be configured also 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 coordinates system is abstracted and generic, allowing developers to use all sorts of units (pixels, inches, meters, miles etc...) using either integers or floating point values (32bit).

    When a User joins an MMORoom his position in the world is still undefined and therefore he will be in a state of limbo until the first SetUserPosition request will be 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 will be removed from the Room.

    As mentioned in the overview there are no USER_ENTER/EXIT events fired to other Users, as in regular Rooms. The way in which players are updated about other User changes in their proximity is via the client PROXIMITY_LIST_UPDATE. All other Room events will 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 will work normally, affecting only those Users who are in the AOI of the request 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 very large broadcast messages with the risk of saturating 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 object accept a pair of Vec3D parameters representing 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

    To learn more see also this introductory tutorial.
    Since:
    2.8.0
    See Also:
    CreateMMORoomSettings, Vec3D, MMOItem, SFSMMOApi

    • Method Detail

      • removeMMOItem

        public void removeMMOItem​(BaseMMOItem item)
        private

      • 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 java.util.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 java.util.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 java.util.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 java.util.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 java.util.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 java.util.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 java.util.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 java.util.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 java.util.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()
        private

      • getProximityManager

        public com.smartfoxserver.v2.mmo.IProximityManager getProximityManager()
        private

      • getItemsManager

        public com.smartfoxserver.v2.mmo.IMMOItemManager getItemsManager()
        private

      • findUserLocation

        public com.smartfoxserver.v2.mmo.P3D findUserLocation​(User user)
        private

      • findItemLocation

        public com.smartfoxserver.v2.mmo.P3D findItemLocation​(BaseMMOItem item)
        private

      • updateUser

        public void updateUser​(User user)
        private

      • 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

      • getUserLimboMaxSeconds

        public int getUserLimboMaxSeconds()
        private

      • isSendAOIEntryPoint

        public boolean isSendAOIEntryPoint()
        private

      • getProximityListUpdateMillis

        public int getProximityListUpdateMillis()
        private

      • 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 java.lang.String toString()
        Overrides:
        toString in class SFSRoom

      • getPlayersList

        public java.util.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 java.util.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