godot-neovim is a Godot 4 editor plugin that integrates a real Neovim process into Godot's built-in script editor. Unlike simple Vim keybinding emulators, this plugin runs an actual Neovim instance and synchronizes the buffer between Godot and Neovim via msgpack-RPC, giving you the full power of Neovim while editing GDScript, shaders, and other text files inside the Godot editor.

Inspired by vscode-neovim and GodotVim.

Source code: https://github.com/shiena/godot-neovim

Why a real Neovim backend?

Most Vim plugins for editors re-implement a subset of Vim in the host language. They cover the basics but tend to drift from the real thing once you hit text objects, registers, macros, Ex commands, or counts. godot-neovim takes the opposite approach: spawn a Neovim process, treat Neovim as the source of truth, and reflect its state in Godot's CodeEdit. The result is consistent, predictable Vim behavior with very few edge cases to memorize.

Features

Editing model

• Real Neovim backend (msgpack-RPC, not keybinding emulation)
• Mode indicator with live cursor position (e.g. NORMAL 123:45)
• Color-coded modes: NORMAL (green), INSERT (blue), VISUAL (orange), COMMAND (yellow), REPLACE (red)
• Cursor synchronization between Godot and Neovim
• Mouse drag selection automatically enters Neovim Visual mode
• Float window support (undocked script editor panels)
• Dual editor support: separate Neovim instances for Script Editor and Shader Editor

Motions

• Basic: h, j, k, l, w, b, e, ge, W, B, E, 0, ^, $, gg, G
• Display lines: gj, gk, g0, g$, g^, g_
• Paragraph / section: {, }, %, [{, ]}, [(, ])
• Viewport: H, M, L, zz, zt, zb
• Scrolling: Ctrl+F, Ctrl+B, Ctrl+D, Ctrl+U, Ctrl+E, Ctrl+Y
• Character find: f, F, t, T, ;, ,
• Method jump: [m, ]m (where Neovim language support is available)

Search and navigation

• /, ?, *, #, n, N
• gd (go to definition via Godot's built-in LSP)
• gf (go to file under cursor)
• gx (open URL/path under cursor in browser)
• K (open Godot documentation for class, method, property, constant)
• Ctrl+O / Ctrl+I (jump list)

Editing commands

• x, X, s, r{char}, ~, dd, D, yy, Y, cc, S, C, p, P, J, gJ, >>, <<, .
• gp, gP, [p, ]p (paste variants)
• Ctrl+A / Ctrl+X (increment/decrement number)
• gu, gU, g~ (case conversion)
• ga (display ASCII/Unicode of char under cursor)
• gqq (format current line)
• Ctrl+/ (toggle comment via Godot's native CodeEdit)

Text objects

• iw, aw (word)
• i", a", i', a' (quoted strings)
• i(, a(, i[, a[, i{, a{, i<, a< (brackets)
• ie, ae (entire buffer)
• is, as, ip, ap, it, at (sentence/paragraph/tag via Neovim)

Registers, marks, macros

• Named registers: "{a-z}
• Clipboard: "+, "*
• Black hole: "_
• Yank register: "0
• Numbered: "1-"9
• Local marks: m{a-z}, '{a-z}, `{a-z}
• Macros: q{a-z}, @{a-z}, @@

Folding

• za, zo, zc, zM, zR

Ex commands

• File: :w, :wa, :q, :qa, :wq, :x, :wqa, ZZ, ZQ
• Open: :e, :e {file}, :e!
• Substitute: :%s/old/new/g, :{range}s/, g&
• Lines: :g/{pattern}/d, :v, :sort, :t, :m
• Buffers (script tabs): :bn, :bp, :bd, :ls
• Jumps: :{number}, :marks, :registers, :jumps, :changes
• Misc: @:, Ctrl+G, command history (Up/Down)
• :help / :h opens GodotNeovim's built-in command reference

Customization

• Neovim Keymaps dock panel: edit Normal/Visual mode bindings without recompiling
• Validation against Neovim key notation, duplicate detection
• Reset to defaults, import keymaps from your Neovim config
• Mappings persist in Editor Settings (godot_neovim/custom_keymaps)

Reliability

• Path validation on startup and settings change
• Automatic recovery when Neovim becomes unresponsive

Requirements

• Godot 4.4 or later
• Neovim 0.9.0 or later (must be installed separately)
• Platforms: Windows (x64), Linux (x64, ARM64), macOS (Apple Silicon, Intel)

Installation

1. Install Neovim 0.9+ and make sure nvim is on your PATH.
2. Download godot-neovim from this Asset Library entry, or grab the latest release from GitHub: https://github.com/shiena/godot-neovim/releases
3. Copy the addons/godot-neovim/ folder into your project's addons/ directory.
4. macOS only: remove the quarantine attribute so Gatekeeper does not block the GDExtension binary:

   xattr -rc addons/godot-neovim
   

5. Enable the plugin in Project > Project Settings > Plugins.

Configuration

All settings live under Editor > Editor Settings > Godot Neovim. You may need to enable Advanced Settings in Editor Settings to see the section.

• Neovim Executable Path: defaults to nvim.exe (Windows) or nvim (macOS/Linux). The plugin validates this on startup and on setting changes.
• Neovim Clean: equivalent to nvim --clean. When enabled, Neovim starts without loading any user config (init.lua, plugins). Recommended to leave on to avoid plugin compatibility issues.
• Timeoutlen (advanced): time in milliseconds to wait for a mapped key sequence to complete. Default 1000.

Go to Definition (gd)

The gd command uses Godot's built-in LSP. Enable it via Editor > Editor Settings > Network > Language Server > Use Thread. When disabled, gd will display a hint asking you to enable it.

Custom Key Mappings

The Neovim Keymaps dock panel appears in the right dock area when the plugin is active. Double-click the Key column to edit a binding, press Delete to remove one, click Reset to restore defaults, or Import from Neovim to pull in user keymaps (requires neovim_clean = false). Custom overrides are marked with *.

Note: keys handled internally by the Neovim state machine (count prefixes, pending operations such as f/t/r, register selection ", macro recording q/@, and operators >/<) are managed by the plugin's Rust backend and are not exposed in the panel.

Exporting Projects

This is an editor-only plugin. It contains no runtime libraries for export targets (iOS, Android, Web, etc.), so Godot will warn about missing GDExtension libraries when exporting. Suppress the warning by adding addons/godot-neovim/* to the Exclude Filter in your export preset's Resources tab.

Architecture

+---------------------+   RPC (msgpack)    +-------------+
|   Godot Editor      | <----------------> |   Neovim    |
|   (GDExtension)     |                    |  (--embed)  |
|                     |                    |             |
|  CodeEdit       <-->|  Buffer Sync       |   Buffer    |
|  Mode Label     <-->|  Mode Changes      |   Mode      |
|                     |                    |             |
|  LSP Client     <-->|  TCP (JSON-RPC)    | Godot LSP   |
|  (gd command)       |                    | (port 6005) |
+---------------------+                    +-------------+

Limitations

Insert mode

Insert mode uses Godot's native input system so that auto-completion and other CodeEdit features keep working. As a result, the following Vim insert-mode commands are not available:

• Ctrl+O (one normal-mode command)
• Ctrl+W (delete word backward)
• Ctrl+U (delete to start of line)
• Ctrl+R (insert from register)
• Ctrl+A (insert previously inserted text)
• Ctrl+N / Ctrl+P (use Godot's auto-completion instead)

Undo

Uses Godot's undo system rather than Neovim's. :earlier / :later are not available.

Neovim config

By default init.lua and plugins are not loaded (neovim_clean = true). You can disable clean mode, but some plugins (e.g. copilot.vim, lexima.vim) are known to conflict with the buffer-sync model.

K for signals

Signal documentation lookup is not supported; class/method/property/constant only.

Method jump for GDScript

[m / ]m rely on Neovim's treesitter or language support. GDScript is not natively recognized by Neovim, so these commands may not work as expected.

Toggle comment (Ctrl+/)

This is a passthrough to Godot's native CodeEdit feature, not a Neovim command. Therefore:

• It is not recorded inside macros (q{a-z})
• . does not repeat it
• Undo uses Godot's undo system

Alt key composition (Option / AltGr)

When the OS produces a composed character via the Alt modifier (e.g. macOS Option+Q → @, Windows AltGr+Q → @ on the German layout), the plugin inserts the composed character as plain text instead of forwarding <A-x> / <C-A-x> to Neovim. This keeps composition-heavy layouts usable in Insert and Replace modes.

As a side effect, certain Vim mappings are unreachable on those layouts:

• macOS: any <A-letter> mapping where Option+letter composes a character. Configure macOS to "Use Option as Meta key" or switch layouts to use these mappings.
• Windows AltGr layouts (German, French, Spanish, etc.): <C-A-letter> mappings on keys AltGr composes. Windows reports AltGr as Ctrl+Alt simultaneously at the OS level, so these are indistinguishable from any application.

Macro recording with IME

Character input is recorded from key events. IME compositions (e.g. Japanese input) are recorded as final confirmed characters only, not intermediate states.

Comparison with GodotVim

godot-neovim and GodotVim solve the same problem from opposite directions:

• godot-neovim: real Neovim backend, full Ex command support, Godot auto-completion preserved, requires Neovim 0.9+ installation.
• GodotVim: self-contained Vim engine in Rust, additional Godot-specific commands (debugger, scene control), .godot-vimrc configuration, no external dependencies.

Pick godot-neovim if you already use Neovim and want behavior identical to your terminal editor. Pick GodotVim if you want a self-contained Vim experience with deeper Godot-specific tooling.

License

Dual-licensed under your choice of:

• Apache License, Version 2.0
• MIT License

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by the Godot Foundation or the Neovim project. "Godot" and the Godot logo are registered trademarks of the Godot Foundation. "Neovim" and the Neovim logo are trademarks of their respective owners. The Neovim logo is licensed under CC BY 3.0 by Jason Long.

Issues and contributions

Bug reports, feature requests, and pull requests are welcome at: https://github.com/shiena/godot-neovim