Developer overview
Overview of GroomLab's developer interfaces (C API, C++ wrapper, .groom format, USD layout, Python) and their stability and versioning rules.
GroomLab is open source (Apache License 2.0), and its source code is on GitHub. You can build a bridge to another host (Houdini, Blender, a game engine, a render farm tool) or a pipeline tool on the public C API below without touching the engine's source, or embed and change the engine itself.
What you get
| Piece | What it is | Use it for |
|---|---|---|
C API (groomlab_c.h) | Plain C99 functions over opaque handles, in one library (groomlab.dll). | Host plugins and any language with a C FFI. |
C++ wrapper (groomlab.hpp) | Header-only C++17 over the C API: RAII, views, exceptions. | C++ hosts. It adds no binary of its own. |
The .groom format | A JSON file holding a groom: graph, guides, scalp, maps. | Moving grooms between hosts, and reading them without the library. |
| The USD layout | The evaluated strands as every USD export writes them, versioned. See USD layout. | Viewers, renderers and pipeline tools that read finished hair. |
| Python | Maya's groomlab package, and the core's groomlab_core module. | Scripting inside Maya and Maya's Python. See Python API. |
| Samples | groom_to_obj (C++) and groom_counts (C), MIT licensed. | A starting point for your own bridge. |
MCP server (groomlab-cli mcp) | GroomLab's tools for AI agents over the Model Context Protocol. See Use GroomLab from AI agents. | Claude, Cursor, VS Code and other AI apps building grooms. |
The C API, its headers and the samples come in the GroomLab SDK (a GroomLabSDK folder). See
C and C++ API to build against it, and Writing a host bridge
for the steps a bridge takes.
Free to use
GroomLab and its bridges are free for any use, commercial included. The engine is Apache-2.0 (with its patent grant), so studios and engine plugins may embed it. The samples are MIT licensed, so you may copy them into your own tools.
What is stable
Four things are versioned, each with its own compatibility rule.
The C API: semantic versioning
GROOMLAB_C_API_VERSION_MAJOR and _MINOR in groomlab_c.h name the API the header declares.
gl_api_version() gives the library's.
- Same major: binary compatible. A minor release only adds functions, and fields at the end
of option structs (which carry their own
struct_size). A program built against 1.0 runs on 1.3. - A new major may change or remove functions. Check it when you load the library:
GROOMLAB_C_API_COMPATIBLE(gl_api_version()). The C++ wrapper does this for you when it makes aSession. - The CMake package
GroomLabSDKhas the same version, sofind_package(GroomLabSDK 1.0)takes any 1.x.
Only groomlab_c.h and groomlab.hpp are the API. Nothing else in GroomLab is, including the
core's C++ classes and the Python modules' internals.
The .groom file: a format version
A .groom file has "format": "groomlab.groom" and a whole-number "version" (1 today).
- A file from a newer GroomLab is refused with a clear error ("update GroomLab to open it"). It is never half-read.
- GroomLab does not migrate files. The version only goes up when an old file would no longer read back, and then files of the old version are refused too. Additions that have defaults (a new optional field) keep the version.
- GroomLab ignores fields it does not know when it reads a file, and does not keep them when it writes one.
The full layout is in The .groom format.
Nodes: a version per node
Each operator (Scatter, Clump, Noise...) has a behaviour version. A saved graph stores, per node, the version it was made with, and every param's value, set or not.
- A newer GroomLab keeps evaluating an old node the old way, so a saved groom keeps its look. A later change of a default never changes a saved file either.
- When a node has a newer behaviour, its panel shows Upgrade. Upgrading is a choice: the look may change.
- A graph holding a node newer than the library knows is refused, as files are.
From the API, gl_session_node_spec_json gives a node's "nodeVersion" and "outdated" (true
when an upgrade exists), and gl_session_upgrade_node upgrades it (API 1.1). See
Node versions.
The USD export: a layout version
Every USD export (Maya, the app, Blender, groomlab-cli) writes the same layout, and each layer
carries its version: customLayerData and the root prim's customData hold
groomlab = {layoutVersion = 1, version = "<GroomLab version>"}.
- Within a layout version, prim paths, attribute and primvar names, types, interpolations and meanings stay as they are. New primvars and prims may be added; ignore what you don't know.
- Any other change raises the layout version, and What's new lists it.
The full layout, with examples for reading one frame or a range, is in USD layout. Read the exports when you only need the strands (a viewer, a renderer, a pipeline check); use the C API when you need to evaluate the groom yourself.
Up axis
Points come out in the groom's up axis ("upAxis", Y by default). A Z-up host turns the groom
into its own axis with gl_session_set_up_axis (API 1.2): the scalp, the guides, the colliders
and the graph's world directions turn with it.
What is not stable yet
- Inner documents of a groom file. The guide hierarchy, parts, flow and correctives are stored as GroomLab writes them. Their inner layout may change within a format version. Keep them as they are; don't edit them by hand.
- Operator specs. Node and param names change rarely, and old ones keep loading. Read them
from
gl_operator_specs_jsonrather than hard-coding a list.
Next
C and C++ API
Evaluate a groom in 20 lines, and the full function reference.
Writing a host bridge
Load a groom, feed the scalp per frame, read the strands.
The .groom format
Every field of the file format.
USD layout
Every prim and primvar of the USD export, versioned.
Python API
Maya's groomlab package and the core module.
Use GroomLab from AI agents
groomlab-cli's MCP server - connect Claude Desktop, Claude Code, Cursor or VS Code to GroomLab, the tools an agent gets, an example session, groom recipes and safety notes.
C and C++ API
The GroomLab C API and C++ wrapper - SDK layout, a minimal example, error handling, ownership, threading, units, attributes and the full function reference.