Develop Blender add-ons with Neovim.
- Run your add-on in Blender directly from Neovim
- Refresh your add-on with a single Neovim command
- Watch your add-on directory for changes and automatically reload
- Project-specific configuration with profiles and
.nvim.luafiles - Debug your add-on with DAP
blender.nvim-demo.mp4
blender.nvim-demo2.mp4
Blender.nvim requires a recent version of Neovim and Blender. The following versions are known to work:
- nui.nvim
- nui-components.nvim
- nvim-dap (Optional, for debugging with DAP)
- nvim-dap-repl-highlights (Optional, for syntax highlighting in the DAP REPL)
It's recommended to use a Python virtual environment for Blender.nvim. Install the following packages in your virtual environment:
Activate your virtual environment and launch Neovim from within it to ensure the Python dependencies are available.
For an example starter project, see blender-addon-template.
If you're managing your virtualenv with Rye, see the note below.
use {
"b0o/blender.nvim",
config = function()
require("blender").setup()
end,
dependencies = {
"MunifTanjim/nui.nvim",
"grapp-dev/nui-components.nvim",
"mfussenegger/nvim-dap", -- Optional, for debugging with DAP
"LiadOz/nvim-dap-repl-highlights", -- Optional, for syntax highlighting in the DAP REPL
},
}Default configuration:
require("blender").setup {
profiles = { -- Profile[]? list of blender profiles
--
{
name = 'blender', -- string profile name, must be unique
cmd = 'blender', -- string|string[] command to run Blender
-- env = {}, -- { [string]: string } environment variables to set when starting Blender
-- use_launcher = true -- boolean? whether to run the launcher.py script when starting Blender
-- extra_args = {} -- string[]? extra arguments to pass to Blender
-- enable_dap = nil -- boolean? whether to enable DAP for this profile (if nil, the global setting is used)
-- watch = nil -- boolean? whether to watch the add-on directory for changes (if nil, the global setting is used)
},
},
dap = { -- DapConfig? DAP configuration
enabled = true, -- boolean? whether to enable DAP (can be overridden per profile)
},
notify = { -- NotifyConfig? notification configuration
enabled = true, -- boolean? whether to enable notifications
verbosity = 'INFO', -- 'TRACE'|'DEBUG'|'INFO'|'WARN'|'ERROR'|'OFF'|vim.log.level? log level for notifications
},
watch = { -- WatchConfig? file watcher configuration
enabled = true, -- boolean? whether to watch the add-on directory for changes (can be overridden per profile)
},
ui = { -- UiConfig? UI configuration
output_panel = { -- { height: number } output panel configuration
height = 0.25, -- number height of the output panel. if 0 < height < 1, the height is a percentage of the window height
},
},
}You can define custom profiles to launch Blender with different configurations. A profile is a table with the following fields:
name: The name of the profilecmd: The command to run Blenderenv: Environment variables to set when launching Blender (optional)use_launcher: Whether to run the launcher.py script when starting Blender (optional)extra_args: Extra arguments to pass to Blender (optional)enable_dap: Whether to enable DAP for this profile (optional)watch: Whether to watch for changes and reload the addon (optional)
You can also use a function to generate profiles dynamically.
For example, the following dynamically populates the env field of a profile:
blender.setup({
profiles = function()
local env = {}
local ok, lines = pcall(vim.fn.readfile, "myproject.env")
if not ok then
-- Don't generate a profile if the file doesn't exist
return
end
if ok and lines then
-- Read a key=value pair from each line of the file, and add it to the env table
for _, line in ipairs(lines) do
local key, value = line:match("^([^#]*)=(.*)$")
if key and value then
env[key] = value
end
end
end
return {
name = "myproject",
cmd = "blender",
env = env,
}
end,
})You can use .nvim.lua (:help exrc) files to configure Blender.nvim on a per-project basis.
To enable support for .nvim.lua files in Neovim, you need to have :set exrc or vim.o.exrc = true in your Neovim configuration. Then, restart Neovim and, when prompted, allow the .nvim.lua file to be loaded.
Blender.nvim's setup() function can be called multiple times. Each call will merge the new configuration with the existing configuration.
For example, to add a profile for a Blender add-on in a specific project, you can create a .nvim.lua file in the project directory:
--- ~/projects/my-blender-addon/.nvim.lua
local has_blender, blender = pcall(require, "blender")
if has_blender then
blender.setup {
profiles = {
{
name = "my_addon",
cmd = "blender",
-- Open a specific file when launching Blender:
extra_args = { vim.env.HOME .. "/blender-files/my-test-file.blend" },
},
},
}
end:Blender- Open the Blender.nvim UI:BlenderLaunch- Launch a Blender profile:BlenderManage- Manage a running Blender task:BlenderReload- Reload the Blender add-on:BlenderWatch- Watch for changes and reload the add-on:BlenderUnwatch- Stop watching for changes:BlenderOutput- Toggle the output panel
local actions = require("blender.actions")
---Open the Blender.nvim UI
---If no task is running, the launcher is shown,
---otherwise the task manager is shown.
actions.show_ui()
---Close the Blender.nvim UI
actions.close_ui()
---Toggle the Blender.nvim UI
actions.toggle_ui()
---Show the Blender.nvim task launcher
actions.show_launcher()
---Manage a running Blender task
actions.show_task_manager()
---Open the output panel
actions.show_output_panel()
---Close the output panel
actions.close_output_panel()
---Toggle the output panel
actions.toggle_output_panel()
---Reload the Blender add-on
actions.reload()
---Start watching for changes in the addon files
---Note: When the task exits, the watch is removed.
---@param patterns? string|string[] # pattern(s) matching files to watch for changes
actions.watch(patterns)
---Stop watching for changes in the addon files
actions.unwatch()Rye is a project and package management solution for Python. It can create virtual environments, manage dependencies, and more.
Rye downloads and manages its own Python installations rather than using your system Python installation. Because of this, you may experience errors when launching Blender from within a Rye virtual environment, because Blender expects to use the system Python installation.
To fix this, you can register the Python installation used by Blender as a Rye toolchain:
$ rye toolchain register -n blender-cpython /usr/bin/python3.12 # replace with your Blender Python executableTo determine the path to your Blender Python executable, launch Blender with the following command (make sure you're not in a Python virtual environment):
$ blender --background --python-expr "import sys; print(sys.executable)"After you've registered the toolchain, create a .python-version file in your Blender Add-on project directory:
# replace with your Rye toolchain name/version:
[email protected]
Then, run rye sync to update the Rye .venv. After this, you should be able to use Blender.nvim from within the Rye virtual environment.
Includes code from the following projects:
- JacquesLucke/blender_vscode (MIT License)
- The Python portion of Blender.nvim is a heavily modified version of the code from blender_vscode.
- The Lua portion of Blender.nvim is inspired by the TypeScript implementation of blender_vscode, but is not a copy.
- stevearc/overseer.nvim (MIT License)
- The jobstart terminal strategy is based on code from overseer.nvim.
- nui.nvim: UI component library for Neovim
- nui-components.nvim: UI framework built on top of nui.nvim
- willothy for the original Buffer component implementation
© 2024 Maddison Hellstrom, MIT License.
Blender is a registered trademark (®) of the Blender Foundation in EU and USA. This project is not affiliated with or endorsed by the Blender Foundation.
