plugins3d-loader

Source: plugins3d-loader.js:11

Consumer-only runtime for UV rendering.

Plugin loading and UI button registration are handled by ghostyles-manager. This module only listens to app events and, when the currently active plugin exports paintUV, renders it on the 3D mesh overlay.

Instance Methods

log3d(message: string): void

Writes loader messages to the shared Ghostmaxxing log under the 3D plugin source, so unavailable runtime operations are attributed to this module.

Parameters

• message (string) — Message to show in the application log.

Returns

• void

• See:
  • reloadPlugins3d - Reports that 3D plugin reloading is delegated to `ghostyles-manager`.

deactivateBroken3dPlugin( entry: object | null | undefined, err: *, ): void

Removes a 3D ghostyle from the active UI path after its paintUV renderer throws, then broadcasts the same effect-change events used by normal plugin toggles. The user-facing Italian log message means the plugin threw during paintUV, and this handler prevents that plugin from breaking subsequent mesh frames.

Parameters

• entry (object | null | undefined) — Loaded ghostyle entry that failed.
• err (*) — Error or thrown value raised by the plugin renderer.

Returns

• void

• See:
  • initPlugins3dLoader - Called by the `landmarks3d` event listener when UV rendering fails.

requireInit(): void

Guards public 3D control APIs so callers cannot manipulate plugin buttons before the loader has captured its DOM nodes and event bus. The thrown Italian message means initPlugins3dLoader() has not been called yet.

Returns

• void

Throws

• Error — When the 3D loader runtime has not been initialized.

• See:
  • activateEffect3d - Verifies initialization before activating a 3D effect.
  • deactivateEffect3d - Verifies initialization before deactivating a 3D effect.
  • toggleEffect3d - Verifies initialization before toggling a 3D effect.
  • reloadPlugins3d - Verifies initialization before reporting reload availability.

clearCanvas(): void

Clears the 3D plugin canvas between mesh frames or when no UV-capable plugin remains active, avoiding stale painted makeup on the overlay.

Returns

• void

• See:
  • syncActiveEntry - Clears the overlay when the active effect has no `paintUV` renderer.
  • initPlugins3dLoader - Clears the overlay before drawing each `landmarks3d` frame.

coerceParam(p: object, value: *): *

Normalizes a 3D ghostyle parameter value to the supported project schema (range, bool, select, or RGB color) before it is stored for paintUV. This keeps panel input values, plugin defaults, and renderer parameters in the same shape regardless of browser form serialization.

Parameters

• p (object) — Plugin parameter definition.
  • p.type (string) — Supported parameter control type.
  • p.default (*) — Default value declared by the ghostyle.
  • p.step (number, optional) — Numeric slider increment.
  • p.min (number, optional) — Numeric slider minimum.
  • p.max (number, optional) — Numeric slider maximum.
  • p.options (Array.<*>, optional) — Selectable values for select parameters.
• value (*) — Raw value from the plugin manifest or parameter control.

Returns

• * — Coerced value ready to pass to the active ghostyle.

• See:
  • ensureParamValues - Coerces initial plugin defaults.
  • createParamRow - Coerces values read from parameter panel controls.

rgbToHex(rgb: Array.<number>): string

Converts a stored RGB array from the 3D parameter map into a browser color input value, clamping invalid plugin-provided components to black-safe channel values.

Parameters

• rgb (Array.<number>) — RGB triplet stored for a color parameter.

Returns

• string — Hex color string used by the parameter panel.

• See:
  • createParamRow - Initializes and updates color controls for 3D ghostyle parameters.

ensureParamValues(id: string, module: object): void

Creates the per-plugin parameter state used by paintUV, seeded from the ghostyle module defaults only once per plugin so user adjustments survive ordinary active-effect refreshes.

Parameters

• id (string) — Loaded ghostyle identifier.
• module (object) — Ghostyle module that may expose configurable UV parameters.
  • module.params (Array.<object>, optional) — Parameter definitions declared by the ghostyle.

Returns

• void

• See:
  • syncActiveEntry - Ensures parameters exist whenever a UV-capable ghostyle becomes active.

syncPanelHeightVar(): void

Publishes the parameter panel height into the --pp-h CSS variable so the rest of the lab UI can reserve space when 3D ghostyle controls are visible.

Returns

• void

• See:
  • hideParamsPanel - Resets the CSS variable when controls are hidden.
  • renderParamsPanel - Updates the CSS variable after rendering controls.

createParamRow( pluginId: string, p: object, ): HTMLDivElement | null

Builds one row in the floating 3D parameter panel for a ghostyle manifest parameter, wiring browser controls back into the runtime value map that is later passed to paintUV.

Parameters

• pluginId (string) — Loaded ghostyle identifier whose values should be edited.
• p (object) — Parameter definition from the ghostyle module.
  • p.name (string) — Runtime parameter key passed to paintUV.
  • p.label (string, optional) — Visible label used in the panel.
  • p.type (string) — Supported parameter control type.
  • p.min (number, optional) — Numeric slider minimum.
  • p.max (number, optional) — Numeric slider maximum.
  • p.step (number, optional) — Numeric slider increment.
  • p.options (Array.<*>, optional) — Selectable values for select parameters.

Returns

• HTMLDivElement | null — Parameter row, or null when the type cannot be rendered.

• See:
  • renderParamsPanel - Creates rows for the active 3D ghostyle parameter list.

hideParamsPanel(): void

Hides and empties the 3D parameter panel when no UV-capable ghostyle is active, or when the active ghostyle has no configurable parameters.

Returns

• void

• See:
  • renderParamsPanel - Delegates here for plugins without parameters.
  • syncActiveEntry - Hides controls when the active effect is not a 3D renderer.

renderParamsPanel(entry: object | null | undefined): void

Renders the floating parameter panel for the active UV ghostyle. The existing Italian heading "Parametri" is the visible label for plugin controls and is generated here together with the active plugin name.

Parameters

• entry (object | null | undefined) — Active loaded ghostyle entry.

Returns

• void

• See:
  • syncActiveEntry - Refreshes the panel whenever the active effect changes.

getActivePaintEntry(): object | null

Resolves the current global active effect to a loaded ghostyle entry only when that module exports the paintUV hook required by the 3D mesh overlay.

Returns

• object | null — Active UV-capable ghostyle entry.

• See:
  • syncActiveEntry - Uses this lookup to align runtime state with `state.activeEffect`.

syncActiveEntry(): void

Synchronizes loader state after a ghostyle effect change by selecting the active paintUV entry, preparing its parameters, refreshing controls, and notifying listeners through effectChanged3d.

Returns

• void

• See:
  • initPlugins3dLoader - Called during initialization and by the `effectChanged` event listener.

Static Methods

getActiveEffect3d(): string | null

Returns the active 3D ghostyle id tracked by this loader, or null when the current active effect is not a UV-capable plugin.

Returns

• string | null — Active 3D plugin id.

• See:
  • main - Exposed as `window.gstmxx.getActiveEffect3d`.
  • hasActivePlugin - Checks whether 2D or 3D compositing should run.
  • hasActivePlugin3d - Checks active plugin state before 3D efficacy compositing.

activateEffect3d(id: string): boolean

Activates a UV-capable ghostyle by delegating to its existing effect button, keeping 3D activation on the same UI path as regular ghostyle toggles.

Parameters

• id (string) — Loaded ghostyle id to activate.

Returns

• boolean — True when a matching clickable 3D effect button was triggered.

• See:
  • main - Exposed as `window.gstmxx.activateEffect3d`.
  • toggleEffect3d - Uses this when the requested 3D plugin is not already active.

deactivateEffect3d(): boolean

Deactivates the current UV-capable ghostyle by clicking the active effect button, preserving the unified active-effect behavior owned by the UI.

Returns

• boolean — True when the active 3D effect button was triggered.

• See:
  • main - Exposed as `window.gstmxx.deactivateEffect3d`.
  • toggleEffect3d - Uses this when the requested 3D plugin is already active.

toggleEffect3d(id: string): boolean

Toggles a UV-capable ghostyle through the shared effect-button workflow, activating it when inactive and deactivating it when it is already selected.

Parameters

• id (string) — Loaded ghostyle id to toggle.

Returns

• boolean — True when a matching UI button was triggered.

• See:
  • main - Exposed as `window.gstmxx.toggleEffect3d`.

reloadPlugins3d(): boolean

Compatibility hook for older 3D plugin callers. In the current project, plugin discovery and reloads are handled by ghostyles-manager, so this function logs that 3D-specific reload is not available and returns false.

Returns

• boolean — Always false because 3D plugins are managed by ghostyles-manager.

• See:
  • main - Exposed as `window.gstmxx.reloadPlugins3d`.

initPlugins3dLoader(options?: object): object

Initializes the 3D plugin runtime by binding the overlay canvas, parameter panel, app event bus, and UV renderer. It then listens for active-effect, compositing, and MediaPipe landmark events so loaded ghostyles with paintUV can draw onto the mesh overlay without owning plugin loading themselves.

Parameters

• options (object, optional, default: "{}") — DOM id and renderer overrides used by startup and tests.
  • options.canvasId (string, optional, default: "'mesh3dOverlay'") — Canvas receiving rendered UV makeup.
  • options.overlayId (string, optional, default: "'overlay'") — Main overlay whose size and mirror transform are followed.
  • options.panelId (string, optional, default: "'plugin3dParamsPanel'") — Floating panel for active plugin parameters.
  • options.videoId (string, optional, default: "'video'") — Webcam video element required by the runtime.
  • options.baseUrl (string, optional) — Base URL for resolving the canonical UV data file.
  • options.uvPath (string, optional) — Explicit URL for face_canonical_uv.json.
  • options.getFaceLandmarker (function, optional) — Provider for the MediaPipe FaceLandmarker instance.

Returns

• object — Initialized singleton runtime.

Throws

• Error — When the required DOM elements are missing.

• See:
  • main - Called during application startup before `ghostyles-manager` loads unified ghostyles.