OpenSpaceOpenSpace v1 installation

All the OpenSpace installation files are contained in the downloaded package in the respective folders.
Offline documentation and full examples are also provided.

Flash components

In order to install the OpenSpace in the Flash authoring environment double click on the OpenSpace.mxp extension package file located in the Flash components folder and follow the instructions. The extension contains the following components:

OpenSpace The OpenSpace component is responsible of rendering the environments built with the OpenSpace Editor desktop application, handling user interaction with environments, rendering avatars appearance and animation, handling communication with SmartFoxServer to broadcast avatar status and movements, dispatch environment and avatar related events to the main application, etc.
The component can be controlled by means of the OpenSpace API.
AvatarLibrary The AvatarLibrary component is a non-visual component containing the IAvatarMovieClip interface and AvatarEvent class required to compile a custom avatar's movieclip class.
HelperGrid
HelperGrid2
The HelperGrid and HelperGrid2 components are accessory components useful to design isometric maps in the Flash authoring environment before implementing them in the OpenSpace Editor application.

 

OpenSpace Editor v1 desktop application

In order to install the OpenSpace Editor you need to have the Adobe Air Runtime installed on your system (Windows XP SP2 or higher / Mac OSX 10.4.11 or higher). You can get it at this url: http://get.adobe.com/air/

To install the Editor double click on the OpenSpaceEditor.air file located in the Editor folder and follow the instructions. Please notice that the application is not digitally signed, so a warning will be displayed.

 

OpenSpaceOpenSpace v1 configuration

The OpenSpace Engine can be configured through a number of operational parameters which are common to all the virtual environments loaded at run-time.

These global 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), can be set at author-time in the Flash authoring tool by accessing the OpenSpace component’s Property Inspector panel and editing the Config path property. The path can also be configured at run-time, before initializing the OpenSpace instance, by means of the OpenSpace.configPath property.

The configuration parameters are ideally divided into four groups: map rendering settings, controller settings, scrolling settings and avatar settings. Each setting is represented by an xml tag (except some avatar parameters which are grouped in a sub-section and are described by multiple tag attributes). All the tags are grouped under the main tag <OpenSpace>.

The following xml shows an example of configuration file containing the default values (except the <AvatarType> element which contains example values). If one or more parameters are missing, default values are applied by the OpenSpace Engine.

<?xml version="1.0" encoding="UTF-8"?>
<OpenSpace>
	<!-- Map rendering parameters -->
	<TileSize>60</TileSize>
	<TileRatio>0.5</TileRatio>
	<ShowTileElevation>1</ShowTileElevation>
	<ShowTilesGrid>0</ShowTilesGrid>
	<ShowTilesFill>0</ShowTilesFill>
	<TileCustomParamsSeparator>|</TileCustomParamsSeparator>
	<ProcessedTilesPerFrame>60</ProcessedTilesPerFrame>
	
	<!-- Controller parameters -->
	<ControllerType>mouse</ControllerType>
	<Use8Directions>1</Use8Directions>
	<UseHandCursor>1</UseHandCursor>
	
	<!-- Scrolling parameters -->
	<UseSmartScrolling>1</UseSmartScrolling>
	<ScrollSensorSize>75</ScrollSensorSize>
	<ScrollPercentage>50</ScrollPercentage>
	<ScrollTime>250</ScrollTime>
	<ScrollTransition>easeOutSine</ScrollTransition>
	<UseContinuousScrolling>0</UseContinuousScrolling>
	
	<!-- Avatar parameters -->
	<EnableAvatarMouseEvents>1</EnableAvatarMouseEvents>
	<UseHandCursorOnAvatars>1</UseHandCursorOnAvatars>
	<EnablePixelCollisionCheck>0</EnablePixelCollisionCheck>
	
	<AvatarTypes>
		<AvatarType type="dummy"
			className="DummyAvatarMovieClip"
			animTime="300"
			stature="30"
			cp0="0,5" cp1="-10,0" cp2="0,-5" cp3="10,0" />
	</AvatarTypes>
</OpenSpace>

The following tables describe all the available settings.

Map rendering

<TileSize> The width of the tiles, in pixels.
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 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.
<ShowTilesGrid> Draw the tiles' wireframe, for debug purposes.
Valid values are 0 and 1; default value is 0.
<ShowTilesFill> Draw the tiles' shaded wireframe, for debug purposes.
Valid values are 0 and 1; default value is 0.
This parameter has effect only if <ShowTilesGrid> is set to 1.
<TileCustomParamsSeparator> The character that OpenSpace should use to split the parameters assigned to tiles in the OpenSpace Editor (check the Editor's documentation, Tile Editor chapter, OLD_customParams parameter).
Default value is "|" (pipe).
<ProcessedTilesPerFrame> The number of tiles processed at each Flash processing cycle during the map rendering process.
In OpenSpace the initial 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 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.

Controller

<ControllerType> The controller enabled for user interaction.
Valid values are mouse (the user clicks on the destination tile to make the avatar move autonomously) and keyboard (the user controls his/her avatar using the arrow keys); default value is mouse.
<Use8Directions> Avatars can move along eight directions instead of four.
Valid values are 0 and 1; default value is 1.
<UseHandCursor> Show the mouse hand cursor on clickable tiles (for mouse controller only).
Valid values are 0 or 1; default value is 1.

Scrolling

<UseSmartScrolling> Activate the "smart scrolling" feature: when tiles are not visible, OpenSpace removes them from stage to improve scrolling performance.
Valid values are 0 and 1; default value is 1.
<ScrollSensorSize> Size of the scroll sensor area, as a percentage of the main viewport size.
Valid values range from 0 to 100; default value is 75.
Scrolling starts when the avatar of the current user reaches the center of a tile which is beyond the boundaries of the scroll sensor area.
If this property is set to 0 the scroll area doesn't exist and the scrolling occurs each time the avatar steps on a new tile; is set to 100 the scroll area fills the entire viewport and scrolling occurs only if the avatar steps on a tile whose center is outside the viewport limits.
<ScrollPercentage> The scrolling amount, as a percentage of the scroll sensor area.
Valid values range from 0 to 100; default value is 50.
This property indicates the position that the avatar of the current user will have at the end of the scrolling animation, with respect to the scroll sensor area: if set to 0, the scrolling amount is the minimum required to bring the avatar back inside the area; if set to 50 the avatar is centered in the viewport; if set to 100 the scrolling will end when the avatar is at the opposite side of the scroll sensor area.
<ScrollTime> The duration, in milliseconds, of a 100 pixels scrolling; for different scrolling amounts a correction is applied to have a constant scrolling speed.
Default value is 250.
<ScrollTransition> The transition type to be applied to the scrolling animation.
See http://hosted.zeh.com.br/tweener/docs/en-us/misc/transitions.html for valid values; default is easeOutSine.
<UseContinuousScrolling> Enable continuous map scrolling.
This feature affects the Flash Player performances negatively, because the viewport scrolls pixel-by-pixel during the movement of the avatar on the map; 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 <ScrollPercentage>, <ScrollTime> and <ScrollTransition> parameters are ignored.

Avatars

<EnableAvatarMouseEvents> Enable click, roll over and roll out mouse events on all the avatars.
Valid values are 0 and 1; default value is 1.
When enabled, listeners to the AvatarEvent.CLICK, AvatarEvent.ROLL_OVER and AvatarEvent.ROLL_OUT event types can be added to the OpenSpace class.
NOTE: this feature is independent from the selected controller type; mouse interaction with avatars can be enabled even if the keyboard controller is used.
<UseHandCursorOnAvatars> Show the mouse hand cursor on avatars if mouse events are enabled.
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 depths on the stage, when a slow avatar animation speed (see the animTime parameter in the following table) 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.

The available avatar types are listed in the <AvatarTypes> section (usually each application makes use of a single avatar type). See the IAvatarMovieClip interface API reference and OpenSpace.createMyAvatar method description for additional informations. Each <AvatarType> element contains the following attributes.

type The avatar identifier. This string must be passed to the OpenSpace.createMyAvatar method to generate the proper avatarand assign it to the current user.
className Name of the avatar movieclip class contained in the avatars library, as entered in the Linkage Properties panel of the Flash authoring tool. A reference to the avatars library is passed to the OpenSpace.initialize method.
animTime

The time, in milliseconds, it takes to the avatar to move from one tile to the next one along diagonal directions (the proper correction is applied for the vertical and horizontal directions).

stature The height of the avatar, used to check if the avatar can walk under over-passes.
cp0...cp3 The four control points which "describe" the avatar projection on the ground.

OpenSpace makes use of these control points to check the avatar position with respect to the tile, to decide whether the avatar has reached the next tile during movement or not. They are also used when the <EnablePixelCollisionCheck> parameter is set to 1, to check the overlapping of avatars and surrounding objects. Setting the control points is optional: if not set, the avatar (0,0) coordinate (which should be located between the avatar's feet, the + in the picture above) is used by the OpenSpace Engine. This is usually enough to have an excellent avatar behavior.
Note: if set, the control points position can't exceed the tile size.