Why Editor Plugins Are Not Fully Supported in Pure Nim (and Workarounds)

Editor plugins cannot be written using pure Nim alone because the Godot editor expects a plugin.cfg file and GDScript entry point that Nim's GDExtension cannot automatically provide, requiring a minimal GDScript wrapper to bridge the gap.

The godot-nim/gdext-nim project generates native GDExtension libraries that Godot loads at runtime. While you can implement game logic and runtime classes entirely in Nim, the editor's plugin discovery mechanism operates differently. It scans for plugin metadata before any GDExtension is instantiated, creating a fundamental limitation for pure-Nim editor tooling.

Why Pure Nim Editor Plugins Are Not Supported

The Godot editor discovers plugins by scanning for a plugin.cfg descriptor file and an accompanying GDScript (or C#) entry point that extends EditorPlugin. This discovery happens before the engine loads your compiled GDExtension library.

According to the source analysis of README.md (lines 92-94), the maintainers explicitly document this limitation: "Editor plugins cannot be written using pure Nim alone. To create an editor plugin, your extension class must be properly wrapped in GDScript and integrated via a plugin.cfg file."

While src/gdext/classes/gdeditorplugin.nim provides the Nim binding for the EditorPlugin API, the engine cannot locate a pure-Nim EditorPlugin class during the initial scan. The editor never inspects GDExtension libraries for the metadata that plugin.cfg supplies, meaning your Nim code remains invisible to the plugin system without an intermediary script.

Workaround: Creating a GDScript Wrapper

To expose a Nim-based editor plugin to Godot, you must export the Nim class and create a thin GDScript wrapper that the editor can discover. Follow these steps:

1. Export the Nim EditorPlugin Class

Create your plugin logic in Nim using the {.gdexport.} pragma so GDScript can instantiate it:

# src/my_nim_plugin.nim

import gdext
import gdext/classes/[gdEditorPlugin]

type MyEditorPlugin* {.gdexport.} = ref object of EditorPlugin

method _enter_tree*(self: MyEditorPlugin) {.base.} =
  echo "Nim EditorPlugin entered the editor"

2. Create the GDScript Entry Point

Write a minimal GDScript file that extends your exported Nim class. This satisfies the editor's requirement for a discoverable script:

# my_plugin.gd

@tool
extends MyEditorPlugin  # class exported from Nim

func _enter_tree():
    ._enter_tree()      # call the Nim implementation (optional)

    print("GDScript wrapper active")

3. Provide the plugin.cfg Descriptor

Place a plugin.cfg file in your plugin directory (e.g., testproject/editor/). This file tells the editor which script to load:

[plugin]
name="My Nim Editor Plugin"
description="Editor plugin written in Nim with a GDScript wrapper"
author="Your Name"
version="1.0"
script="res://my_plugin.gd"

4. Enable the Plugin

Place the plugin.cfg, the .gd script, and your compiled GDExtension library (e.g., libmy_plugin.*) inside testproject/editor/. Enable the plugin from Project Settings → Plugins, or programmatically via EditorInterface.set_plugin_enabled("My Nim Editor Plugin", true).

Automating the Scaffolding

While the wrapper setup is not fully automated, you can streamline project creation using the gdextwiz CLI tool. This utility generates the basic GDExtension project structure, after which you only need to manually add the plugin.cfg file and the GDScript wrapper to activate editor plugin functionality.

Summary

• Discovery timing: The Godot editor scans for plugins before loading GDExtensions, preventing pure-Nim classes from being found automatically.
• File requirements: Every editor plugin requires a plugin.cfg descriptor and a script entry point (GDScript or C#).
• Nim implementation: Use src/gdext/classes/gdeditorplugin.nim to implement EditorPlugin logic, but export the class with {.gdexport.}.
• Bridging strategy: Create a minimal GDScript wrapper that extends your Nim class and references it via plugin.cfg.
• Directory structure: Place all three components (plugin.cfg, .gd script, and compiled library) in the same plugin folder (e.g., testproject/editor/).

Frequently Asked Questions

Can I write editor plugins entirely in Nim without any GDScript?

No. According to the godot-nim/gdext-nim documentation in README.md lines 92-94, editor plugins require a GDScript (or C#) entry point and a plugin.cfg file that the editor scans before loading any GDExtension. The Nim code must be wrapped in a GDScript class that extends your exported Nim EditorPlugin.

What is the purpose of the {.gdexport.} pragma in the Nim code?

The {.gdexport.} pragma marks the Nim class for exposure to Godot's scripting system, allowing GDScript to extend it. Without this pragma in your EditorPlugin class definition, the GDScript wrapper cannot inherit from your Nim implementation.

Where should I place the plugin.cfg file?

The plugin.cfg file must reside in the same directory as your GDScript wrapper, typically inside your plugin folder such as testproject/editor/. The script entry in plugin.cfg must point to the path of your GDScript file using the res:// prefix (e.g., script="res://my_plugin.gd").

Does gdext-nim plan to automate the plugin wrapper generation?

Currently, the setup is not automated. While the gdextwiz CLI tool can scaffold the basic extension project, you must manually create the plugin.cfg and GDScript wrapper to enable editor plugin functionality. The source code shows this remains a manual process as of the 4.6-stable branch.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}