Juli 2009 „Howto“-Dokument „SRR-Objekt“ Version v0.01 – step 0010

SrrTrains: Do-it-yourself-virtuelle-muliplayer-Modelleisenbahn

Wie baue ich mein eigenes SRR

Objekt

1Einleitung

In seinem Kern ist SRR ein Framework, das X3D-Prototypen zur Verfügung stellt, mit deren Hilfe man Anlagen, Module und Modelle für eine virtuelle multiplayer Modelleisenbahn auf X3D/VRML-Basis erstellen kann.

Auf der Homepage http://simulrr.wordpress.com/download-area sind neben diesem Framework selbst auch Anleitungen und eine Beispielanlage verfügbar.

Die zentralen Teile von SRR, also der „SRR Controller“, der „Modul-Koordinator“, aber auch die „SRR-Objekte“ werden eigentlich vom SRR Kern-Team zur Verfügung gestellt.

Allerdings sollte es kein großes Problem darstellen, eigene SRR-Objekte zu implementieren, da ja der gesamte SRR Code veröffentlicht ist.

Um dies nun zusätzlich zu vereinfachen, dient die vorliegende Beschreibung (noch unfertig).

Es wird höflichst darum gebeten, selbst gebaute SRR-Objekte über die Homepage http://simulrr.wordpress.com/download-area verfügbar zu machen (indem man z.B. einen Kommentar schreibt, in dessen Text auf das Objekt verwiesen wird).

2SRR-Objekte

Die Objekte, die vom SRR Kern-Team zur Verfügung gestellt werden, sind auf http://members.chello.at/christoph.valentin/lowlevelinterface.htm beschrieben. Im vorliegenden Dokument werden zusätzliche Informationen geliefert, die es ermöglichen sollen, eigene SRR-Objekte in Analogie dazu zu entwickeln.

3Szenarien

3.1Beschreibung der externen Messages (Network Sensor Kommunikation)

3.1.1SrrControl

Nachricht	Typ	Adressierung/Inhalt
Access Request	SFString	Jede Szeneninstanz kann einen Access Request senden, wenn sie eine Änderung des Communication State beantragen möchte (ausgenommen ist die Registrierung zusätzlicher Module, die wird mit dem Registration Request beantragt). Access Request wird als Event verteilt und nur vom Controller gelesen. Alle anderen Szeneninstanzen ignorieren dieses Event. Ein Access Request ist ein String mit der Syntax sessionId=<sessionId>[;controller=yes][;sequence=<sequence>][;modules=<modules>] [;roles=<roles>]
Registration Request	MFString	Jede Szeneninstanz kann die Registrierung neuer Module beantragen. Registration Request wird als Event verteilt und nur vom Controller gelesen. Alle anderen Szeneninstanzen ignorieren dieses Event. Jedes Element des Registration Request enthält genau einen Modulnamen.
Communication State	MFString	Ein Communication State ist die generelle Antwort des Controllers auf Access Requests und Registration Requests. Ein Communication State wird als State verteilt und von allen Szeneninstanzen gelesen. Er enthält für jede Szeneninstanz einen String mit sessionId=<sessionId>[;controller=yes][;sequence=<sequence>][;modules=<modules] [;moc=<mocRoles>][;roles=<roles>] und für jedes registrierte Modul einen String mit registeredModule=<module> Der gesendete Communication State ist dahingehend konsistent, dass es immer genau einen Controller gibt, welcher an erster Stelle steht, und dass es für alle Module, die in mindestens einer Szeneninstanz aktiviert sind, genau einen MOC gibt.

Console Command

MFString

Console Command enthält im ersten Element [0] die sessionId der Szeneninstanz, an die es adressiert ist. Alle anderen Szeneninstanzen ignorieren die Nachricht.

[1] enthält die Antwortadresse (sessionId des Senders)

[2] enthält das Kommando, also „read“, „set“ oder „options“

Im Falle von „set“:

[3] enthält den adressierten Modulnamen

[4] enthält die adressierte Objekt-Id

[5] enthält den adressierten Parameternamen

[6] enthält den neuen Wert (oder einen Leerstring im Fall, dass der Default-Wert gesetzt wrden soll)

Verbesserungsvorschlag: im Falle, dass der Default-Wert gesetzt werden soll, ist [6] nicht vorhanden

Im Falle von „read“:

[3] enthält den adressierten Modulnamen

[4] enthält die adressierte Objekt-Id

[5] enthält den adressierten Parameternamen oder „*“

Im Falle von „options“:

[3] enthält, wenn vorhanden, den adressierten Modulnamen

[4] enthält, wenn vorhanden, die adressierte Objekt-Id

[5] enthält, wenn vorhanden, den adressierten Parameternamen

Console Response

MFString

Console Response enthält im ersten Element [0] die sessionId der Szeneninstanz, an die sie adressiert ist. Alle anderen Szeneninstanzen ignorieren die Nachricht.

Die Elemente [1] bis [length-1] enthalten Textzeilen, die als Antwort auf der Konsole ausgegeben werden sollen.

3.1.2SrrSwitchA

Nachricht	Typ	Adressierung/Inhalt
Toggle Request	SFBool	Jede Szeneninstanz kann eine Änderung des Soll-Schaltzustandes (scheduled state) beantragen. Nur der MOC liest dieses Event, alle anderen Szeneinstanzen ignorieren es.
State Update	SFBool	Zu bestimmten Anlässen verteilt der MOC den „scheduled state“ des Schalters,also den Soll-Wert, als State. Alle Szeneninstanzen lesen diesen Wert und wenn das Modul aktiviert ist, starten sie die Animation.
Update Request	SFBool	Wenn ein Modul in einer Szeneninstanz aktiviert wird, senden alle Schalter dieses Moduls einen Update Request an den MOC, um sich mit der Szene zu synchronisieren. Nur der MOC liest dieses Event, alle anderen Szeneninstanzen ignorieren es.

3.1.3SrrDriveA

3.1.4SrrKeyContainer/SrrLock

3.1.5SrrAvatarContainerCore

3.2Szenarien von SrrControl

Trigger	Typ	Reaktion/Output
User Interface (uiControl)
sessionId	SFInt32	Zu beschreiben
multiuserRequest	SFBool	Zu beschreiben
useConnection	SFString	Zu beschreiben
controllerRequest	SFBool	Zu beschreiben
activatedModulesRequest	MFString	Zu beschreiben
activatedModulesIxsRequest	MFInt32	Zu beschreiben
selectedRolesRequest	SFString	Zu beschreiben
init	SFBool	Zu beschreiben
handleAccessRequest()	Int. function	Zu beschreiben
sessionIdLeft	SFInt32	Zu beschreiben
traceLevel	SFInt32	Zu beschreiben
keysToPut	MFString	Zu beschreiben
consoleCommand	SFString	Zu beschreiben

Network Interface (niControl)
Access Request	SFString	Zu beschreiben
Registration Request	MFString	Zu beschreiben
handleServerRequest()	Int. function	Zu beschreiben

Communication State

MFString

Folgende Aktionen werden durch den Communication State in allen Szeneninstanzen ausgelöst :

Communication State Timer wird gestoppt
Communication State wird dekodiert
Sequence in recvdCommStateSequence speichern
Communication State in den commParam speichern und am User Interface ausgeben
Module announcement, module move und module withdrawal für alle registrierten Module bearbeiten, dabei zuerst sessionIds und danach registered des SrrModCoord updaten
Lokale User Information abspeichern
MocRolesBoolArr und activatedModulesBoolArr in commParam speichern und feststellen, welches Modul aktiviert/deaktiviert worden ist und die MOC Rolle übernommen/abgegeben hat  dementsprechend das Feld activated aller Modulkoordinatoren updaten.
Ist der Communication State die Antwort auf einen Access Request? Ja  Access Request Timer stoppen, flags updaten
Ist der Communication State die Antwort auf einen Registration Request? Ja  Registration Request Timer stoppen, flags updaten
Bei Bedarf einen neuen Access Request bilden und senden
Bei Bedarf einen neuen Registration Request bilden und senden
Wenn iAmController Wahr ist  handleServerRequest() aufrufen (Queues bearbeiten)
Bei Bedarf (wenn es sich um eine Initialisierung handelt)  Initialisierung finalisieren

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

3.3Szenarien von SrrModCoord

Trigger	Typ	Reaktion/Output
User Interface (uiMod)
moduleName	SFString	Modulnamen speichern und tryInit() aufrufen
commParam	SFNode	commParam-Referenz speichern und tryInit() aufrufen
tryInit()	Int. function	Wenn moduleName ungleich Leerstring und commParam ungleich null  announceModule über das iiControl – Interface ausgeben  Modulregistrierung starten, announceModule zeigt auf den internen Script-Knoten SrrModCoordScript.
activateRequest	SFBool	storedActivateRequest setzen. activate() aufrufen, wenn registered >= 0.
activate()	Int. function	storedActivateRequest löschen. activateModRequest = registered setzen am iiControl-Interface (Input für SRR Control)
deactivateRequest	SFBool	Nicht implementiert
SRR Control (iiControl)
sessionIds	MFInt32	Über modParam sessionIds an alle SRR-Objekte weitergeben, sessionIds über User Interface (uiMod) ausgeben.
registered	SFInt32	registered über User Interface (uiMod) ausgeben. Falls registered >= 0, modParam initialisieren und über User Interface (uiMod) ausgeben. Wenn storedActivateRequest  activate() aufrufen
activated	SFInt32	activated über das User Interface (uiMod) ausgeben, die Bitleiste filtern und dementsprechend, keines, eines oder mehrere der Events takeMOC, grantMOC, activate und deactivate an die SRR-Objekte über modParam weitergeben (in dieser Reihenfolge). Bei grantMOC noch vorher die Liste announcedObjects löschen (siehe auch announceObject).
carriedKeysChanged	SFBool	carriedKeysChanged über modParam an die SRR-Objekte weitergeben.
receiveConsoleCommand	MFString	wenn bereits SrrModCoord die Antwort geben kann, dann Antwort an collectConsoleResponse (Input für SRR Control) ansonsten Weiterleitung des Konsolenkommandos an consoleCommand des Objektes, collectedConsoleResponse vorher löschen

SRR Objects (iiObj)
takeKeys	MFString	takeKeys weitergeben an SRR Control
bindKeyContainer	SFNode	bindKeyContainer weitergeben an SRR Control
unbindKeyContainer	SFNode	unbindKeyContainer weitergeben an SRR Control
announceObject	SFNode	Das Objekt in die Liste announcedObjects aufnehmen (siehe auch grantMOC)
collectConsoleResponse	MFString	Eine beliebige Anzahl von Zeilen an die Antwort collectedConsoleResponse anfügen
consoleResponseFinished	SFString	Damit wird eine Console Response abgeschlossen, an srrControl.collectConsoleResponse gesendet und hernach wieder collectedConsoleResponse gelöscht und somit auf die nächste Sammlung vorbereitet.

3.4Szenarien von SrrSwitchA

Trigger	Typ	Reaktion/Output
User Interface (uiObj)
objId	SFString	Objekt-Id speichern und tryInit() aufrufen
modParam	SFNode	modParam-Referenz speichern und tryInit() aufrufen
tryInit()	Int. function	Wenn objId ungleich Leerstring und modParam ungleich null  Network Sensor initialisieren Dynamische Routen für takeMOC, grantMOC, activate und deactivate legen Wenn es ein lock-Objekt gibt  dynamische Route für locked legen Wenn die Szeneninstanz bereits der MOC für dieses Modul ist  takeMOC() aufrufen Wenn das Modul in dieser Szeneninstanz bereits aktiv ist  activate() aufrufen
toggle	SFBool	Wenn das Modul aktiviert und der Schalter nicht versperrt ist  Toggle Request senden
Network Interface (niObj)
Toggle Request	SFBool	Diese Message wird nur vom MOC bearbeitet: Lokalen „scheduled state“ invertieren und als State Update an alle Szeneninstanzen senden
Update Request	SFBool	Diese Message wird nur vom MOC bearbeitet: Lokalen „scheduled state“ als State Update an alle Szeneninstanzen senden
State Update	SFBool	Den State im lokalen “scheduled state” speichern Wenn das Modul aktiv ist  startAnimation() aufrufen
startAnimation()	Int. Funktion	Bei Bedarf Soft State Timer stoppen Neue Eigenschaften von Soft State Timer und Soft State Interpolator berechnen (startValue, endValue, duration) und setzen Soft State Timer starten  softState wird kontinuierlich von Soft State Interpolator am User Interface (uiObj) ausgegeben
Timer (SrrSwitchA intern)
Soft State Timer	SFBool	scheduled State als actualState am User Interface (uiObj) ausgeben (Animation ist fertig)
Modulkoordinator (iiObj)
consoleCommand	MFString	Konsolenkommando bearbeiten (“set”, “read” und “options”) und Ergebnis an collectConsoleResponse und consoleResponseFinished melden (iiObj – Modulkoordinator)
takeMOC	SFBool	Objekt beim Modulkoordinator announcen (announceObject) und “scheduled state” in einem State Update senden
grantMOC	SFBool	Keine Aktion
activate	SFBool	Update Request an den MOC senden
deactivate	SFBool	Keine Aktion

1Einleitung

2SRR-Objekte

3Szenarien

3.1Beschreibung der externen Messages (Network Sensor Kommunikation)

3.1.1SrrControl

3.1.2SrrSwitchA

3.1.3SrrDriveA

3.1.4SrrKeyContainer/SrrLock

3.1.5SrrAvatarContainerCore

3.2Szenarien von SrrControl

3.3Szenarien von SrrModCoord

3.4Szenarien von SrrSwitchA

3.5Szenarien von SrrDriveA

3.6Szenarien von SrrKeyContainer

3.7Szenarien von SrrLock

3.8Szenarien von SrrAvatarContainer

3.9Szenarien von SrrMasterAvatarContainer