v1.2.0-beta1 - The New Paradigm, and "On Hold" activation options

[mpaperno]

Changes since v1.1.0.1

This version bring a number of fundamental changes, all of which hopefully make the system more flexible overall.
I've preserved backwards compatibility with actions/connectors from the previous versions, except in the case of the "One-Time"
action (details below). I encourage everyone to update to the new versions of the actions/connectors, but please
do let me know if you find "regression" issues which break existing actions/connectors. An update to the new version is meant to be
as seamless as possible.

Plugin Core

• New paradigm decouples "Script" (Expression/File/Module) instances from Engine instances and from Touch Portal States:
  • Creating a Touch Portal State for each named Script instance is now optional.
    Consequently, the "State Name" field for each action has been renamed to "Instance Name."
  • Private Engine instances can now be independent from Script instances; they become their own named entities which can be re-used.
  • Script instances can be run in any existing Private Engine instances (or create their own, or run in Shared engine, as before).
  • Engine instances now "own" the system thread they (and all associated Scripts) run in.
• Added support for using Actions in "On Hold" Touch Portal button setup, with multiple behavior options:
  • Activation options: On Press and/or On Release, Press and Repeat, Repeat After Delay.
  • Repeat delay and rate (interval) are controllable at both global default and per-instance levels.
  • Current repeat delay, rate, and maximum number of repeats can be set via instance properties.
• Script instance properties and methods are now available in the JavaScript environment, allowing extended code-level functionality and customization (details below).
• Scripts can now keep data in persistent storage which is saved and restored at plugin startup (for example to preserve state/settings between sessions).
• Any Script Instance can now be set to "temporary persistence" and deleted automatically after a delay. This removes the need for a separate "one-time" action.
• Added a plugin Setting to load/run a script file at plugin startup.
• Added stack trace logging for unhandled script exceptions.
• Added command-line switch to specify the Touch Portal Plugin ID to use in all communications (for advanced usage with custom entry.tp configuration).
• Fixed/removed automatic replacement of spaces with underscores in Touch Portal State names/IDs.
• Fixed all saved instances being removed if plugin is started w/out available Touch Portal host.
• The "Shared" Engine instance now runs in its own system thread so as not to impact core plugin functions.
• The Touch Portal network client (responsible for core communications) has also been moved to its own thread.
• Miscellaneous optimizations, cleanups, and stability improvements.

Changes to Actions/Connectors

• Added "Create State" option to each of the primary Script actions (Expression/File/Module). This is now also where the State's default value type is set.
• Added "Instance Persistence" option which controls if a Script instance only exists for the current session, is saved at shutdown and loaded at startup, or is temporary (replaces "One-Time" action).
  • REMOVED: the "Anonymous (One-Time) Script" action (redundant with the more flexible new system).
    Unfortunately, due to internal changes, backwards compatibility could not be preserved in this one case.
• Script Instances can now use any existing Engine instance (eg. created by another Script) in addition to Shared and Private engine types as previously;
  • Selecting the "Private" choice effectively creates a new private Engine with the same name as the Script. This reproduces the previous behavior.
• Added "On Hold" option to each Script action type which controls when exactly Script evaluation happens if an Action is used in "On Hold" button setup tab.
• The "Update Existing Instance" action/connector:
  • Now uses a choice list to select an existing Script instance to update (instead of having to type one in).
  • Can run an expression in a "Shared Default" instance which evaluates in the Shared engine scope but independent of any specific named Script instance (and does not create a Touch Portal State).
• Renamed "Plugin Actions" to "Instance Control Actions" and:
  • Resets are now performed on named Engine instances, not Script Instances (this matters if multiple scripts share the same engine).
  • Added option to Delete Engine Instance(s).
  • Added options to Save, Load, and Remove Script Instance data to/from persistent storage.
  • DEPRECATED: "Set State Value" option;
    Existing instances will continue to work for now but cannot be edited; Support will be fully removed in the next major version;
• Added "Set Held Action Repeat Rate/Delay" action & connector to set/adjust repeat rate/delay at both global default and instance-specific levels.

New States/Event

• Added "Plugin running state" (stopped/starting/started) Touch Portal State and Event;
• Added "Default held action Repeat Delay" and "Default held action Repeat Rate" States;

Documentation

• Updated main Plugin Documentation pages to reflect changes in actions/connectors and features
  (including the new overall relationship between Script instances, Engine instances, and Touch Portal States).
• Added Plugin -> "Quick Start" page.
• Added Plugin -> "Settings, States and Events" page.
• Added new JS Library Reference category for Plugin API objects (DSE and DynamicScript).
• Updated JavaScript Reference pages for all additions and changes.

JavaScript Library

Please see the full CHANGELOG on the DSE site,
which has better formatting and links to related documentation.

---

The plugin is fully documented at https://dse.tpp.max.paperno.us/

Please report any issues or let me know if you have any questions or requests here on GitHub or over on my Discord server.

All feedback and input is always welcome! I'd love to know how you're using DSEP!

---

This discussion was created from the release v1.2.0-beta1 - The New Paradigm, and "On Hold" activation options.