Extending CopperCube with JavaScript

You can extend CopperCube by defining your own actions using the Javascript programming language. Both files are located in the CopperCube documents folder. In my case this path is C:\Users\Mike\Documents\CopperCube\extensions. The name of the file you create is important. If you are creating a new action prefix your file with the name action_, while if you are creating a new behavior, instead use behavior_. In this case, we are going to create a simple new action called test. So create a file called action_Test.js in this directory.

We are going to create a simple node that you can attach to Sound nodes in the scene. This action simply toggles between looping the sound or stopping it completely. First, you start off with a special comment that defines the action and what parameters it uses. This is a simple XML file inside an HTML comment:

/*
 <action jsname="action_Test" description="This is a test action">
 <property name="ChangeWhichNode" type="scenenode" />
 </action>
 */

This defines a new action named action_Test… this must match the file name to work! We also define a description to be displayed in the Coppercube editor. This action takes a single parameter called ChangeWhichNode which is of type scenenode.

Now we implement the logic of our action. When the action runs, it looks for a function called execute(), we declare our new action and then implement the execute function.

action_Test = function()
{
};

// called when the action is executed
action_Test.prototype.execute = function(currentNode) {

    if(ccbGetSceneNodeProperty(this.ChangeWhichNode,"Type") !== "sound"){
        print("Not an audio node!");
        return;
    }
    print(ccbGetSceneNodeProperty(this.ChangeWhichNode,"PlayMode"));
    if(ccbGetSceneNodeProperty(this.ChangeWhichNode,"PlayMode") == "nothing") {
        ccbSetSceneNodeProperty(this.ChangeWhichNode, "PlayMode", "looping");
        print("Playing audio");
    }
    else {
        ccbSetSceneNodeProperty(this.ChangeWhichNode, "PlayMode", "nothing");
        print("Stopping audio");
    }
}

In this code we simply check to see if the node passed in is of type “sound”, if it is, we toggle the property “PlayMode” between nothing and looping, causing the sound to either stop playing or to start playing over and over.

Now head back over to Coppercube and select Plugins->Reload and Verify Extensions and Plugins.

CopperCube 6 - Extending CopperCube with JavaScript - Reload and Verify Extensions and Plugins

So long as there are no errors in your code, your newly written addon should now be available for use. Add a 3D Sound object to your scene, add a Key pressed behavior to this object. Now in the Action of that Behavior, your newly created Action should be available for use under the Scripted Action section.

CopperCube 6 - Extending CopperCube with JavaScript - Scripted Actions

You will notice in the properties, there is a parameter you can use to define which Sound node to toggle on and off.

CopperCube 6 - Extending CopperCube with JavaScript - Sound Node

There you go, you just expanded the functionality of CopperCube to now be able to toggle playback of audio files, functionality that was currently missing. This action will no be available to all of your future CopperCube projects.

You may have noticed under Scripted actions and Scripted Behaviors, there was an option to Download more…

CopperCube 6 - Extending CopperCube with JavaScript - Scripted Behaviors

This will bring you to a download page with plenty of examples of both actions and behaviors, a great way to extend your engine or to learn from for writing your own extensions.

CopperCube 6 - Extending CopperCube with JavaScript - Downloaded Scripted Actions, Behaviors and Plugins

On the topic of coding, you might wonder exactly what code you have available to you. You can learn more about the programming model here and find a full api reference here. Additionally, Coppercube is built on top of the open-source Copperlicht game engine. I personally downloaded the engine Javascript source and configured it as a library in IntelliJ to give me full code completion when writing code.

You can also enter JavaScript directly into a script window inside of CopperCube, either to make one-off changes or to develop your own action code. Select View->Show Scripting Window

CopperCube 6 - Extending CopperCube with JavaScript - Show Scripting Window

Then in this Window, you can enter whatever Javascript code you want.

CopperCube 6 - Extending CopperCube with JavaScript - Scripting

To run the code click execute:

CopperCube 6 - Extending CopperCube with JavaScript - Execute

Scroll to Top