Add Avalonia desktop command line parameter --script to load & run a Lua script when app is started

Author: highbyte

doc/SCRIPTING-TEMP-TODO.md

@@ -1,4 +1,17 @@
 Scripting:
-- How to send input (keyboard and joystick) in addition to change memory locations? 
-- Specific c64 Lua namespace with keyboard and joystick input? 
-- How to make system-specific Scripting/Lua handlers without hard-coding in scripting engine? Should there a scripting abstraction for sending keyboard and joystick input? 
+- Expose more C64-specific functions to Lua scripting:
+  - Has basic started (check flag or event or both?)
+  - Copy current Basic source code to a string variable
+  - Write a string to Basic
+  - Load and start a .d64 image
+  - Set C64 config:
+    - Check if config is valid, get list of validation errors.
+    - If running on desktop:
+      - Get/set C64 ROM directory.
+      - Get/set C64 ROM files.
+
+Scripting on Browser
+- Load & run a Lua script supplied in query parameter as a URL to download from? 
+- C64 exposed functions if running on browser:
+    - Auto-download C64 ROMs
+    - MAYBE:  Get or set C64 ROMs from browser local storage

resources/scripts/shared/example_c64_cli_demo.lua

@@ -0,0 +1,103 @@
+-- example_c64_cli_demo.lua
+--
+-- Demonstrates end-to-end CLI-driven automation for the C64 emulator.
+--
+-- Launch command (from the app output directory):
+--   ./Highbyte.DotNet6502.App.Avalonia.Desktop --script scripts/example_c64_cli_demo.lua
+--
+-- The --script path is resolved relative to the current working directory.
+-- An absolute path also works:
+--   ./Highbyte.DotNet6502.App.Avalonia.Desktop --script /path/to/example_c64_cli_demo.lua
+--
+-- The script selects the C64 system and starts the emulator itself,
+-- so no --system or --start flags are needed.
+--
+-- Sequence:
+--   1. Ensure the C64 system is selected and running
+--   2. Wait for the BASIC "READY." prompt to appear in screen RAM
+--   3. Cycle the border through all 16 C64 colors for ~2 seconds
+--   4. Restore the default border color
+--   5. Type "HELLO!" at a human-like typing speed
+
+-- ── Step 1: Ensure C64 is running ────────────────────────────────────────────
+
+if emu.selected_system() ~= "C64" then
+    log.info("[demo] Selecting C64 system...")
+    emu.select("C64")
+end
+
+if emu.state() ~= "running" then
+    log.info("[demo] Starting emulator...")
+    emu.start()
+end
+
+-- Wait until C64 is actually up and running
+while emu.state() ~= "running" or emu.selected_system() ~= "C64" do
+    emu.yield()
+end
+
+log.info("[demo] C64 is running. Waiting for BASIC READY prompt...")
+
+-- ── Step 2: Wait for BASIC "READY." in screen RAM ────────────────────────────
+-- Wait 3 seconds (wall-clock)
+local start_time = emu.time()
+while emu.time() - start_time < 3.0 do
+    emu.yield()
+end
+
+log.info("[demo] BASIC READY detected. Cycling border color for 2 seconds...")
+
+-- ── Step 3: Cycle border color (~2 seconds at C64 PAL 50 fps ≈ 100 frames) ──
+--
+-- C64 border color register: $D020 (bits 3–0, 16 colors 0–15)
+
+local BORDER_REG = 0xD020
+local border_start = emu.time()
+local color = 0
+while emu.time() - border_start < 2.0 do
+    mem.write(BORDER_REG, color)
+    color = (color + 1) % 16
+    emu.frameadvance()
+end
+
+-- ── Step 4: Restore default border (C64 default: light blue = 14) ─────────
+
+mem.write(BORDER_REG, 14)
+log.info('[demo] Border cycling done. Typing "HELLO!" ...')
+
+-- ── Step 5: Type "HELLO!" at human-like speed ────────────────────────────────
+--
+-- C64 BASIC starts in uppercase mode, so h–o produce uppercase letters on screen.
+-- '!' on C64 keyboard = lshift + 1.
+--
+-- Input injection pattern: input.key_press() must be called every frame to keep
+-- a key held (ClearScriptInput fires at the start of each frame). So we loop for
+-- hold_frames, pressing the key each iteration, then wait gap_frames with no press.
+--
+-- Timing at 50 fps (PAL C64):
+--   hold_frames = 4  →  ~80 ms per key
+--   gap_frames  = 6  →  ~120 ms between keys
+--   Total per keystroke ≈ 200 ms  →  ~5 characters/second
+
+local HOLD_FRAMES = 4
+local GAP_FRAMES  = 6
+
+local function type_key(key, with_shift)
+    for _ = 1, HOLD_FRAMES do
+        input.key_press(key)
+        if with_shift then input.key_press("lshift") end
+        emu.frameadvance()
+    end
+    for _ = 1, GAP_FRAMES do
+        emu.frameadvance()
+    end
+end
+
+type_key("h")
+type_key("e")
+type_key("l")
+type_key("l")
+type_key("o")
+type_key("1", true)   -- lshift + 1  →  '!'
+
+log.info('[demo] Done. "HELLO!" typed.')

src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Core/App.axaml.cs

@@ -45,6 +45,7 @@ public partial class App : Application
     private readonly Action<string, string>? _saveScript;
     private readonly Action<string>? _deleteScript;
     private readonly Func<Task>? _loadExamples;
+    private readonly bool _skipDefaultSystemSelection;
     private AvaloniaHostApp _hostApp = default!;
     private IServiceProvider _serviceProvider = default!;
 
@@ -92,6 +93,7 @@ public partial class App : Application
     /// <param name="saveScript">Optional callback to persist a script by file name and content (browser: to localStorage).</param>
     /// <param name="deleteScript">Optional callback to remove a script by file name (browser: from localStorage).</param>
     /// <param name="loadExamples">Optional callback to fetch and seed bundled example scripts (browser-only).</param>
+    /// <param name="skipDefaultSystemSelection">When true, suppresses the UI's automatic default system selection on startup (e.g. when a script or automated startup handles it).</param>
     public App(
         IConfiguration configuration,
         EmulatorConfig emulatorConfig,
@@ -106,7 +108,8 @@ public App(
         Func<string, string?>? loadScript = null,
         Action<string, string>? saveScript = null,
         Action<string>? deleteScript = null,
-        Func<Task>? loadExamples = null)
+        Func<Task>? loadExamples = null,
+        bool skipDefaultSystemSelection = false)
     {
         WriteBootstrapLog("App constructor called");
 
@@ -123,6 +126,7 @@ public App(
         _saveScript = saveScript;
         _deleteScript = deleteScript;
         _loadExamples = loadExamples;
+        _skipDefaultSystemSelection = skipDefaultSystemSelection;
 
         // Set static reference for external access (e.g., debug adapter)
         Current = this;
@@ -331,6 +335,11 @@ private void InitializeHostApp()
             // Wire Lua scripting engine (NoScriptingEngine used when null, e.g. in WASM)
             _hostApp.SetScriptingEngine(_scriptingEngine ?? new NoScriptingEngine());
 
+            // Suppress UI default system selection when automated startup or a script handles it.
+            // Set before TrySetResult so the flag is visible to MainViewModel.InitializeAsync().
+            if (_skipDefaultSystemSelection)
+                _hostApp.SkipDefaultSystemSelection = true;
+
             // Signal waiters (e.g. automated startup on a background thread) that HostApp is ready.
             // TrySetResult guarantees all writes above are visible to awaiters before they resume.
             s_hostAppReady.TrySetResult(_hostApp);

src/apps/Avalonia/Highbyte.DotNet6502.App.Avalonia.Desktop/Program.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.IO;
 using System.Linq;
 using System.Threading.Tasks;
@@ -65,6 +66,20 @@ internal sealed partial class Program
     ///       Only effective when used with <c>--debug-port</c>. Times out after 30 seconds.
     ///     </description>
     ///   </item>
+    ///   <item>
+    ///     <term><c>--script &lt;path&gt;</c></term>
+    ///     <description>
+    ///       Load and auto-enable a specific Lua script file (absolute or relative to CWD).
+    ///       Can be specified multiple times to load several scripts.
+    ///       Overrides the ScriptDirectory from configuration; only the specified files are loaded.
+    ///     </description>
+    ///   </item>
+    ///   <item>
+    ///     <term><c>--scriptDir &lt;path&gt;</c></term>
+    ///     <description>
+    ///       Override the Lua script directory from configuration. All .lua files in the directory are loaded and auto-enabled.
+    ///     </description>
+    ///   </item>
     /// </list>
     /// <para>
     /// <b>Examples:</b>
@@ -138,6 +153,10 @@ public static int Main(string[] args)
         string? loadPrgPath = AutomatedStartupHandler.ParseStringArgument(args, "--loadPrg");
         bool runLoadedProgram = args.Contains("--runLoadedProgram");
 
+        // Parse scripting override arguments
+        List<string> scriptFilePaths = ParseMultipleStringArgument(args, "--script");
+        string? scriptDirectoryOverride = AutomatedStartupHandler.ParseStringArgument(args, "--scriptDir");
+
         // Validate automated startup arguments
         if (!AutomatedStartupHandler.ValidateArguments(systemName, systemVariant, autoStart, waitForSystemReady, loadPrgPath, runLoadedProgram))
         {
@@ -240,13 +259,17 @@ public static int Main(string[] args)
         // ----------
         // Initialize Lua scripting engine
         // ----------
-        var scriptingEngine = MoonSharpScriptingConfigurator.Create(configuration, loggerFactory);
+        var scriptingEngine = MoonSharpScriptingConfigurator.Create(configuration, loggerFactory, scriptFilePaths, scriptDirectoryOverride);
+
+        // Skip the UI's default system selection when a script or --system arg will handle it,
+        // to avoid a race where the UI tries to select a system while the script/handler already has.
+        bool skipDefaultSystemSelection = systemName != null || scriptFilePaths.Count > 0 || scriptDirectoryOverride != null;
 
         // ----------
         // Start Avalonia app
         // ----------
         WriteBootstrapLog($"Starting Avalonia app.");
-        var app = BuildAvaloniaApp(configuration, emulatorConfig, logStore, logConfig, loggerFactory, avaloniaLoggerBridge, gamepad, debugController, scriptingEngine);
+        var app = BuildAvaloniaApp(configuration, emulatorConfig, logStore, logConfig, loggerFactory, avaloniaLoggerBridge, gamepad, debugController, scriptingEngine, skipDefaultSystemSelection);
 
         // If automated startup is requested, handle it after the app starts
         if (systemName != null)
@@ -267,10 +290,6 @@ public static int Main(string[] args)
                 var hostApp = await Core.App.WhenHostAppReadyAsync.ConfigureAwait(false);
                 startupLogger.LogInformation("HostApp initialized.");
 
-                // Suppress default system selection in the Avalonia UI (automated startup handles it)
-                if (hostApp is AvaloniaHostApp avaloniaHostApp)
-                    avaloniaHostApp.SkipDefaultSystemSelection = true;
-
                 await AutomatedStartupHandler.ExecuteAsync(
                     hostApp,
                     systemName,
@@ -316,7 +335,8 @@ public static AppBuilder BuildAvaloniaApp(
         AvaloniaLoggerBridge avaloniaLoggerBridge,
         IGamepad? gamepad = null,
         IExternalDebugController? externalDebugController = null,
-        IScriptingEngine? scriptingEngine = null)
+        IScriptingEngine? scriptingEngine = null,
+        bool skipDefaultSystemSelection = false)
         => AppBuilder.Configure(() => new Core.App(
                 configuration,
                 emulatorConfig,
@@ -327,7 +347,8 @@ public static AppBuilder BuildAvaloniaApp(
                 saveCustomConfigSection: null,
                 gamepad: gamepad,
                 externalDebugController: externalDebugController,
-                scriptingEngine: scriptingEngine))
+                scriptingEngine: scriptingEngine,
+                skipDefaultSystemSelection: skipDefaultSystemSelection))
             .UsePlatformDetect()
             .WithInterFont()
             .LogToTrace()
@@ -371,6 +392,21 @@ private static LogLevel ParseLogLevel(string[] args, LogLevel defaultLevel)
         return defaultLevel;
     }
 
+    /// <summary>
+    /// Parses all occurrences of a named argument from command line arguments.
+    /// Usage: --script foo.lua --script bar.lua → ["foo.lua", "bar.lua"]
+    /// </summary>
+    private static List<string> ParseMultipleStringArgument(string[] args, string argumentName)
+    {
+        var result = new List<string>();
+        for (int i = 0; i < args.Length - 1; i++)
+        {
+            if (args[i] == argumentName)
+                result.Add(args[i + 1]);
+        }
+        return result;
+    }
+
     /// <summary>
     /// Parses the debug port from command line arguments.
     /// Usage: --debug-port 6502

src/libraries/Highbyte.DotNet6502.Scripting.MoonSharp/MoonSharpScriptingConfigurator.cs

@@ -11,7 +11,11 @@ namespace Highbyte.DotNet6502.Scripting.MoonSharp;
 /// </summary>
 public static class MoonSharpScriptingConfigurator
 {
-    public static IScriptingEngine Create(IConfiguration configuration, ILoggerFactory loggerFactory)
+    public static IScriptingEngine Create(
+        IConfiguration configuration,
+        ILoggerFactory loggerFactory,
+        IReadOnlyList<string>? scriptFilePaths = null,
+        string? scriptDirectoryOverride = null)
     {
         var logger = loggerFactory.CreateLogger(nameof(MoonSharpScriptingConfigurator));
 
@@ -24,7 +28,32 @@ public static IScriptingEngine Create(IConfiguration configuration, ILoggerFacto
             return new NoScriptingEngine();
         }
 
-        if (string.IsNullOrWhiteSpace(config.ScriptDirectory))
+        // Apply CLI overrides
+        if (scriptDirectoryOverride != null)
+        {
+            logger.LogInformation("[Scripting] ScriptDirectory overridden via CLI: {Dir}", scriptDirectoryOverride);
+            config.ScriptDirectory = scriptDirectoryOverride;
+        }
+
+        if (scriptFilePaths != null && scriptFilePaths.Count > 0)
+        {
+            logger.LogInformation("[Scripting] Loading {Count} specific script(s) via CLI: {Files}",
+                scriptFilePaths.Count, string.Join(", ", scriptFilePaths));
+            config.ScriptLoader = () => scriptFilePaths.Select(path =>
+            {
+                var fullPath = Path.GetFullPath(path);
+                return (Path.GetFileName(fullPath), File.ReadAllText(fullPath));
+            });
+        }
+
+        // Force auto-enable when CLI overrides are in effect (automation intent)
+        if (scriptFilePaths?.Count > 0 || scriptDirectoryOverride != null)
+        {
+            config.EnableScriptsAtStart = true;
+        }
+
+        // ScriptDirectory is only required when no ScriptLoader is set
+        if (config.ScriptLoader == null && string.IsNullOrWhiteSpace(config.ScriptDirectory))
         {
             logger.LogWarning("[Scripting] Enabled but ScriptDirectory is not set. Using NoScriptingEngine.");
             return new NoScriptingEngine();