Back to Content

Plugins

CopperCube supports plugins, the creation and using of little helpers in the editor to make your work easier. Plugins can manipulate 3d geometry in the scene, import 3d file formats, setup and modify 3d scenes, adjust material settings and more.

How to create a plugin

If you have started CopperCube at least once, it usually already has created an empty example plugin for you in the documents folder if you are using Windows. Go to the directory C:\Documents and Settings\username\Documents\CopperCube\plugins, there should be an example_plugin.js file. This is the place you can start creating your own plugins. If you are using Mac OS X, go to your ~/Documents folder, create a sub directory 'CopperCube' and then 'plugins' there.
Open an text editor, and create a new file, named for example 'test.js'. Plugins are written in JavaScript, hence the extension '.js'.
Write the following line of text into the file:

function printHello()
{
  alert("Hello from your own plugin");
}

// add the hello function to the plugin menu
editorRegisterMenuEntry("printHello()", "Print Hello (example script)\tCtrl+H");

Then save it, and start CopperCube. When everything worked correctly, you should see a menu entry named 'Print Hello' in the plugin menu of CopperCube under Edit -> Plugins:

If you click the command, or press the shortcut Ctrl+H (as specified in the code above), the function printHello() will be started, and show this message box:

If you don't see this, you did something wrong. For seeing potential error messages, you can open the Output Window, choose 'View -> Show Output Window' for this. Starting with this knowledge, you should be able to create your own simple plugins.

Using the script window

The need to restart the editor all the time to test your code is a bit impractical. That's why there is the script window:

You can develop your code in there as well, and once it is working, copy it to your script file. Use the menu command 'Show -> Scripting Window' to open the scripting window. Note that some functions, like the editorRegisterMenuEntry() function to create the menu item, only work from the startup plugin files and not from the scripting window.
This window is also useful for developing plugins: By entering a new implementation for an already existing function (like the printHello() function above), you overwrite existing functions. When you use the command from the plugin menu again, your new function will be executed instead of the old one.

Do something more useful

In order to do something more useful in the plugin instead of just printing a message, there are numerous functions available to access almost everything in the editor. See the comprehensive CopperCube JavaScript API scripting reference for this, with a list of all functions and lots of examples. As example, here is a plugin which will print the polygon count of the currently selected item:

function printSelectedPolyCount()
{
  var meshnode = editorGetSelectedSceneNode();
  var bufferCount = ccbGetSceneNodeMeshBufferCount(meshnode);
  if (bufferCount == 0)
    alert('The selected node has no 3D geometry.');
  else
  {
    var totalIndexCount = 0;
    for (var i=0; i<bufferCount; ++i)
      totalIndexCount += ccbGetMeshBufferIndexCount(meshnode, i);

    alert('The selected node has ' + (totalIndexCount/3) + ' polygons.' );
  }
}

editorRegisterMenuEntry("printSelectedPolyCount()", "Show poly count\tCtrl+P");

Copy and paste this code into your test.js, restart the editor, and you have a new tool available.

Function List

You can find a list of all avaiable functions here.