Plugin API

Chunky 1.4 added experimental plugin support. This page documents how to build a new plugin for Chunky, and the available plugin API interfaces.

The full JavaDoc API documentation is unavailable at the time.

Creating a basic plugin

Chunky plugins are packaged as Jar files with a main class extending the interface se.llbit.chunky.plugin.Plugin.

The simplest way to start building a plugin is to copy one of these existing sample plugins:

The Chunky plugin API can also be used to build new applications based on Chunky. Here is an application that uses parts of the Chunky rendering system to render different kinds of Minecraft blocks and items:

Test Renderer

For building your plugin you can use Gradle. Here is the Gradle build script from the custom Render Controls tab plugin:

apply plugin: 'java'
apply plugin: 'application'

repositories {
    mavenLocal()
    mavenCentral()
}

sourceCompatibility = '1.8'
targetCompatibility = '1.8'

dependencies {
    compile 'se.llbit:chunky-core:1.4.1'
}

defaultTasks 'jar'

mainClassName = 'se.llbit.chunky.plugin.TabMod'

If you want to test running your plugin using Gradle you will have to change the mainClassName property to your plugin class name. The plugin class then also needs a main method. Here is how you can launch Chunky from your plugin main class:

import se.llbit.chunky.Plugin;
import se.llbit.chunky.main.Chunky;
import se.llbit.chunky.main.ChunkyOptions;
import se.llbit.chunky.ui.ChunkyFx;

public class MyPlugin implements Plugin {
  public static void main(String[] args) throws Exception {
    // Start Chunky normally with this plugin attached.
    Chunky.loadDefaultTextures();
    Chunky chunky = new Chunky(ChunkyOptions.getDefaults());
    new MyPlugin().attach(chunky);
    ChunkyFx.startChunkyUI(chunky);
  }
}

Plugin manifest

Since version 1.4.3, plugins have a metadata file inside their Jar file named plugin.json, which defines the main class of the plugin, and other metadata about the plugin.

This is the current JSON format used in the plugin.json file:

Key	Type	Description
main	String	The main plugin class name (must extend `se.llbit.chunky.plugin.Plugin`).
name	String	Name of the plugin.
author	String	The author of the plugin.
version	String	Plugin version.
targetVersion	String	The Chunky version the plugin is compatible with.
description	String	Plugin description.

If you use Gradle to build your plugins, place the plugin.json file in the directory src/main/resources/.

Plugin manager

A plugin manager is integrated into the Chunky launcher since version 1.10 of the launcher. The plugin manager is accessed via the "Manage Plugins" button under the Advanced tab.

Plugin API methods

The plugin API will be expanded as needed for future plugins. If you have a request for a new plugin API method, please suggest it on the issue tracker.

This is a list of the methods available to plugins currently in the plugin API:

se.llbit.chunky.main.Chunky:
- setRenderContextFactory() - changes the RenderContext factory. The render context is used for locating the scene directory and controlling some renderer configurations like the number of render threads.
- setSceneFactory() - changes the Scene factory for the renderer. The Scene class encapsulates most of the scene state in the renderer.
- setPreviewRayTracerFactory() - this sets the factory that builds the preview ray tracer. The preview ray tracer is used for rendering preview frames.
- setRayTracerFactory() - this can be used to change the default Java path tracing renderer to a completely different renderer. This is done in the ambient occlusion plugin demo.
- setRenderControlsTabTransformer() - sets a callback for transforming the list of Render Controls tab. This can be used to insert a custom tab in the Render Controls window. See the demo plugin for a usage example.
se.llbit.chunky.world.Block:
- set(int, Block) - used to change the representation for a Minecraft block in the renderer. This can be used for simple things like changing textures or material properties (emittiance, shinyness, ...), as well as more advanced things like completely changing the block rendering model. See [the demo plugin][4] for an example.

Things that will change

Since the plugin API is very new, with currently no third-party plugins using it, it is very much unstable. Anything may change at this point, but in particular these things will probably change:

The Scene class is not well suited for encapsulating the scene state in a clean way. Some parts of the state are intentionally shared between threads in a way that is likely confusing to other developers. It also uses a very unintuitive synchronization scheme. The current implementation makes it difficult for plugins to safely extend or alter the scene state.
Building a new type of renderer is not very well supported right now since there is only one current implementation: the default Java renderer. Adding an OpenCL renderer is likely very difficult right now just because the rendering architecture has been tightly integrated with the default renderer.
The way block rendering for most blocks works is not pretty. It uses nonstandard triangle and quadrilateral representations for most block geometry. The ray tracing for these is not well documented and should probably be replaced by more standard triangle-based ray tracing.