Build a feature

Each feature of a plugin has a build function. Moket calls it whenever the part rebuilds the feature: when it is added, when a value it uses changes, when an earlier feature changes. build reads what it needs, makes shapes with the kernel and returns the bodies it made or changed.

Access: src/plugin.ts in your plugin's folder. See Write a plugin.

import { definePlugin, fail, nameResult, sweepSeeds } from '@moket/plugin-sdk';

export default definePlugin({
  features: {
    'com.example.tools.plate': {
      async build(ctx, params) {
        const thickness = ctx.value('thickness');
        const profile = params['profile'] as { sketch: string };
        const sketch = await ctx.sketch(profile.sketch);
        if (!sketch) throw fail('The sketch is gone', 'profile');
        // ... make the shape with ctx.kernel
        return { bodies: { [params['body'] as string]: body } };
      },
    },
  },
});

The function is async: everything it asks Moket for is a promise.

What the feature can read

Call	What it gives
`ctx.feature`	The feature's `id` and `name`
`ctx.value(name)`	A number param, evaluated: mm, radians or a plain number
`ctx.sketch(id)`	A sketch: its `plane`, its closed `regions` (each with its `loops` and `segmentIds`, `polygon`, `area`, `primary`) and `entities`
`ctx.body(id)`	A body before this feature: its `shape`, `topology` and `named` faces and edges
`ctx.bodies()`	Every body before this feature
`ctx.resolve(ref, body?)`	A picked face or edge by its name: `{ ok: true, body, index }`, the index in the body's `topology`, or why it is not found
`ctx.plane(id)`	A construction plane's origin, normal and x direction
`ctx.marks(body)`	Lines earlier features drew on a body, such as stitches
`ctx.data(feature)`	What an earlier feature returned as `data`
`ctx.parameterText(name)`	A document parameter's value as text, without its unit
`ctx.tools(id)`	The tool solids an earlier Extrude, Revolve or Hole applied
`ctx.context(id)`	A copy of another component's face or edge in an in-context part

Picks come in params: a regions pick is { sketch, regions? }, read the sketch with ctx.sketch and take the regions whose key is listed (or the primary ones when none is); faces and edges are names that ctx.resolve finds in a body.

Make shapes

ctx.kernel is Moket's geometry kernel. Every call returns { ok: true, ... } or { ok: false, error }, so check ok before you use the result:

const box = await ctx.kernel.makeBox(20, 10, 5);
if (!box.ok) throw fail(box.error.message);

Calls	What they do
`makeBox`, `makeCylinder`, `makeVertex`, `helix`	Solids and curves from sizes
`makeProfileFace`, `makeWire`, `joinEdges`	A planar face from loops of lines, arcs, circles and splines; open paths
`extrude`, `revolve`, `sweep`, `loft`	Solids from faces and paths; `extrude` and `revolve` say which faces came from which edge
`boolean`	`fuse`, `cut` or `common` of two shapes
`fillet`, `chamfer`, `thickSolid`, `offsetShape`, `draft`	Rounds, bevels, shells, offsets and draft angles
`transform`	A moved, turned or mirrored copy, by a 3 x 4 matrix
`topology`, `properties`, `check`, `distance`, `subShape`	Faces, edges and vertices with their geometry; volume, area and bounding box; validity
`importBrep`, `exportBrep`, `importStep`, `exportStep`	Shapes from and to bytes

Shapes are handles that last one build. Your feature may use the shapes Moket gave it and those it made; Moket frees them all after the build.

Return a result

Field	What it is
`bodies`	Bodies the feature made or changed, by id: `{ shape, topology, named }`
`removes`	Ids of bodies the feature takes away
`marks`	Lines drawn on bodies without changing them: `{ body, style, points, closed? }`, `style` is `stitch`, `fold` or `line`
`replacesMarks`	Bodies whose earlier marks `marks` replace, when the feature moves a body
`data`	JSON for later features (`ctx.data`) and for exports, up to 1 MB
`appearances`	A body's look by id: a `finish` and an optional `color` such as `#c08a5a`

Finishes are default, bead-blasted, brushed, polished, anodized, polished-steel, stainless, black-oxide, zinc-plated, brass, copper, gold, rubber, matte-plastic, satin-plastic, glossy-plastic, wood, leather, suede and glass. A person's own appearance on a body wins over the feature's.

Name faces and edges

Every body names its faces and edges. Later features, measurements, drawings, assemblies and agents refer to faces by these names, so a name must stay the same when the part changes and point at the same face.

For a solid swept from a profile, use sweepSeeds with the ids of the profile's segments, then nameResult. The bottom is start, the top end and each side is named after its segment:
ts
```
const named = nameResult({
  feature: ctx.feature.id,
  inputs: [],
  topology,
  seeds: sweepSeeds(solid.sweep, face.segmentEdges, [
    ['front', 'right', 'back', 'left'],
  ]),
});
```
The ids are one list per loop of the face. For a region of a sketch, pass region.segmentIds, the sketch's own entity ids, so the sides keep their names when the sketch changes.
For a shape changed by a kernel call that keeps a history (boolean, fillet, thickSolid and others), pass the input's names and the history: faces that were there keep their names, new ones are named after what they came from.
ts
```
const named = nameResult({
  feature: ctx.feature.id,
  inputs: [body.named],
  history: shell.history,
  topology: walls,
  generatedRole: 'wall',
});
```
faceName(feature, role, source?) spells a face name, and nameEdges names the edges after the faces they join.

Names that need a position to tell two faces apart are fragile: they are listed in named.fragile, and Moket warns people who pick them.

Tell people what happened

throw fail(message, param) stops the feature. The message shows on the feature and in its dialog, on the field param names. Write what to change: The corners take the whole side: make them smaller.
Any other error stops the feature too, with its message.
ctx.report({ severity: 'info', message, details }) adds a note. The dialog shows the first note in its status line, and agents read the notes and their details.
ctx.report({ severity: 'warning', message, path }) warns without stopping the feature: the feature shows as a warning.

Build a feature ​

What the feature can read ​

Make shapes ​

Return a result ​

Name faces and edges ​

Tell people what happened ​