Plugins
Plugins
Section titled “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.
How to Add Plugins
Section titled “How to Add Plugins”- Open Settings (click the gear icon).
- Scroll down to the Plugins section.
- Click the Open Plugins Folder button. This opens the directory on your computer where plugins are stored.
- Drop your plugin file (
.js) into this folder. - Return to the visualizer settings and click Reload.
- Your plugin should appear in the list. Make sure the checkbox is checked to enable it.
Designing Plugins
Section titled “Designing Plugins”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.
Basic Structure
Section titled “Basic Structure”Create a .js file (e.g., my-plugin.js) with the following structure:
// Register a custom exporterturtle.registerExporter("My Custom Format", (data) => { return "Path length: " + data.lines.length;});
// Register a custom themeturtle.registerTheme( "Midnight Blue", ` :root { --bg-color: #0f172a; --text-color: #f8fafc; }`,);The turtle API
Section titled “The turtle API”The turtle object provides several methods and properties to interact with the visualizer:
Core Methods
Section titled “Core Methods”registerExporter(name, handler): Adds a new option to the Export menu.name: Display name for the exporter.handler: Function receiving projectdataand 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 }
- Returns:
Advanced Features
Section titled “Advanced Features”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 likeonSave,onLoad, etc. TheonSavehook 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 Sveltegetfunction to read current store values.
Custom Actions and Command Libraries
Section titled “Custom Actions and Command Libraries”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.
Example: A Simple Exporter
Section titled “Example: A Simple Exporter”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.
Example: Adding a Button
Section titled “Example: Adding a Button”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!"); },});