Skip to content

Plugins

TurtleTracer supports a powerful plugin system that allows you to extend its functionality. You can add custom code exporters, UI themes, and even new interface elements using simple JavaScript files.

  1. Open Settings (click the gear icon).
  2. Scroll down to the Plugins section.
  3. Click the Open Plugins Folder button. This opens the directory on your computer where plugins are stored.
  4. Drop your plugin file (.js) into this folder.
  5. Return to the visualizer settings and click Reload.
  6. Your plugin should appear in the list. Make sure the checkbox is checked to enable it.

Plugins are standard JavaScript files that run within the application. The visualizer provides a global turtle object that serves as your API to interact with the system.

Create a .js file (e.g., my-plugin.js) with the following structure:

// Register a custom exporter
turtle.registerExporter("My Custom Format", (data) => {
return "Path length: " + data.lines.length;
});
// Register a custom theme
turtle.registerTheme(
"Midnight Blue",
`
:root {
--bg-color: #0f172a;
--text-color: #f8fafc;
}
`,
);

The turtle object provides several methods and properties to interact with the visualizer:

  • registerExporter(name, handler): Adds a new option to the Export menu.
    • name: Display name for the exporter.
    • handler: Function receiving project data and returning a string.
  • registerTheme(name, css): Adds a new theme to the Settings > Interface menu.
    • name: Display name for the theme.
    • css: CSS string defining the theme variables.
  • getData(): Returns the current project state (read-only).
    • Returns: { startPoint, lines, shapes, sequence }

For more complex plugins, you can access internal registries and stores:

  • turtle.registries:

    • components: Register custom Svelte components.
    • tabs: Add new tabs to the side control panel.
    • navbarActions: Add buttons to the top navigation bar.
    • hooks: Listen for events like onSave, onLoad, etc. The onSave hook runs for every save, however the user saves a project. Before 2.4.0 it ran only for saves from the file manager.
  • turtle.stores:

    • project: Access reactive stores for path data (startPointStore, linesStore, etc.).
    • app: Access application-level state.
    • get: The Svelte get function to read current store values.

If your plugin registers an action that generates code for the sequential export, read context.targetLibrary ("SolversLib", "NextFTC", or "Ivy") to see which command library the user picked. The older context.isNextFTC flag still works for existing plugins, but it is deprecated and can't tell Ivy from SolversLib.

The same context has a language ("java" or "kotlin"). If your action's toJavaCode and toSequentialCommand write Kotlin when context.language is "kotlin", set supportsKotlin: true on the action. Without it, Kotlin exports leave a // TODO comment in the action's place. See Kotlin export.

When the user exports a project that mirrors for the alliance, context.allianceMirroring is true and a ctx variable (TurtleTracerLib's AutoContext) is in scope. Wrap any pose your action writes in ctx.pose(...) and any heading in radians in ctx.heading(...), so it is mirrored with the rest of the path. See Mirroring for the Other Alliance.

The plugins/turtle.d.ts type definitions in the Turtle Tracer repository list the current types.

An exporter receives the project data (the same shape getData() returns) and returns a string. This one writes the route as CSV:

turtle.registerExporter("Simple CSV", (data) => {
let csv = "Name,X,Y\n";
csv += `Start,${data.startPoint.x},${data.startPoint.y}\n`;
for (const line of data.lines) {
csv += `${line.name},${line.endPoint.x},${line.endPoint.y}\n`;
}
return csv;
});

The Turtle Tracer repository includes a fuller version, plugins/Example-csv-exporter.ts.

Here is a simple example that adds a button to the top navigation bar:

turtle.registries.navbarActions.register({
id: "hello-world-btn",
icon: `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5"/></svg>`,
title: "Say Hello",
onClick: () => {
alert("Hello from TurtleTracer Plugin!");
},
});