Direct Edit State Machine Scripts

Powerful interactive GUI tools (dimensioning, drawing, snapping) built with FCS + FCC platform integration.

Migration / Verification Status

Last updated: 2026-05 — initial skeleton for the full-wiki migration wave.

What This Enables

Direct Edit State Machines let FCS/FCC developers create custom interactive tools that run inside the HiStruct 3D GUI:

• Click a button on an Input page → launch a state-machine-driven picking/drawing/dimensioning session.
• User clicks points, the script collects them via userInput, visual feedback (dots, lines, shaded regions) is drawn live.
• On completion the collected points (or other parameters) are fed back into the model via a validation trigger / constraint.
• Classic use cases: custom dimension tools, rectangle/volume drawers, polygon tools, snapping helpers, measurement overlays, etc.

This is the secret sauce behind many advanced configurators and productivity tools inside HiStruct.

The wiki documents:

• The exact InputItemAction + Behavior = "direct-edit-script:..." registration pattern.
• The full state machine JSON grammar (formatVersion 0.2).
• A rich library of ParametricPoint / ParametricVector / ParametricScalar / ParametricLine / ParametricPlane / ParametricRay helpers for describing geometry relationships without hard-coded numbers.
• 8 complete, real-world tool examples (with videos in the original).

The 8 Documented Tool Examples (to be ported)

From the source Direct-edit-script-examples.md:

1. Draw rectangle tool — two-point rectangle with live preview (triangle-fan fill).
2. Draw volume tool — 3D extrusion / volume creation.
3. Dimension tool — full multi-point dimensioning with projections.
4. Simple dimension tool — minimal working dimensioner (good first candidate for port).
5. Dimension tool with axes projections — snaps to local axes.
6. Polygon draw example — free-form polygon creation.
7. Line snapping example — advanced snapping behavior.
8. Distance measurement tool — pure measurement without permanent geometry.

Each example in the wiki includes the complete stateMachine object + the FCS-side registration (InputItemAction, validation trigger, InputItemArray storage, triggerFn that consumes userInput.parameters.*).

Plan: Port them one or two at a time into examples/direct-edit-tools/<tool-name>/ with modernized formatVersion, clean English comments, a minimal runnable FCC wrapper context, and execution notes.

Core Registration Pattern (from the wiki)

// 1. Button on the input page that launches the script
res.fit.InputItemAction {
    HtmlContent = "dimension tool",
    ValidationTrigger = "dimensionToolActionScriptDone(%userInput)",
    Behavior = "direct-edit-script:dimensionToolActionScriptDefinition",
},

// 2. The state machine definition object (usually stored as a variable or inline)
dimensionToolActionScriptDefinition := {
    id = "dimension-tool",
    formatVersion = "0.2",
    stateMachine = {
        data = { parameters = { ... } },
        states = [ ... ],
        transitions = [ ... ],
        initState = "0",
        finalStates = ["done"]
    }
}

// 3. Storage for the result + the trigger that receives the collected points
dimensionToolPoints := []

dimensionToolActionScriptDone = userInput => 
    site.construct.geometryVolumes.inputs[0].dimensionToolActionScriptTriggerFn(userInput)

dimensionToolActionScriptTriggerFn := userInput => {
    Constraints = [
        {
            Variable = "site.construct.geometryVolumes.inputs[0].dimensionToolPoints",
            Condition = False,
            Init = [
                userInput.parameters.firstPoint.values[0],
                // ... more points from userInput.parameters.*
            ],
            Explanation = "direct-edit dimension tool completed"
        }
    ]
}

The userInput object shape is derived automatically from the parameters declared in the state machine + the saveAsPointId / saveAs* names used in transitions.

Parametric Geometry Helpers (Reference)

The state machine supports a powerful expression language for points, vectors, scalars, lines, planes, and rays so you can describe "the projection of the cursor onto the ray from A in direction X" without writing custom math in FCS.

Full list (from wiki):

ParametricPoint variants: cursor, point, point-value, point-values, point-projected-to-ray, point-projected-to-line, point-projected-to-plane, point-on-line-segment, translate-point, ...

ParametricVector: vector, vector-value, parallel-vector, perpendicular-vector, camera-direction, rotate-vector, ...

ParametricScalar: scalar, scalar-value, line-length, product, ...

(Full grammar and GridAxis, ParametricLine, ParametricPlane, ParametricRay definitions live in the original wiki pages and will be transcribed here as each tool is ported.)

Verified Examples (Golem / FLI-tested)

Current status: Only the basic registration pattern below has been extracted as a starter skeleton.

See examples/direct-edit-tools/minimal-dimension-trigger/

Future entries will appear here once:

• The state machine is modernized to current formatVersion.
• A minimal self-contained FCC context (InputPage + class) that makes the tool actually launchable is provided.
• Execution record (FLI run or Golem-style integration test) is attached.

Migration Notes for Contributors

• The original examples are marked outdated (format 0.1). Any port must target the current supported formatVersion and be tested.
• These tools are almost always fragments that live inside a larger FCC-defined InputPage. The example folders should include a minimal but complete wrapper (class + input page registration) so a developer can drop the folder into a real configurator and see the button.
• Videos and screenshots from the wiki are extremely valuable — when possible, recreate or link them.
• Every ported tool must eventually have a corresponding entry in the Golem test suite or a documented "run this in FLI + paste the collected userInput" verification record.
• Spelling/grammar from the wiki (e.g. "reffers") is cleaned during porting.
• Cross-link heavily from 22, 27, 19, and the main configurator patterns page.

Do not claim any tool "verified in D-Zone" until the above is recorded.

Related Wiki Pages (for full context during migration)

• https://github.com/HiStructOrg/femcad-doc/wiki/Direct-edit-scripts
• https://github.com/HiStructOrg/femcad-doc/wiki/Direct-edit-script-examples
• https://github.com/HiStructClient/femcad-doc/wiki/Direct-edit-scripts (the version the sidebar points to)

This page was created as Wave 1 of the full femcad-doc wiki → D-Zone migration (May 2026). It follows the exact discipline established by the 26-MATERIAL-VISUALIZATION pilot: source traceability, explicit verification status, no untested claims, English-first, Golem/agent-friendly structure.

Next in this wave: Extract and modernize the "Simple dimension tool" or "Line snapping example" into a fully working, documented, minimal example folder with execution notes.