Plugins: arc docs

How Plugins Work

Each plugin is a standard .lua script. On startup or when hitting Reload Plugins, arc evaluates every script and registers its lifecycle hooks. Plugins run in an isolated Lua runtime, keeping the interactive viewport fluid and responsive.

Plugin Directories

arc searches for plugins in two locations:

Next to the application executable: A plugins/ directory adjacent to the binary.
User app data directory: A plugins/ directory in your user profile (e.g., ~/.config/arc/plugins on Linux or %APPDATA%/arc/plugins on Windows).

Managing Plugins

Open Settings → Plugins to view all detected scripts, toggle them on or off, and inspect execution logs or syntax errors. Enabled plugins run automatically on their registered events.

Lifecycle Hooks

Register event handlers using arc.on(event, callback):

Available Events
Event	Trigger	Argument
start	Fires when arc initializes and plugins load	None
new	Fires when a new document is created	None
open	Fires when a document is opened from disk	{ path }
save	Fires when a document is saved	{ path }

The arc Lua API

arc API Methods
Function	Returns	Description
on(event, fn)	none	Register an event handler.
log(message)	none	Print a message to the arc application console.
active_document()	id or nil	Return the active document ID.
entities()	array	List all entities in the active document.
add_entity(geom, name?)	id	Add a parametric solid or sketch geometry entity; returns new ID.
set_transform(id, xform)	none	Update position, rotation (quaternion), and scale of an entity.
raycast(origin, dir)	hit or nil	Perform a 3D raycast against scene geometry.
undo() / redo()	none	Trigger reversible document history steps.

Examples

A sample script that automatically logs events and generates a parametric mounting plate:

-- plugins/mounting_plate.lua

arc.on("new", function()
  local plate = arc.add_entity({
    type = "box",
    width = 100,
    depth = 60,
    height = 10,
    corner_radius = 2
  }, "Mounting Plate")

  arc.log("Created base plate: " .. tostring(plate))
end)

arc.on("save", function(doc)
  arc.log("Document saved to: " .. doc.path)
end)