ScriptTap AI Function Reference v1
Generated: 2026-06-03
URL: https://scripttap.com/ai_functions_v1.txt

Purpose:
This is the public command reference for AIs creating ScriptTap V1 `.scripttap.json` script packages.
Use this with https://scripttap.com/ai_prompt.txt when available.

Core rule:
Build by default. If a coordinate, asset, app package, script target, or exact value is unknown, return an incomplete but importable JSON draft. Put unresolved work in `requirements`, `assetRequirements`, command `validationState`, and top-level `notes`. Do not ask questions outside the returned JSON.

Required command object fields:
- `id`: required package-local id, starts with `cmd_`.
- `type`: required exact command type.
- `nickname`: required string, max 20 chars; empty string is allowed.
- `disabled`: required boolean.
- `validationState`: required `complete`, `incomplete`, or `unknown`.

Strict field rule:
- Command objects may contain only `type` plus the accepted public JSON fields listed for that command.
- Do not include unknown fields or app-maintained fields.
- The compact archive schema omits `type`, but public JSON import requires `type` on every command.

Never generate these app-maintained fields:
- `estimatedWorkPerSecond`
- `workEstimateVersion`
- `validationReason`
- `validationSignature`
- `validationVersion`
- `validationAssetGeneration`
- `aiImported`

Variable rules:
- Active variable types: `integer`, `boolean`, `hex`, `string`, `time`.
- Default single variables: Integer `i1`, Boolean `b1`, Hex `h1`, String `s1`, Time `t1`.
- Default array letters: Integer `i`, Boolean `b`, Hex `h`, String `s`, Time `t`.
- A normal field accepts exactly one variable token unless this reference says it is an array-letter field or row array.
- Do not use CSV variable lists or variable ranges in operational fields.
- Predeclaring output variables with SetVariable is a readability best practice, not a requirement. Unknown valid output variables are allowed, but known existing variables must match the writer type.

Coordinates, areas, and colors:
- Literal coordinate fields use whole integers.
- Value fields such as `tapXValue`, `leftValue`, `areaLeftValue`, and `visualLineStartXValue` may hold a whole integer string or a variable token.
- Unknown screen coordinates should usually be `0`/blank with `validationState:"incomplete"` and a note.
- Hex colors use six hex digits such as `FF00AA`; literal `0` is accepted where ScriptTap normalizes it to `000000`.
- ScriptTap `confidencePercent` is deterministic RGB/channel/pixel matching, not AI visual likeness.

Assets:
- JSON names assets only. It never includes image bytes, screenshots, PNGs, filesystem paths, or base64.
- Asset-backed commands remain incomplete until the user supplies the assets inside ScriptTap.
- If an AI names a missing future asset, also add an `assetRequirements[]` row for that command.

Flow and blocks:
- Balanced pairs must stay ordered in one script: `loop`/`end_loop`, `for_each_index`/`end_for_each_index`, `pause_concurrent`/`unpause_concurrent`, IF start/end pairs.
- `else` is allowed once inside an IF block and must appear before that IF block's end row.
- `pause_concurrent` is user-facing `Exclusive`; it is the only command that blocks other runtime branches.

Normal generated commands
=========================

Function: Tap
Command type: `click`
Category: Actions
Purpose: Taps a fixed point, selected area, last tap, or X/Y array points.
Required fields:
- Choose one mode: fixed point with `tapXValue` and `tapYValue`; area with `inArea=true` and area bounds; `repeatLastTap=true`; or array mode with `useVariableArray=true`, `xVariableName`, and `yVariableName`.
Optional fields:
- Repeat and pacing fields: `clickRepeatEnabled`, `clickRepeatValue`, `clickRepeatSequential`, `clickRepeatPerPointValue`, `clickRepeatTapDelayValue`, `clickRepeatPointDelayValue`, `clickArrayDelayValue`.
- Press duration: `tapPressDurationValue`.
- Literal coordinate mirrors: `x`, `y`, `areaLeft`, `areaTop`, `areaRight`, `areaBottom`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `x`, `y`, `tapXValue`, `tapYValue`, `repeatLastTap`, `clickRepeatEnabled`, `clickRepeatValue`, `clickRepeatSequential`, `clickRepeatPerPointValue`, `clickRepeatTapDelayValue`, `clickRepeatPointDelayValue`, `clickArrayDelayValue`, `tapPressDurationValue`, `useVariableArray`, `inArea`, `areaLeft`, `areaTop`, `areaRight`, `areaBottom`, `areaLeftValue`, `areaTopValue`, `areaRightValue`, `areaBottomValue`, `xVariableName`, `yVariableName`.
Common mistakes:
- Do not leave all tap modes blank and mark the command complete. Unknown coordinates mean incomplete.

Function: Delay
Command type: `delay`
Category: Timing
Purpose: Waits before running the next command.
Required fields:
- `delayMs` integer, or `delayVariableName` holding an Integer variable.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `delayMs`, `delayVariableName`.
Common mistakes:
- Use milliseconds, not seconds.

Function: Delay Until
Command type: `delay_until`
Category: Timing
Purpose: Waits until a clock time/date or until any selected image appears in a screen area.
Required fields:
- `delayUntilMode`: `time` or `image`.
- Time mode: `delayUntilHour`, `delayUntilMinute`, `delayUntilSecond`.
- Time mode with `delayUntilUseDate=true`: also `delayUntilMonth`, `delayUntilDay`, `delayUntilYear`.
- Image mode: `assetNames[]` or legacy `delayUntilAssetName`, area fields, and `delayUntilImageCheckMs`.
Optional fields:
- `delayUntilUse24Hour`, `delayUntilUseDate`, `delayUntilLeftValue`, `delayUntilTopValue`, `delayUntilRightValue`, `delayUntilBottomValue`.
Allowed enum values:
- `delayUntilMode`: `time`, `image`.
Output variable fields: none.
Asset rules:
- Image mode requires existing asset names or matching `assetRequirements[]` rows.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `delayUntilHour`, `delayUntilMinute`, `delayUntilSecond`, `delayUntilUse24Hour`, `delayUntilUseDate`, `delayUntilMonth`, `delayUntilDay`, `delayUntilYear`, `delayUntilMode`, `delayUntilAssetName`, `delayUntilLeft`, `delayUntilTop`, `delayUntilRight`, `delayUntilBottom`, `delayUntilLeftValue`, `delayUntilTopValue`, `delayUntilRightValue`, `delayUntilBottomValue`, `delayUntilImageCheckMs`, `assetNames`.
Common mistakes:
- Image mode waits only; it does not tap and does not write variables.

Function: ReTap
Command type: `retap`
Category: Actions
Purpose: Repeats a user tap, or captures that tap's X/Y into Integer variables.
Required fields:
- Repeat mode: `retapMode:"repeat"`, `retapRepeats`, and `delayMs`.
- Set Coordinates mode: `retapMode:"set_coordinates"`, `xVariableName`, and `yVariableName`.
Optional fields:
- `retapUseTimeout`, `retapTimeoutMs`, `retapCoordinateTimeoutValue`, `tapPressDurationValue`.
Allowed enum values:
- `retapMode`: `repeat`, `set_coordinates`.
Output variable fields:
- Set Coordinates mode writes Integer `xVariableName` and `yVariableName`.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `delayMs`, `retapRepeats`, `retapUseTimeout`, `retapTimeoutMs`, `tapPressDurationValue`, `retapMode`, `retapCoordinateTimeoutValue`, `xVariableName`, `yVariableName`.
Common mistakes:
- Set Coordinates captures a user tap into variables and does not dispatch a tap afterward.

Function: Multi-Tap
Command type: `multi_click`
Category: Actions
Purpose: Taps multiple points or targets.
Required fields:
- `multiClicks[]`, or area mode, or array mode with `xVariableName` and `yVariableName`.
Optional fields:
- `delayMs`, repeat and pacing fields, `tapPressDurationValue`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `multiClicks`, `useVariableArray`, `xVariableName`, `yVariableName`, `clickRepeatEnabled`, `clickRepeatValue`, `clickRepeatSequential`, `clickRepeatPerPointValue`, `clickRepeatTapDelayValue`, `clickRepeatPointDelayValue`, `clickArrayDelayValue`, `tapPressDurationValue`, `inArea`, `areaLeft`, `areaTop`, `areaRight`, `areaBottom`, `areaLeftValue`, `areaTopValue`, `areaRightValue`, `areaBottomValue`, `delayMs`.
Common mistakes:
- Do not put CSV coordinates into one field. Use `multiClicks[]` rows or X/Y arrays.

Function: Swipe
Command type: `swipe`
Category: Actions
Purpose: Runs a saved swipe path or a press-then-drag path.
Required fields:
- `gestureStrokes[]`.
Optional fields:
- `swipeMode`, `swipeActionMode`, `swipePressDurationValue`.
Allowed enum values:
- `swipeMode`: `exact`, `quick`.
- `swipeActionMode`: `swipe`, `drag`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `swipeMode`, `gestureStrokes`, `swipeActionMode`, `swipePressDurationValue`.
Common mistakes:
- Missing/default paths are incomplete. Do not mark a zero-point swipe complete.

Function: Pinch
Command type: `pinch`
Category: Actions
Purpose: Dispatches two simultaneous finger paths as one Android gesture.
Required fields:
- `gestureStrokes[]` with exactly two stroke objects.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `gestureStrokes`.
Common mistakes:
- Both strokes need real start/end paths and positive timing. All-zero placeholder strokes are incomplete.

Function: Gesture
Command type: `gesture`
Category: Actions
Purpose: Replays a legacy recorded gesture path.
Required fields:
- `gestureStrokes[]`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `gestureStrokes`.
Common mistakes:
- Prefer `swipe` or `pinch` for new scripts unless a legacy gesture path is specifically needed.

Function: ImgFind
Command type: `img_find`
Category: Vision
Purpose: Finds saved image assets on screen, then optionally taps or writes variables.
Required fields:
- `assetName` or `assetNames[]`.
- Area: `left`, `top`, `right`, `bottom` or matching `leftValue`, `topValue`, `rightValue`, `bottomValue`.
- Outcome: `clickIfFound=true`, or `setVariables=true` with outputs, or an output mode with required output fields.
Optional fields:
- `multiAsset`, `useNegativeAssets`, `negativeAssetNames[]`, `negativeConfidencePercent`, `confidencePercent`, `tolerance`, `findAll`, `findFirstRightToLeft`, `findFirstBottomToTop`, `returnXY`, `clickTargetCenter`, `clickTargetXValue`, `clickTargetYValue`, `imgFindOutputMode`, `imgFindAssetLabel`, `imgFindAssetLabels`, classify behavior fields.
Allowed enum values:
- `imgFindOutputMode`: `standard`, `classify`, `boolean_array`.
- `imgFindClassifyUnknownMode`: `write_unknown`, `write_empty`, `keep_previous`.
- `imgFindClassifyAmbiguousMode`: `write_ambiguous`, `write_empty`, `keep_previous`, `write_unknown`, `use_highest_confidence`, `use_asset_order_priority`.
Output variable fields:
- Standard: `variableName` Boolean, optional `xVariableName` and `yVariableName` Integer.
- Classify/Find All: `imgFindClassifyOutputIndexVariable`, `imgFindClassifyOutputXVariable`, `imgFindClassifyOutputYVariable`, `imgFindClassifyOutputStateVariable`, `imgFindClassifyOutputFoundVariable`, `imgFindClassifyOutputConfidenceVariable`, `imgFindBooleanArrayName`.
Asset rules:
- Positive and negative assets must exist in ScriptTap or be listed in `assetRequirements[]`; JSON does not carry PNGs.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `assetName`, `multiAsset`, `assetNames`, `useNegativeAssets`, `negativeAssetNames`, `negativeConfidencePercent`, `imgFindOutputMode`, `imgFindAssetLabel`, `imgFindAssetLabels`, `imgFindClassifyOutputStateVariable`, `imgFindClassifyOutputIndexVariable`, `imgFindClassifyOutputFoundVariable`, `imgFindClassifyOutputXVariable`, `imgFindClassifyOutputYVariable`, `imgFindClassifyOutputConfidenceVariable`, `imgFindClassifyUnknownMode`, `imgFindClassifyAmbiguousMode`, `imgFindBooleanArrayName`, `left`, `top`, `right`, `bottom`, `leftValue`, `topValue`, `rightValue`, `bottomValue`, `tolerance`, `confidencePercent`, `findAll`, `setVariables`, `returnXY`, `clickIfFound`, `clickTargetCenter`, `clickTargetXValue`, `clickTargetYValue`, `variableName`, `xVariableName`, `yVariableName`, `findFirstRightToLeft`, `findFirstBottomToTop`.
Common mistakes:
- Do not invent an asset as if it exists. Name the needed asset, mark the command incomplete, and add an asset requirement.

Function: SmartTap
Command type: `smart_tap`
Category: Vision
Purpose: Watches an area for selected saved images and taps according to trigger rules.
Required fields:
- `smartTapAssets[]` with enabled positive asset rows.
- Area: `left`, `top`, `right`, `bottom` or matching value fields.
Optional fields:
- `smartTapTriggerMode`, `smartTapTapMode`, `smartTapTapX`, `smartTapTapY`, `smartTapUseNegativeAssets`, `smartTapNegativeAssetNames`, `confidencePercent`, `tolerance`.
Allowed enum values:
- `smartTapTriggerMode`: `switch_only`, `first_seen`, `every_change`, `every_match`.
- `smartTapTapMode`: `matched_center`, `fixed`.
Output variable fields:
- `smartTapOutputChangedVariable` Boolean, `smartTapOutputXVariable` Integer, `smartTapOutputYVariable` Integer.
Asset rules:
- Requires existing positive assets or asset requirements. Negative assets apply only when `smartTapUseNegativeAssets=true`.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `smartTapAssets`, `smartTapTriggerMode`, `smartTapTapMode`, `smartTapTapX`, `smartTapTapY`, `smartTapUseNegativeAssets`, `smartTapNegativeAssetNames`, `smartTapOutputChangedVariable`, `smartTapOutputXVariable`, `smartTapOutputYVariable`, `left`, `top`, `right`, `bottom`, `leftValue`, `topValue`, `rightValue`, `bottomValue`, `confidencePercent`, `tolerance`.
Common mistakes:
- SmartTap needs a real area and enabled assets. A blank asset list is incomplete.

Function: PixelFind
Command type: `pixel_find`
Category: Vision
Purpose: Finds one or more colors on screen, then optionally taps or writes variables.
Required fields:
- `pixelColors[]`.
- Area: `left`, `top`, `right`, `bottom` or matching value fields.
- Outcome: `clickIfFound=true` or `setVariables=true` with output fields.
Optional fields:
- `findAll`, `findFirstRightToLeft`, `findFirstBottomToTop`, `pixelIgnoreRadius`, `pixelFindMidpoints`, `pixelFindUseConfidence`, `confidencePercent`, `tolerance`, `returnXY`, `clickTargetCenter`, `clickTargetXValue`, `clickTargetYValue`, `imgFindOutputMode`, `imgFindClassifyOutputIndexVariable`.
Allowed enum values:
- `imgFindOutputMode`: `standard`, `classify`, `boolean_array`.
Output variable fields:
- `variableName` Boolean or Boolean array depending on mode, `xVariableName` and `yVariableName` Integer outputs or arrays, `imgFindClassifyOutputIndexVariable` Integer array.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `variableValue`, `variableName`, `xVariableName`, `yVariableName`, `left`, `top`, `right`, `bottom`, `leftValue`, `topValue`, `rightValue`, `bottomValue`, `tolerance`, `confidencePercent`, `findAll`, `setVariables`, `clickIfFound`, `pixelIgnoreRadius`, `pixelFindMidpoints`, `pixelFindUseConfidence`, `pixelColors`, `imgFindOutputMode`, `imgFindClassifyOutputIndexVariable`, `findFirstRightToLeft`, `findFirstBottomToTop`, `returnXY`, `clickTargetCenter`, `clickTargetXValue`, `clickTargetYValue`.
Common mistakes:
- `pixelFindUseConfidence=false` means exact color matching. Confidence is RGB tolerance math, not image similarity.

Function: GetPixelColor
Command type: `get_pixel_color`
Category: Vision
Purpose: Reads one screen pixel and stores its hex color.
Required fields:
- `x`, `y`, `variableName`.
Optional fields:
- Common fields only.
Output variable fields:
- `variableName` Hex output.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `x`, `y`, `variableName`.
Flow/block pairing rules:
- ScriptTap may place `pixel_color_result` child rows under this command.
Common mistakes:
- Default `0,0` is usually a fill-later placeholder unless the user explicitly requested that point.

Function: GetPixelColor Result
Command type: `pixel_color_result`
Category: Vision
Purpose: Child result row for a GetPixelColor command.
Required fields:
- `variableValue`.
Optional fields:
- `variableName`.
Output variable fields:
- Optional `variableName` Hex output when set.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `variableName`, `variableValue`.
Flow/block pairing rules:
- Usually belongs directly under a `get_pixel_color` row. Do not use as a standalone color reader.
Common mistakes:
- Use `get_pixel_color` for the actual screen read.

Function: Visual Trigger
Command type: `visual_trigger`
Category: Vision
Purpose: Waits for screen conditions and taps when the combine rule passes.
Required fields:
- `visualTriggerSlots[]`.
- Tap target: `visualTapX` and `visualTapY`, or supported action mode targeting a trigger slot.
Optional fields:
- Line/color fields, pointer asset fields, ROI fields, stable/timeout/cooldown/tap delay fields, combine/action/fire modes, and value-coordinate fields.
Allowed enum values:
- `visualTriggerMode`: `color_line`.
- `visualLineColorMode`: `each_frame`, `once_on_start`.
- `visualPointerMode`: `asset_tip`.
- `visualTriggerRelation`: `tip_over_target_color`.
- `visualFireMode`: `first_fire_then_complete`.
- `visualActionMode`: `tap_fixed`, `tap_trigger_slot_1`.
- `visualTriggerCombineMode`: `any`, `all`, `exactly_one`.
- Slot `visualSlotMode`: `pixel_line`, `asset`.
- Slot `visualLineOrientation`: `vertical`, `horizontal`.
Output variable fields: none.
Asset rules:
- Pointer/asset slot references require existing assets or asset requirements.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `visualTriggerMode`, `visualLineStartX`, `visualLineStartY`, `visualLineEndX`, `visualLineEndY`, `visualLineSampleCount`, `visualLineHitRadiusPx`, `visualLineColorMode`, `visualTargetColorHex`, `visualTargetColorTolerance`, `visualPointerMode`, `visualPointerAssetName`, `visualPointerConfidence`, `visualPointerTolerance`, `visualPointerTipOffsetX`, `visualPointerTipOffsetY`, `visualPointerRoiLeft`, `visualPointerRoiTop`, `visualPointerRoiRight`, `visualPointerRoiBottom`, `visualTriggerRelation`, `visualStableFrames`, `visualTimeoutMs`, `visualCooldownMs`, `visualFireMode`, `visualActionMode`, `visualTapX`, `visualTapY`, `visualTapDelayMs`, `visualTriggerCombineMode`, `visualTriggerSlots`, `visualLineStartXValue`, `visualLineStartYValue`, `visualLineEndXValue`, `visualLineEndYValue`.
Common mistakes:
- Visual Trigger is not globally blocking by itself. Wrap it in Exclusive only when other runtime branches must wait.

Function: Screenshot
Command type: `screenshot`
Category: Debug
Purpose: Captures the current runtime screen as-is into Recent Screenshots.
Required fields:
- None beyond common command fields.
Optional fields:
- `screenshotUseArea`, area integer fields, and area value fields.
Output variable fields:
- Creates a Recent Screenshots PNG in the app, not a JSON value.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `screenshotUseArea`, `left`, `top`, `right`, `bottom`, `leftValue`, `topValue`, `rightValue`, `bottomValue`.
Common mistakes:
- Screenshot requires screen-share permission at runtime and does not hide ScriptTap overlays.

Function: SetVariable
Command type: `set_variable`
Category: Variables
Purpose: Creates or changes a typed variable.
Required fields:
- `setVariableMode`: `single` or `array`.
- `variableType`: `integer`, `boolean`, `hex`, `string`, or `time`.
- Single mode: `variableName`, `variableValue`.
- Array mode: `variableLetter`.
Optional fields:
- `variableShared`, `variableArraySize`.
Allowed enum values:
- `setVariableMode`: `single`, `array`.
- `variableType`: `integer`, `boolean`, `hex`, `string`, `time`.
Output variable fields:
- `variableName` in single mode, or generated full numbered array for `variableLetter` in array mode.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `variableName`, `variableLetter`, `variableArraySize`, `setVariableMode`, `variableType`, `variableValue`, `variableShared`.
Common mistakes:
- Do not write ranges such as `i1-i3`. Array mode takes one array letter.

Function: ModVariable
Command type: `mod_variable`
Category: Variables
Purpose: Updates a variable with basic math or an Integer expression.
Required fields:
- `modMode`.
- Basic mode: `modTargetVariableName`, `modLeftValue`, `modOperator`, `modRightValue`.
- Expression mode: `modTargetVariableName`, `modExpression`.
Optional fields:
- `modUseHex` for Basic mode.
Allowed enum values:
- `modMode`: `basic`, `expression`.
- `modOperator`: `+`, `-`, `*`, `/`.
Output variable fields:
- `modTargetVariableName` is updated in place.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `modTargetVariableName`, `modLeftValue`, `modOperator`, `modRightValue`, `modUseHex`, `modMode`, `modExpression`.
Common mistakes:
- Expression mode is Integer-only. Known non-Integer references make the command incomplete.

Function: ColorClassify
Command type: `color_classify`
Category: Advanced
Purpose: Compares one Hex variable to target colors and writes the first matching class value.
Required fields:
- `sourceVariableName`, `confidencePercent`, `outputType`, `outputVariableName`, `noMatchValue`, `targets[]`.
Optional fields:
- Common fields only.
Allowed enum values:
- `outputType`: `integer`, `string`.
Output variable fields:
- `outputVariableName` Integer or String.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `sourceVariableName`, `confidencePercent`, `outputType`, `outputVariableName`, `noMatchValue`, `targets`.
Common mistakes:
- Use after GetPixelColor. It does not read the screen itself.

Function: ArrayGet
Command type: `array_get`
Category: Advanced
Purpose: Reads one numbered array slot and writes it to a variable.
Required fields:
- `arrayLetter`, `indexValue`, `variableType`, `outputVariableName`.
Optional fields:
- `variableShared`.
Allowed enum values:
- `variableType`: `integer`, `boolean`, `hex`, `string`, `time`.
Output variable fields:
- `outputVariableName`.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `arrayLetter`, `indexValue`, `variableType`, `variableShared`, `outputVariableName`.
Common mistakes:
- `indexValue` is 1-based and accepts a whole integer or Integer variable. Valid range is 1-255.

Function: ArraySet
Command type: `array_set`
Category: Advanced
Purpose: Writes a literal or variable value into one numbered array slot.
Required fields:
- `arrayLetter`, `indexValue`, `variableType`, `valueSourceMode`.
- Literal mode: `literalValue`.
- Variable mode: `sourceVariableName`.
Optional fields:
- `variableShared`.
Allowed enum values:
- `valueSourceMode`: `literal`, `variable`.
- `variableType`: `integer`, `boolean`, `hex`, `string`, `time`.
Output variable fields:
- Writes `arrayLetter[indexValue]`.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `arrayLetter`, `indexValue`, `variableType`, `variableShared`, `valueSourceMode`, `literalValue`, `sourceVariableName`.
Common mistakes:
- Use `array_set` for new array writes. Do not use retired `set_integer_array`.

Function: ForEachIndex
Command type: `for_each_index`
Category: Advanced
Purpose: Runs a block once per integer index value.
Required fields:
- `indexVariableName`, `startValue`, `endValue`, `stepValue`, and matching `end_for_each_index`.
Optional fields:
- `loopDelayMs`, `forEachUseStopVariable`, `stopVariableName`.
Output variable fields:
- `indexVariableName` Integer.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `indexVariableName`, `startValue`, `endValue`, `stepValue`, `loopDelayMs`, `forEachUseStopVariable`, `stopVariableName`.
Flow/block pairing rules:
- Must be followed by a matching `end_for_each_index`.
Common mistakes:
- Step cannot be 0. ScriptTap uses 1 if 0 is supplied.

Function: End ForEachIndex
Command type: `end_for_each_index`
Category: Advanced
Purpose: Ends the nearest ForEachIndex block.
Required fields:
- Matching `for_each_index`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Flow/block pairing rules:
- Must match an earlier `for_each_index`.
Common mistakes:
- Do not create orphan end rows.

Function: StackMoveValid
Command type: `stack_move_valid`
Category: Advanced
Purpose: Checks whether a column-stack move is legal and writes a Boolean result.
Required fields:
- `sourceColumnValue`, `destinationColumnValue`, `columnCount`, `columnHeight`, `cellArrayLetter`, `outputVariableName`.
Optional fields:
- `useFrameArray`, `frameArrayLetter`, `requireDestinationFrameMatch`, `useMoveCountOutput`, `outputMoveCountVariableName`.
Output variable fields:
- `outputVariableName` Boolean, optional `outputMoveCountVariableName` Integer.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `sourceColumnValue`, `destinationColumnValue`, `columnCount`, `columnHeight`, `cellArrayLetter`, `useFrameArray`, `frameArrayLetter`, `requireDestinationFrameMatch`, `outputVariableName`, `useMoveCountOutput`, `outputMoveCountVariableName`.
Common mistakes:
- The cell array is column-major. Column 1 row 1 is `cellArrayLetter1`.

Function: AppendTapMove
Command type: `append_tap_move`
Category: Advanced
Purpose: Appends source/destination column-center taps to X/Y arrays.
Required fields:
- `sourceColumnValue`, `destinationColumnValue`, `columnCenters[]`, `xArrayLetter`, `yArrayLetter`, `tapCountVariableName`, `maxTapsValue`.
Optional fields:
- `columnCenterMode`, `useMoveCountOutput`, `moveCountVariableName`.
Allowed enum values:
- `columnCenterMode`: `manual`.
Output variable fields:
- Writes `xArrayLetter[]`, `yArrayLetter[]`, `tapCountVariableName`, and optionally `moveCountVariableName`.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `sourceColumnValue`, `destinationColumnValue`, `columnCenterMode`, `columnCenters`, `xArrayLetter`, `yArrayLetter`, `tapCountVariableName`, `useMoveCountOutput`, `moveCountVariableName`, `maxTapsValue`.
Common mistakes:
- It skips without writing if the appended taps would exceed `maxTapsValue` or 255.

Function: PromptMe
Command type: `prompt_me`
Category: Advanced
Purpose: Shows a runtime modal, waits for user input, and writes selected values to variables.
Required fields:
- `promptHeader`.
- At least one input mode: buttons, toggles, or text.
Optional fields:
- `promptUseButtons`, `promptButtons[]`, `promptUseTogglesText`, `promptUseToggles`, `promptToggles[]`, `promptUseText`, `promptTextVariableName`, `promptTextCaption`, `promptTextType`.
Allowed enum values:
- `promptTextType`: `string`, `integer`.
Output variable fields:
- Button/toggle `variableName` fields write Boolean outputs.
- `promptTextVariableName` writes String or Integer according to `promptTextType`.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `promptHeader`, `promptUseButtons`, `promptButtons`, `promptUseTogglesText`, `promptUseToggles`, `promptToggles`, `promptUseText`, `promptTextVariableName`, `promptTextCaption`, `promptTextType`.
Common mistakes:
- Buttons complete immediately only when the toggles/text section is not enabled.

Function: Text Type
Command type: `text_type`
Category: Actions
Purpose: Types literal text or the contents of a String variable.
Required fields:
- `textValue`.
Optional fields:
- `textUseVariable`, `variableName`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `textValue`, `textUseVariable`, `variableName`.
Common mistakes:
- If `textUseVariable=true`, `textValue` must be one String variable name, not literal text.

Function: Label
Command type: `label`
Category: Flow
Purpose: Marks a destination for GoTo.
Required fields:
- `labelName`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `labelName`.
Common mistakes:
- Keep label names unique inside one script.

Function: GoTo
Command type: `goto`
Category: Flow
Purpose: Jumps to a label in the same script.
Required fields:
- `labelName` matching a `label` in the same script.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `labelName`.
Common mistakes:
- GoTo cannot jump to a different script.

Function: Loop
Command type: `loop`
Category: Flow
Purpose: Starts a repeated block.
Required fields:
- Matching `end_loop`.
Optional fields:
- `loopTimes`, `loopDelayMs`, `loopInfinite`, `loopConcurrent`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `loopDelayMs`, `loopTimes`, `loopInfinite`, `loopConcurrent`.
Flow/block pairing rules:
- Add a matching `end_loop`.
- Concurrent loops run as background branches and do not globally block other branches unless they enter Exclusive.
Common mistakes:
- Do not create a loop start without its matching end row.

Function: End Loop
Command type: `end_loop`
Category: Flow
Purpose: Ends a Loop block.
Required fields:
- Matching `loop`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Common mistakes:
- Orphan End Loop rows are invalid.

Function: Break Loop
Command type: `break_loop`
Category: Flow
Purpose: Exits the current loop early.
Required fields:
- Must be inside a loop block.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Common mistakes:
- Do not place outside a `loop`/`end_loop` segment.

Function: Call Script
Command type: `call`
Category: Flow
Purpose: Runs another script from this command and then returns here.
Required fields:
- `targetMacroId`, `targetMacroName`.
Optional fields:
- `callReferenceOnly`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `targetMacroId`, `targetMacroName`, `callReferenceOnly`.
Flow/block pairing rules:
- Enabled complete calls must target a script included in the same package. Import rewrites script ids.
Common mistakes:
- Do not target a script that is not included in `scripts[]`; leave the call incomplete or disabled instead.

Function: Break Call
Command type: `break_call`
Category: Flow
Purpose: Returns out of the current called script.
Required fields:
- Must run inside a called script.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Common mistakes:
- Use only in scripts reached by Call Script.

Function: Stop Call
Command type: `stop_call`
Category: Flow
Purpose: Stops one or more direct called-script branches and descendants.
Required fields:
- `targetMacroId` and `targetMacroName`, or `targetMacroIds[]` and `targetMacroNames[]`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `targetMacroId`, `targetMacroName`, `targetMacroIds`, `targetMacroNames`.
Flow/block pairing rules:
- Targets should be direct called scripts from the current script.
Common mistakes:
- Target names are display hints; ids are the real references.

Function: Exclusive
Command type: `pause_concurrent`
Category: Flow
Purpose: Starts a global Exclusive block that blocks other runtime branches.
Required fields:
- Matching `unpause_concurrent`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Flow/block pairing rules:
- Must be paired with `unpause_concurrent`.
Common mistakes:
- Only Exclusive has cross-runtime blocking effect. Normal concurrent-loop commands do not.

Function: End Exclusive
Command type: `unpause_concurrent`
Category: Flow
Purpose: Ends an Exclusive block.
Required fields:
- Matching `pause_concurrent`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Common mistakes:
- Do not create an orphan End Exclusive row.

Function: Break Exclusive
Command type: `break_exclusive`
Category: Flow
Purpose: Exits the current Exclusive block.
Required fields:
- Must be inside `pause_concurrent`/`unpause_concurrent`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Common mistakes:
- Use only inside an active Exclusive segment.

Function: IF(OR)
Command type: `or`
Category: Flow
Purpose: Starts an IF block that runs when any condition row passes.
Required fields:
- `conditions[]` and matching `end_or`.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Allowed enum values:
- Condition `variableComparator`: `=`, `<>`, `>`, `>=`, `<`, `<=`, `between`, `contains`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `variableName`, `variableComparator`, `variableValue`, `conditions`, `confidencePercent`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Flow/block pairing rules:
- Must be closed by `end_or`; optional `else` goes before `end_or`.
Common mistakes:
- Use `conditions[]` for normal comparisons. Do not use legacy `if`.

Function: IF(AND)
Command type: `and`
Category: Flow
Purpose: Starts an IF block that runs when every condition row passes.
Required fields:
- `conditions[]` and matching `end_and`.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Allowed enum values:
- Condition `variableComparator`: `=`, `<>`, `>`, `>=`, `<`, `<=`, `between`, `contains`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `variableName`, `variableComparator`, `variableValue`, `conditions`, `confidencePercent`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Flow/block pairing rules:
- Must be closed by `end_and`; optional `else` goes before `end_and`.
Common mistakes:
- `between` needs both values; missing bounds make the IF incomplete.

Function: IF(XOR)
Command type: `xor`
Category: Flow
Purpose: Starts an IF block that runs when exactly one condition row passes.
Required fields:
- `conditions[]` and matching `end_xor`.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Allowed enum values:
- Condition `variableComparator`: `=`, `<>`, `>`, `>=`, `<`, `<=`, `between`, `contains`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `variableName`, `variableComparator`, `variableValue`, `conditions`, `confidencePercent`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Flow/block pairing rules:
- Must be closed by `end_xor`; optional `else` goes before `end_xor`.
Common mistakes:
- XOR means exactly one condition is true, not one-or-more.

Function: IF(RGB Confidence)
Command type: `rgb_confidence`
Category: Flow
Purpose: Starts an IF block comparing a Hex variable to a target color using confidence percent.
Required fields:
- `variableName` Hex variable, `variableValue` target hex color, `confidencePercent`, and matching `end_or`.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `variableName`, `variableValue`, `confidencePercent`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Flow/block pairing rules:
- Runtime uses `end_or` as the matching end row.
Common mistakes:
- RGB confidence is deterministic color matching, not AI image similarity.

Function: ELSE
Command type: `else`
Category: Flow
Purpose: Starts the else branch for the nearest IF block.
Required fields:
- Enclosing IF block.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Flow/block pairing rules:
- At most one ELSE per IF group; it must appear before that IF end row.
Common mistakes:
- Do not put ELSE outside an IF block.

Function: End IF(AND)
Command type: `end_and`
Category: Flow
Purpose: Ends an IF(AND) block.
Required fields:
- Matching `and`.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Common mistakes:
- Match end type to start type.

Function: End IF(OR)
Command type: `end_or`
Category: Flow
Purpose: Ends an IF(OR) block or IF(RGB Confidence) block.
Required fields:
- Matching `or` or `rgb_confidence`.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Common mistakes:
- Use `end_or` for RGB Confidence too.

Function: End IF(XOR)
Command type: `end_xor`
Category: Flow
Purpose: Ends an IF(XOR) block.
Required fields:
- Matching `xor`.
Optional fields:
- Compatibility-only app-created fields: `babyIfAttached`, `babyIfParentId`, `babyIfSource`. Do not generate these in new AI drafts.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `babyIfAttached`, `babyIfParentId`, `babyIfSource`.
Common mistakes:
- Match end type to start type.

Function: Open App
Command type: `device_open_app`
Category: Device
Purpose: Opens a selected launchable Android app.
Required fields:
- `devicePackageName`.
Optional fields:
- `deviceAppLabel`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `devicePackageName`, `deviceAppLabel`.
Common mistakes:
- If the package name is unknown, leave the command incomplete and tell the user to select the app inside ScriptTap.

Function: Settings
Command type: `device_settings`
Category: Device
Purpose: Preferred Device command for Wi-Fi, Bluetooth, Do Not Disturb, Rotation, Airplane, Brightness, and Volume settings.
Required fields:
- At least one enabled child setting.
Optional fields:
- `deviceSettings*Enabled` booleans, `deviceSettings*State` on/off values, brightness percent/adaptive, volume percents/apply streams.
Allowed enum values:
- Toggle states: `on`, `off`.
- Volume streams inside apply/percent rows: `call`, `media`, `system`, `alert`, `message`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `deviceSettingsWifiEnabled`, `deviceSettingsWifiState`, `deviceSettingsBluetoothEnabled`, `deviceSettingsBluetoothState`, `deviceSettingsDndEnabled`, `deviceSettingsDndState`, `deviceSettingsRotationEnabled`, `deviceSettingsRotationState`, `deviceSettingsAirplaneEnabled`, `deviceSettingsAirplaneState`, `deviceSettingsBrightnessEnabled`, `deviceSettingsBrightnessPercent`, `deviceSettingsBrightnessAdaptive`, `deviceSettingsVolumeEnabled`, `deviceSettingsVolumePercents`, `deviceSettingsVolumeApplyStreams`.
Common mistakes:
- Use `device_settings` for new setting changes. Legacy direct Device rows are still accepted but not preferred.

Function: Brightness
Command type: `device_brightness`
Category: Device
Purpose: Legacy direct row for changing brightness or adaptive brightness.
Required fields:
- `devicePercent` or `deviceBrightnessAdaptive`.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `devicePercent`, `deviceBrightnessAdaptive`.
Common mistakes:
- Prefer `device_settings` for new scripts.

Function: Volume
Command type: `device_volume`
Category: Device
Purpose: Legacy direct row for changing a selected volume stream.
Required fields:
- `deviceVolumeStream`, `devicePercent`.
Optional fields:
- `deviceVolumePercents`.
Allowed enum values:
- `deviceVolumeStream`: `call`, `media`, `system`, `alert`, `message`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `devicePercent`, `deviceVolumeStream`, `deviceVolumePercents`.
Common mistakes:
- Prefer `device_settings` for new scripts.

Function: Wi-Fi
Command type: `device_wifi`
Category: Device
Purpose: Legacy direct row for Wi-Fi state.
Required fields:
- `deviceToggleState`.
Optional fields:
- Common fields only.
Allowed enum values:
- `deviceToggleState`: `on`, `off`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `deviceToggleState`.
Common mistakes:
- Android may require user-driven settings access. Prefer `device_settings` for new scripts.

Function: Bluetooth
Command type: `device_bluetooth`
Category: Device
Purpose: Legacy direct row for Bluetooth state.
Required fields:
- `deviceToggleState`.
Optional fields:
- Common fields only.
Allowed enum values:
- `deviceToggleState`: `on`, `off`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `deviceToggleState`.
Common mistakes:
- Android may require user-driven settings access. Prefer `device_settings` for new scripts.

Function: Do Not Disturb
Command type: `device_do_not_disturb`
Category: Device
Purpose: Legacy direct row for Do Not Disturb state.
Required fields:
- `deviceToggleState`.
Optional fields:
- `deviceDndMode`.
Allowed enum values:
- `deviceToggleState`: `on`, `off`.
- `deviceDndMode`: `priority_only`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `deviceToggleState`, `deviceDndMode`.
Common mistakes:
- Android may require notification policy access. Prefer `device_settings` for new scripts.

Function: Rotation Lock
Command type: `device_rotation`
Category: Device
Purpose: Legacy direct row for rotation state.
Required fields:
- `deviceToggleState`.
Optional fields:
- Common fields only.
Allowed enum values:
- `deviceToggleState`: `on`, `off`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `deviceToggleState`.
Common mistakes:
- Prefer `device_settings` for new scripts.

Function: Airplane Mode
Command type: `device_airplane`
Category: Device
Purpose: Legacy direct row for airplane mode state.
Required fields:
- `deviceToggleState`.
Optional fields:
- Common fields only.
Allowed enum values:
- `deviceToggleState`: `on`, `off`.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`, `deviceToggleState`.
Common mistakes:
- Android may require user-driven settings access. Prefer `device_settings` for new scripts.

Function: Divider
Command type: `divider`
Category: Utility
Purpose: Visual separator in the script.
Required fields:
- None beyond common command fields.
Optional fields:
- Common fields only.
Output variable fields: none.
Accepted public JSON fields:
- `type`, `id`, `nickname`, `disabled`, `validationState`.
Common mistakes:
- Divider has no runtime action.

Legacy and retired compatibility: do not generate
================================================

Command type: `set_integer_array`
Status: Retired.
Rule: Do not generate. Old saved rows may load as removed/incomplete. Use `array_set` for new array writes.

Command type: `if`
Status: Accepted legacy alias.
Rule: Do not generate. Use `or`, `and`, `xor`, or `rgb_confidence`. ScriptTap normalizes legacy `if` to IF(OR).

Command type: `end_if`
Status: Accepted legacy alias.
Rule: Do not generate. Use `end_or`, `end_and`, or `end_xor`. ScriptTap normalizes legacy `end_if` to End IF(OR).