docs/PLUGINS.md

Plugin and task-service map

Source-level finding F23, 2026-10-21. Baseline is 2016-03-10-c; member identities, includes, literal expressions, callback registrations and line anchors are in source-map.json. PLUGIN_INDEX.md lists every observed initTool call site/name. These are static declarations and calls, not a measured runtime registration trace.

The latest distribution contains 17 top-level plugin sources, 5 experimental sources, 9 task-client includes, 10 utility/misc includes, 5 Core includes, and 1 model generator: 47 IXPL files in total. There are 201 initTool call sites in plugin/experimental sources, with conservatively resolved source names: 194 in top-level plugins and 7 in examples. They include service/internal tools; they are not 201 distinct user-facing commands or proof that all tools are active simultaneously.

Top-level modules

Plugin source basename	Responsibility visible in source	Main dependencies / port boundary
camera	Camera controls, fly/navigation tools, camera panel and stopped notifications	Core camera/view services; Camera task clients
grid	Grid panel/settings/presets, cursor and update notifications	Core-Grid, raycast, camera and projection services
projections	Projection controls, saved memories and change notifications	Core view/projection services and task clients
Mb3 main editing tools	Main editing toolbox and modal operations	World/grid APIs, grid/camera/raycast/log helpers
Mb3 render modes	Six rendering mode selections, toolbar/view synchronization	MB3 per-view render settings and ViewEvents
view layouts	Six viewport layout presets and toolbar	View geometry/lifecycle APIs; shared-world views
main menu	New/load/save/export/world workflows, native dialogs and converter process calls	Core/WorldController/ViewEvents/Log and conversion BAT files
world controller	World registration, view clone/close policy and events	Core view lifecycle, task priorities, ViewEvents
view events	Fan-out of created/cloned/closing/closed notifications	Named task protocol; no rendered UI required
raycast	Raycast request/reply adapter returning position/normal	Core intersections and selected-brush plane access
task priorities	Ordered task-name/priority lookup	Config records and task buffers
plugins menu	Collect plugin menu entries and dispatch selected callbacks	PluginsMenu and TaskPriorities protocols
Mb3 plugins	Shortcut palette opening editing/render-mode toolbars and other panels	Named tools and plugin-menu registration
GUI layout designer	Interactive GUI construction/layout tooling	Widget APIs, config, log/help/menu utilities
log	Log registrations/messages and log UI	Core GUI, settings and typed task messages
notes	Notes window and settings/lifecycle behavior	GUI/config/log/plugin-menu helpers
window controls	Window interaction instructions/shortcuts	Core UI/window services

The two plugin-menu/palette modules are not evidence of an implemented dynamic loader API. Actual .plugin discovery, load order, runtime isolation, unload behavior and error containment still belong to host investigation.

Named task protocols

All nine client includes use a named !interface tool, a discriminant in bufI, and other typed buffers as needed. See data/sources/include/tasks/ in the machine report.

Endpoint	Client request / response shape	Source-level concern
camera.!interface	Register client tool ID and handler index; return handler index	Fires when a continuous camera transformation stops, according to source comment
grid.!interface	Register client tool ID and handler index; return handler index	Grid cursor/look-at updates
projections.!interface	Register client tool ID and handler index; return handler index	Projection-settings changes
log.!interface	Register a log handle and post messages through task buffers	String/integer-buffer conversion and message ownership need runtime tests
pluginsMenu.!interface	Register caption plus callback target/index; toggle/toggle-at; click response	Registration collection is scheduled through task priorities
raycast.!interface	Request [0, replyTool, pastNearClip] + two vec3s; response [0, hit] + hit point/normal if hit	One client callback slot; host path can temporarily alter selection
taskPriorities.!interface	Request [0, replyTool] + name; response [0, priority]	Missing service replies synchronously with 0; configured names use first-match lookup
viewEvents.!interface	Register listener, notify created/cloned/closing/closed; fan out IDs	Closing and closed are separate phases
worldController.!interface	Register first view of a new world	Applies background color and publishes a created event

For camera/grid/projections, source helpers store callback plus a tag and send a zero-based handler index to the provider. Negative/invalid indices, malformed payload buffers, lifetime and concurrency rules remain unspecified. In particular, do not assume these helpers validate every incoming buffer.

Registration and lifecycle

Akula.ixpl:988–1034 shows that initTool fills press/release/abort/task callbacks and integer tags; initPackage stores a tool list; registerPackage iterates it and calls registerTool. Static blocks register packages and runtime callbacks. Core version validation is also in a static block.

Most UI plugins register all-loaded initialization and finalization saves. Grid/projections/render modes also register view-selected handlers; editing tools register view-mouse-move and camera-tick handlers. Core comments say selectView itself does not trigger view-selected notification and tasks cannot be queued from static blocks. A Rust event model must represent these distinctions explicitly.

world controller.ixpl:96–100,137–150 publishes “closing”, queues a task with the configured priority, then closes the view and publishes “closed” when that task is handled. Resource cleanup cannot assume the initial close request is the actual destruction point.

raycast.ixpl:40–61 temporarily selects an unselected hit into the main set to read its plane, then deselects via another ray call. This is an observed source sequence, not a reproduced visible selection bug. It is a focused equivalence test for a future side-effect-free Rust picking implementation.

Experimental modules

extra stuff/readme.txt labels these unfinished/experimental and describes manually copying source into the top-level plugin directory before compilation and adding a binding.

• AAA_bevel: ray-targeted bevel helper; geometry behavior and numerical limits remain open.
• AAA_lego: procedural brush construction example, registering Lego.!interface.
• AAA_patchtest: curved-patch construction experiment, registering Patchtest.!interface.
• AAA_blank and AAA_blank (2): extension templates. Both declare the same Blank.!interface name; do not assume they can be enabled together without a name collision.

Native functionality and third-party compiled-plugin compatibility remain separate product decisions. No IXPL VM/compiler or Rust plugin system is selected by this mapping pass.

Next: P4.04/P4.05 lifecycle and protocol experiments, P4.08 module behavior specifications, and P7 complete tool state machines. The index maps registration/call dependencies without closing those parity tasks.