Project

General

Profile

Wiki » History » Version 38

Josip Almasi, 10/15/2021 04:34 PM

1 4 Josip Almasi
{{toc}}
2
3 1 Josip Almasi
h1. Welcome!
4 2 Josip Almasi
5 18 Josip Almasi
h2. External resources
6 4 Josip Almasi
7 14 Josip Almasi
Demo site: https://www.vrspace.org/
8
9 15 Josip Almasi
Github project page: https://github.com/jalmasi/vrspace
10 2 Josip Almasi
11 16 Josip Almasi
OpenSource.com article (motivation): https://opensource.com/article/20/12/virtual-reality-server
12 3 Josip Almasi
13 15 Josip Almasi
VR Days video (features, technologies): https://vimeo.com/475142708
14 3 Josip Almasi
15 15 Josip Almasi
Youtube channel: https://www.youtube.com/channel/UCLdSg22i9MZ3u7ityj_PBxw
16 1 Josip Almasi
17 16 Josip Almasi
Facebook page: https://fb.com/vrspace.org
18 14 Josip Almasi
19
Client API jsdoc: https://www.vrspace.org/docs/jsdoc/index.html
20
21
Server javadoc: https://www.vrspace.org/docs/javadoc/index.html?overview-summary.html
22 4 Josip Almasi
23 23 Josip Almasi
h2. Playgrounds
24
25
Multi-user interaction, shared objects: https://playground.babylonjs.com/#ZBK155
26
Multi-user world: https://playground.babylonjs.com/#Y6ILJ5
27
Avatar selection, portals: https://playground.babylonjs.com/#HDV7LA
28 24 Josip Almasi
VR Avatar template world: https://www.babylonjs-playground.com/#VXA0R3
29 23 Josip Almasi
30 17 Josip Almasi
h1. Frequently Asked Questions
31
32
h2. Is this open source, free to use and share?
33
34
Yes, it's all free and open. Server and client code is published under Apache 2 license, all 3D models published by their respective authors under Creative Commons Attribution license.
35
36
h2. Is there any documentation?
37
38
This is good place to start, this page links to all available resources.
39
40
h2. How many users can share a “world/space” simultaneously?
41
42
By default, number of users per space is not limited. There is a server parameter to limit that (org.vrspace.server.maxSessions) that can be specified either in config file or command line. Users that hit the limit remain in the queue for configurable timeout (org.vrspace.server.sessionStartTimeout, zero by default) until someone leaves. An error is raised on timeout.
43
44 36 Josip Almasi
h2. How can I implement custom authentication and/or authorization
45
46
Implement your own "ClientFactory":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/core/ClientFactory.java and configure it in "application.properties":https://github.com/jalmasi/vrspace/blob/master/server/src/main/resources/application.properties file.
47 37 Josip Almasi
This allows you to do your own database queries, REST calls or whatever else you may need to identify your users.
48 36 Josip Almasi
49 38 Josip Almasi
h2. What is difference between vrspace.org server and a game engine
50
51
52
53 4 Josip Almasi
h1. Setting up development environment
54
55
Here's all you need to start development on Windows.
56 20 Josip Almasi
Linux distributions include all these tools as native packages, so no additional downloads should be required.
57 4 Josip Almasi
58
h2. Basic setup
59
60
h3. Git bash
61
62
IDEs can work with github directly, but whatever you ask, you'll get a command line answer.
63
Command line git is simply a must have. Bash also includes a lot of goodies like ssh.
64
65
https://git-scm.com/downloads
66
67
h3. Java
68
69 21 Josip Almasi
Java 8 will work, java 11 recommended. JDK is required to build the server.
70
Get it either from Oracle or elsewhere, e.g. Zulu OpenJDK: https://www.azul.com/downloads/zulu-community/?package=jdk
71 4 Josip Almasi
72
h3. Node.js
73
74
Node is used by IDE to evaluate javascript. You'll also may need it if you modify any of babylon.js source.
75
Mind that IDE will complain if you installed unsupported version of Node; should that happen, remove Node, and install latest one supported.
76
77
Get it from https://nodejs.org/
78
79 19 Josip Almasi
h3. Maven
80
81
Apache Maven is used to build the server from command prompt.
82
83
Get it from https://maven.apache.org/download.cgi
84
85
86 4 Josip Almasi
h3. IDE
87
88
Eclipse for Java developers (not enterprise), with Spring and Web plugins:
89
90
Download eclipse here: https://www.eclipse.org/
91
92
And then go to Help -> Eclipse Marketplace
93
Search and install Spring Tools 4 and Wild Web Developer plugins.
94
95 6 Josip Almasi
You'll also need to download and install https://projectlombok.org/
96 8 Josip Almasi
Once done, restart the eclipse.
97 6 Josip Almasi
98 5 Josip Almasi
h2. Import and start the project
99
100 22 Josip Almasi
h3. IDE
101
102 5 Josip Almasi
In Eclipse, you can use either default or new workspace for the project.
103
Assuming you have cloned the project from the github, 
104
Go to File -> Open Projects From the Filesystem
105
Then choose vrspace directory.
106
107
This will import vrspace folders and project subfolders, click Finish.
108
109
In vrspace project folder, in src/main/java, there's org.vrspace.server.ServerApplication.java.
110
Open it, then right click on the code.
111
From the menu, choose either Run as or Debug as -> Spring Boot App.
112
113
Open http://localhost:8080/babylon/connect.html with two browsers, and navigate around.
114
115
That's all, you're all set!
116 22 Josip Almasi
117
h3. git bash
118
119
git clone https://github.com/jalmasi/vrspace.git
120
cd vrspace
121
mvn clean install
122
java -jar server/target/server-0.2.2.jar
123 4 Josip Almasi
124
h2. Advanced setup
125
126 12 Josip Almasi
h3. SSL
127 4 Josip Almasi
128 12 Josip Almasi
HTTPS is required for pretty much everything - WebXR, camera, mic access.
129
By default, the server runs on 8080 port with plain HTTP. To enable HTTPS, edit application.properties (found in src/main/resources), and change following properties:
130 1 Josip Almasi
131 12 Josip Almasi
<pre>
132
server.ssl.enabled=false
133
# default port 8080
134
#server.port=8443
135 13 Josip Almasi
</pre>
136 12 Josip Almasi
137
h3. Apache
138
139
Apache reverse proxy setup, linux, windows, TBD
140 4 Josip Almasi
141
h3. Docker and OpenVidu
142
143
OpenVidu voice/video chat server runs as docker image. This is only required for development of voice chat functions.
144
145 10 Josip Almasi
Local execution (development):
146 11 Josip Almasi
docker run -p 4443:4443 --rm -e OPENVIDU_SECRET=YOUR_SECRET -e DOMAIN_OR_PUBLIC_IP=YOUR_IP openvidu/openvidu-server-kms:2.17.0
147 10 Josip Almasi
148
Running on server:
149 1 Josip Almasi
https://docs.openvidu.io/en/2.17.0/deployment/deploying-on-premises/
150 11 Josip Almasi
151
Then either modify openvidu.publicurl and openvidu.secret in application.properties, or run server.jar with -Dopenvidu.publicurl=YOUR_URL and -Dopenvidu.secret=YOUR_SECRET
152 25 Josip Almasi
153
h1. Software Architecture
154 26 Josip Almasi
155
!https://redmine.vrspace.org/attachments/download/15/vrspace-diagram.png!
156
157
h2. Client-Server Communication
158
159 31 Josip Almasi
Clients communicate with server by sending JSON messages over "WebSockets":https://en.wikipedia.org/wiki/WebSocket. Reference javascript implementation of client communication layer is in "VRSpace.js":https://www.vrspace.org/docs/jsdoc/VRSpace.html.
160 26 Josip Almasi
161
General approach to communication is rather obscure Half-Object pattern: server-side and client-side object have same properties, but different implementations.
162
Whenever an object's property changes in (any) client's address space, it's transmitted to the server, that broadcasts it to all clients currently 'watching' the object.
163
164
Whenever a client wants to perform any change to any object in the space, it has to go through the VRSpace server.
165
Clients may or may not communicate directly, but this is out of the scope of VRSpace server.
166
167
h2. Server Responsibilities
168
169
Sole responsibility of VRSpace server is management of 3D space: persisting space objects, tracking their properties, processing and distributing events from/to objects.
170 27 Josip Almasi
Whenever we talk about objects, that includes clients, i.e. users - a client is a special case of an object.
171
The server does not even handle the authentication - it is assumed to be responsibility of web app serving the space.
172
3D geometry is also not in server's scope, it's just another property of an object (mesh).
173
174
h2. Server design
175
176
Key concepts here are Active Objects, Actor model, and Live distributed object.
177
178
"VRObject":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/obj/VRObject.java is a basic shared object, with some basic properties like position and rotation, and of course, mesh. It essentially a "Live distributed object":https://en.wikipedia.org/wiki/Live_distributed_object.
179
180 28 Josip Almasi
"Client":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/obj/Client.java extends VRObject, and adds capabilities to communicate over web sockets, and listen to changes to other objects. Typically, a client represents a remote user, but it can also represent a robot connected over a web socket, or be a base class for a server-side robot.
181
A Client can be thought of as "Active Object":https://en.wikipedia.org/wiki/Active_object or an "Actor":https://en.wikipedia.org/wiki/Actor_model, 
182 27 Josip Almasi
183
Server relies on Spring Boot and embedded Tomcat to handle all I/O and threads.
184 29 Josip Almasi
185 33 Josip Almasi
h3. Client
186 29 Josip Almasi
187 30 Josip Almasi
Each "Client":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/obj/Client.java has it's own "Scene":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/core/Scene.java that tracks all shared objects - including other clients - visible by the client. The scene is initially populated once the client logs in to the server, and starts the session. Scene is refreshed periodically, after a movement, or explicitly.
188 29 Josip Almasi
189
Scene maintains the event model, by adding the Client as listener to all other active objects (usually other users) in the scene.
190 1 Josip Almasi
191 30 Josip Almasi
Client simply notifies it's own listeners on any changes to any of it's own properties. As a listener, it propagates any observed change on any other object over the network, to the user.
192
193
Client has just a couple of persistent properties, like position, rotation and name. The name must be unique.
194
All other properties are transient.
195
196 33 Josip Almasi
"ClientFactory":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/core/ClientFactory.java allows for customization of Client class and instances.
197 1 Josip Almasi
198 33 Josip Almasi
h3. Events and messages
199
200 30 Josip Almasi
Typically events exchanged are changes to properties of active objects, e.g. user moves around, changing own position and rotation. However, an object may emit any event, and the event gets propagated to all listeners.
201 1 Josip Almasi
This is to simplify client development: simply emit any custom event you want.
202 32 Josip Almasi
All distributed events are encapsulated in "VREvent":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/dto/VREvent.java class.
203
204
However, there are other types of messages that are not distributed to other clients: commands and their return values, and errors.
205 1 Josip Almasi
Client will typically execute at least one command during the session - "Session":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/dto/Session.java start. It will not receive any messages before that.
206
Should any server-side exception occur during the session, errors are sent to the client as simple JSON maps.
207 33 Josip Almasi
208
"WorldManager":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/core/WorldManager.java manages clients and event distribution between them.
209
210
h3. Worlds
211
212
A server can host many worlds, i.e. shared spaces. A world contains users and other objects that are shared only within the world. It can be thought of as a chatroom, but mind the difference: being in the same world does not mean that users can see and talk to each other.
213
Client can enter another world by issuing "Enter":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/dto/Enter.java command.
214
215 35 Josip Almasi
h3. Ownership and privacy
216
217
A class can be annotated as Owned, and all of instances automatically become owned as they are created. An owned object does not receive events from anyone by owner(s). A Client is owned, and nobody but himself can change his name.
218
On the other hand, a generic VRObject is public, and receives events from anyone. Like a door, anybody can open and close it. But even public objects can have some properties annotated as Owned, that can't be change by anyone but owner.
219
Fields of a class can be annotated as Private, and their contents will never be published.
220
221
"Dispatcher":https://github.com/jalmasi/vrspace/blob/master/server/src/main/java/org/vrspace/server/core/Dispatcher.java takes care of it before property changes are applied, and before they are published to listeners.
222
223 33 Josip Almasi
h3. Package structure
224
225
Package "org.vrspace.server":https://github.com/jalmasi/vrspace/tree/master/server/src/main/java/org/vrspace/server contains only main application class. Under it,
226
- config package contains server configuration classes that are executed only on server statup
227
- core is the core of the server
228 34 Josip Almasi
- dto is misnomer that stands Data Transfer Objects, though this package contains all objects that are not shared nor persisted
229 33 Josip Almasi
- obj contains persistent objects, most importantly Client and VRObject
230
- types are custom types used elsewhere, be it interfaces or annotations
231
- web is a primitive admin interface, disabled by default