Ved plugins

This page details how to install or develop plugins for Ved.

Last updated: Sunday 5 February 2023 16:57 (UTC) (this is the last edit date of the file)

How to install plugins

The plugins folder can be found at:

• %appdata%\LOVE\ved\plugins\ (Windows, source)
• %appdata%\ved\plugins\ (Windows, .exe version)
• /Users/user/Library/Application Support/LOVE/ved/plugins/ (Mac)
• ~/.local/share/love/ved/plugins/ (Linux)

How to make plugins

For an example of a plugin, check example_plugin.zip (1.1, now contains source edits). There's a technical documentation of Ved that can be found here. You'll probably need to look at Ved's code while developing the plugin, and you can find it at the repository. You can also unzip the .love (it's actually a zip).

Ved is written in Lua and uses the LÖVE framework. So to be able to make plugins, it would help a lot to be familiar with that. To start making a plugin, make a new folder for it in the plugins folder (see above). You can name it anything you want, but the name isn't shown inside Ved itself, instead, the name you specify in the info file (info.lua) is. info.lua is a file inside your plugin folder, containing the name for your plugin, a description, author name, version number, the minimum version of Ved that is required for the plugin to work, and some other things.
An example for the info file can be found here: info.lua

Next, to integrate the plugin with Ved, you can use hooks, or you can make the plugin edit Ved source code (see below). To use hooks, make a folder called hooks in your plugin folder.

Hooks

Plugins can make use of hooks, which are specific points in the Ved code where plugin code can be run. For example, there is a hook that is called after displaying everything on the screen, so you can use that hook to display something related to your plugin.

To use a hook, place a file with the name of the hook and the .lua extension in the hooks folder in your plugin. So to use the hook called love_draw_end, you need a file love_draw_end.lua inside YourPlugin/hooks/.

To use the args in your hook, you can use .... So in love_update_start, which has the variable dt, you'd put local dt = ... at the top of your hook. In love_mousepressed_start, which has three arguments, you can use local x, y, button = ....

If you need a hook that doesn't exist yet or have an idea for one, or if you need further help with developing a plugin, don't hesitate to tell Dav!

Source edits

As of Ved beta 2, plugins can do find and replace operations on files in the Ved source code. Every internal Lua file can be modified this way, except for main.lua, corefunc.lua, plugins.lua, errorhandler.lua, incompatmain8.lua, incompatmain9.lua, love10compat.lua and love11compat.lua.

The file sourceedits.lua in your plugins folder controls these source edits. It contains an array in the following format:

sourceedits =
{
	["SOURCENAME"] =
	{  -- First file to edit: SOURCENAME.lua
		{  -- Edit 1 in that file
			find = [[
FIND CODE
]],
			replace = [[
REPLACE BY THIS
]],
			ignore_error = false,
			luapattern = false,
			allowmultiple = false, -- allowmultiple nyi
		},
		{  -- Edit 2 in that file
			...
		},
	},
	["SOURCE2"] =
	{  -- Second file to edit: SOURCE2.lua
		...
	},
}

If ignore_error is false (or missing), and the edit can't be made because the find code can't be found in the source file, then an orange warning screen will be shown to the user (which they can then dismiss and continue loading). If ignore_error is true, then this warning screen will not be shown.

If luapattern is true, then find will be interpreted as being in pattern format (aka Lua's regex, click here and here for more information), if false or missing it will just be searched as a plain snippet of code.

allowmultiple is currently not yet implemented, but if false it would warn if the same edit is being made multiple times in the same file.

If you need to include ]] in your find and/or replacement string, it's possible to include it by replacing it with something like ]] .. "]]" .. [[

Example:

sourceedits =
{
	["func"] =
	{
		{
			find = [[
function setColorArr(yourarray)
	love.graphics.setColor(yourarray[1], yourarray[2], yourarray[3])
end]],
			replace = [[
function setColorArr(yourarray)
	love.graphics.setColor(yourarray[3], yourarray[2], yourarray[1])
end]],
			ignore_error = false,
			luapattern = false,
			allowmultiple = false,
		},
	},
}

It does not matter whether your plugin files use Unix-style (LF) line endings, Windows-style (CR+LF) ones, or even classic Mac (CR) ones. Make sure your Ved source files use LF ones, however! If you downloaded a packaged version (.love or Windows/Mac version), it'll probably be fine.

Including files

It's also possible to include entire source files in your plugin, which will be considered as being inside Ved's root directory. Included source files go in the include folder in your plugin. After that, it can just be included with ved_require("your_file"), in a hook or otherwise. Note that this is not much different from how you would normally include a file in Lua: require("your_file").

Warning: this is only intended for your own (original) plugin files, not edited versions of Ved source files (even though it will work)! Adding an entire file will stop official Ved updates from affecting these files (yes, after downloading a new version of Ved) and also overrides any other plugin editing them.

In Ved 1.1.4 and later, you can also have subfolders inside the include folder, so it's probably a good idea to put all your included files in a folder with the name of your plugin to avoid clashes with other plugins or future files in Ved, and then just include them with something like ved_require("my_1st_plug/drawingcode").

Including assets like images is not yet supported in this way, this may be added later!

Technical documentation

There's a technical documentation of Ved that can be found here.