OpenSpaceExtension

Kind of class:public class
Package:com.smartfoxserver.openspace
Inherits from:SFSExtension
Version:1.0.2 for SmartFoxServer 2X
Author:The gotoAndPlay() Team
http://www.openspace-engine.com
http://www.smartfoxserver.com
http://www.gotoandplay.it
Package classpath:com.smartfoxserver.openspace.OpenSpaceExtension
File last modified:Saturday, 02 April 2011, 17:18:43
OpenSpace Extension main class.
This class is the default SmartFoxServer 2X Zone extension required by the OpenSpace component in order to run. This extension is responsible of sending avatar types to the clients during initialization, loading map data and sending it to the clients, save the updated map data received from the clients which edit maps at runtime, calculate avatar paths and more.

The OpenSpaceExtension class can be extended to add custom logic to applications. In order to keep the OpenSpace Extension logic safe, the default SmartFoxServer's com.smartfoxserver.v2.extensions.SFSExtension methods have been overridden and declared as final, and a new set of methods with the same names but with an "_" prefix was created.
Developers should override the "_" methods to add their own logic, just like they would override the default extensions.SFSExtension methods during standard extension development.

Other public methods, without the "_" prefix, are also available:
  • the non-final methods (for example isMapUpToDate) can be overridden to modify the behavior of the OpenSpace Extension in some circumstances; in fact those methods are all related to library/map/inventory data loading and map updating: by overriding them the default data storage system (file) can be modified (for example maps can be saved to a database);
  • the final methods (for example moveAvatar) can be called from within the custom extension to force the OpenSpace client execute specific operations.
A typical task of the child class extending the OpenSpace Extension is the creation and management of Non-Player Characters. NPCs are fake users created by means of the SmartFoxServer's ISFSApi.createNPC method (check the ISFSApi interface in the SmartFoxServer server-side Java API documentation for more informations).
After creating the NPC, the following User Variables should be set to make the OpenSpace client recognize the NPC and create the corresponding avatar:
  • _os_type: the avatar's type, as defined in the <AvatarTypes/> section of the OpenSpace server-side configuration;
  • _os_name: the avatar's name; if not set, the SmartFoxServer user name of the NPC is used;
  • _os_skin: a SFSObject containing any number of custom parameters describing the avatar's appearance;
  • _os_aTime: duration in milliseconds of the avatar movement from tile to tile along N/E/S/W directions; if not set, a default value is assigned by the OpenSpace client;
After creating the NPC and setting the avatar's User Variables described above, we still have to make the NPC join the SmartFoxServer Room corresponding to the map on which we want the NPC's avatar to appear. For this purpose, the sendAvatarToMap method can be used.
At last, in order to make the avatar actually appear on the map, the following avatar position User Variables must be set:
  • _os_px: the isometric x coordinate of the tile on which the avatar should appear;
  • _os_py: the isometric y coordinate of the tile on which the avatar should appear;
  • _os_pz: the isometric z coordinate (elevation) of the tile on which the avatar should appear;
  • _os_dir: the direction faced by the avatar. Valid values are described in the OpenSpace client AvatarDirections class.
Note: check the Avatar class in the OpenSpace client-side API for more informations on the properties corresponding to the User Variables described above.

Summary


Instance methods
  • getVersion String getVersion
    • Get the OpenSpace Extension version.
  • setEventsListener void setEventsListener(IOpenSpaceEventsListener listener)
    • Register an events listener class.
  • sendAvatarToMap void sendAvatarToMap(User user, int roomId, String roomPassword)
    • Send the avatar of a user to a new map.
  • sendAvatarToMap void sendAvatarToMap(User user, int roomId, String roomPassword, int roomIdToLeave)
    • Send the avatar of a user to a new map.
  • moveAvatar void moveAvatar(User user, int roomId, int targetX, int targetY, int targetZ)
    • Send a user's avatar to target coordinates on a target map.
  • isLibraryUpToDate boolean isLibraryUpToDate(String libraryId, long lastUpdate)
    • Check if a tiles' library is up-to-date.
  • loadLibraryData String loadLibraryData(String libraryId)
    • Load a tiles' library.
  • isMapUpToDate boolean isMapUpToDate(String mapId, long lastUpdate)
    • Check if a map is up-to-date.
  • loadMapData String loadMapData(String mapId)
    • Load a map.
  • isInventoryUpToDate boolean isInventoryUpToDate(String inventoryId, long lastUpdate)
    • Check if an inventory is up-to-date.
  • loadInventoryData String loadInventoryData(String inventoryId)
    • Load an inventory.
  • getInventoryItemsList List<ItemProperties> getInventoryItemsList(String inventoryId, ISFSObject filterParams, User requester)
    • Retrieve a filtered list of inventory items.
  • isMapUpdateAllowed boolean isMapUpdateAllowed(String mapId, User requester, Room room)
    • Check if an user is allowed to apply the map changes he submitted.
  • saveMapData long saveMapData(String mapId, String mapJsonString)
    • Save a map.
  • _init void _init
    • See the ISFSExtension interface in the SmartFoxServer 2X server-side Java API documentation.
  • _destroy void _destroy
    • See the ISFSExtension interface in the SmartFoxServer 2X server-side Java API documentation.

Instance methods

_destroy

public void _destroy(
)

See the ISFSExtension interface in the SmartFoxServer 2X server-side Java API documentation.

_init

public void _init(
)

See the ISFSExtension interface in the SmartFoxServer 2X server-side Java API documentation.

getInventoryItemsList

public List<ItemProperties> getInventoryItemsList(
String inventoryId, ISFSObject filterParams, User requester)

Retrieve a filtered list of inventory items.
This method is called by the OpenSpace Extension when an inventory is requested by a client, and it is in charge of filtering (if needed) the inventory items that will be sent to that client.
Parameters:
inventoryId :
the id of the OpenSpace Editor project to which the inventory to be filtered belongs.
filterParams:
a SFSObject containing custom parameters sent by the OpenSpace client; it can contain strings, numbers, booleans, arrays and nested objects.
requester :
the SmartFoxServer User requesting the inventory.
Implementation note:
  • By default, all the items contained in an inventory are sent to the clients requesting that inventory.
    This method should be overridden by the OpenSpace Extension child class in case inventory items must be filtered, for example to send to a user the items he purchased only. Additional filtering parameters can be send by the client, by means of a filterParams object passed to the client-side OpenSpace.loadInventory method.
Returns:
  • a list of ItemProperties objects; each list item contains the id of the inventory item and an optional map of additional custom properties to be sent back to the requester.

getVersion

public final String getVersion(
)

Get the OpenSpace Extension version.
Returns:
  • the OpenSpace Extension version.

isInventoryUpToDate

public boolean isInventoryUpToDate(
String inventoryId, long lastUpdate)

Check if an inventory is up-to-date.
This method is called by the OpenSpace Extension during the inventory loading process, to check if the stored version has changed since it was cached in memory.
Parameters:
inventoryId:
the id of the OpenSpace Editor project to which the inventory being checked belongs.
lastUpdate :
the time, expressed in milliseconds, when the inventory was loaded and the in-memory cache updated.
Implementation note:
  • By default, inventories are stored as INV files inside a folder in the SmartFoxServer installation path (check the OpenSpace Editor documentation for more informations). When an inventory is requested by a client, it is loaded and cached in memory.
    When the same inventory is requested again, this method is called to check if, in the meanwhile, the previously loaded inventory was updated: if yes, the inventory is reloaded and the cached version updated.
    This method should be overridden by the OpenSpace Extension child class in case inventories are stored in a custom way (for example a database), to check the inventory's up-to-date status properly.
Returns:
  • true if the inventory is still up-to-date; false if the inventory is out-of-date and should be reloaded.

isLibraryUpToDate

public boolean isLibraryUpToDate(
String libraryId, long lastUpdate)

Check if a tiles' library is up-to-date.
This method is called by the OpenSpace Extension during the tiles' library loading process, to check if the stored version has changed since it was cached in memory.
Parameters:
libraryId :
the id of the OpenSpace Editor project to which the library being checked belongs.
lastUpdate:
the time, expressed in milliseconds, when the library was loaded and the in-memory cache updated.
Implementation note:
  • By default, the tiles' libraries are stored as LIB files inside a folder in the SmartFoxServer installation path (check the OpenSpace Editor documentation for more informations). When a map is requested by a client, the corresponding library file (the library belonging to the same project) is loaded and cached in memory.
    When a new map belonging to the same project is requested, this method is called to check if, in the meanwhile, the previously loaded library was updated: if yes, the library file is reloaded and the cached version updated.
    This method should be overridden by the OpenSpace Extension child class in case libraries are stored in a custom way (for example a database), to check the library's up-to-date status properly.
Returns:
  • true if the library is still up-to-date; false if the library is out-of-date and should be reloaded.
See also:

isMapUpdateAllowed

public boolean isMapUpdateAllowed(
String mapId, User requester, Room room)

Check if an user is allowed to apply the map changes he submitted.
This method is called by the OpenSpace Extension during the map saving process, to check if the user submitting the changes he made on the client-side (by means of the OpenSpace runtime map editing feature) is allowed to save a new version of the map.
Parameters:
mapId :
the id of the map to be saved.
requester:
the SmartFoxServer User requesting to save the submitted map changes.
room :
the SmartFoxServer Room to which the map associated.
Implementation note:
  • By default, the OpenSpace Extension saves all the changes submitted by the users who edited an editable map at runtime (see the client-side IOpenSpaceAPI.leaveEditMode method).
    This method should be overridden by the OpenSpace Extension child class in case an additional control system must be implemented to avoid malicious users to submit unauthorized map changes circumventing the client-side checks.
Returns:
  • true if the map updating is still allowed; false if the user is not authorized to update the map.

isMapUpToDate

public boolean isMapUpToDate(
String mapId, long lastUpdate)

Check if a map is up-to-date.
This method is called by the OpenSpace Extension during the map loading process, to check if the stored version has changed since it was cached in memory.
Parameters:
mapId :
the id of the map being checked.
lastUpdate:
the time, expressed in milliseconds, when the map was loaded and the in-memory cache updated.
Implementation note:
  • By default, maps are stored as MAP files inside a folder in the SmartFoxServer installation path (check the OpenSpace Editor documentation for more informations). When a map is requested by a client, it is loaded and cached in memory.
    When the same map is requested again, this method is called to check if, in the meanwhile, the previously loaded map was updated: if yes, the map is reloaded and the cached version updated.
    This method should be overridden by the OpenSpace Extension child class in case maps are stored in a custom way (for example a database), to check the map's up-to-date status properly.
Returns:
  • true if the map is still up-to-date; false if the map is out-of-date and should be reloaded.

loadInventoryData

public String loadInventoryData(
String inventoryId) throws LoadInventoryException

Load an inventory.
This method is called by the OpenSpace Extension during the inventory loading process, and it is in charge of returning the stored version of the inventory data to be cached in memory.
Parameters:
inventoryId:
the id of the OpenSpace Editor project to which the inventory to be loaded belongs.
Implementation note:
  • By default, inventories are stored as INV files inside a folder in the SmartFoxServer installation path (check the OpenSpace Editor documentation for more informations). When an inventory is requested by a client, it is loaded and cached in memory.
    This method should be overridden by the OpenSpace Extension child class in case inventories are stored in a custom way (for example a database), to load and return their data properly. A LoadInventoryException exception must be thrown in case an error occurs during the loading process, so that the OpenSpace Extension can terminate it properly.
Returns:
  • a string containing the inventory data as exported by the OpenSpace Editor in the corresponding INV file.
Throws:

loadLibraryData

public String loadLibraryData(
String libraryId) throws LoadLibraryException

Load a tiles' library.
This method is called by the OpenSpace Extension during the tiles' library loading process, and it is in charge of returning the stored version of the library data to be cached in memory.
Parameters:
libraryId:
the id of the OpenSpace Editor project to which the library to be loaded belongs.
Implementation note:
  • By default, the tiles' libraries are stored as LIB files inside a folder in the SmartFoxServer installation path (check the OpenSpace Editor documentation for more informations). When a map is requested by a client, the corresponding library file (the library belonging to the same project) is loaded and cached in memory.
    This method should be overridden by the OpenSpace Extension child class in case libraries are stored in a custom way (for example a database), to load and return their data properly. A LoadLibraryException exception must be thrown in case an error occurs during the loading process, so that the OpenSpace Extension can terminate it properly.
Returns:
  • a string containing the library data as exported by the OpenSpace Editor in the corresponding LIB file.
Throws:

loadMapData

public String loadMapData(
String mapId) throws LoadMapException

Load a map.
This method is called by the OpenSpace Extension during the map loading process, and it is in charge of returning the stored version of the map data to be cached in memory.
Parameters:
mapId:
the id of the map to be loaded.
Implementation note:
  • By default, maps are stored as MAP files inside a folder in the SmartFoxServer installation path (check the OpenSpace Editor documentation for more informations). When a map is requested by a client, it is loaded and cached in memory.
    This method should be overridden by the OpenSpace Extension child class in case maps are stored in a custom way (for example a database), to load and return their data properly. A LoadMapException exception must be thrown in case an error occurs during the loading process, so that the OpenSpace Extension can terminate it properly.
Returns:
  • a string containing the map data as exported by the OpenSpace Editor in the corresponding MAP file.
Throws:
See also:

moveAvatar

public final void moveAvatar(
User user, int roomId, int targetX, int targetY, int targetZ) throws Exception

Send a user's avatar to target coordinates on a target map.
This method can be used to send the avatar of a user from the current tile to another tile on the same map automatically, without the need of user interaction. This method is similar to the client-side OpenSpace.moveMyAvatar method.
Parameters:
user :
the SmartFoxServer User owning of the avatar that should be moved.
roomId :
the id of the SmartFoxServer Room corresponding to the map on which the avatar should be sent to the target coordinates. In case the Room does not contain the User (in other words the avatar is not on the map), a warning is logged and the request is ignored.
targetX:
target coordinate along the isometric grid x axis.
targetY:
target coordinate along the isometric grid y axis.
targetZ:
target coordinate along the isometric grid z axis (elevation).
Implementation note:
  • This method should be called from within the OpenSpace Extension child class when an avatar must be sent to target coordinates. In particular, this can be useful to make Non-Player Characters move around on a map.
Throws:
  • PathfindingException if the avatar couldn't be sent to the target coordinates, due to wrong coordinates, wrong type assigned to avatar, etc.
  • Exception if a generic error occurred; check the stack trace for more informations on the error.

saveMapData

public long saveMapData(
String mapId, String mapJsonString) throws SaveMapException

Save a map.
This method is called by the OpenSpace Extension during the map saving process, and it is in charge of storing the new map data.
Parameters:
mapId :
the id of the map to be saved.
mapJsonString:
a string representing the JSON-encoded map data to be saved.
Implementation note:
  • By default, maps are stored as MAP files inside a folder in the SmartFoxServer installation path (see the loadMapData method).
    This method should be overridden by the OpenSpace Extension child class in case maps are stored in a custom way (for example a database), to save their data properly. A SaveMapException exception must be thrown in case an error occurs during the saving process, so that the OpenSpace Extension can terminate it properly.
Returns:
  • the time stamp, in milliseconds, taken after the map data was saved.
Throws:
See also:

sendAvatarToMap

public final void sendAvatarToMap(
User user, int roomId, String roomPassword) throws Exception

Send the avatar of a user to a new map.
This method can be used to send a user to a new map without the need of calling the client-side OpenSpace.loadMap method.
Parameters:
user :
the SmartFoxServer User owning of the avatar that should be sent to the new map.
roomId :
the id of the SmartFoxServer Room corresponding to the map to which the avatar should be sent.
roomPassword:
the password (if any) of the SmartFoxServer Room corresponding to the map to which the avatar should be sent.
Implementation note:
  • This method should be called from within the OpenSpace Extension child class when an avatar must be sent to a map (and its owner joined to the corresponding SmartFoxServer Room).
    A typical use case scenario is represented by the "player home". The player's own home is usually a non-public map that only the owner can access. In order to have a proper authorization control system (in particular if the map can also be edited at runtime), the map loading process should be initiated on the server side.
    A possible high-level workflow could be:
    1. user clicks on a button in the application interface to enter his own home: a custom request is sent to our server-side extension (which in turn extends the default OpenSpace Extension);
    2. if this is the first time that the user enters his home, the extension generates a new map file by duplicating a predefined template (the empty home) created by map designers with the OpenSpace Editor (the new map file should probably contain the user name according to a naming convention, so that its existence can be checked the next time the user requests to enter his home);
    3. a new SmartFoxServer Room is created dynamically (with the user set as its owner) and the map is assigned to it by means of a Room Variable (check the OpenSpace.loadMap method in the OpenSpace client-side API documentation for more informations on map-Room association);
    4. by means of this sendAvatarToMap method, the user is joined to the newly created Room and the map data is sent to the OpenSpace client, which will render the new map.

    Sending an avatar to a map is useful in case of regular (human) users, but also in case of Non-Player Characters.
    In particular, this method can be used to re-create the NPCs after a user has edited a map. In fact, when the runtime editing is started on a client, all the avatars are removed from that map on that client. When the user then saves the changes, the previous avatars aren't recreated immediately, because this could cause issues in case the tiles they were standing on have been removed. Instead, an event is sent to all the clients in the same Room, which are forced to reload the changed map, causing their avatars to be re-created on the client of the user who edited the map too.
    In case of NPCs, there's no client listening to the event which forces the map reloading: then NPCs would never appear again on the edited map. For this reason, the child extension can listen to the IOpenSpaceEventsListener.onMapUpdated event and then force the NPCs creation by calling this sendAvatarToMap method.
Throws:
  • JoinMapRoomException if an error occurred while making the user join the SmartFoxServer Room corresponding to the passed id.
  • LoadMapException if an error occurred while loading the map corresponding to the SmartFoxServer Room being joined.
  • Exception if a generic error occurred; check the stack trace for more informations on the error.

sendAvatarToMap

public final void sendAvatarToMap(
User user, int roomId, String roomPassword, int roomIdToLeave) throws Exception

Send the avatar of a user to a new map.
This method can be used to send a user to a new map without the need of calling the client-side OpenSpace.loadMap method.
The last parameter can be used in case the user joined a non OpenSpace-related Room, and it must be left while making him enter the new map.
Parameters:
user :
the SmartFoxServer User owning of the avatar that should be sent to the new map.
roomId :
the id of the SmartFoxServer Room corresponding to the map to which the avatar should be sent.
roomPassword :
the password (if any) of the SmartFoxServer Room corresponding to the map to which the avatar should be sent.
roomIdToLeave:
the id of the SmartFoxServer Room to be left after joining the new one.
Implementation note:
  • This method should be called from within the OpenSpace Extension child class when an avatar must be sent to a map (and its owner joined to the corresponding SmartFoxServer Room).
    A typical use case scenario is represented by the "player home". The player's own home is usually a non-public map that only the owner can access. In order to have a proper authorization control system (in particular if the map can also be edited at runtime), the map loading process should be initiated on the server side.
    A possible high-level workflow could be:
    1. user clicks on a button in the application interface to enter his own home: a custom request is sent to our server-side extension (which in turn extends the default OpenSpace Extension);
    2. if this is the first time that the user enters his home, the extension generates a new map file by duplicating a predefined template (the empty home) created by map designers with the OpenSpace Editor (the new map file should probably contain the user name according to a naming convention, so that its existence can be checked the next time the user requests to enter his home);
    3. a new SmartFoxServer Room is created dynamically (with the user set as its owner) and the map is assigned to it by means of a Room Variable (check the OpenSpace.loadMap method in the OpenSpace client-side API documentation for more informations on map-Room association);
    4. by means of this sendAvatarToMap method, the user is joined to the newly created Room and the map data is sent to the OpenSpace client, which will render the new map.

    Sending an avatar to a map is useful in case of regular (human) users, but also in case of Non-Player Characters.
    In particular, this method can be used to re-create the NPCs after a user has edited a map. In fact, when the runtime editing is started on a client, all the avatars are removed from that map on that client. When the user then saves the changes, the previous avatars aren't recreated immediately, because this could cause issues in case the tiles they were standing on have been removed. Instead, an event is sent to all the clients in the same Room, which are forced to reload the changed map, causing their avatars to be re-created on the client of the user who edited the map too.
    In case of NPCs, there's no client listening to the event which forces the map reloading: then NPCs would never appear again on the edited map. For this reason, the child extension can listen to the IOpenSpaceEventsListener.onMapUpdated event and then force the NPCs creation by calling this sendAvatarToMap method.
Throws:
  • JoinMapRoomException if an error occurred while making the user join the SmartFoxServer Room corresponding to the passed id.
  • LoadMapException if an error occurred while loading the map corresponding to the SmartFoxServer Room being joined.
  • Exception if a generic error occurred; check the stack trace for more informations on the error.

setEventsListener

public final void setEventsListener(

Register an events listener class.
The OpenSpace Extension fires a number of events. Registering a listener class let us catch those events to perform specific actions.
The listener class must implement the IOpenSpaceEventsListener interface, which contains the specific listeners that will be called when the relevant events are fired.
Parameters:
listener:
a reference to the class implementing the IOpenSpaceEventsListener interface and responsible for events listening.
Implementation note:
  • The OpenSpace Extension child class can act as events listener itself by implementing the IOpenSpaceEventsListener interface. For a more polished extension design, a specific class should be used instead.