Cult3D 5.3 Java API Documentation First Page

Welcome to a wonderful world of Cult3D and Java.

This documentation is an short introduction in how to use Cult3D's Java API. Use it as a quick quick-reference, you really should read the Cult3D Documentation and it's appendix enclosed in Cult3D Designer software package.

The topic KnownGotchas has some guideline what not to do, it is important that you read this.

There is also a Cult3D community on the web, which among many things have several forums where Cult3D users can ask and discuss things about Cult3D. It is called World Of 3D and can be found at this address http://www.worldof3d.com

See the enclosed Cult3D Designer documentation and it's appendix for a fuller description of Cult3D Java.

Have a lot of fun with Cult3D.
Your Cycore team.

Cult3D Java API Documentation What is Java

A brief explanation of what Java is and isn't

First some terminology
The computer language Java is a "compiled" programming language created by Sun Microsystem Inc. In Java you can do both big applications and small applets. (Applets are running in your webbrowser).
JavaScript is a interpreted language which you don't compile, and the majority of all Javascripts is in HTML web site's, and it's purpose is to enhance the look'n feel of the webpage.

In Cult3D you use the Java programming language with Cycore's Cult3D Java API. Java code used in Cult3D is known as Cult3D Java.
To be more precise, you can use Cult3D Java to control and manipulate Cult3D objects. Some very popular things to do with Cult3D Java is to change textures and rotate object. The Cult3D Java code must be embedded into the Cult3D Designer and is stored in the .co file. JavaScript is not embedded in the Cult3D Designer neither is it in the .co file. You include the Javascript code in your HTML page which hosts the Cult3D object.

Some links

- Sun's Java tutorial (http://java.sun.com/docs/books/tutorial/)
- Introduction for Java (http://developer.java.sun.com/developer/onlineTraining/new2java/)
- A free online Java book (http://www.bruceeckel.com)

Cult3D Java API Documentation Java Startup class

How to implement Java into Cult3D

When programming Java for Cult3D you must declare one class to be your startup class, to do this you must implement the interface com.cult3d.Cult3DScript, and you must implement the method public void cult3dDestroy() in your class. The method cult3dDestroy() is called from the Cult3D Viewer when it is being shutdown, and is the perfect place to do cleanup and release resources.

When making your startup class for Cult3D you must do a public constructor which takes no argument, even if it does nothing. You must also make your startup class public.

When having several classes in your project you must use your startup class as a sort of a proxy. Let all your calls to other classes go through your startup class.

When you use Java packages let your startup class reside in the default package, more detail in Java Packages.

EXAMPLE CODE

>     The most basic Java class one can do.

>     import com.cult3d.Cult3DScript;

>     //Your public startup class for your Cult3D Project which implements the interface com.cult3d.Cult3DScript
>     public class BasicSnippet implements Cult3DScript
>     {
>         // Standard constructor
>         public BasicSnippet()
>         {
>         }

>         // This method is called when the
>         // Cult3D viewer is being shutdown.
>         public void cult3dDestroy()
>         {
>         }
>     }

>     A proxy Java class

>     import com.cult3d.Cult3DScript;

>     //Your public startup class for your Cult3D Project which implements the interface com.cult3d.Cult3DScript
>     public class BasicSnippet implements Cult3DScript
>     {
>         // Your other class
>         private OtherClass x;

>         // Standard constructor
>         public BasicSnippet()
>         {
>             x = new OtherClass();
>         }

>         //This method is called from the Cult3D Designer, and it forwards a call
>         // to the other class's method startObject()
>         public void startObject(String s)
>         {
>             x.startObject();
>         }

>         // This method is called when the
>         // Cult3D viewer is being shutdown.
>         public void cult3dDestroy()
>         {
>         }
>     }

Cult3D Java API Documentation Threads

Threads with Cult3D

When doing multi-threaded Java in Cult3D, you should think of some important issues. Load all heavy things in a separate thread, such as resources and textures, in other case your Cult3D scene may freeze.

If you are looping in your run method, check a boolean variable if the Cult3D Viewer is about to die, set this boolean in the method cult3dDestroy().

When you are inside the run method you should catch the exception java.lang.IllegalStateException, it will be thrown if the Java code tries to do anything meanwhile the Cult3D Viewer is about to die.

In a multi-threaded Java program you can in some cases end up with different versions of the same variable in a multi-threaded Java, due to the JIT compiler introduced by Sun in Java 1.1. This can be true in Cult3D Viewer were different viewer threads calls your Java methods. To avoid this you should use the keyword volatile, please understand that a variable declared volatile is less efficient than it's counterpart. It is strongly recommended to declare your "thread death" variable volatile.

EXAMPLE CODE

>     import com.cult3d.Cult3DScript;

>     public  ThreadSnippet  implements Cult3DScript, Runnable
>     {
>         // Declare this variables volatile to ensure
>         // it is always holds the correct value
>         private volatile boolean  stillRunning;
>         private volatile boolean  finishedLoading;

>         // Standard constructor
>         public  ThreadSnippet()
>         {
>             stillRunning = true;
>             finishedLoading = false;

>             new Thread(this).start();
>         }

>         // This class thread-run method.
>         public void run()
>         {
>             // Load some resources or other heavy stuff

>             // State the loading is done
>             finishedLoading = true;

>             while (stillRunning)
>             {
>                 // do something repeatedly
>                 try
>                 {
>                     Thread.currentThread().sleep(100);
>                 }
>                 catch (InterruptedException e)
>                 {
>                 }
>             }
>         }

>         // Some method you call from the Cult3D Designer
>         public void methodX(String arg)
>         {
>             // If all has not been loaded return
>             if (!finishedLoading)
>             {
>                 return;
>             }

>             // Do something
>         }

>         // This method is called when the
>         // Cult3D viewer is being shutdown.
>         public void cult3dDestroy()
>         {
>             try
>             {
>             	// Tell the thread to stop working
>             	stillRunning = false;
>             }
>             catch (Exception e) // Catch all exceptions silently while stopping threads
>             {
>             }
>         }
>     }

Try to use an absolute minimum of extra threads. Cult3D as well as Java are cross platform and there are systems and web browsers which do poorly multi-threading. It is strongly recommended to just have two threads in you Cult3D Java, your main thread and an extra thread that you create to load resources.

You can simulate threads in Cult3D Designer. One way to do this is to have a Timer event which activates a Java method, the Timer resets itself after been triggered.

Cult3D Java API Documentation Class path for Cult3D Java

Class path

When you compile Cult3D Java, you must supply the path to the Cult3DDevelop.jar file.
However you cannot enter this to your system class path when any web browser is running, you should supply it when compiling your Java classes. Otherwise some web browsers will be very confused.

Example with Sun's JDK 1.1
In this example lets assume you have installed the Cult3D Designer in its default path, C:\Program Files\Cycore\Cult3D Designer\

javac -classpath ".;%CLASSPATH%;C:\Program Files\Cycore\Cult3D Designer\Cult3DDevelop.jar;" YourCode.java

Cult3D Java API Documentation Java Packages

Java Packages

In some large projects it is often necessary to have Java classes in different directories on your filesystem. When putting Java files in directories it is called to put those files in a package.

When you want to structure your Cult3D Java project with Java packages, you must let your startup class to be in the default package, (do not explicitly tell what package your startup class is resided in). You can put any number of the other classes in any number of Java packages.

See the enclosed Cult3D Designer documentation for screenshots and more info on this topic

Cult3D Java API Documentation Connect Java with Cult3D Designer

Connect Java with Cult3D Designer

In order to add functionality to Cult3D with Java, you must have methods in your Java startup class which are public and takes a string as its only parameter. Note, In the Cult3D Designer you should only call methods from your startup class.

EXAMPLE CODE

public void cult3dMethod(String designerArg)
{
}

In the Cult3D Designer choose View->Java Actions. In the window that pops up choose to add your compiled Java classes to the Cult3D Designer.
In the field where it says Startup class you choose the Java class which implements the com.cult3d.Cult3DScript.
If you have a Cult3D Designer prior to 5.2 you must write the name of the class which implements the com.cult3d.Cult3DScript, note you must also supply the extension .class for your startup class the first time you add it.

Click the (+) sign in front of your startup class and all your methods which are public and have a string as its only parameter is becoming visible. You can drag this Java methods to any Cult3D Designer events.

If you connect a Java method to a mouse event, the string parameter in the Java code will hold the name of the object you clicked on with the mouse. If you connect a Java method to a KeyEvent the key pressed will be passed to the string parameter, etc.

See the enclosed Cult3D Designer documentation for more information and some screenshots.

Cult3D Java API Documentation Compilation

Getting a Java compiler
The first thing you need to do is to install a Java compiler, you can find the defacto standard compilers at Sun's Java site, http://java.sun.com .

You can find Sun's Java compilers at the Java platform standard edition site http://java.sun.com/j2se/ .
When deciding which compiler to download and use, remember that most web browsers supports only Java 1.1.

There is also other than Sun that supplies Java compilers, for example IBM , GNU and WebGain

Installing
Follow the onscreen instructions to install the selected Java compiler.
Sun's Java compiler is a command-line program which must be invoked from a command prompt, "\bin\javac your-Java-code.java".

Writing Java code
You can use any text editor which can save your Java code in plain text (ASCII), such as Notepad or Emacs, just be sure to save with .java file-extension.
You can also use an IDE (Integrated Development Environment) to write the Java code, these IDE's offers various help as you write your code such as project management, syntax error highlights, etc.
There is a lot of IDE's out in the world, both commercial and non-commercial.
Here is a list of some them.
Unordered List of Java IDE's
OmniCore's CodeGuide , Written in Java, Syntax error highlights, Code completion, etc
Sun's Forte for Java, , Written in Java, Gui Builder, etc
WebGain's VisualCafe , Gui Builder, Code completion, etc
Borland's JBuilder Written in Java, Gui Builder, Syntax error highlights, etc

Compiling Java code
When you compile Java for Cult3D, you must supply the path to the Cult3DDevelop.jar file.
However you cannot enter this to your system class path when any web browser is running, you should supply the path when compiling your Java classes. Otherwise some web browsers will be very confused, and you will get (not so) funny error messages.

Example to compile with Sun's JDK 1.1
In this example lets assume you have installed the Cult3D Designer in its default path, C:\Program Files\Cycore\Cult3D Designer\, and your Java compiler in c:\jdk1.1

c:\jdk1.1\bin\javac -classpath ".;%CLASSPATH%;C:\Program Files\Cycore\Cult3D Designer\Cult3DDevelop.jar;" YourCode.java

Cult3D Java API Documentation Howto Debug

Debug Cult3D Java

There is no really easy way of debugging Cult3D Java code. One way of debug is to write debug text to the Java console at certain points in your code.
The output ends up in the applications Java console that runs the Cult3D scene.

### How to open the Java console

- In Netscape's webbrowser 4.7 you open the Java console by choosing the menu alternative Tools-->Java Console. In earlier versions of Netscape you can find the Java console in the View menu
- In Microsoft's webbrowser Internet Explorer 4.0 and later you must first activate the Java console for it to appear in the menu. You activate the Java console by choosing the menu alternative Tools-->Internet Options, there you select the tab Advanced. Search for the topic "Microsoft VM" and make sure that all three checkboxes are checked. Restart then Internet Explorer for the settings to be activated. In the restarted Internet Explorer you find the Java console by choosing the menu alternative Menu-->Java console.
  Be sure that you have the Java console open before you load the Cult3D object, otherwise you will not see the messages printed in Cult3D's initializing phase.
- In Acrobat and Acrobat Reader the output you write is written to a file in the same folder you installed the plug-in.

Cult3D Java API Documentation Known bugs

Known limitations in Cult3D's Java support

- JVM version
  Most major web browsers only supports Java 1.1, if any at all.
  However there are separate plug-ins to download to different web browsers to upgrade the version of the Java Virtual Machine (JVM). When planning on displaying an object on a computer or on a public webpage, take in consideration that objects which take use of Java features of any other version than the current JVM installed will of natural causes not work properly. Also note that using a higher version a Java compiler and a lower version Java VM compatibility might cause incompabilities.

- Java GUI
  The GUI part of Java should be avoided. In particular AWT and Swing. Other parts of these packages might be used.

- Threads
  Use only one thread per Cult3D project.
  In order to have a fully functional Cult3D object with threads you should avoid restart/pause that single thread.
  Let the thread sleep in intervals and poll a variable to see if the thread should perform any action.

- Cult3D Designer preview
  You cannot preview the Java code in the Cult3D Designer. You must save the project as an Internet file (.co) and load that file in an appropriate Cult3D enhanced application, in order to see the result of your Java code.
  There is a third-party tool to simplify this process, and allows Java code to be previewed in the Designer, you can find the program "Cult3D Designer Extension" in www.WorldOf3D.com resources section. Please note that Cycore does not support that program.

- Textures and images
  When you create your model in your modeling application, please remember that you always should have the textures width and height in power of 2. Today Cult3D supports sizes of 1, 2, 4, 8, 16, 32, 64, 128, 246, 512, 1024 and 2048.
  Cult3D is not restricted to square textures, you can for instance use the texture size 512x64.

- Materials
  Indexes on multisub-materials are not constant during loads of the Cult3D object. And you can of that reason not assume materials indexes in your Java code.
  There are two things you can do to change materials with more than one indexes. You can use 5.3 way of handling Materials, read the com.cult3d.Material documentation, or you can traverse every material on your object and search for the one you are interested in. It is recommended to avoid Cult3D's Material class and substitute it with the Cult3D's texture class.

- Subworlds in Java
  There are some methods in the com.cult3d.World package that are reported having bugs.
  The methods reported are
  - java.lang.String getActionName(java.lang.String name)
  - java.lang.String getEventName(java.lang.String name)
  - java.lang.String getExpressionName(java.lang.String name)
  - java.lang.String getMaterialNameName(java.lang.String name)
  - java.lang.String getSceneGraphName(java.lang.String name)
  - java.lang.String getSoundName(java.lang.String name)
  - java.lang.String getTextureName(java.lang.String name
  - java.lang.String getToolTip Name(java.lang.String name)
  - java.lang.String getWorldName(java.lang.String name)
  These methods are supposed to get the new name assigned to it, if there is a conflict between names. But the Java methods often enough throws a com.cult3d.NameNotFoundException(), a workaround for this is to give every node, material, texture, world, etc a unique name and by that avoid the name-conflict, and therefore you don't need to use these methods.
  Note: Cycore will fix this bugs, in a near future, but can do so when releasing a small update of the viewers and or designer, without notify the users.

- Undocumented methods in the Java API
  Undocumented methods in the Java API are not supported by Cycore and Cul3D, you can test them if they work, but there are no guarantees that it will work, and how it will work in an other browser and operating system, and in different versions of Cult3D. Undocumented methods can be removed in a later version of Cult3D.

Last updated: 28:th of August, in the year of our lord 2002.