OpenSpace logo

Support » OpenSpace server-side configuration

A number of parameters required to configure the OpenSpace engine has been moved to the server-side. These settings are kept separate from the other configuration parameters described in the Client configuration manual because the OpenSpace Extension must be aware of them to accomplish its pathfinding tasks properly. In fact the server-side configuration stores the definitions of the available avatar types for your application/game, which affect the extension's pathfinder behavior.

After installing the OpenSpace Extension as described in this manual (for SmartFoxServer PRO) or this manual (for SmartFoxServer 2X), the OpenSpace_server.xml server-side configuration XML file can be found respectively in the [SFS installation location]/Server/openSpace/ folder (SmartFoxServer PRO) or [SFS installation location]/SFS2X/extensions/openSpace/ folder (SmartFoxServer 2X). The file is loaded by the OpenSpace Extension during initialization, when SmartFoxServer loads the extension itself. Please notice that if the configuration file is missing, or its <AvatarTypes> section is missing, initialization can't be accomplished and OpenSpace can't run on the client-side either.

In order to edit the configuration, open the OpenSpace_server.xml file with a text editor. The configuration parameters are ideally divided into four groups: general extension settings, pathfinding settings, the terrains definition section and the avatar types definition section. Each setting is represented by an xml tag (or a list of tags) and all the tags are grouped under the main <OpenSpace> tag.

The following XML shows an example of configuration file containing the default values (except the <AvatarType> and <Terrain> elements, which contain example values). If one or more parameters are missing (excluding the <AvatarTypes> section which, again, is mandatory) default values are applied by the OpenSpace Extension.

<?xml version="1.0" encoding="UTF-8"?>
<OpenSpace>

	<!-- General extension parameters -->	
	<EnableLog>1</EnableLog>
	
	<!-- Pathfinding parameters -->	
	<PathfinderType>default</PathfinderType>
	<PfMaxTimeBeforeWarning>0</PfMaxTimeBeforeWarning>
	<PfMaxTimeBeforeQuit>0</PfMaxTimeBeforeQuit>
	
	<!-- Terrains definition -->
	<Terrains>
		<Terrain speed="100">default</Terrain>
		<Terrain speed="70">gravel</Terrain>
		<Terrain speed="40">sand</Terrain>
		<Terrain speed="120">ice</Terrain>
	</Terrains>
	
	<!-- Avatar types definition -->
	<AvatarTypes use8Directions="1">
		<AvatarType mainClass="DemoAvatar"
			ghostClass="DemoGhost" stature="30" terrains="*">demo</AvatarType>
	</AvatarTypes>

</OpenSpace>
			

The following sections describe all the settings in detail. Changing on or more parameters require the OpenSpace Extension to be reloaded by SmartFoxServer for the new configuration to take effect.

General extension parameters

This set of parameters controls the general behavior the OpenSpace Extension.

<EnableLog> Enable the OpenSpace Extension activity logger, which makes use of the default SmartFoxServer logging system.
Even if disabled, warning and error messages are still reported.
Valid values are 0 and 1; default value is 1.

Pathfinding parameters

This set of parameters fine-tunes the pathfinding algorithm used by OpenSpace.

<PathfinderType> The pathfinder type.
Valid values are default and concurrent. The concurrent pathfinding makes use of multiple threads to optimize the path calculations, but it also uses more memory; using the default default value is recommended.
<PfMaxTimeBeforeWarning> The number of milliseconds after which the OpenSpace Extension should log a warning if a pathfinding process is still running without having found the requested path yet.
Default value is 0; if set to 0, no warning is logged.
<PfMaxTimeBeforeQuit> The number of milliseconds after which the OpenSpace Extension should stop a pathfinding process if the requested path can't still be found.
Default value is 0; if set to 0, the pathfinding process is never interrupted.

Terrains setup

The <Terrains> section contains a list of <Terrain> elements.
Each <Terrain> element contains the name of a terrain to be used in the OpenSpace Editor during the tile creation process (see the Tile editor documentation and the following configuration section). Also, each element has the following attributes.

speed The avatar speed change on the terrain, expressed as a percentage of the nominal avatar speed.
For example, 100 means that the avatar walking on that terrain will have the nominal speed defined on the client-side. A value less than 100 makes the avatar slow down; a value grater than 100 makes the avatar accelerate.
Valid values are greater than 0. Default value is 100.
Some examples:
(1) <Terrain speed="40">sand</Terrain>
The sand terrain reduces the avatar speed to 40%
(2) <Terrain speed="100">default</Terrain>
The default terrain doesn't affect the avatar speed
(3) <Terrain speed="120">ice</Terrain>
The ice terrain increases the avatar speed of 20%

Avatar types setup

The <AvatarTypes> section contains a list of <AvatarType> elements. This list is sent to the OpenSpace client during its initialization process. The <AvatarTypes> tag has the following attributes.

use8Directions Avatars can move along eight directions on the map, instead of four.
Valid values are 0 and 1; default value is 1.
   

Each <AvatarType> element defines an avatar type to be used on the client-side to create an avatar instance (see the IOpenSpace.createMyAvatar method description in the OpenSpace client-side API reference). Also, each element has the following attributes.

mainClass Fully qualified name of the custom ActionScript 3 class used by the OpenSpace client to render the main avatar.
Read the Avatar class description in the OpenSpace client-side API reference for more informations.
If this attribute is missing, the OpenSpace Extension initialization can't be completed!
ghostClass Fully qualified name of the custom ActionScript 3 class used by the OpenSpace client to render the ghost avatar.
Read the Avatar class description in the OpenSpace client-side API reference for more informations.
This attribute is optional, and by default it is not set.
stature The height of the avatar in pixels, used to check if the avatar can walk under passages.
The height property of the Avatar class is not used as it may lead to wrong results due to the isometric projection.
Valid values are greater than 0. Default value is 0.
terrains A comma-separated list of terrains on which that avatar is allowed to walk (provided that the default tile walkability is set to true).
Each listed terrain must exist in the <Terrains> section, otherwise it will be ignored. An asterisk can be used to declare that the avatar can walk on tiles with no terrain assigned. If this attribute is not set or it is set to an empty value, the default tile walkability is applied during the avatar movement. By default the attribute is not set.
Some examples:
(1) <AvatarType ... terrains="road,sand">pedestrian</AvatarType>
The pedestrian avatar can walk on tiles with terrain set to road and sand only
(2) <AvatarType ... terrains="road,sand,*">pedestrian</AvatarType>
The pedestrian avatar can walk on tiles with terrain set to road and sand, and on tiles with no terrain assigned
(3) <AvatarType ... terrains="*">pedestrian</AvatarType>
The pedestrian avatar can walk on tiles with no terrain assigned only
(4) <AvatarType ... terrains="">pedestrian</AvatarType>
Empty terrain assigned: default tile walkability is applied during the pedestrian avatar movement
(5) <AvatarType ...>pedestrian</AvatarType>
No terrain assigned: default tile walkability is applied during the pedestrian avatar movement