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

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

Cult3D Java API Documentation

Known bugs

Known limitations in Cult3D's Java support

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