July 2009 „Howto“-Document „SRR-Object“ Version v0.01 – step 0010

SrrTrains: Do-it-yourself-multiplayer-virtual-model-railroad

How To Build My Own SRR

Object

1Introduction

Basically, SRR is a framework that provides X3D prototypes to help building layouts, modules and models of a virtual multiplayer model railroad on X3D/VRML basis.

The homepage http://simulrr.wordpress.com/download-area contains the framework and additionally some „how to use“ information and a sample model railroad layout.

The central parts of the framework – SRR Control and the Module Coordinator – are provided by the SRR core team. SRR objects are provided additionally.

It should not cause big problems to implement your own SRR objects, because the whole code of SRR is public.

However, to ease the job of implementing own SRR objects, this document is published as a helper.

We ask you kindly to make your own SRR objects available via http://simulrr.wordpress.com/download-area , e.g by writing a Wordpress comment that contains a reference to the object.

2SRR Objects

The SRR objects provided by the SRR Core Team are described at http://members.chello.at/christoph.valentin/lowlevelinterface.htm.

The present document contains additional information about those objects to help you to develop your own SRR objects in analogy.

3Scenarios

3.1External Messages (Network Sensor Communication)

3.1.1SrrControl

Message	Type	Addressing/Content
Access Request	SFString	Each scene instance can request a change of the communication state by sending an Access Request (or an Registration Request, if some additional modules have to be registered). An Access Request is distributed as an Event and only read by the controller. All other scene instances ignore this event. An Access Request is a string with the syntax sessionId=<sessionId>[;controller=yes][;sequence=<sequence>][;modules=<modules>] [;roles=<roles>]
Registration Request	MFString	Each scene instance can request the registration of some additional modules A Registration Request is distributed as an Event and only read by the controller. All other scene instances ignore this event. Each element of the Registration Request contains exactly one module name.
Communication State	MFString	A Communication State is the common answer of the controller to Access Requests and Registration Requests. A Communication State is distributed as a State and it is read by all scene instances.Er enthält für jede Szeneninstanz einen String mit A communication state contains one string for each scene instance sessionId=<sessionId>[;controller=yes][;sequence=<sequence>][;modules=<modules] [;moc=<mocRoles>][;roles=<roles>] and one string for each registered module registeredModule=<module> The distributed Communication State is consistent with regard to the rules, that exactly one controller is contained in the first place and that exactly one MOC exists for each module that is active in at least one scene instance.

Console Command

MFString

Console Command contains the destination sessionId in the first element [0], i.e. The scene instance which is the MOC of the addressed module. All other scene instances ignore this message.

[1] contains the response address (sessionId of the sender)

[2] contains the command, i.e. „read“, „set“ or „options“

In case of „set“:

[3] name of the addressed module

[4] objId of the addressed object

[5] parameterName of the addressed parameter

[6] contains the value to be set (or an empty string, if the default value should be set)

improvement proposal: omit [6], if default value should be set

In case of „read“:

[3] name of the addressed module

[4] objId of the addressed object

[5] parameterName of the addressed parameter or „*“

In case of „options“:

[3] name of the addressed module, if present

[4] objId of the addressed object, if present

[5] parameterName of the addressed parameter, if present

Console Response

MFString

Console Response contains the sessionId of the addressed scene instance in element [0]. All other scene instances ignore the message.

The elements [1] to [length-1] contain lines of text, that should be output as answer at the console.

3.1.2SrrSwitchA

Message	Type	Addressing/Content
Toggle Request	SFBool	Each scene instance can request the inversion of the scheduled state. Only the MOC reads this Event, all other scene instances ignore it.
State Update	SFBool	At certain happenings, the MOC distributes the „scheduled state“ of the switch as a State. All scene instances read the value and if the module is activated they will start the animation.
Update Request	SFBool	When a module becomes activated in a scene instance, all switches of the module send an Update Request to the MOC to synchronize with the scene. This event is only read by the MOC, all other scene instances ignore it.

3.1.3SrrDriveA

3.1.4SrrKeyContainer/SrrLock

3.1.5SrrAvatarContainerCore

3.2Scenarios of SrrControl

Trigger	Type	Reaction/Output
User Interface (uiControl)
sessionId	SFInt32	To be described
multiuserRequest	SFBool	To be described
useConnection	SFString	To be described
controllerRequest	SFBool	To be described
activatedModulesRequest	MFString	To be described
activatedModulesIxsRequest	MFInt32	To be described
selectedRolesRequest	SFString	To be described
init	SFBool	To be described
handleAccessRequest()	Int. function	To be described
sessionIdLeft	SFInt32	To be described
traceLevel	SFInt32	To be described
keysToPut	MFString	To be described
consoleCommand	SFString	To be described

Network Interface (niControl)
Access Request	SFString	To be described
Registration Request	MFString	To be described
handleServerRequest()	Int. function	To be described

Communication State

MFString

Following actions are triggered by the reception of a Communication State in all scene instances:

Stop Communication State Timer
Decode Communication State
store sequence in recvdCommStateSequence
store communication state in commParam and output it at the user interface (uiControl)
handle module announcement, module move and module withdrawal according to current and old registered modules, report first sessionIds and afterwards registered to module coordinator (iiControl)
update local user information
store mocRolesBoolArr and activatedModulesBoolArr in commParam and calculate delta to previous state → set activated of all module coordinators
is the communication state an answer to an outstanding Access Request ? Yes → stop Access Request Timer, update flags
is the communication state an answer to an outstanding Registration Request ? Yes → stop Registration Request Timer, update flags
if necessary → build a new Access Request and send
if necessary → build a new Registration Request and send
.iAmController is true → call handleServerRequest() (process queues)
if it is an initialisation → finalize initialization

Console Command	MFString	To be described
Console Response	MFString	To be described
Timer (SrrControl internal)
Access Request Timer	SFBool	To be described
Registration Request Timer	SFBool	To be described
Communication State Timer	SFBool	To be described
Module Coordinator (iiControl)
Announce Module	SFNode	To be described
Activate Module Request	SFInt32	To be described
Take Keys	MFString	To be described
Bind Key Container	SFNode	To be described
Unbind Key Container	SFNode	To be described
Collect Console Response	MFString	To be described

3.3Scenarios of SrrModCoord

Trigger	Type	Reaction/Output
User Interface (uiMod)
moduleName	SFString	Store module name and call tryInit().
commParam	SFNode	Store commParam reference and call tryInit()
tryInit()	Int. function	If moduleName is not empty and commParam is not null → output announceModule to SRR Control (iiControl interface), i.e. Start registration of module
activateRequest	SFBool	Set storedActivateRequest. Call activate(), if registered >= 0.
activate()	Int. function	Clear storedActivateRequest. Set activateModRequest = registered (iiControl interface)
activateRequest	SFBool	Not implemented
SRR Control (iiControl)
sessionIds	MFInt32	Forward sessionIds to all SRR objects via modParam, output sessionIds at the user interface (uiMod).
registered	SFInt32	Output registered at the user interface (uiMod). If registered >= 0, initialize modParam and output at user interface (uiMod). If storedActivateRequest  call activate()
activated	SFInt32	Output activated at the user interface (uiMod), filter the bits from the SFInt32 and output none, one or several of the events takeMOC, grantMOC, activate and deactivate to the SRR objects via modParam (in this order). In case of grantMOC clear list announcedObjects.
carriedKeysChanged	SFBool	Forward carriedKeysChanged via modParam to the SRR objects.
receiveConsoleCommand	MFString	If the answer can be given by SrrModCoord → give the answer via collectConsoleResponse to SRR Control (iiControl interface) else forward the command via consoleCommand (iiObj) to the addressed object (object must be announced). Clear collectedConsoleResponse in advance

SRR Objects (iiObj)
takeKeys	MFString	Forward takeKeys to SRR Control
bindKeyContainer	SFNode	Forward bindKeyContainer to SRR Control
unbindKeyContainer	SFNode	Forward unbindKeyContainer to SRR Control
announceObject	SFNode	Add the object to the list announcedObjects
collectConsoleResponse	MFString	Add an arbitrary number of lines to the collectedConsoleResponse
consoleResponseFinished	SFString	Finish the console response from one object (SFString contains the objId). The collectedConsoleResponse will be sent to srrControl.collectConsoleResponse and deleted again to be prepared for the next console command.

3.4Scenarios of SrrSwitchA

Trigger	Type	Reaction/Output
User Interface (uiObj)
objId	SFString	Store object id and call tryInit().
modParam	SFNode	Store modParam reference and call tryInit().
tryInit()	Int. function	If objId is not empty and if modParam is not null → Initialize network sensor create dynamic routes from modParam for takeMOC, grantMOC, activate and deactivate If a lock-object exists → create dynamic route for the locked state if the scene instance is already the MOC for this module → call takeMOC() if the scene instance is already active → call activate()
toggle	SFBool	If the module is active and if the switch is not locked → send Toggle Request
Network Interface (niObj)
Toggle Request	SFBool	This message is processed by the MOC only invert „scheduled state“ and send as State Update to all scene instances
Update Request	SFBool	This message is processed by the MOC only send „scheduled state“ as State Update to all scene instances
State Update	SFBool	Store the state in the local „scheduled state“ if the module is active → call startAnimation()
startAnimation()	Int. Funktion	If necessary, stop Soft State Timer Calculate new properties of Soft State Timer and Soft State Interpolator (startValue, endValue, duration) and set them start Soft State Timer → softState is continuously output at the user interface (uiObj)
Timer (SrrSwitchA intern)
Soft State Timer	SFBool	Output scheduled State as actualState at the user interface (uiObj) (animation finished)
Module Coordinator (iiObj)
consoleCommand	MFString	Process console command (“set”, “read” and “options”) and report response via collectConsoleResponse and consoleResponseFinished to the module coordinator (iiObj)
takeMOC	SFBool	Announce object at the module coordinator (announceObject) and send “scheduled state” in a State Update
grantMOC	SFBool	No action
activate	SFBool	Send Update Request to the MOC
deactivate	SFBool	No action

1Introduction

2SRR Objects

3Scenarios

3.1External Messages (Network Sensor Communication)

3.1.1SrrControl

3.1.2SrrSwitchA

3.1.3SrrDriveA

3.1.4SrrKeyContainer/SrrLock

3.1.5SrrAvatarContainerCore

3.2Scenarios of SrrControl

3.3Scenarios of SrrModCoord

3.4Scenarios of SrrSwitchA

3.5Scenarios of SrrDriveA

3.6Scenarios of SrrKeyContainer

3.7Scenarios of SrrLock

3.8Scenarios of SrrAvatarContainer

3.9Scenarios of SrrMasterAvatarContainer