Visual Script Builder for Remote Control Plugin

[kutaibaa-akraa]

Feature: Visual Script Builder for Remote Control Plugin

Author: @kutaibaa-akraa
Date: 2026-04-21
Type: New Feature / UI Enhancement
Stellarium: v26.1
Status: Partially ready - not released

---

Overview

This feature introduces a Visual Script Builder to the Remote Control Plugin, replacing the need to manually write .ssc script files. The interface provides a drag-and-drop canvas where users can construct Stellarium scripts by selecting from a library of available actions, configuring parameters through intuitive controls, and generating executable code in real-time.

The Script Builder bridges the gap between the existing "Actions" panel (which executes single commands) and the "Scripts" panel (which runs pre-written files). It enables users to create, edit, save, and share complex scripts without writing a single line of code.

---

Key Features

Phase 1-4 Complete (Current State)

Feature	Description
Dual Action Library	Loads both StelActions (from /api/stelaction/list) and Scripting API functions (manually defined with parameters)
Parameter Configuration	Each action displays editable parameters via sliders, checkboxes, color pickers, and text inputs
Drag & Drop Reordering	Actions can be reordered via drag-and-drop or up/down buttons
Real-time Code Preview	Generated .ssc code updates instantly as actions are added, removed, or modified
Auto-Wait Insertion	Intelligently inserts core.wait() after movement/zoom actions with configurable duration
Smart Wait Duration	Automatically uses the action's own duration parameter (e.g., duration: 3.0 → core.wait(3.5))
Templates	Pre-built templates for common tasks (Reset View, Moon/Venus Tour, Constellation Tour, Quick Cleanup)
Variables Panel	Define and manage script variables (string, number, boolean, array)
Loop Actions	Create for, for-in, and while loops with nested child actions
Condition Actions	Create if/else blocks with separate "then" and "else" action lists
Custom Code Injection	Insert raw JavaScript code directly into the script
Children Editor	Edit actions nested inside loops and conditions
Save/Load Scripts	Save generated code or load existing .ssc files
Export/Import JSON	Export script structure as JSON for backup, sharing, or version control
Direct Execution	Run the constructed script directly in Stellarium via API

In Development (Phase 5 - Planned)

Feature	Status
Full Script Parsing	Parse existing .ssc files into editable actions (currently partial)
Function Support	Define and call custom JavaScript functions
Live Preview Sync	Update Stellarium view in real-time while editing parameters
Advanced Search/Filter	Filter action library by keyword, category, or usage frequency

---

Technical Implementation

New Files Created

File	Description
webroot/js/ui/scriptbuilder/scriptbuilder.js	Main module (1400+ lines) - UI rendering, action management, code generation
webroot/js/ui/scriptbuilder/scriptbuilder-actions.js	Database of Scripting API functions with parameter definitions
webroot/js/ui/scriptbuilder/scriptbuilder-parser.js	Parses .ssc files into action objects (supports variables, loops, conditions, 30+ command patterns)
webroot/js/ui/scriptbuilder/scriptbuilder-templates.js	Pre-built script templates
webroot/scriptbuilder.css	Comprehensive styling for builder interface

Modified Files

File	Changes
webroot/index.html	Added Script Builder section to tab_actions
webroot/tablet7in.html	Responsive adjustments for tablet layout
webroot/js/mainui.js	Initialization hook for Script Builder module
webroot/js/main.js	Module loading configuration

Key API Endpoints Used

Endpoint	Method	Purpose
/api/stelaction/list	GET	Load all available StelActions with categories
/api/stelaction/do	POST	Execute a StelAction directly
/api/scripts/list	GET	Retrieve list of available .ssc files
/api/scripts/info	GET	Retrieve script metadata and content (HTML format)
/api/scripts/stop	POST	Stop currently running script
/api/scripts/status	POST	Sync currently script running/stop state (e.g runningScriptId "" & scriptIsRunning

---

Data Flow Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           SCRIPT BUILDER ARCHITECTURE                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────────┐  │
│  │  StelAction API  │    │  Scripting API   │    │  User Variables      │  │
│  │  /stelaction/list│    │  (Actions DB)    │    │  (string/number/     │  │
│  │                  │    │                  │    │   boolean/array)     │  │
│  └────────┬─────────┘    └────────┬─────────┘    └──────────┬───────────┘  │
│           │                       │                          │              │
│           └───────────────────────┼──────────────────────────┘              │
│                                   ▼                                         │
│                    ┌──────────────────────────────┐                         │
│                    │       Script Actions Array    │                         │
│                    │  (scripting/stelaction/loop/ │                         │
│                    │   condition/custom)          │                         │
│                    └──────────────┬───────────────┘                         │
│                                   │                                         │
│           ┌───────────────────────┼───────────────────────┐                 │
│           ▼                       ▼                       ▼                 │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐         │
│  │  Canvas Render  │    │  Code Generator │    │  Script Parser  │         │
│  │  (Drag & Drop)  │    │  (.ssc output)  │    │  (.ssc → actions)│         │
│  └─────────────────┘    └────────┬────────┘    └─────────────────┘         │
│                                  │                                          │
│                                  ▼                                          │
│                    ┌──────────────────────────────┐                         │
│                    │  /api/scripts/Run (Run)             │                         │
│                    └──────────────────────────────┘                         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────────┘

---

Current Capabilities Demonstrated

Successfully Parsed Actions (30+ Patterns)

The parser currently recognizes and converts the following command patterns:

• core.clear("state") → Clear View action
• core.wait(seconds) → Wait action
• core.moveToAltAzi(alt, azi, duration) → Move to Alt/Azimuth action
• core.setDate("date", "spec") → Set Date action
• core.setTimeRate(rate) → Set Time Rate action
• StelMovementMgr.zoomTo(fov, duration) → Zoom To FOV action
• StelMovementMgr.autoZoomIn(duration) → Auto Zoom In action
• StelMovementMgr.setFlagTracking(bool) → Set Tracking action
• LandscapeMgr.setFlagLandscape(bool) → Show Landscape action
• ConstellationMgr.setLines(bool) → Show Constellation Lines action
• StarMgr.setStars(bool) → Show Stars action
• SolarSystem.setPlanets(bool) → Show Planets action
• ...and 20+ more patterns

Example: Parsing analemma.ssc

When loading the built-in analemma.ssc script, the parser successfully extracts:

• Variables detected: JD, color, label, labelWeek, labelWinter, labelSummer, labelFinal
• Actions recognized: core.goHome(), core.setGuiVisible(), core.setTimeRate(), core.clear(), LabelMgr.labelScreen(), StelMovementMgr.autoZoomIn(), StelMovementMgr.zoomTo(), GridLinesMgr.setFlagAzimuthalGrid(), core.wait(), and more
• Loop structure: The for (i=0; i<53; i++) loop is correctly identified as a Loop action
• Condition structure: The if (week==1) and if (week==26) conditions are correctly parsed

Result: The script is reconstructed in the canvas as 25+ editable actions, ready for modification.

---

Challenges Encountered

1. Script Content Retrieval

Problem: The Remote Control API does not provide a direct endpoint to retrieve the raw content of .ssc files. Endpoints tested:

Endpoint	Result
/api/scripts/get	400 Bad Request
/api/scripts/content	400 Bad Request
/api/scripts/read	400 Bad Request
/scripts/bennett.ssc (direct path)	404 Not Found
/api/scripts/info	Returns HTML-wrapped metadata, not raw code

Workaround: Currently using /api/scripts/info with HTML stripping to extract code content. A proper /api/scripts/raw endpoint would be beneficial.

2. StelAction to Script Command Mapping

Problem: StelActions (from /api/stelaction/list) do not have direct script command equivalents. For example, actionShow_Constellation_Lines executes via API but cannot be directly written as a script command.

Current Solution: Maintain a manual mapping of ~60 common StelActions to their script equivalents (e.g., actionShow_Constellation_Lines → ConstellationMgr.setLines(true)). Unknown actions display as comments in generated code.

Ideal Solution: Stellarium could expose a mapping API or include script syntax in the StelAction metadata.

3. Parser Limitations

Current Limitations:

• Does not parse multi-line function definitions with complex bodies
• Limited support for nested ternary operators
• Cannot parse inline object definitions (e.g., {x: 10, y: 20})
• Custom user functions defined in scripts are not converted to reusable actions

Planned Improvements:

• Enhance regex patterns for more complex JavaScript syntax
• Add AST-based parsing for robust code analysis
• Support for importing user-defined functions as custom action templates

4. Auto-Wait Timing Accuracy

Problem: Different movement actions require different wait durations. The current "smart wait" uses the action's duration parameter but may not account for acceleration/deceleration curves.

Observation: From testing, duration + 0.5 seconds works reliably for most cases, but very short durations (< 1s) may need proportionally longer waits.

---

Proposed Enhancements (Discussion Points)

1. Native Script Content API

Suggestion: Add a new endpoint to the Remote Control API:

GET /api/scripts/content?id=scriptname.ssc

This would return the raw, unprocessed content of the script file with proper MIME type text/plain. Currently, the lack of this endpoint requires HTML scraping from /api/scripts/info.

2. StelAction Metadata Extension

Suggestion: Extend the StelAction system to include script syntax information:

{
    "id": "actionShow_Constellation_Lines",
    "text": "Constellation lines",
    "isCheckable": true,
    "scriptSyntax": "ConstellationMgr.setLines(true)"
}

This would eliminate the need for manual mapping and ensure all actions can be properly exported to .ssc files.

3. Script Execution State Feedback

Suggestion: Add WebSocket or Server-Sent Events support to notify the Remote Control when a script completes execution. Currently, the UI relies on timeout-based estimates, which can be inaccurate for scripts with variable durations.

4. Collaborative Script Editing

Suggestion: Consider adding real-time collaboration features using the existing multi-client architecture. Multiple users could edit the same script simultaneously, with changes synchronized across all connected Remote Control instances.

5. Script Versioning / History

Suggestion: Integrate with Stellarium's existing script management to support version history or undo/redo across sessions. This would be particularly valuable for educational and presentation contexts.

---

Files Modified/Created Summary

File	Type	Description
webroot/js/ui/scriptbuilder/scriptbuilder.js	New	Main builder module (1400+ lines)
webroot/js/ui/scriptbuilder/scriptbuilder-actions.js	New	Scripting API action definitions
webroot/js/ui/scriptbuilder/scriptbuilder-parser.js	New	.ssc file parser
webroot/js/ui/scriptbuilder/scriptbuilder-templates.js	New	Pre-built script templates
webroot/scriptbuilder.css	New	Builder component styles
webroot/index.html	Modified	Added Script Builder section
webroot/tablet7in.html	Modified	Responsive tablet layout
webroot/js/mainui.js	Modified	Module initialization

---

Next Steps

I am actively working on the following improvements:

1. Enhanced Parser - Adding support for function definitions and complex expressions
2. Live Preview - Real-time Stellarium updates while editing parameters
3. Better StelAction Integration - Automatic discovery of script syntax where possible
4. Performance Optimization - Reducing initial load time for the action library

---

Figure 1: Script Builder interface showing the dual-panel layout (Actions Library left, Script Canvas right) with generated code preview at bottom.

Figure 2: Edit Modal for configuring action parameters with appropriate input controls (sliders for numbers, checkboxes for booleans, color pickers).

Figure 3: Variables panel showing user-defined variables with type indicators and delete functionality.

Figure 4: Children Editor for adding actions inside loops and condition blocks.

---

[gzotti]

OMG! I think ALL script authors have dreamed of this for the last 15 years.
When I develop scripts, I also write comments to know what I did and why, 3 years later. Is that possible with the drag&drop action editor? Also, in my brief flyover I did not see the script header discussed, where e.g. hotkey action or script description can be given.

[kutaibaa-akraa]

Is that possible with the drag&drop action editor? Also, in my brief flyover I did not see the script header discussed, where e.g. hotkey action or script description can be given.

---

I really appreciate the suggestions regarding comments and script headers—these are exactly the kinds of details that make scripts maintainable in the long term. I'm currently working on implementing both features (a dedicated "Comment" action and a "Settings" panel for script metadata) and will include them in the next iteration.

Right now, I'm still in the intensive testing and refinement phase—making sure everything works reliably across different scenarios before finalizing the code. Once I'm fully confident in the implementation and all edge cases are handled, I'll prepare a proper Pull Request for review.

---