## Plugins

With CindyScript it is possible to enhance and customize the behavior of Cinderella in an almost unlimited variety of ways. Still it may be desirable from time to time to be able to use self-written Java code in connection with Cinderella. The Cinderella Plugin Structure gives a way to handle such situations. There may be several reasons that make it desirable to use a plugin. Here are some of them

- Performance: For some tasks CindyScript may simply be too slow, so that one wants to use some custom optimized code.

- Native libraries: Sometimes one wants to use native libraries (like for instance the JOGL library for dealing with 3D graphics). In these cases a plugin may be used to link Cinderella to this library.

- Licensing issues: Plugins make it possible to write and to offer extensions for Cinderella that run under a specifically chosen license (for instance GNU GPL). We will make use of this ourselves in the future and publish open source extensions to Cinderella. These plugins will be available for download soon under....

- Third-party code: Plugins also form a good basis to include Java code written by others into a Cinderella project.

At the time of this writing, Plugins are only available in the standalone version of Cinderella and are not applicable in applets. This will be fixed in the near future.

### Plugin Architecture

For detailed descriptions of the plugin architecture see our website at http://cinderella.de/plugins. There you may also find example plugins as well as suitable make files to create them. Here we only describe the workflow very roughly.
A plugin itself is a `.jar` file that contains executable Java classes. The core link of the plugin is a Java file (compiled to a class file) that exports all the functionality of the plugin to Cinderella. Within Cinderella, the plugin can be accessed using CindyScript. The core file of the plugin must extend the Java class `CindyScriptPlugin`. This parent class is available through the `cindy2.jar` file in the Cinderella application.
The code for a plugin may typically look as follows

    import de.cinderella.api.cs.CindyScript;
    import de.cinderella.api.cs.CindyScriptPlugin;
    import java.awt.*;
    import java.util.ArrayList;
    import java.util.Arrays;

    public class ExamplePlugin extends CindyScriptPlugin {

        public String getName() {
            return "Example Plugin";
        }

        public String getAuthor() {
            return "Ulrich Kortenkamp and Juergen Richter-Gebert";
        }

        @CindyScript("sayHello")
        public String testFunction() {
            return "Hello from Plugin";
        }

        @CindyScript("square")
        public double quadrieren(double x) {
            return x * x;
        }

        @CindyScript("grayvalue")
        public double getGray(Color c) {
            return (c.getBlue() + c.getRed() + c.getGreen()) / 3.;
        }

        @CindyScript("testarray")
        public String writeArray(ArrayList al) {
            return Arrays.toString(al.toArray());
        }

    }

The fragments given by code like `@CindyScript("square")` declare the name under which the function is accessible in CindyScript. The plugin can be used in CindyScript after it has been loaded with the `use` function:

#### Loading a plugin: `use(<string>)`

Description: This function loads a plugin with the name given as argument.
It is good practice to call this function in the initialization slot of CindyScript.
So the above plugin may be used within CindyScript as follows:

    use("ExamplePlugin");
    println(sayHello());
    println(square(4));
    println(grayvalue((0.7,0.4,0.1)));
    println(testarray([1,2,3,4,5]));

This will create the output

    Hello from plugin
    16
    102.3333
    [1.0, 2.0, 3.0, 4.0, 5.0]

Observe that all class casts are performed automatically. For a detailed description of the casting rules see the online documentation.

### Available Plugins

At the time of this writing there are only few plugins available. We publish all user contributed plugins on our website at http://cinderella.de/plugins, so please check there for current versions. Here we briefly present two of the them.

#### Cindy to LegoNXT Communication

This plugin written by Michael Schmid provides a high-level interface to Lego Mindstorms NXT block. With this plugin all inputs and outputs of the Lego computer can be accessed and controlled. Thus it is possible to use Cinderella as a controller for Lego robots.
Among others this plugin implements statements like `nxtforward(...)`, `nxtturnright(...)`, or `nxtgetlight()`. Using these statements it is for isntance directly possible to use a CindyScript program to influence the behavior of a robot car that is sensible to light changes.
You can download the plugin along with a brief documentation from our webpage.

#### Cindy3D

Another project is the use of the JOGL 3D interface as a 3D output device for Cinderella. A Plugin called Cindy3D designed by Matthias Reitinger, Jürgen Richter-Gebert and Jan Sommer will be specialized to this task. Using this plugin it will be possible to use 3D drawing functions directly from CindyScript. There will be functions for drawing points, lines, circles, polygons and three-dimensional meshes. The following three pictures which were generated via CindyScript give a rough impression of the possibilities of the plugin.

Page last modified on Monday 05 of September, 2011 [10:14:28 UTC].
The original document is available at http://doc.cinderella.de/tiki-index.php?page=Plugins