PLEASE Read this throughly. This for version 1.03 and later, so there have been some major changes in Quick Start!
Updated as of 1/08/2013.
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, Vista, 7 and 8 based
on Instant Player requirements.
It will work on Apple computers, both
powerPC and Intel processors based again on Instant Player requirements.
However, the included bash files which were written for Apple will have to be
modified directory-wise accordingly.
It has been tested and works on
the linux flavors of Suse, Fedora, Debian, and Ubuntu and will
MOST PROBABLY work on Red Hat as long as the Instant Player
requirements are again met AND there is "instantreality.jar" in the bin
directory.
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_05.zip:
A. On Windows as: "C:\DeepMatrixIP9-v1_05"
(If you are using another drive you must edit the batch files
by hand to match.)
B. On Apple as:
"Applications/DeepMatrixIP9-v1_05"
C. On Linux to your Desktop as:
"DeepMatrixIP9-v1_05"
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 Suse, Debian, 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.
Send your problem to: pyth7@deepmatrix.org or pyth7@verizon.net
You can also join the forum @ Deep Matrix Forum
To join
please send an e-mail to either of the above e-mail addresses with the
subject line: "Join Deep Matrix
Forum".