Space File IDs and Configuration Formats

From Digital Spaces

Contents 1 3D Scenegraph Manager 1.1 Configuration IDs 1.1.1 scene 1.2 Example 2 3D Visuals 2.1 Configuration IDs 2.2 Example 3 Resource Management 3.1 Configuration IDs 3.1.1 searchpath 3.2 Example 4 GUI 4.1 Configuration IDs 4.1.1 scheme 4.1.2 defaultcursor 4.1.3 defaultfont 4.1.4 layout 4.2 Example 5 User Input 5.1 Configuration IDs 5.1.1 map 5.1.1.1 event 5.2 Common Configuration 5.2.1 SimulationControl_FPSCamera 5.2.2 HumanAvatar 5.2.3 GUI_CEGUI 5.2.4 Vehicle Agent Controller 5.3 Example 6 Script Interpreter 6.1 Configuration IDs 6.1.1 heartbeatscript 6.2 Example 7 Physics Simulation 7.1 Configuration IDs 7.2 Example 8 Agent Management 8.1 Configuration IDs 8.1.1 template 8.1.2 agent 8.1.3 Example

3D Scenegraph Manager

ID: {4BC0FC3A-6ADA-4302-A770-1706CE7BBBF4} - DI3DScenegraphManager1

Reference Implementation: SGManager

Configuration IDs

{3F139EEC-0EEE-4062-9914-BB7DC58F7B2E} - DID_SceneManagerConfiguration

scene

Multiple scene entries are supported. Also available as <extern>. If the node has no children, it is checked for:

• src - string - Path / identifier of a .scene format file.

Otherwise, the node is expected to be the root of a .scene format XML chunk. NOTE: Specifying a .scene formatted chunk in the .space file will probably result in failure with the current implementation.

Example

<required id="{4BC0FC3A-6ADA-4302-A770-1706CE7BBBF4}" >
	<configuration id="{3F139EEC-0EEE-4062-9914-BB7DC58F7B2E}">
		<scene src="example.scene" />
	</configuration>
</required>
 

3D Visuals

ID: {9DCE6830-EBA8-44a0-88C1-B7FE386B5E07} - DI3DVisuals1

Reference Implementation: 3DVisuals_OGRE

Configuration IDs

None.

NOTE: Previously the configuration ID {1661521C-9E30-42e9-86EF-7129669B5F89} was DID_3DVisualsOgreConfigure1. However this format only contained information for setting up the Ogre resource manager paths. In revision 456, this ID is now DID_DataResourceManagerConfiguration, as the ResourceManager implementation now handles this task. Due to the ResourceManager implementation being garenteed to be loaded and available, the configuration information is correctly parsed.

Example

Old format. This is still compatible, but is deprecated.

<required id="{9DCE6830-EBA8-44a0-88C1-B7FE386B5E07}" >
	<configuration id="{1661521C-9E30-42e9-86EF-7129669B5F89}">
		<searchpath src="." />
		<searchpath src="./textures" />
	</configuration>
</required>
 

Recommended format. Use with Resource Management as shown below.

<required id="{9DCE6830-EBA8-44a0-88C1-B7FE386B5E07}" />
 

Resource Management

The reference Resource Management component is always loaded before any other. As such, it is not technically neccessary to specify that it is required. ID: {9CEC16F5-F8AE-4f37-8795-9FA2C3160D87} - DIDataResourceManager

Reference Implementation: ResourceManager class in DigitalSpacesCore

Configuration IDs

{9DCE6830-EBA8-44a0-88C1-B7FE386B5E07} - DID_DataResourceManagerConfiguration

searchpath

Multiple searchpath entries are supported.

• src - string - Path where resources can be located.

This should be a path to a file container. Currently, local directories (C:\Path\To\Space) and HTML index files are supported. Local directories can be specified as relative to the folder the .space file is located in.

NOTE: The current path testing is limited. If the path contains a colon : then it is considered an absolute path. Otherwise it attempts to add it as a local path, by stripping any leading "./" from the provided path, then appending it to the .space files containing directory.

When adding a path, it first checks for a file.index available at that path (both when working locally and remotely). This is a HTML index file. If found, it will be used and override any other file discovery mechanism. When working with an online folder (eg a HTTP path), if the server does not generate folder indexes, then the use of a file.index is a suitable replacement. For an example, see like http://www.digitalspaces.net/welcome/ . No directory content index is generated, but because there is a file.index ( http://www.digitalspaces.net/welcome/file.index ) this is used. Additionally, if the folder index was a human targeted HTML file (such as an index.html) then the presence of the file.index file allows it to still be used.

The file.index format is designed to be compatible with the indexes automatically generated by the popular web server applications. In essence, they are a set of <a> links, with the href value being used to access the content, and the text contents of the <a> tag as the "file path" used when referring to the file from other resources. For example:

<html>
<body>
<a href="index.space">index.space</a>
<a href="myscene.scene">myscene.scene</a>
 
<a href="subfolder/texture.jpg">texture.jpg</a>
<a href="http://example.com/texture2.jpg">othertexture.jpg</a>
</body>
</html>
 

The above example shows a basic file, with some rename tricks. After loading this exmaple, the Resource Manager would know of 4 resources, available as "index.space", "myscene.scene", "texture.jpg" and "othertexture.jpg". These are the names that other components can request these resources by. The Resource Manager will internally perform the neccessary conversion of the href properties, and provide the resources irrespective of where they are stored.

If the HTML index file is not valid XML, it will not be parsed correctly (even if a web browser will display it).

Adding a searchpath is not recursive. So if you had

• models
  • vehicles
  • furniture

the configuration <searchpath src="models" /> would not add any files in the vehicles and furniture folders. For this, you should use

<searchpath src="models" />
<searchpath src="models/vehicles" />
<searchpath src="models/furniture" />
 

Example

<required id="{9CEC16F5-F8AE-4f37-8795-9FA2C3160D87}">
	<configuration id="{1661521C-9E30-42e9-86EF-7129669B5F89}">
		<searchpath src="." />
		<searchpath src="./textures" />
	</configuration>
</required>
 

GUI

ID: {0FAAF303-F452-4eee-A352-8FC6BB2788B9} - DI3DVisualsGUI1

Reference Implementation: GUI_CEGUI

The reference implementation requires the presence of DIUserInput1, and will fail to load if it is not also specified in the .space file. See User Input below.

Configuration IDs

{8A24B303-2FE1-4f2c-9B3E-23534A3EC3C7} - DID_CEGUIConfiguration1

These configuration options are all CEGUI specific, and use CEGUI formatted data files. See http://www.cegui.org.uk/ for documentation on these formats.

scheme

If not specified, default DigitalSpaces.scheme is used.

• src - string - path to a CEGUI .scheme format.

defaultcursor

If not specified, default cursor is used.

• imageset - string - Imageset to locate image in.
• imagename - string - Name of image in imageset to use as cursor.

defaultfont

If not specified, the first font specified in the CEGUI .scheme is used.

• name - string - The .font definition file to use.

layout

Multiple layout entries are supported.

• src - string - path to a CEGUI .layout format file.

Example

Use all defaults:

<required id="{0FAAF303-F452-4eee-A352-8FC6BB2788B9}"/>
 

Fully custom settings:

<required id="{0FAAF303-F452-4eee-A352-8FC6BB2788B9}">
	<configuration id="{8A24B303-2FE1-4f2c-9B3E-23534A3EC3C7}" >
		<scheme src="CustomCEUI.scheme" />
		<defaultcursor imageset="CustomImages" imagename="CustomCursor" />
		<defaultfont name="CustomFont" />
 
		<layout src="MyWindows.layout" />
		<layout src="MyOtherWindows.layout" />
	</configuration>
</required>
 

User Input

ID: {8B125698-7D02-4015-934A-83EA89D36E55}

Reference Implementation: UserInput_DirectInput

Configuration IDs

{B11EFB3C-E3C6-4df8-9BBD-61F56B82F70B} - DID_UserInputOGREConfiguration

{E1D80EF9-94AA-41d6-B26A-067FEF421B2E} - DID_UserInputDirectInputConfiguration1

These two configuration formats are synonymous. DID_UserInputOGREConfiguration was implemented by the previous reference implementation. When creating the new reference implementation, a new configuration ID was generated, but has never been distinguished. The current reference implementation accepts both identifiers.

map

Multiple map elements are supported.

• signal - string - Identifier the singal will be accessed by. Ones commonly used by the reference implementations are:

event

Multiple event elements are supported. Event elements are additive, not ANDed. Thus triggering two events for the same map (pressing two keys at once) will double the level of the signal, and depending on the implementation, may double the effect the signal triggers. There is currently no way to have a ANDed signal, i.e. requiring two keys to be pressed to trigger the signal. An example where this could be used is a "run" effect, where pressing Shift while pressing the forward arrow key would increase the speed the user representation moves at.

• code - string - A string code that identifies which physical device to use to produce this signal. See UserInputDirectInputConfiguration1 input codes for a full list.
• type - string - Not used. Was added to the specification with the intention of having different types of events, such as toggle switches (where pressing a key once would activate the state, again would deactivate it). The initial specification only defined one value, "switch", which is on when key is down, off when key is up.
• multiplier - float - Used to scale the signal produced. While commonly signals range from 0.0 to 1.0, this is not always the case, and often not the desired behaviour, especially when using they keyboard. A common example is using the keyboard to produce HAPTIC_XAXIS and HAPTIC_YAXIS signals, which are expected to range from -32768 to 32768.

Common Configuration

The reference implementation does not provide any default mappings (except for KC_SYSREQ to PRINTSCREEN), so the "standard" mappings must be specified. Signals used by reference implementations:

SimulationControl_FPSCamera

• FORWARD - Used to move the camera (viewpoint) "forward", i.e. the direction it is displaying.
  • KC_UP - 10.0 - The multiplier affects the speed the camera will move at. E.g. 10.0 means the camera will move at 10 meters per second.
• STRAFE_LEFT - Not used in our default set ups. First Person Shooter style movement really needs mouse-look, and current implementation doesn't allow seperation between mouse-look and cursor movement. Moves the camera sideways (left), relative to its facing direction.
• STRAFE_RIGHT - Not used in our default set ups. First Person Shooter style movement really needs mouse-look, and current implementation doesn't allow seperation between mouse-look and cursor movement. Moves the camera sideways (right), relative to its facing direction.
• BACKWARD - Used to move the camera (viewpoint) "backward", i.e. in reverse of the direction it is displaying.
  • KC_DOWN - 10.0 - The multiplier affects the speed the camera will move at. E.g. 10.0 means the camera will move at 10 meters per second.
• TURN_LEFT - Used to rotate the camera (viewpoint) left around the cameras upward axis.
  • KC_LEFT - 1.0 - The multiplier affects the speed the camera will rotate at. E.g. 1.0 means that camera will rotate at 1.0 radians per second.
  • Example for Mouse Look: MA_X_NEG - 0.1
• TURN_RIGHT - Used to rotate the camera (viewpoint) right around the cameras upward axis.
  • KC_RIGHT - 1.0 - The multiplier affects the speed the camera will rotate at. E.g. 1.0 means that camera will rotate at 1.0 radians per second.
  • Example for Mouse Look: MA_X_POS - 0.1
• LOOK_UP - Used to rotate the camera (viewpoint) up around the cameras horizontal axis.
  • KC_PGUP - 0.5 - The multiplier affects the speed the camera will rotate at. E.g. 0.5 means that camera will rotate at 0.5 radians per second.
  • Example for Mouse Look: MA_Y_NEG - 0.1
• LOOK_DOWN - Used to rotate the camera (viewpoint) down around the cameras horizontal axis.
  • KC_PGDOWN - 0.5 - The multiplier affects the speed the camera will rotate at. E.g. 0.5 means that camera will rotate at 0.5 radians per second.
  • Example for Mouse Look: MA_Y_POS - 0.1

HumanAvatar

Uses DIEventProvider::SubscribeEvent/DIEventSubscriber::ReceiveEvent rather then DIUserInput1::QuerySignal. This means it can only work with the keyboard, which supplies true/false for keypress/keyup occurences.

• AGENT_FORWARD - Moves the agent (avatar) forward.
  • KC_UP - 1.0 - The multiplier has no effect
• AGENT_BACKWARD - Moves the agent (avatar) backward.
  • KC_DOWN - 1.0 - The multiplier has no effect
• AGENT_MOVE_LEFT - Not used in our default setups. Performs a strafe/sidestep to the left.
• AGENT_MOVE_RIGHT - Not used in our default setups. Performs a strafe/sidestep to the right.
• AGENT_ROTY+ - Rotates the avatar to the left, around the vertical axis.
  • KC_LEFT - 1.0 - The multiplier has no effect
• AGENT_ROTY- - Rotates the avatar to the right, around the vertical axis.
  • KC_RIGHT - 1.0 - The multiplier has no effect
• JUMP - Lifts the avatar into the air. Holding this for a second causes the avtar to begin flight mode. Flight mode stops when the avatar collides with an object.
  • KC_SPACE - 1.0 - The multiplier has no effect
• CROUCH - Lowers the avatar in the air when in flight mode. Has no effect outside flight mode.
  • KC_LCONTROL - 1.0 - The multiplier has no effect

GUI_CEGUI

GUI_CEGUI uses QueryEvent to track the state of the mouse, and DIUserInputKeyboard1::GetKeyEvent to track keys.

• MOUSE_X_ABS - X position of the mouse
  • MA_X - 1.0
• MOUSE_Y_ABS - Y position of the mouse
  • MA_Y - 1.0
• MOUSE_CLICK - State of the (left) mouse button. 1.0 is mouse button down, 0.0 is mouse button up.
  • MB_1 - 1.0

Vehicle Agent Controller

The Vheicle Agent Controller was designed to read a joystick and control a vehicle. It is hard coded to use any additional pheripheral found, such as a joystick or gamepad. Additionally, other input devices can be used to construct the signals, for reasons such as keyboard control.

NOTE: Because the UserInput_DirectInput component adds signals, sending the same signal via two devices (ie, pressing forward on a joystick as well as a keyboard) may cause a vehicle to travel at a higher rate then is possible alone.

• HAPTIC_XAXIS - Analog input device (joystick) horizontal axis. Used for steering. Values range from -32768 to 32768.
  • KC_A - -30000 - Provides an alternative to the left half of the joystick axis, allows turning left. -30000 is used so the keypress is equivalent to most of the way along the axis. This is binary, signal goes from 0 to -30000 immediately.
  • KC_D - 30000 - Provides an alternative to the right half of the joystick axis, allows turning right. 30000 is used so the keypress is equivalent to most of the way along the axis. This is binary, signal goes from 0 to 30000 immediately.
• HAPTIC_YAXIS - Analog input device (joystick) vertical (forward/back) axis. Used for acceleration. Values range from -32768 to 32768.
  • KC_W - -30000 - Provides an alternative to the forward half of the joystick axis, allows moving forward. -30000 is used so the keypress is equivalent to most of the way along the axis. This is binary, signal goes from 0 to -30000 immediately.
  • KC_S - 30000 - Provides an alternative to the lower half of the joystick axis, allows reversing. 30000 is used so the keypress is equivalent to most of the way along the axis. This is binary, signal goes from 0 to 30000 immediately.
• HAPTIC_BUTTON0 - Handbrake - Vehicle mode HANDBRAKE - This is more a brake than a handbrake, i.e. it is only applied while pressed. However it's expected the vehicle will bring it's wheels to a full halt as quickly as it is able to.
  • KC_E - 1
• HAPTIC_BUTTON1 - Activate Car mode (for multimode vehicles) - Vehicle mode CAR
  • KC_R - 1
• HAPTIC_BUTTON2 - Activate Tank mode (for multimode vehicles) - Vehicle mode TANK
  • KC_F - 1
• HAPTIC_BUTTON3 - Raise the powered suspension (if available) - Vehicle mode SUSPENSION, applies positive value.
  • KC_Z - 1
• HAPTIC_BUTTON4 - Lower the powered suspension (if available) - Vehicle mode SUSPENSION, applies negative value.
  • KC_X - 1
• HAPTIC_BUTTON5 - Temporarily activate boost (speed multiplier) - Vehicle mode BOOST
  • KC_T - 1

Example

<required id="{8B125698-7D02-4015-934A-83EA89D36E55}" >
	<configuration id="{B11EFB3C-E3C6-4df8-9BBD-61F56B82F70B}" >
		<map signal="FORWARD" >
			<event code="KC_UP" type="switch" multiplier="10" />
		</map>
		<map signal="BACKWARD" >
			<event code="KC_DOWN" type="switch" multiplier="10" />
		</map>
		<map signal="TURN_LEFT" >
			<event code="KC_LEFT" type="switch" multiplier="1.0" />
		</map>
		<map signal="TURN_RIGHT" >
			<event code="KC_RIGHT" type="switch" multiplier="1.0" />
		</map>
		<map signal="LOOK_UP" >
			<event code="KC_PGUP" type="switch" multiplier="0.5" />
		</map>
		<map signal="LOOK_DOWN" >
			<event code="KC_PGDOWN" type="switch" multiplier="0.5" />
		</map>
		<map signal="JUMP" >
			<event code="KC_SPACE" type="switch" multiplier="1.0" />
		</map>
		<map signal="MOUSE_X_ABS">
			<event code="MA_X" type="switch" multiplier="1.0" />
		</map>
		<map signal="MOUSE_Y_ABS">
			<event code="MA_Y" type="switch" multiplier="1.0" />
		</map>
		<map signal="MOUSE_CLICK">
			<event code="MB_1" type="switch" multiplier="1.0" />
		</map>
		<map signal="HAPTIC_XAXIS">
			<event code="KC_A" stype="switch" multiplier="-30000" />
			<event code="KC_D" stype="switch" multiplier="30000" />
		</map>
		<map signal="HAPTIC_YAXIS">
			<event code="KC_W" stype="switch" multiplier="-30000" />
			<event code="KC_S" stype="switch" multiplier="30000" />
		</map>
		<map signal="HAPTIC_BUTTON0">
			<event code="KC_E" stype="switch" multiplier="1" />
		</map>
		<map signal="HAPTIC_BUTTON1">
			<event code="KC_R" stype="switch" multiplier="1" />
		</map>
		<map signal="HAPTIC_BUTTON2">
			<event code="KC_F" stype="switch" multiplier="1" />
		</map>
		<map signal="HAPTIC_BUTTON3">
			<event code="KC_Z" stype="switch" multiplier="1" />
		</map>
		<map signal="HAPTIC_BUTTON4">
			<event code="KC_X" stype="switch" multiplier="1" />
		</map>
		<map signal="HAPTIC_BUTTON5">
			<event code="KC_T" stype="switch" multiplier="1" />
		</map>
	</configuration>
</required>
 

Script Interpreter

ID: {A07E78D6-1F91-414a-9ED8-4A0AC7CF055C} - DIScriptInterpreter

Reference Implementation: Script_Python

Configuration IDs

{1BF2273B-7C88-4eab-9325-44DBF8AD5EC8} - DID_ScriptInterpreterConfiguration

heartbeatscript

Multiple heartbeatscript elements are permitted.

• src - string - Path / identifier of a script file

NOTE: Scripts are interpreted at load time, and executed each heartbeat (10ms or 100 times a second). Variable state is kept across runs, so data can be collected once and kept.

Example

<required id="{A07E78D6-1F91-414a-9ED8-4A0AC7CF055C}" >
	<configuration id="{1BF2273B-7C88-4eab-9325-44DBF8AD5EC8}">
		<heartbeatscript src="scriptfile.py" />
	</configuration>
</required>
 

Physics Simulation

ID: {71CCEAD1-37AD-4572-A267-895207B1082C} - DIPhysics

Reference Implementation: Physics_ODE

Configuration IDs

{E0899640-98BA-4d51-A3B5-15C324800CC5} - DID_PhysicsConfig

NOTE: Previously DID_PhysicsConfig was used to configure Physics_Gangsta, the previous reference implementation. However none of the properties configured apply to the new implementation. DID_PhysicsConfig is still supported, but not required.

Example

<required id="{71CCEAD1-37AD-4572-A267-895207B1082C}" />
 

Agent Management

ID: {96E29E53-95F9-4bd5-81D6-DB5FFC90675E}

Reference Implementation: AgentManager

Configuration IDs

{E7720449-338B-4bfc-88CC-331C506E1210} - DID_AgentManagerConfiguration1

NOTE: A number of components designed to use Agent Management (eg VehicleAgent_Control and HumanAvatar) will allow you to specify a simplified version of this configuration to them, and it will be responsible for configuring the Agent Management appropriately.

template

• name - string - Unique identifier to be used for referring to the template.
• src - string - Path / identifier for .agent formated definition file.

agent

• name - string - Unique identifier to be used for referring to the Agent instance.
• src - string - Identifier of the template to be used for instancing the Agent.

Example

<required id="{96E29E53-95F9-4bd5-81D6-DB5FFC90675E}" >
	<configuration id="{E7720449-338B-4bfc-88CC-331C506E1210}" >
		<template name="AGENT_TEMPLATE" src="template.agent" />
		<agent name="AGENT_NAME" src="AGENT_TEMPLATE" />
	</configuration>
</required>