fluidcad-custom-features
GitHubWriting custom features for FluidCAD: a feature type of the project's own in a `*.feature.js` module (`fluidcad/sdk` — `Feature.with()`, `defineFeature()`, `buildTool()`, named buckets and frames, pickers, call shapes, raw OpenCascade via `fluidcad/sdk/occt`) that the Custom dropdown offers with its own dialog and that models call like a built-in; and generated definitions: a feature as an insertable part (`definePart`) or a sub-assembly made by code (`Generator`, `layout(g)`, `defineAssembly`). Use it whenever the user wants a custom feature, their own feature type or toolbar button, a `.feature.js` file, `fluidcad/sdk`, `defineFeature`, `registerBuilder`, `definePart`, `defineAssembly` or a generator, asks to turn a repeated construction into one statement, or wants to share them as a package (`package` block, `pack`). Trigger it alongside the FluidCAD skill when the FluidCAD MCP tools (`mcp__FluidCAD__*`) are available and a feature type or a generated definition, not a plain part, is being written.
Install
npx skills add Fluid-CAD/FluidCAD --skill fluidcad-custom-features -g -y
SKILL.md
Frontmatter
{
"name": "fluidcad-custom-features",
"description": "Writing custom features for FluidCAD: a feature type of the project's own in a `*.feature.js` module (`fluidcad\/sdk` — `Feature.with()`, `defineFeature()`, `buildTool()`, named buckets and frames, pickers, call shapes, raw OpenCascade via `fluidcad\/sdk\/occt`) that the Custom dropdown offers with its own dialog and that models call like a built-in; and generated definitions: a feature as an insertable part (`definePart`) or a sub-assembly made by code (`Generator`, `layout(g)`, `defineAssembly`). Use it whenever the user wants a custom feature, their own feature type or toolbar button, a `.feature.js` file, `fluidcad\/sdk`, `defineFeature`, `registerBuilder`, `definePart`, `defineAssembly` or a generator, asks to turn a repeated construction into one statement, or wants to share them as a package (`package` block, `pack`). Trigger it alongside the FluidCAD skill when the FluidCAD MCP tools (`mcp__FluidCAD__*`) are available and a feature type or a generated definition, not a plain part, is being written."
}
Provenance: maintained in the FluidCAD repo (https://github.com/Fluid-CAD/FluidCAD), under mcp/skills/. The installed local skill files are the runtime source of truth.
Writing a custom feature
This skill layers on top of the fluidcad skill. That one owns the loop: read the docs, plan in generic CAD terms, build in increments, check render.state and objectErrors, resolve filters before writing them, screenshot when a feature earns it, and report only what was checked. Follow it for the test part. This skill covers what is specific to a custom feature: deciding that one is warranted, designing it as a feature a user fills in, writing the module, and proving it in a part.
The governing principle: a custom feature is a CAD feature first and code second. Its user picks a face and types a height in a dialog, then fillets its rim and repeats it; design for that user, write the code to that design, and prove it the way that user will use it.
1. Decide whether one is warranted
Write a custom feature when one construction recurs (across models, or across places in a model with different values) and should be one statement, one dialog, one timeline row: a PCB standoff on any face, a ring of clearance holes around any axis, a vent grid on any panel, bosses at a set of connectors.
Don't write one, and say why, when:
- the geometry occurs once: write the statements in the model;
- it is the same geometry again in one model:
repeat()re-applies a feature at new positions,copy()duplicates a finished shape; - it is a whole part reused with other dimensions: a
part()withparam()values, inserted where needed (the fluidcad-assembly skill) — unless one feature builds that part and it should carry the feature's dialog: then the feature plusdefinePart(section 9); - it is several parts that move against each other, sized from one set of values (a wardrobe with hinged doors and sliding drawers): a generated assembly,
Generator+defineAssembly(section 9); - a built-in already does it (
hole()for drilled, clearance, tapped, counterbored and countersunk holes;draft();rib();shell()): search the docs first.
2. Design it in CAD terms
Before code, write the design down the way a CAD user would describe a feature dialog, and show it (under the autonomous fallback, put it in the report):
-
Name and id. A label for the toolbar ("Vent grid") and a plain id (
ventGrid). It may not be one of the engine's own types (extrude,fillet,part,sketch,distance, …: "'extrude' is one of the engine's own types: give the feature another id"). The id is the feature's type in every timeline: pick it once. Installed from a package, the feature's type becomes@<handle>/<package>:ventGrid(whatget_scene_summaryshows); a model still imports and callsventGrid, and never writes that key. -
What it does to the solids. Adds material, cuts it, or keeps a separate body: that is a tool (
buildTool()returns solids, the base fuses or cuts them) withoperations. Changes existing solids in another way (tilts faces, offsets, splits): a modifier (build()); prefer a tool whenever the feature adds or removes material — the modifier surface is the engine's internals, not a settled SDK. -
Operations and the default.
['add', 'new']for a boss-like feature,['remove']for a cut-only one (it cuts with no chain and shows no tabs),['remove', 'new']for a pocket that may also be a separate body. The default isaddwhen offered, else the first listed.buildTool()reads the operation its statement applies — the chain's, else the default; the dialog's tab in the preview; the statement's on a repeat's copy — withthis.getOperationMode()('add','new'or'remove'), when a remove needs a different tool than an add (an internal gear adds the whole ring but removes only the tooth space). -
Each value, as a dialog row. Typed in:
length(in the model's unit),angle(degrees),integer,number,boolean,select,radio,text, with amin/maxthat keep the geometry valid. A row left alone in the dialog builds what it shows: abooleanwithout adefaultis off, aselector aradiowithout one takes its first option (anoptionalone stays unset), a slider without one sits at itsmin, a select withmultiple: trueis[]; a number or a text without one must be typed in (Apply says "Height is required."), so give every size a sensibledefault. Picked:face,edge,axis(takes world axes, axis statements, straight edges and connectors),plane,sketch,solid,feature,connector,point,anchor, or a union of kinds that take different clicks. One pick or a list (multiple: true). Hide rows that only matter for one choice (visibleWhen), or for one kind of pick (visibleWhen: { at: { not: { surface: 'cylinder' } } }hides a hub's rows while a shaft is picked); a list of such objects shows the row while any one holds ([{ type: 'wardrobe', doors: true }, { type: 'base' }]). -
The control for each typed-in value.
typeis what the value is;displayand the fields beside it are only how its row looks, and never change the statement. Choose by what the user is deciding:- a few choices, all worth seeing at once:
radio—display: 'buttons'for 2–3 short labels,'cards'when pictures tell them apart; - many choices:
select—display: 'grid'with animageper option when they are recognised by shape,search: truebeyond a dozen; - several at once:
selectwithmultiple: true(the value is a list;min/maxcount it); - a bounded number the user explores:
display: 'slider'(needsminandmax); a small count:display: 'stepper'(number/integeronly); a unit:suffix: 'mm'; a remark that must stay visible:hint(descriptionis the tooltip); - one choice narrows another (the sizes of the chosen standard): one select whose options carry
when: { standard: 'iso' }, not two selects swapped withvisibleWhen(a size table, where an option comes with several combinations, giveswhena list of such objects, any one holding).whennarrows the dialog only — a hand-written call may pass any declared option, so the builder must handle every one; - one value's sensible default depends on another (a wall cabinet is 720 high, a wardrobe 2400):
defaults: [{ when: { type: 'wall' }, value: 720 }, { when: { type: 'wardrobe' }, value: 2400 }]beside the plaindefault, not a value per type. The first entry whosewhenholds wins; an untouched dialog row follows it live, a touched one keeps its value; a call that leaves the value out gets it from its other values. Awhennames typed-in values withoutdefaultsof their own (one level), and eachvaluemust fit the declaration (range, options, offered where itswhenholds); - images are files next to the module (
'./vent/slots.svg'), drawn as pictures: use mid-tone strokes, notcurrentColor.
- a few choices, all worth seeing at once:
-
The layout, only when it earns it. A handful of rows needs none: declaration order is the dialog, with a value's
groupandtabas the short form. Write alayout(withwidth: 'wide'when rows sit side by side) when values pair up in arow(count and spacing), a rarely used set should fold ({ section, collapsed: true }), or a dimension drawing belongs in theaside. A value that measures something the user may not know (a pressure angle, a profile shift, a backlash) earns anasideof its own — a diagram and a one-line note the card shows while its row has the focus. Rows never cut a label short: a cell that can't fit wraps to its own line, so pair narrow controls and give a long segmented choice (or a select) its own line. A layout places every value exactly once, and then no value may keep its owngrouportab. -
The call a model writes. Picked geometry first and positional, sizes in one object of options:
ventGrid(panel.endFaces(), { rows: 4, columns: 6, pitch: 8 }). A list of picks is one array argument or a trailing rest. A pick that may be left out (optional: true, a placement that defaults to the origin) stays first: a call without it goes straight to the options,gear({ teeth: 24 })(nevergear(undefined, …)), and the dialog writes it that way. -
The buckets: declare named buckets for what a user will fillet, chamfer or sketch on. A downstream fillet, a sketch and every pick on the feature read its buckets; without them
f.endEdges()names nothing and the editor writes picks on it as filters. Two layers:- the standard ones: which faces are its start faces (where it meets what it grew from), end faces (its far end), side faces, internal faces (bores, a cut's walls) and cap faces. For a cut, the plane the tool starts on (
startPlane) classifies the rims; - named buckets of its own, for the parts of the result a user will name: a gear's
tipFaces/tipEdges, a pocket'sfloorFaces/floorEdges, a boss'sboreFaces/boreEdges. Declared withFeature.with(params, { buckets: { tipFaces: {}, tipEdges: {} } }), each becomes a typed method (fillet(0.3, g.tipEdges()),r.instance(2).tipEdges()on a repeat's copy), the editor writes picks through it first, and the right-click menu offers it ("Gear Tip Edges"). A name ends inFacesorEdges; an edge bucket exists only when declared, and one left out ofsetBuckets()is the edges of its…Facessibling. A declaration holds only an optionallabel(the menus' words). Name the face the feature grows fromstartFaces, not a bucket of your own: a named bucket drops a face the fusion merges away,startFacesis re-homed onto the stock face.
List each named bucket in the design with what it holds and in what order (teeth in tooth order, flanks two per tooth); that list becomes the feature's
docs/page (section 4). - the standard ones: which faces are its start faces (where it meets what it grew from), end faces (its far end), side faces, internal faces (bores, a cut's walls) and cap faces. For a cut, the plane the tool starts on (
-
The preview. The feature chooses with
ghostin its metadata:'toggle'(the default) gives the dialog a Preview toggle that starts off (remembered per feature once the user turns it on) — for a build that may be slow;'always'previews from the start with no toggle — for a cheap build;falsedraws none. While it previews, a tool runsbuildTool()on every change, and one that takes over 5 s to build times out (the user turns the toggle off and on, or presses Try again with no toggle, to ask again). Keep the build cheap, or overrideghost()with a cheaper shape. -
Can the curated kernel build it?
fluidcad/sdk/kernelhas cylinders, spheres, cuts and placement transforms. Anything else (a box, a loft, a sweep, an offset) needs raw OpenCascade insidethis.occ(): say so in the design, since it is unstable and unchecked.
3. Read the docs
read_doc these before writing (in parallel sub-agents when your client has them; sub-agents read, never write):
concepts/custom-features— the module, discovery, the lifecycle, where errors show;api/feature— the class,buildTool()andgetOperationMode(),setBuckets()and what it refuses, named buckets in short, the reference readers,ghost();api/feature-buckets— named buckets in full: the naming rule, derived edge buckets, every refusal and its message, what a fusion, a remove and a repeat do to them, the editor's picks;- the worked example closest to the design:
api/feature-example-gear(named buckets, a raw OpenCascade outline),api/feature-example-bearing-seat(named buckets through a remove),api/feature-example-bosses(several tools at connectors and points),api/feature-example-tube(a different tool for a remove); api/define-feature— the metadata, operations, the call shape, what the dialog can edit;api/feature-params— every value kind, picker and option, unions; eachdisplay; the table of what an untouched row shows and the builder gets; a runnable example with every control ("a screw hole with choices");api/feature-layout— only when the design has alayout,width, anasideor a value's ownaside;api/sdk-kernel— the geometry, and who owns which shape;api/sdk-occt— only when the design needs raw OpenCascade;api/register-builder— only when the builder must act before it reads its arguments;api/feature-frames— when the feature publishes where it stands (a gear's axis):Feature.with(params, { frames }),setFrames(),g.frame(name);api/define-part,api/generator,api/define-assembly— for a generated part or assembly (section 9).
get_type_definition resolves Feature, FeatureBuckets, FeatureWithOptions, FeatureBucketSpec, FeatureFrameSpec, NamedFrames, ParamSpec, ChoiceOption, FeatureLayout, CallShape, FeatureMeta, OccScope, the kernel classes, and the generated-definition types (Generator, GeneratorLayout, GeneratedPartSpec, GeneratedFrameSpec, GeneratedPose, GeneratorBuildContext, DefinePartMeta, DefineAssemblyMeta, GeneratedSchema); get_api_signature resolves defineFeature, registerBuilder, parseCall, getOC, definePart and defineAssembly. Then read references/traps.md in this skill.
4. Write the module
One file, <name>.feature.js, anywhere in the workspace except under node_modules, a dot directory or a gitignored path; beside the models that use it is the norm. The suffix is what the editor scans for, and it keeps the module's own stack frames out of the statement's source location. The shape:
import { Feature, defineFeature } from 'fluidcad/sdk';
import { BooleanOps, Primitives, ShapeOps } from 'fluidcad/sdk/kernel';
import { Matrix4, Plane } from 'fluidcad/math';
export class VentGrid extends Feature.with({
face: { picker: 'face', label: 'Panel face', surface: 'planar' },
rows: { type: 'integer', display: 'stepper', default: 3, min: 1, max: 50 },
pitch: { type: 'length', display: 'slider', default: 8, min: 2, max: 40, suffix: 'mm' },
// …
}, {
buckets: {
holeFaces: {}, // the wall of every hole, row by row
holeEdges: { label: 'Hole Rims' }, // declared, not filled: the edges of holeFaces
},
}) {
static id = 'ventGrid';
buildTool() {
const { rows, pitch } = this.values; // typed: numbers
const [face] = this.facesOf(this.values.face);
// Build on the XY plane, sort the faces into buckets there, place with
// ShapeOps.transformTracking, name the placed images, dispose what you drop.
this.setBuckets({ /* startFaces, endFaces, sideFaces, internalFaces, startPlane, */ holeFaces });
return [/* the solids */];
}
}
export const ventGrid = defineFeature(VentGrid, {
label: 'Vent grid',
description: 'A grid of round vent holes through a panel',
group: 'create',
operations: ['remove'],
call: ['face', { rows: 'rows', pitch: 'pitch' /* , … */ }],
// layout: ['face', { row: ['rows', 'pitch'] }, …], width: 'wide' — only when the design calls for one
});
Every value the class declares must appear in call (and in the layout, when there is one). A complete module with every control and a layout is the screw hole in api/feature-params; complete modules with named buckets are the gear (api/feature-example-gear) and the bearing seat (api/feature-example-bearing-seat).
The rules that keep it right:
- Export the builder by name. A default export is skipped by the editor's scan.
- No constructor, no module-level state, no geometry at module level. The module is evaluated anew on every render and by the editor's scan, so the class is new each time: never
instanceofit. The engine compares features by id and values. - Read references only through the helpers:
facesOf,edgesOf,shapesOf,axisOf,planeOf,frameOf,pointOf,isLocation. The preview hands the feature stand-ins, not the scene's objects. - Validate the picks and values the metadata can't, and throw a message that names the feature and the fix (
vent grid: the holes (6) must be narrower than the pitch (5)):surface: 'planar'only limits the dialog's picks, never a hand-written call. - Build tools on the XY plane (start at
z = 0), sort their faces into buckets there, then place them withShapeOps.transformTrackingand name the images it returns. - Dispose every intermediate (a cylinder a cut consumed, a shape you moved); never dispose a shape
buildTool()returns or one read from a reference. - A loop inside
buildTool()is fine: the instances come from one statement and one row. The no-loops rule is for models. - Raw OpenCascade only inside
this.occ(({ oc, track }) => …): construct through the scope'soc,track()every object a method returns, return wrappers made withShapeFactory.fromShape(raw). Never construct throughgetOC(), never free a shape the scene holds. - Fill every named bucket you declare in
setBuckets(), except anxEdgesmeant to be the edges ofxFaces. A misspelt name, a non-list, a face in an edge bucket or a face of a shape you don't return fails the feature's row (gear: setBuckets() 'tipFace' is not a bucket of gear — did you mean tipFaces?).
Describe each named bucket in the feature's docs/ page. A bucket declaration takes no description (one is refused): what a bucket holds belongs in docs/<feature>.md at the workspace root (the folder a package ships), which other authors and the LLM read. Write it with write_file (any file that is not a model or a module renders nothing): for each named bucket, what it holds, in what order (g.tipFaces(i) is tooth i's top land, counting from the face's X direction), and what a user does with it (fillet(0.3, g.tipEdges())). A line comment beside each declaration is for the code's reader; the page is the documentation.
Writing it with the MCP. write_file on a *.feature.js (or any module, or fluidcad.json) never renders the module itself: it re-renders the open model in full, and render carries openModel: true with that model's state and objectErrors. So write the module, then write the test part (which renders and becomes the open model); from then on, every module write reports on the test part. render.state of no-open-model means no model is open yet; render-failed carries the first lines of the error the model hit loading the module (a refused metadata field, a syntax error), and get_compile_error has the whole message with the module's line a moment later.
5. Write a test part that uses it the way a user would
A recognisable part (a panel, a bracket, a PCB plate), built by the FluidCAD skill's rules: imports from every entry it uses (import { ventGrid } from './vent-grid.feature.js'), named dimensions, fully constrained sketches. Exercise what a user will do:
- every argument as the dialog writes it: a select, radio or text as a plain literal, a
multiple: trueselect as an array literal (finishes: ['deburr'],[]for none); - the feature on a picked face written as an accessor (
panel.endFaces()), as the dialog would write it; - each operation it offers, and
.scope(…)when it matters; - a
repeat()orcopy()of the feature, when its use calls for patterns; - a fillet or chamfer through one of its named buckets (
fillet(0.3, g.tipEdges()),chamfer(0.5, post.boreEdges())), a standard one where it fits (post.endEdges()), and a downstream feature on one of its faces (sketch(p.floorFaces(), …)); - values at their limits (the smallest count, a value left to its default).
6. Render and check
render.stateandobjectErrors. Where each failure shows:- a refused metadata field, a syntax error in the module, or a call the builder can't read (
ventGrid(): 'rows' must be at least 1, got 0) fails the whole model to compile:compile-erroron the model's write,render-failedon the module's; buildTool()throwing, returning nothing, or an operation the feature doesn't offer fails its row only:build-error, with the message underobjectErrors.
- a refused metadata field, a syntax error in the module, or a call the builder can't read (
validateevery solid the feature made, thenscreenshotit (a section through a cut feature) andmeasurethe dimensions its values drive: a hole's diameter, a boss's height, a pitch between two instances.- The buckets resolve. Find the feature's scene-object
idandindexwithget_scene_summary, thenresolve_selectionthe expression$obj["<id>"].startEdges()and each named bucket ($obj["<id>"].holeFaces(),….holeEdges()), scoped to its part, withbeforeset to the index right after the feature: a later fillet or chamfer replaces the edges and faces it touches, so at the model's end those buckets resolve to nothing. The count must be what the design says (a 3 × 5 vent grid: 15 start edges, 15 end edges, 15 hole faces), and the summaries' centres and diameters must sit where the values put them. Zero means the fusion or the cut removed them, or the bucket was left unfilled (a misspelt or wrong-kind name fails the row instead). The synthesizedsourceof a whole named bucket is the bucket itself (g.holeFaces()), which shows the editor will write picks through it. - A value change rebuilds. Change one value in the test part and confirm the geometry follows;
render.changes.rebuiltlists the feature's row. - It typechecks under the workspace's
jsconfig.json(fluidcad initwrites one withcheckJs): when you have a shell,npx -p typescript tsc --noEmit -p jsconfig.jsonin the workspace, expecting no errors.this.valuesand the builder's arguments are typed by inference; a misspelled option in the test part is an error. - The editor offers it. When you have a shell,
GET http://localhost:<port>/api/features/catalog(the port fromlist_workspaces) lists the feature with noerror; anerroris what the Custom dropdown's greyed cell says.
7. Iterate
Saving the module's code rebuilds its statements in every model that read it, with no engine restart; with the MCP, the module write re-renders the open model in full and reports on it. Change one thing per write. When a value change misbehaves but a fresh write is right, suspect state kept between renders.
8. Package it, when it should travel
Do this only when the user wants the feature in other projects or for other people; a feature used in its own workspace needs no package. A package is the workspace's own fluidcad.json with a package block; fluidcad publish packs it into one .fluidpkg file and uploads it to the hub (read_doc concepts/packages). Packages reach other projects only through the hub: the archive itself never installs.
- The layout. The folders decide what a package exports: every
*.feature.jsinfeatures/, every*.part.js(or*.fluid.js) inparts/and every*.assembly.jsinassemblies/, nested folders allowed. Move each feature module intofeatures/with its images (they resolve next to the module, so./vent-grid.svgkeeps working), and a part or assembly that should travel intoparts/orassemblies/; its imports become relative to the folders (import { ventGrid } from '../features/vent-grid.feature.js'). Plain.jshelpers can sit in any of the three, never at the root: pack refuses an import that leaves them (outside-layout) and a module in the wrong folder for its suffix (wrong-folder). A test part that should not travel stays outside the three folders, at the root, and imports./features/vent-grid.feature.js. A package needs at least one part or assembly to be published on the hub; a features-only package still packs, but can't be published. - The block. The name is
@<handle>/<name>, where the scope is the user's hub handle: ask them, or runnpx fluidcad whoami. With a shell,npx fluidcad package init --name @<handle>/vent-hardwarein the workspace writes it: the name and version0.1.0, and it says what the folders hold (signed in,--name vent-hardwaretakes their handle and says so). Without one, add it tofluidcad.jsonwithwrite_file, keeping every other key (engine,unit,materials):
Packages are named @handle/name, each part in lowercase letters, digits and single dashes, starting with a letter. A name without the scope ("package": { "name": "@acme/vent-hardware", "version": "0.1.0", "description": "A vent grid for enclosure panels" }vent-hardware) is refused, and the scope must be the handle they publish under:fluidcad publishrefuses another one. Feature ids stay plain. There is noexportskey: a block that has one is refused. Files the package reads. Aload()or.font()written in the package's files reads the package's own file once installed (imports/<name>.brep,fonts/Brand.ttf), whichpackships because a part read it; it never reads a file of that name in the project using the package, and a missing one fails naming the package. A file name that comes from that project — a part'sFontor STEP-name parameter, a value a user types — must say so:text(label).font(font, { from: 'project' }),load(name, { from: 'project' }). In this workspace both read the same files, so the mistake only shows after install: check everyload()and.font()whose name comes from a parameter before you pack. pack, to check the package without publishing it, withsaveAsPathset to an absolute path named as the result'sfileName(acme-vent-hardware-0.1.0.fluidpkg), outside the workspace unless the user asked for it there. The engine evaluates every export and builds every part and assembly first;pack-refusedcarries one sentence naming the file and adetails.code(wrong-folder,outside-layout,no-exports, orrefusedfor a name without its scope, two features sharing an id, a missing image, an import from node_modules or another package, a file a part reads from node_modules, outside the workspace or an installed package, a part that fails to build, unsaved editor changes; for a generated definition also an image its schema declares that is missing or outside the workspace, and aminEnginebelow 0.0.49). Fix that file and pack again.- Report the package name, version,
savedToand what it holds (the result'scontents: the features, parts and assemblies by folder). Tell the user how it reaches other projects: only through the hub.npx fluidcad publish, run in the workspace, packs it again and uploads it (it needs a hub handle and publishing rights, and an admin reviews it before it is public); the saved archive is for looking at, not a step before publishing; then, in another project,npx fluidcad install @acme/vent-hardwareinstalls it and a model imports it by that name (import { ventGrid } from '@acme/vent-hardware'). The archive itself doesn't install. To try the package, use its features and models in this workspace. Never publish or install on the user's behalf. - A new version: edit the module, raise
package.version(npx fluidcad version minor, or edit the block), and check it withpackagain;npx fluidcad publishreleases it. An installed version never changes, so a fix to a released version is always a new version.
9. Generated parts and assemblies
The values a feature declares are also the interface of an insertable part and, through Generator.with(), of a sub-assembly made by code. Both are inserted into assemblies with their values by id and edited in the assembly toolbar's Generate Parts dropdown with the feature-style dialog and a live preview of the real result. Read references/generators.md in this skill before writing either; it has the rules, the MCP checks and the traps.
- Generated part —
export const gearPart = definePart(Gear, { label: 'Gear', icon: '../features/icons/gear.png' })in a*.part.js(a package'sparts/). The class is a tool whose every pick isoptional: true(the part leaves picks out and builds at its origin). Each frame the class declares (Feature.with(params, { frames: { axis: {} } }), set withthis.setFrames({ axis: plane })) becomes a connector of its name:insert(gearPart, { teeth: 18 }).connectors.axis. - Generated assembly — a class that
extends Generator.with({ … })with astatic id, a synchronouslayout(g)(plain JavaScript:g.part(type, { name, inputs, connectors, appearance, material }),.grounded(),.pose(),g.mate(…).flip().limits(…).name(…),g.relation(); it returnsoccurrence.parts) and astatic build(type, inputs, ctx)that reads only its plain-JSONinputsand returns the part's shapes (ctx.detail'preview'skips drilling and small hardware).export const wardrobe = defineAssembly(WardrobeUnit, { label: 'Wardrobe' })in an*.assembly.js(a package'sassemblies/); the class beside its images infeatures/. - Rules that bite: values only, no picks; inputs and frames plain JSON (
[x, y, z], never aPlane); everything a part's geometry depends on in itsinputs; rounded numbers so equal parts share a template; a frame on both sides of a joint plus.flip(), so 0 is closed; never keep shapes in module state; generated parts and their joints are read-only rows — change them through the insert's values; no configurations. - Verify with a test assembly at the workspace root that inserts the definition the way a user would:
render.stateandobjectErrors(a bad value or a layout throw is a row error at the insert's line; abuildthrow is on that part's row),get_scene_summary(occurrences,instancesbyowner, onepartrow per template withparams.generatedByand itsconnectorrows, the layout'smatesandrelations— engine-owned, under the occurrence's path — with their sides, limits and flips),screenshot,interfereandmeasureat the starting poses, a value change that leaves untouched templatesfromCache, andpack(images,minEngine0.0.49 or later). The'preview'tier runs only in the editor's dialog: say it was not checked unless a browser drove it.
10. Report only what was checked
Report the design (section 2), what you rendered, validated, measured and resolved, and the typecheck and catalog results. Name what you did not check: the dialog and its preview are only seen in the FluidCAD UI, so unless a browser drove them, say "not checked in the dialog" rather than implying it. Tell the user where the feature appears (the toolbar's Custom dropdown, last on the part toolbar) and that a model imports it from the module; a generated part or assembly appears in the assembly toolbar's Generate Parts dropdown and the Insert dialog, and an assembly imports it from its *.part.js / *.assembly.js.
Quick reference: the custom-feature loop
- Decide that a feature is warranted, or say what to use instead (section 1).
- Design it in CAD terms: tool or modifier, operations, each value as a dialog row, the call, the standard buckets and the named buckets a user will fillet, chamfer or sketch on, kernel or raw OpenCascade (section 2). Show it.
read_docthe custom-feature docs; readreferences/traps.md.write_filethe*.feature.jsmodule, anddocs/<feature>.mddescribing each named bucket (what it holds, its order).write_filea recognisable test part that uses it as a user would, with a fillet or chamfer through a named bucket.render.state,objectErrors,validate,screenshot,measure,resolve_selectionon its buckets, named ones included; typecheck and the catalog when a shell is available.- Iterate on the module: each write re-renders the open model (
render.openModel). - When it should travel: the modules into
features/,parts/andassemblies/, thepackageblock influidcad.json, thenpackwithsaveAsPath(section 8). - For a generated part or assembly:
references/generators.md, the defining*.part.js/*.assembly.js, a test assembly that inserts it by id, and its checks (section 9). - Report what was checked, and what was not.
Version History
- 5b8e897 Current 2026-11-07 13:50


