lua-plugin-authoring

Write, test, and debug Lua 5.4 sampling plugins for the HOT-Step CPP audio engine.

151|22|Updated Apr 19, 2026
One-click install
npx skills add https://github.com/scragnog/HOT-Step-CPP --skill lua-plugin-authoring-scragnog
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: lua-plugin-authoring
Source: https://github.com/scragnog/HOT-Step-CPP/tree/main/.claude/skills/lua-plugin-authoring
Command: npx skills add https://github.com/scragnog/HOT-Step-CPP --skill lua-plugin-authoring-scragnog

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? HOT-Step CPP routes all audio sampling through Lua plugins, but the plugin API has many non-obvious traps: 0-indexed FloatArrays, silent state bleeding across generations, lazy apg() registration, and restart procedures that fail silently. This Skill encodes the verified contracts, golden rules, and failure signatures so plugins load and behave correctly on the first attempt. ## Core Features & Use Cases - Four plugin type contracts: Complete signatures and engine invariants for solvers (step/sample), schedulers, guidance modes (guide/post_step), and postprocess VAE-decode replacements, verified against engine/src/lua-plugin.h. - Debug and test workflow: PowerShell commands to confirm plugin loading via ace_engine.log, verify /api/plugins visibility, and diagnose runtime errors like pure-noise output from aborted step() calls. - Param flow documentation: How declared UI params travel from PluginControls.tsx through plugin_params to the injected params global, including the toggle-default trap and nil-handling rules. - Use Case: You want to add a custom Heun-style solver. Copy engine/plugins/solvers/unipc.lua as a template, drop it in plugins/solvers/, restart via the shutdown API, and confirm the [DiT] Solver log line before generating. ## Quick Start Ask the AI to write a new Lua solver plugin for HOT-Step that modifies how the latent advances each sampling step, then verify it loaded by checking the engine log.

Frequently Asked Questions about lua-plugin-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a custom sampling solver to HOT-Step CPP?

Create a .lua file in repo-root plugins/solvers/ defining a global solver table and a step(xt, vt, t_curr, t_prev, n) function that mutates xt in place. Restart the app via POST /api/shutdown/restart, then confirm the [Plugins] load line in ace_engine.log.

Why does my Lua plugin generate pure noise without errors?

A Lua runtime error inside step() aborts the call each step, so xt never advances and the output is raw noise. The most common cause is 1-indexing a FloatArray, which is 0-indexed. Grep ace_engine.log for '[Plugins] ERROR in' to see the traceback.

Do HOT-Step Lua plugins hot-reload after editing?

No. Plugins are scanned once at ace-server startup, so editing a .lua file requires an app restart via POST /api/shutdown/restart. The /api/plugins/reload endpoint only clears the Node server's 60-second metadata cache and does not re-read files.

Why does calling apg() fail or behave strangely in a guidance plugin?

apg() is registered lazily on the first guide() dispatch, so calling it at file top level fails at load with a nil-value error. Calling it from post_step() silently reuses a stale momentum buffer. Only call apg() inside guide().

Can one Lua plugin work across ACE-Step, MiniMax-Music3, and SA3 samplers?

Mostly yes, since all three samplers dispatch through the same plugin layer, but with caveats: owns_loop solvers are refused on MM3, guidance is near-decorative on SA3 which lacks an unconditional branch, and SA3 rescales scheduler output to its strength range.

Why does my plugin toggle parameter ignore the off setting?

The idiom (params and params.key) or true always evaluates to true because false or true is true in Lua. Instead, check explicitly: set a local default, then override only when params.key is not nil.