Types & constants
The callbacks a plugin implements, the descriptor structs it fills in, and the constants that govern ABI compatibility. Generated from sdk/include/yu3d_plugin.h.
Constants
| Constant | Value | Meaning |
|---|---|---|
YU3D_PLUGIN_H | | — |
YU3D_PLUGIN_ABI_VERSION | 2u | ABI version = MAJOR only. Versioning policy (semver-style for a C ABI): - Backwards-COMPATIBLE changes do NOT bump the major and MUST be additive only: append new function pointers / fields to the END of Yu3dHostApi, append new enum values at the END. Never reorder, resize, or repurpose an existing field. struct_size grows; old plugins keep working because every field they know still sits at the same offset. - Backwards-INCOMPATIBLE changes (removing/reordering a field, changing a signature or semantics) bump YU3D_PLUGIN_ABI_VERSION. A plugin MUST require an exact major match (host->abi_version == YU3D_PLUGIN_ABI_VERSION it built against) and MUST guard any field that may be absent in an older host with YU3D_HOST_HAS() below. The host advertises how many fields it actually provides via struct_size. |
YU3D_HOST_HAS(host, field) | \ | True if host actually provides field (i.e. the host's struct is at least large enough to include it). Use before calling any field that was added after the original 1.0 surface, so a plugin built against a newer header still loads in an older host. Example: if (YU3D_HOST_HAS(host, plan_set_pick_id)) host->plan_set_pick_id(c, 3); |
YU3D_JCT_CORRIDORS | 0x01u | junction_create / junction_create_multileg flag bits. |
YU3D_JCT_SPLIT_BOX | 0x02u | intersection / fillet corridors |
YU3D_JCT_TIE_PROFILE | 0x04u | carve the box on leg corridors |
YU3D_JCT_PRIMARY_CROWN | 0x08u | 2-road: tie secondary profile |
YU3D_JCT_PAVEMENT | 0x10u | 2-road: keep the primary crown |
YU3D_JCT_TURN_LANES | 0x20u | 2-road: standalone pavement TIN |
YU3D_RB_INSIDE_BUILT_UP | 0x01u | roundabout_create flag bits. |
YU3D_RB_AUTO_CENTER | 0x02u | location class for the rb.* seed |
YU3D_RB_CORRIDORS | 0x04u | centre at the first two legs' X |
YU3D_RB_CARVE_LEGS | 0x08u | ring + apron corridors |
Callbacks you implement
The host calls these; each one is a field of a descriptor struct you register.
Yu3dWriteFn
Per-node callbacks. payload is the plugin-owned blob read returned (or that a command passed to doc_add_node); the host stores it inside a node and hands it back on every call. user is whatever the plugin set on the Yu3dNodeType.
void (*Yu3dWriteFn)(Yu3dWriter* w, const void* payload, void* user)Yu3dReadFn
void* (*Yu3dReadFn)(Yu3dReader* r, const char* uuid, const char* name, void* user)Yu3dDestroyFn
void (*Yu3dDestroyFn)(void* payload, void* user)Yu3dPlanRenderFn
void (*Yu3dPlanRenderFn)(const void* payload, Yu3dPlanCtx* ctx, void* user)Yu3dSceneRenderFn
void (*Yu3dSceneRenderFn)(const void* payload, Yu3dSceneCtx* ctx, void* user)Yu3dCommandFn
void (*Yu3dCommandFn)(Yu3dDocument* doc, void* user)Yu3dSummaryFn
Return a read-only summary string for the Properties dock. The pointer must stay valid until the plugin's next call (the host copies it).
const char* (*Yu3dSummaryFn)(const void* payload, void* user)Yu3dPropGetFn
void (*Yu3dPropGetFn)(const void* payload, Yu3dPropValue* out, void* user)Yu3dPropSetFn
void (*Yu3dPropSetFn)(void* payload, const Yu3dPropValue* value, void* user)Yu3dCommandArgsFn
void (*Yu3dCommandArgsFn)(Yu3dDocument* doc, const Yu3dCommandArgs* args, void* user)Yu3dSubPropGetFn
---- sub-entity properties (M2) ------------------------------------------- A node with internal parts (e.g. a network's pipes / structures) exposes a per-part property page keyed by the pick sub-id. get/set receive the sub_id; the list fn fills the field schema for a given sub-entity.
void (*Yu3dSubPropGetFn)(const void* payload, int sub_id, Yu3dPropValue* out, void* user)Yu3dSubPropSetFn
void (*Yu3dSubPropSetFn)(void* payload, int sub_id, const Yu3dPropValue* value, void* user)Yu3dSubPropListFn
Fill up to max field descriptors for sub-entity sub_id; return the count written. Called by the host when a sub-entity of a node of this type is picked. The host copies the descriptors during the call.
uint32_t (*Yu3dSubPropListFn)(const void* payload, int sub_id, Yu3dSubPropertyDesc* out, uint32_t max, void* user)Yu3dPlanGripFn
Fill up to max grips for payload; return the count written.
uint32_t (*Yu3dPlanGripFn)(const void* payload, Yu3dPlanGrip* out, uint32_t max, void* user)Yu3dPluginRegisterFn
The single entry point a plugin DLL must export. Return 1 to accept, 0 to decline (the host unloads the DLL). Called once at startup.
int (*Yu3dPluginRegisterFn)(const Yu3dHostApi* host)Structures
Yu3dPropValue
A tagged value crossing the property seam. Only the field matching kind is meaningful. For TEXT: on get, the plugin sets text to a pointer valid until its next call (the host copies immediately); on set, text is host-owned and valid only during the call (the plugin copies).
| Field | Meaning |
|---|---|
Yu3dPropKind kind | — |
double real | — |
int64_t integer | — |
int flag | bool |
const char* text | — |
Yu3dPropertyDesc
One editable field of a node type.
| Field | Meaning |
|---|---|
const char* key | stable id, unique within the type |
const char* label | UI label |
Yu3dPropKind kind | — |
int read_only | nonzero => display only |
Yu3dPropGetFn get | required |
Yu3dPropSetFn set | required unless read_only |
void* user | — |
Yu3dPropertyDescEx
Richer editable field (M3 extra): adds a category header, CHOICE options and a unit quantity to Yu3dPropertyDesc. Register with register_property_ex.
| Field | Meaning |
|---|---|
const char* key | — |
const char* label | — |
Yu3dPropKind kind | — |
int read_only | — |
Yu3dPropGetFn get | — |
Yu3dPropSetFn set | — |
void* user | — |
const char* group | category header; "" => "Properties" |
const char* const* choices | CHOICE only: n_choices option labels |
uint32_t n_choices | — |
Yu3dQuantity quantity | REAL only |
Yu3dNodeType
A node type the plugin contributes. type_id must be globally unique and STABLE across versions — it is the tag written to the file.
| Field | Meaning |
|---|---|
const char* type_id | e.g. "acme.pole" |
Yu3dWriteFn write | required |
Yu3dReadFn read | required |
Yu3dDestroyFn destroy | required (frees payload) |
Yu3dPlanRenderFn plan_render | nullable |
Yu3dSceneRenderFn scene_render | nullable |
void* user | opaque, echoed to callbacks |
Yu3dCommandParam
| Field | Meaning |
|---|---|
const char* name | key read back via args_get |
const char* label | form label |
Yu3dParamType type | — |
double default_value | — |
double min, max, step | — |
const char* const* choices | CHOICE only: array of n_choices |
uint32_t n_choices | — |
Yu3dCommandDesc
| Field | Meaning |
|---|---|
const char* id | unique, namespaced: "acme.create" |
const char* label | menu text |
const char* group | section within the page |
const char* page | ribbon tab + top-level menu; "" => generic Modules menu |
const char* icon | semantic icon name; "" => generic glyph |
Yu3dCommandFn run | used when n_params == 0 |
const Yu3dCommandParam* params | nullable |
uint32_t n_params | — |
Yu3dCommandArgsFn run_args | used when n_params > 0 |
void* user | — |
Yu3dSubPropertyDesc
| Field | Meaning |
|---|---|
const char* key | — |
const char* label | — |
Yu3dPropKind kind | — |
int read_only | — |
Yu3dSubPropGetFn get | — |
Yu3dSubPropSetFn set | null => read-only |
void* user | — |
Yu3dPlanGrip
---- draggable plan grips (M2) -------------------------------------------- The host draws these for the selected node and, on release, commits the move through the node's sub-entity "pos_x"/"pos_y" (Move) or "rotation" (Rotate) properties — so a module offering grips MUST expose those via its sub-entity property list. The commit is undoable for free.
| Field | Meaning |
|---|---|
int sub_id | — |
double x, y | handle position (world metres) |
int kind | 0 = Move, 1 = Rotate |
double cx, cy | Rotate pivot (world metres) |
Enumerations
Yu3dPropKind
---- editable properties (shown in the Properties dock, edited through the host's undo stack) ----
| Value | Meaning |
|---|---|
YU3D_PROP_REAL = 0 | — |
YU3D_PROP_INT = 1 | — |
YU3D_PROP_TEXT = 2 | — |
YU3D_PROP_BOOL = 3 | — |
YU3D_PROP_CHOICE = 4 | — |
Yu3dQuantity
Physical quantity a REAL field stores (SI). The Properties dock shows/parses it in the document's display units; the VALUE crossing the seam stays SI.
| Value | Meaning |
|---|---|
YU3D_QTY_NONE = 0 | — |
% | — |
count | — |
angle) */
YU3D_QTY_LENGTH = 1 | — |
YU3D_QTY_AREA = 2 | — |
YU3D_QTY_VOLUME = 3 | — |
Yu3dParamType
---- rich command contribution (M1) --------------------------------------- register_command_ex supersedes the flat register_command: it adds menu/ ribbon placement (page + icon), and an optional input FORM. When n_params > 0 the host renders a generated form from params, then calls run_args with the resolved values (read them via host->args_get); when n_params == 0 the host calls run. Everything is copied by the host during the call — the plugin's arrays/strings need not outlive register_command_ex.
| Value | Meaning |
|---|---|
YU3D_PARAM_REAL = 0 | — |
YU3D_PARAM_INT = 1 | — |
YU3D_PARAM_BOOL = 2 | — |
YU3D_PARAM_CHOICE = 3 | default_value = default option index; uses choices |