PLEASE Read this throughly. This for a version 1.03 so there have been some major changes in Quick Start!
Introduction:
This is a working version of the open source Deep Matrix client/server
system for Instant Player. This version's ultimate goal is an easy
to run and use small scale community server.
The idea is for it to work right "out-of-the-box" as much as possible
with the developer simply modifying existing files
for their own work.
The DeepMatrix MU client and server is written entirely in Java.
It is cross-platform!
It will work on Windows XP based on Instant Player requirements.
It will work on Apple computers, both powerPC and Intel processors
based again on Instant Player requirements.
It has NOT been tested on linux, but will MOST PROBABLY work as long
as Instant Player requirements are again met.
However, the included bash files which were written for Apple will
have to be modified directory-wise accordingly.
It has also NOT been tested on the new Windows7 or Vista, although
I would expect the EAI aspect to work on these operating systems
as Instant Reality develops Instant Player itself on them. However
the ability to play mp3 files and launch html browsers on them is unknown!
Any feedback on these systems is welcome!
Requirements:
1. VERY IMPORTANT! This assumes you have the latest Sun Java installed!
The Windows Java version should be 1.6 or greater! Needless to say
Apple Java
should be latest as well.
2. InstantPlayer has been successfully installed from the Latest
Instant Player Build at InstantReality.org
3. The DeepMatrixIP9 client software has been installed (see Quick
Start below)
Quick
Start for either the public server at http://www.deepmatrix.org
OR testing
the client and server locally on your computer.
1. Unzip the DeepMatrixIP9-v1_03.zip:
A. On Windows as: "C:\DeepMatrixIP9-v1_03"
(If you are using another drive you must edit the batch
files by hand to match.)
B. On Apple as:
"Applications/DeepMatrixIP9-v1_03"
C. On Linux to your Desktop as: "DeepMatrixIP9-v1_03"
the folder was must then be copied in the "opt" directory that
was created by the Instant Reality installation.
Permissions to copy into that directory must be changed
using the chmod command.
Create desktop short cuts the following scripts:
Linux_Client/Public_Linux_Client.sh
Linux_Client/Local_Linux_Client.sh
server_application/Linux_DeepMatrixIP9Server.sh
and the Linux scripts in the bot folder.
Change the permissions on "Linux_Client" so it is executable
only.
You will want to make sure the server_application/Linux_DeepMatrixIP9Server.sh
and client_application/bot Linux bot scripts
are executable by right-clicking each script ->
"Permissions" tab ->make sure the "Execute:" "Allow executing file as program"
check box IS checked.
3. To join the public server:
Open the client_application/Win_Client folder and
double click the Public_Win_Client.bat
Apple: open the client_application/Mac_Client folder and
double click the Public_Mac_Client.sh
If you have problems, especially on Leopard OS please read this: Permission
Issues
Linux: open the client_application/Linux_Client folder and
double click the Public_Linux_Client.sh
You may get a flag asking:
"Do you want to run "Public_Linux_Client.sh" or display its contents?"
A. If you want to debug then select "Run in Terminal" or if
everything is great just select "Run".
If you have problems, please read this: Permission
Issues
OR to run and enter the DeepMatrix server locally:
Windows:
A. open server_application folder, double click the DeepMatrixIP9Server.bat
file
and give the server time to finish starting up.
B. Open the client_application/Win_Client folder and
double click the Local_Win_Client.bat
Apple:
A. Open the server_application folder, double click the Mac_DeepMatrixIP9Server.sh
file
and give the server time to finish starting up.
B. Open the client_application/Mac_Client folder and
double click the Local_Mac_Client.sh file
If you have problems, especially on Leopard OS please read this: Permission
Issues
Linux:
A. Open the server_application folder, double click the Linux_DeepMatrixIP9Server.sh
file
and give the server time to finish starting up.
B. Open the client_application/Linux_Client folder and
double click the Local_Linux_Client.sh file
If you have problems, please read this: Permission
Issues
4. It takes a few seconds for Instant Player to initially load.
If you have a lot of programs running it is suggested you close some
of them for the initial loading.
5. Enter your name in "User Name" window and press connect.
6. (optional) You may want to create desktop short-cuts for the scripts.
7. As Gerhard use to say, I hope you have fun with Deep Matrix!
How to get your world permanently
on the public server.
1. You first put your world on temporary display
by selecting from the "Worlds" pull down menu
"Add-Remove-World" and follow the directions
that are presented in the chat.
2. Normally if you leave your world it will disappear
from the list.
3. You can keep your room open by either remaining
online or by running a bot in your world
( see the bot_READ_ME.txt file in the bots folder
for information on running a bot )
Running a bot has the advantage of using far
less system resources.
4. Contact me at pyth7@deepmatrix.org to approve
the world as admin, so you won't have to run a bot.
Please note the world has to be functional for
me to approve it!
Display Info:
This was developed on a Widows desktop of 1024 x 768 pixels and
Apple
display of 1440 x 900
If your desktop is something else modify the following files and parameters
to meet your needs.
Windows:
a. ScreenX3dv and its position and size parameters.
b. win_local_matrixclientrc and win_public_matrixclientrc: the
xpos, ypos, xsize, ysize parameters
Apple:
a. MacScreenX3dv and its position and size parameters.
b. mac_local_matrixclientrc and mac_public_matrixclientrc: the
xpos, ypos, xsize, ysize parameters
Linux:
a. ScreenX3dv and its position and size parameters.
NOTE! As of 6/25/10 the position parameters seem to be ignored
in Linux - a minor annoying bug.
b. win_local_matrixclientrc and win_public_matrixclientrc: the
xpos, ypos, xsize, ysize parameters
c. The correct positioning of Instant Player is improved if
"Run" is selected from the pop-up menu, rather than "Run in Terminal"
(which is good for debugging).
New Features:
1. This IS a stand-alone application and NOT a plugin for a HTML browser.
2. A general replacement of pull-down choice menus to replace buttons
on the client GUI.
3. This version has server based persistent storage for shared events.
Suffixing the "tag" exposedField of Network Proto instances
with
"_P" or "_F" will produce "while populated" or "forever"
shared events
respectively ala' blaxxun. There is also a "_C" suffix
tag to clear events.
(see the "chess" world for functioning examples)
5. Functioning blaxxun style LOCK code for a single user to control
particular events. (see the CtrlNetworkSFBool Proto instance in the
"matrix" world)
See the proto.html here: Proto Text
for details.
6. The very beginnings of blaxxun-style backpack objects have been started.
Currently they are in only a basic demo state.
A. At this point all the objects only belong to the world
they are listed in.
B. Objects can be removed or added to that world at will.
C. They can be positioned and rotated by users using a
blaxxun-style HUD.
The position and orientation changes for each object can
saved and written to file on the server.
D. All shared events and lock features can be applied
to backpack objects.
E. Objects can send text either locally (the immediate
user's chat window only) or to the entire network.
7. A special Proto that enables a user to deliver text from the GUI
to the world for a variety of purposes such as
commands.
8. The ability to use H-Anim avatars and more particulary the ability
to use Avatar Studio2 avs
after conversion to both the H-Anim spec and the Deep Matrix Avatar
Proto design.
See avatar.html here: Avatar
Info Page for details.
9. A room list with the current number of users from which a user can enter at anytime.
8. A user can add or "hang" a world to the rooms list now.
A. If it is approved by the admin it will be retained
and listed in the rooms window by the server.
B. If it has not been approved it will be removed
when empty of users.
B. A user can define their world as private and
grant access to certain users.
C. Ease of use. Instructions for the above features
are provided by the client when the user makes a
selection from the "Rooms"
pull down menu.
9. Taking a clue from Rick Kimball, The necessary code for each world
to load
and function properly in multi-user is now created on the fly
if it is found not to exist.
So in essence any basic world will load and ATTEMPT to simply work.
See the worlddeveloper.html here: How
Worlds are Loaded for details.
7. Admin functions.
See the admin.html here: Admin
Page for more details.
8. World navigation and speed have been added to the Java GUI.
A. Viewpoints may be listed too, but that requires prep
work on the part of the
world builder.
9. A developer can customize the Deep Matrix Java client GUI by a special
Proto
that can change its colors and add a anchor button or
label to it.
10. A user can designate a world as a preferred start room and write
this change to the configuration file.
If the world has the special Proto that changes
the GUI's colors that color change will be written to the
configuration file as well. Please note the user
HAS to be in his selected start room when he makes the
designated start room for the permanent color change
to take place!
11. Check the change_log.txt for new features/fixes and updates!
FAQ
General Questions:
What is this?
What is it good for?
Isn't Java EAI dead?
How
do I get started?
Why is the Instant Player download so large?
Technical and Bug Questions:
Nothing Works or 3D Viewer Does Not Load
Avatar not working
Textures not loading
Sound files won't play
Landscape creeps
Animated viewpoint
is jerky
Instant Player crashes
Ghost mode
2DChat doesn't work
How to use client features
Why does Instant Player's console print so many
errors?
Sound files play when they should not.
How do I find which version of Deep Matrix I am
using?
Linux Issues?
This is a system that allows different
individuals to participate, inter-act and share together in realtime computer
simulated 3D environments.
that are usually called "worlds".
The individuals appear as computer generated images to other users sharing
the same
world. Users communicate by both
typing messages and using shared events where the same animation can appear
almost simultaneously
on the users' computers.
I used the term system because
the client application is actually two applications working
together on the end user's computer.
A. The application that generates
the 3D images -in this case called "Instant Player".
B. An open-source application
that does the networking that is called the "Deep Matrix client".
Instant
Player and Deep Matrix commuicate with each other using
External
Authoring Interface or "EAI".
There is a third application involved
as well and that is the "Deep Matrix server". It is the hub that unifies
all the users
on the network. It is part of
the same open-source code as the Deep Matrix client. All of my coding work
has been with
the open-source Deep Matrix client/server
system which is written in the Java programming language. The name "Deep
Matrix"
was given to the code by the now-defunct
organization called Geometrek back in the late 1990s and made open-source
by them.
Instant Player uses a 3D
programming language called VRML to generate the 3D images. VRML has been
around since 1995
and has been reincarnated as X3D.
Please see this link for more on VRML and/or X3D: Web3D.org
Finally, I did not write "Instant
Player" or take part in its development. All the work for Instant Player
was done by the organization
found at this link: Instant
Reality
Education. My long term vision for it
is to be able to give real-time lessons in geometry with it, but it could
be
used to teach architecture or a variety
of other subjects as well.
It can be used by artists too. I hope to see
it used by performance artists.
Games can be played with it as well, although
it really isn't fast enough or graphically sophisticated enough to keep
up with
what are called "first person shooter games".
It also has a potential as a social networking
medium.
3. Isn't Java EAI obsolete? -or- Isn't Java EAI deader than VRML itself?
"EAI" is only an acronym that means "External Authoring Interface"
There are many ways to implement an External Authoring Interface and
the most
famous (or infamous) one involving VRML browser plug-ins for Internet
Explorer
and Netscape is indeed dead. However Instant Player's implementation
of the EAI
spec is a stand-alone one with no HTML browser involved and utilizes
the very latest
Java Runtime Environment from Sun Microsystems. As a matter of fact
Instant Player's
spec
http://www.instantreality.org/tutorial/external-authoring-interface-javanet/
allows its EAI to be written in a variety of programming languages.
I chose to use Java, because I am familiar with its use in the dead
plugin implementation
of EAI.
4. How
do I start working with Deep MatrixIP9?
Please see Quick Start
above and read these documentation htmls thoroughly.
5. Why is the download size for Instant Player so large?
The Windows version is large. The Mac and linux versions
are relatively normal.
The reason the Windows version is so large is because
there are alot of other programs that are associated or are
meant to work in coordination with Instant Player included
in the download. Quite honestly I don't know what most
of those progams are for! My interest in Instant Player
has been purely in its VRML and EAI capabilities.
However there is information about those other programs
available at the Instant Reality site: Instant
Reality
6. I tried adding my world without modification to the room list and
it had one or more of the following problems:
A. I went into ghost to view my avatar and was taken
to a viewpoint not anywhere near where I started.
Most probably it is a result of an Instant Player bug stemming from the
use of DirectionalLights
below the first level of your scene-graph. Please read this help page:
DirectionalLights
Issue
I have all seen the problem occur in some worlds that have the ProximitySensor
creep issue.
B. Not all of my textures loaded.
Hopefully, part of this has been fixed as of version 1.03!
Another Instant Player bug. Please read this help page: Textures
Not Loading
C. When I am not moving I notice that somehow I
still am ever so slightly.
Yet another bug. Please read this help page ProximitySensor
Creep
D. My sound files won't play.
Please read this help page: Sound
Files Not Playing
E. My animated Viewpoint
is really jerky.
Animated viewpoints in InstantPlayer must have the NavigationalInfo mode
set to "NONE" or "FLY".
It is a conflict with gravity of the "WALK" mode that is causing the jerkiness.
Please read my brief tutorial
on animated Viewpoints:
F. Instant Player crashed.
Instant Player is still in beta (testing) development. This means it has
bugs and since it is relatively new
it doesn't have the stability of Bitmanagement Contact which has been in
development for over a decade.
While I cannot claim Deep MatrixIP9 is completely stable, I will claim
it IS more stable than blaxxun
community chat server system and more particularly its chat client.
Most crashes I have dealt with involve problems with DirectionalLights
mentioned above: DirectionalLights
7. When I select "Ghost" under the Navigation menu
to view my avatar why doesn't my avatar stay in front of me when
I move?
This is a feature
generally put into 3D viewers that are purposely designed for use multi-user
systems.
Instant Player
does not fall into that description, rather Instant Player has been adapted
to use in the Deep Matrix multi-user system.
Sadly Instant
Player doesn't have a way to duplicate that feature of Contact, Vivaty
and OctagaPlayer.
My attempts
to duplicate it in Instant Player did not have the avatar following terrain
with the camera, so if the user is going up hill the
avatar will
be partly submerged in the landscape. Likewise if a user is going down
hill his avatar will appear to be up in the air.
However Instant
Player is still in beta with a lot of extension Nodes that have not yet
been fully implemented. Prehaps had some time in
the future one
of those Nodes will provide a solution. In the mean time I am kept the
Ghost mode of the original Geometrek applet version
of Deep Matrix.
This Ghost mode cause the avatar geometry stops moving completely.
8. The 2D chat application compiles, but doesn't work
right.
The Chat only application
found in the chat folder has not been tested at all recently, because my
focus has been on the 3D networking code.
Fixing it is a "To Do".
9. How do I use the various choices and options in
the Deep Matrix client?
Just pull
down the menu and select your desired choice/option or feature.
The client
will tell you how to use it -sometimes with simple examples.
10. Why do I see all kinds of errors -some of which
are marked as "FATAL" in red letters"- on Instant Player's console?
Instant Player is still in beta. It still has bugs
in it. Basically those errors should be ignored IF your world works fine.
However if your world DOES NOT work fine, then it IS time
to pay attention to the console!
Especially if the "FATAL" error looks like this:
"FATAL ECMASpt Cannot compile/evaluate script: "
A red "FATAL ECMASpt" is cause to look at your code!
11. Why does my AudioClip plays automatically when
I enter the world? -or- Why do the Sound Node parameters of maxFront, maxBack
minFront and minBack seem to be ignored? Sadly this is a bug related
to Instant Player, Windows XP, Mac and and prehaps Linux operating systems.
Please see my thread on the Instant Reality support
board: http://forum.instantreality.org/index.php?topic=609.0
The short story is Windows XP is fixable by setting
the sound card hardware acceleration to either basic or none (which ever
works)
Mac there is no fix per se and Linux I am simply
unsure.
The best work around is to use the Matrix_Sound
Node. It will play .wav formats as well as the more esoteric ones.
12. How do I find which version of Deep Matrix I am
using?
Type into the chat (minus quotes): "/version?"
13. Linux Issues?
DISCLAIMER! I am a Linux novice, so any Linux information in
this README may be incorrect!
Deep MatrixIP9 has been successfully run on Fedora 11 and Ubuntu
9.04.
The rules of thumb for working on Linux seem to be basically
four fold:
A. Successfull installation the 3D graphics driver.
B. Successfull installation of Instant Reality/Instant Player.
C. Successfull installation of the latest Java JRE.
D. (The all-important gotcha) DOES the bin folder of the instant
Realtiy directory contain "instantreality.jar"?
If it so, then Deep MatrixIP9 should work.
If it IS there and all you cannot get a local connection to
the Instant Player browser and have an error similar to this:
vrml.eai.ConnectionException: Connection reset - localhost/127.0.0.1:4848
Then there is a bug with that particular Linux Instant Player
build and it needs reported to the Instant
Reality Forum !
See this thread for the initial problem I had with Fedora: http://forum.instantreality.org/index.php?topic=666.msg1869#msg1869
If the instantreality.jar is NOT there then, then EAI for Instant
Player (and consequently Deep MatrixIP9) will not work for that version
of Linux.
and probably will still not work even if an instantreality.jar
is placed into that folder.
Consequently Deep MatrixIP9 seems NOT to be able to work on:
Ubuntu 10.04 and Ubuntu 9.1!
See my post here: http://forum.instantreality.org/index.php?topic=660.msg1857#msg1857
E. Sound issues. Sound has always been a tricky issue in Linux.
The rule of thumb is (hopefully) If Instant Player has sound,
then the Matrix_Sound Node that plays mp3 files
will work too.
Again: As of 6/25/10 the position parameters in the Screen.x3dv
file seem to be ignored in Linux - a minor annoying bug.
14. Nothing works -or- on initial starting
the Deep MatrixIP9 Java Client shows but the Instant Player 3D viewer does
not load.
Deep Matrix is intialized or started via scripts. Permissions
maybe needed to run these scripts. Reports from Apple Leopard users
have stated issues with this.
On permissions on Apple and Linux are done with:
with the terminal and the chmod command:
chmod +x client_application/Mac_Client/*
chmod +x client_application/Linux_Client/*
As of version 1.03 the Java application loads and closes the
Instant Player to clear memory. The application does
this by calling the appropriate script for your operating system
in the client_applications/browser_scripts directory.
There maybe a permissions or security issue that keeps the Java
application from launching those scripts.
In the case of Apple permissions can be done via terminal with:
chmod +x client_application/browser_scripts/*
chmod +x client_application/browser_scripts/*
This system has NOT been tested on Vista Windows which has a reputation
for being paranoid on security,
so issues with that may need to be worked out. Any reports or information
on Vista problems would be appreciated!
Compiling:
As of version 1.03 there is now a compiling folder with scripts for
each operating system and a read me.
Please refer to that folder and read me!
To Do:
2. Finish the backpack object code.
3. Finish the admin code
4. Retro work the code for the old EAI applet version. Since InstantPlayer
can only open one
window at time, having an actual second vrml browser as a user/client
would be a useful thing
for testing.
5. Look into text to speech engines
6. Test methods for reducing bandwidth useage.
7. Get the 2D basic chat applet working again.
Support Requests:
All support requests must come with Instant Player console error print
outs AND Java console print outs.
Requests without those items will be ignored.
Post your problems on the deepmatrix.org forum: Deep
Matrix Forum
-or-
Send your problem to: pyth7@deepmatrix.org