Index of /documentation

[ICO]NameLast modifiedSizeDescription
[PARENTDIR]Parent Directory  -  
[IMG]AS2Conversion1.jpg2017-06-08 20:25 47K 
[IMG]AS2Conversion2.jpg2017-06-08 20:25 33K 
[IMG]AS2Conversion3.jpg2017-06-08 20:25 18K 
[IMG]AS2Conversion4.jpg2017-06-08 20:25 16K 
[TXT]Protos.txt2017-06-08 20:25 60K 
[ ]Protos.wrl2017-06-08 20:25 60K 
[TXT]README.html2017-06-08 20:25 32K 
[TXT]admin.html2017-06-08 20:25 7.4K 
[TXT]avatar_sharedobjects.html2017-06-08 20:25 21K 
[ ]pbtb.tmp2017-06-08 20:25 25K 
[TXT]worlddeveloper.html2017-06-08 20:25 25K 
README Quick Start
Introduction  Requirements  How to Put Your World on the Public Server Display Info New Features FAQ
Compiling  To Do Support Requests  Avatars and Shared Objects  Server Administration World Developer Information Deep Matrix Prototypes

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?

1. What is this?

       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

2. What is it good for?

      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".