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.lua
files - 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.
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
-- 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)
},
}
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
local actions = require("blender.actions")
---Launch a Blender profile
actions.show_launcher()
---Manage a running Blender task
actions.show_task_manager()
---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()
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.