OpenSpace logo

Support » OpenSpace client-side configuration

The client-side engine of OpenSpace can be configured through a number of operational parameters which are common to the whole virtual environment. Additional parameters must be configured on the server-side, as described in the Server configuration manual.

The client-side settings are collected in an external configuration XML file which is loaded by the OpenSpace component during its initialization. The file path (including the file name) of the configuration file can be set at author-time in the Flash or Flex authoring tool by clicking on the OpenSpace component on the stage and accessing the Parameters tab in the Component Inspector panel (Flash) or the Flex Properties panel (Flex/Flash Builder). The name of the property to be set is Configuration path, and the default value is config/OpenSpace_client.xml. The path can also be configured at run-time, before initializing the OpenSpace instance, by means of the IOpenSpace.configPath property.

The configuration parameters are ideally divided into six groups: general engine settings, tiles rendering settings, camera settings, input controllers settings, map scrolling settings and avatar settings. Each setting is represented by an xml tag and all the tags are grouped under the main <OpenSpace> tag.

The following XML shows an example of configuration file containing the default values. If one or more parameters are missing, default values are applied by the OpenSpace engine.

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

	<!-- General engine parameters -->
	<CustomParamsSeparator>|</CustomParamsSeparator> 
	<ProcessedTilesPerFrame>60</ProcessedTilesPerFrame>
	<EditModeIdlePing>120</EditModeIdlePing>
	
	<!-- Tiles rendering parameters -->
	<TileSize>60</TileSize>
	<TileRatio>0.5</TileRatio>
	<ShowTileElevation>1</ShowTileElevation>
	<ShowWireframe>0</ShowWireframe>
	<SolidWireframe>0</SolidWireframe>
	<PlayModeOverSensor>0066FF;0</PlayModeOverSensor>
	<EditModeOverSensor>0066FF;0</EditModeOverSensor>
	<ValidDropSensor>00FF00;0.3</ValidDropSensor>
	<InvalidDropSensor>FF0000;0.3</InvalidDropSensor>
	<DragProxyAlpha>0.8</DragProxyAlpha>
	
	<!-- Camera parameters -->
	<FadeDuration>500</FadeDuration>
	<FadeEasingEq>Linear.easeNone</FadeEasingEq>
	<CameraPanSpeed>400</CameraPanSpeed>
	<PanEasingEq>Sine.easeOut</PanEasingEq>
	<BlurAmountOnCameraMove>10</BlurAmountOnCameraMove>
	<BlurQuality>1</BlurQuality>
	<ZoomDuration>500</ZoomDuration>
	<ZoomEasingEq>Sine.easeOut</ZoomEasingEq>
	<StaticTransitionDuration>500</StaticTransitionDuration>
	<StaticTransitionColor>FFFFFF</StaticTransitionColor>
	
	<!-- User input controller parameters -->
	<AvatarMouseControl>1</AvatarMouseControl>
	<UseHandCursor>0</UseHandCursor>
	<AvatarKeyboardControl>0</AvatarKeyboardControl>
	
	<!-- Scrolling parameters -->
	<ScrollOnPathCompletion>1</ScrollOnPathCompletion>
	<LeftScrollLimit>75</LeftScrollLimit>
	<LeftScrollAmount>50</LeftScrollAmount>
	<RightScrollLimit>75</RightScrollLimit>
	<RightScrollAmount>50</RightScrollAmount>
	<TopScrollLimit>75</TopScrollLimit>
	<TopScrollAmount>50</TopScrollAmount>
	<BottomScrollLimit>75</BottomScrollLimit>
	<BottomScrollAmount>50</BottomScrollAmount>
	<ScrollSpeed>400</ScrollSpeed>
	<ShowBlurOnScroll>1</ShowBlurOnScroll>
	<EnableContinuousScrolling>0</EnableContinuousScrolling>
	
	<!-- Avatar parameters -->
	<EnableAvatarMouseEvents>1</EnableAvatarMouseEvents>
	<EnableBringGhostToFront>1</EnableBringGhostToFront>
	<EnablePixelCollisionCheck>0</EnablePixelCollisionCheck>
	<SortAvatarsOnTile>1</SortAvatarsOnTile>

</OpenSpace>
			

The following sections describe all the settings in detail. Changing on or more parameters require the client to be restarted for the new configuration to take effect.

General engine parameters

This set of parameters controls some general behaviors of the OpenSpace engine.

<CustomParamsSeparator> The character that OpenSpace should use to split the custom parameters assigned to skin instances in the Tile editor of the OpenSpace Editor.
Default value is | (pipe).
<ProcessedTilesPerFrame> The number of tiles processed at each processing cycle during the map rendering process.
In OpenSpace the tiles rendering is distributed over multiple frames to avoid blocking the Flash Player: if a low number is set, the map rendering takes more time (in the order of seconds, also depending on the map size and its complexity) but the Flash Player doesn't slow down; an higher number instead reduces the rendering time but could make the Flash Player freeze for that time.
Default value is 60.
<EditModeIdlePing> The number of seconds between each keep alive message sent to SmartFoxServer by the OpenSpace client during runtime map editing.
When a player enters Edit mode, he stops sending messages to the server (path requests, avatar properties change, public or private messages, etc.). This could potentially cause a user disconnection due to the idle user timeout set in the SmartFoxServer configuration. To avoid the disconnection, during runtime map editing OpenSpace "pings" the server at the given interval.
Default value is 120; set to 0 to turn off the keep alive message.

Tiles rendering parameters

This set of parameters defines the tile size and appearance.

<TileSize> The width of the tiles, in pixels.
This setting is applied to all the maps loaded by OpenSpace (tile size is not intrinsic to the map).
Default value is 60.
<TileRatio> The aspect ratio of the tiles: it's the ratio between the height and width of the tile.
This value can be greater than 0 and lesser than or equal to 1; default value is 0.5.
<ShowTileElevation> Show the tiles elevation along the isometric z-axis.
Valid values are 0 and 1; default value is 1.
This parameter can be set to 0 only in conjunction with a tile ratio equal to 1, in order to have a top-down view of the map.
<ShowWireframe> Draw the tiles' wireframe, for debug purposes.
Valid values are 0 and 1; default value is 0.
<SolidWireframe> Draw the tiles' shaded faces of the tiles' wireframe, for debug purposes.
Valid values are 0 and 1; default value is 0.
This parameter has effect if <ShowWireframe> is set to 1 only.
<PlayModeOverSensor> The color and transparency of the tile's highlighting when the player moves the mouse cursor over a walkable tile in Play mode. Highlighting the tile shows the player the exact tile on which his avatar will be sent if the tile is clicked (and, of course, if a valid path to it exists).
The color must be expressed as an hexadecimal value; the transparency must be an alpha value comprised between 0 and 1 (the two values must be separated by a semicolon). Default value is 0066FF;0.
<EditModeOverSensor> The color and transparency of the tile's highlighting when the player moves the mouse cursor over a tile in Edit mode. Highlighting the tile shows the player the exact tile that will be selected if the tile is clicked (and, of course, if that tile is — or is part of — a selectable map item).
The color must be expressed as an hexadecimal value; the transparency must be an alpha value comprised between 0 and 1 (the two values must be separated by a semicolon). Default value is 0066FF;0.
<ValidDropSensor> The color and transparency of the tile's highlighting when the player drags an inventory or map item over one or more valid tiles in Edit mode. Highlighting the tile/s shows the player the exact position where the item will placed when dropped on the map.
The color must be expressed as an hexadecimal value; the transparency must be an alpha value comprised between 0 and 1 (the two values must be separated by a semicolon). Default value is 00FF00;0.3.
<InvalidDropSensor> The color and transparency of the tile's highlighting when the player drags an inventoryor map item over one or more invalid tiles in Edit mode. Highlighting the tile/s gives the player the immediate feedback that the dragged item can't be dropped in that position.
The color must be expressed as an hexadecimal value; the transparency must be an alpha value comprised between 0 and 1 (the two values must be separated by a semicolon). Default value is FF0000;0.3.
<DragProxyAlpha> The transparency to be applied to inventory item or map item proxies when dragged on the map. It must be an alpha value comprised between 0 and 1; default value is 0.8.

Camera parameters

This set of parameters controls the viewport behavior during pan, zoom and map scrolling (mainly speed and applied effects). More scrolling-related parameters are defined in a specific section of the configuration.
See the IOpenSpace.panView and IOpenSpace.zoomView methods description in the OpenSpace client-side API reference for more informations.

<FadeDuration> The duration, in milliseconds, of the fade-in and fade-out transitions occurring when the map is rendered and reset respectively.
Default value is 500; set to 0 to disable the transition effect.
<FadeEasingEq> The easing equation used in fade-in and fade-out map transitions.
See the fl.motion.easing package (Flash) or the mx.effects.easing package (Flex) documentation for a description of possible values.
Default value is Linear.easeNone.
<CameraPanSpeed> The camera speed, expressed in pixels/sec, during a pan action.
Default value is 400; set to 0 for a discontinuous camera movement (the viewport "jumps" to the target position immediately).
<PanEasingEq> The easing equation used during viewport panning.
See the fl.motion.easing package (Flash) or the mx.effects.easing package (Flex) documentation for a description of possible values.
Default value is Sine.easeOut.
<BlurAmountOnCameraMove> The amount of motion blur effect applied to the viewport during a pan or zoom action, or during map scrolling caused by the avatar movement (see next section).
Default value is 10; set to 0 to disable the blur effect.
<BlurQuality> The quality of the motion blur effect applied to the viewport during a pan or zoom action, or during map scrolling.
Valid values are in the range between 1 and 3; default value is 1.
<ZoomDuration> The duration, in milliseconds, of the zoom-in and zoom-out transitions during a zoom action.
Default value is 500; set to 0 to disable the transition effect and obtain a discontinuous camera movement (the viewport "jumps" to the target zoom factor immediately).
<ZoomEasingEq> The easing equation used during viewport zooming.
See the fl.motion.easing package (Flash) or the mx.effects.easing package (Flex) documentation for a description of possible values.
Default value is Sine.easeOut.
<StaticTransitionDuration> The duration, in milliseconds, of the fading-out transition displayed on discontinuous camera movements. When a discontinuous camera movement occurs, for example on avatar teleporting to a new location, a rapidly fading-out flash effect is displayed. The flashing color can be set by means of the <StaticTransitionColor> setting.
Default value is 500; set to 0 to disable the transition effect.
<StaticTransitionColor> The color of the fading-out transition displayed on discontinuous camera movements. Default value is FFFFFF.

User input controller parameters

This set of parameters defines the controller that players will use to move their avatars on the map.

<AvatarMouseControl> Use the mouse to control the avatar movement on the map, by clicking the destination tile.
Valid values are 0 and 1; default value is 1. Even if set to 0, mouse control is still enabled for interaction with map objects and during runtime map editing.
<UseHandCursor> Show the mouse hand cursor on clickable tiles if the mouse controller is used.
Valid values are 0 and 1; default value is 0.
<AvatarKeyboardControl> Use the keyboard to control the avatar movement on the map, by means of the arrow keys. The keyboard control can be enable together with the mouse control.
Valid values are 0 and 1; default value is 0.

Scrolling parameters

This set of parameters controls the specific behavior of OpenSpace with respect to the map scrolling caused by the avatar movements on the map. The scrolling animation is triggered by the avatar stepping on a tile whose center is beyond the limits of a virtual scroll sensor area.

The size of the scroll sensor area is determined by the <...ScrollLimit> parameters described below, as a percentage of half the viewport size in the corresponding direction. The area can be asymmetric.

The scroll amount is determined by the <...ScrollAmount> parameters, as a percentage of the whole scroll sensor area. These parameters indicate the position that the player's avatar will have at the end of the scrolling animation, with respect to the scroll sensor area: if set to 0, the scroll amount is the minimum required to bring the avatar back inside the sensor area; if set to 50 the avatar is centered in the sensor area; if set to 100 the scrolling will end when the avatar is at the opposite side of the sensor area.

<ScrollOnPathCompletion> Scroll the map when the player's avatar reaches the target coordinates only.
Valid values are 0 and 1; default value is 1. If set to 0, the scrolling occurs as soon as the avatar crosses the scroll sensor area described by the <...ScrollLimit> parameters. This setting is ignored if the avatar goes past the viewport limits during the movement: in this case the scrolling occurs immediately, even if the avatar has not reached its destination yet.
<LeftScrollLimit> The scroll sensor area left limit, defined as a percentage of the viewport's left half.
Valid values are in the range between 0 and 100; default value is 75.
<LeftScrollAmount> The scroll amount in the right direction when the avatar crosses the scroll sensor area left limit; the value is a percentage of the whole scroll sensor area.
Valid values are in the range between 0 and 100; default value is 50.
<RightScrollLimit> The scroll sensor area right limit, defined as a percentage of the viewport's right half.
Valid values are in the range between 0 and 100; default value is 75.
<RightScrollAmount> The scroll amount in the left direction when the avatar crosses the scroll sensor area right limit; the value is a percentage of the whole scroll sensor area.
Valid values are in the range between 0 and 100; default value is 50.
<TopScrollLimit> The scroll sensor area top limit, defined as a percentage of the viewport's top half.
Valid values are in the range between 0 and 100; default value is 75.
<TopScrollAmount> The scroll amount in the down direction when the avatar crosses the scroll sensor area top limit; the value is a percentage of the whole scroll sensor area.
Valid values are in the range between 0 and 100; default value is 50.
<BottomScrollLimit> The scroll sensor area bottom limit, defined as a percentage of the viewport's bottom half.
Valid values are in the range between 0 and 100; default value is 75.
<BottomScrollAmount> The scroll amount in the up direction when the avatar crosses the scroll sensor area bottom limit; the value is a percentage of the whole scroll sensor area.
Valid values are in the range between 0 and 100; default value is 50.
<ScrollSpeed> The speed of map scrolling, expressed in pixels/sec.
An easing equation is applied to the scrolling animation according to the <PanEasingEq> parameter described above.
Default value is 400; set to 0 for a discontinuous map movement (the map "jumps" to the target position immediately).
<ShowBlurOnScroll> Show a motion blur effect during the scrolling animation, accroding to the <BlurAmountOnCameraMove> and <BlurQuality> parameters described above.
Valid values are 0 and 1; default value is 1.
<EnableContinuousScrolling> Enable continuous map scrolling. Combined with proper values assigned to the <...ScrollLimit> parameters described above, this setting can force the camera to follow the player's avatar continuously.
This feature affects the Flash Player performances negatively, because the map scrolls pixel-by-pixel during the avatar movement; for this reason it should be enabled after accurate testing only.
Valid values are 0 and 1; default value is 0. When set to 1, <ScrollOnPathCompletion>, <...ScrollAmount>, <ScrollSpeed> and <PanEasingEq> parameters described above have no effect.

Avatar parameters

This parameters set some OpenSpace behaviors when handling the avatars. Additional mandatory avatar parameters must be declared in the OpenSpace server-side configuration.

<EnableAvatarMouseEvents> Enable click, roll over and roll out mouse events on all the avatars.
When mouse events are enabled, listeners to the AvatarEvent.CLICK, AvatarEvent.ROLL_OVER and AvatarEvent.ROLL_OUT event types can be added to the OpenSpace component.
This feature is independent of the active controller type (mouse or keyboard): mouse interaction with avatars can be enabled even if the <AvatarMouseControl>parameter is set to 0.
Valid values are 0 and 1; default value is 1.
<EnableBringGhostToFront> Enable the ghost avatar click to bring it to front with respect to the overlapping ghosts.
Read the Avatar class description in the OpenSpace client-side API reference for more informations on the ghost avatar.
Valid values are 0 and 1; default value is 1.
<EnablePixelCollisionCheck> Enable advanced pixel overlapping detection technique for more accurate avatar rendering.
Due to the way OpenSpace handles tiles z-sorting, when a slow avatar animation speed (see the OpenSpace server-side configuration) is combined with avatar graphics which tend to occupy the whole tile area, a wrong avatar-tile overlapping could be noticed in certain movement conditions:

By means of this parameter it is possible to correct this issue and make OpenSpace render the avatars properly:

This feature affects the Flash Player performances negatively, in particular when a large number of avatars is displayed in the viewport; for this reason it should be enabled after accurate testing only.
Valid values are 0 and 1; default value is 0.
<SortAvatarsOnTile> Adjust the z-sorting of avatars placed on the same tile, according to their y orthogonal coordinate.
Valid values are 0 and 1; default value is 1.