Add AmbientLight control commands. Clean up Viewport a little.

Author: ichortower

EventCommandCodex.csproj

@@ -1,6 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
-        <Version>0.6.0-beta</Version>
+        <Version>0.7.0-beta</Version>
         <TargetFramework>net6.0</TargetFramework>
 
         <ModFolderName>$(MOD_NAME)</ModFolderName>

docs/author-guide.md

@@ -22,7 +22,11 @@ This document explains how to use the event commands added by this mod.
 * [Viewport Control](#viewport-control)
   * [ViewportMove](#viewportmove)
   * [ViewportAwait](#viewportawait)
-  * [ViewportStop](#viewportstop)
+  * [ViewportHalt](#viewporthalt)
+* [Ambient Light Control](#ambient-light-control)
+  * [AmbientLightShift](#ambientlightshift)
+  * [AmbientLightAwait](#ambientlightawait)
+  * [AmbientLightHalt](#ambientlighthalt)
 * [World Control](#world-control)
   * [WorldAdvanceTime](#worldadvancetime)
   * [TemporaryMapTiles](#temporarymaptiles)
@@ -277,7 +281,7 @@ well.
 
 ### `ViewportMove`
 
-`ichortower.ECC_ViewportMove <x> <y> <time> [override] [wait]`
+`ichortower.ECC_ViewportMove <x> <y> <duration> [override] [wait]`
 
 This command sets up a viewport movement.
 
@@ -289,7 +293,7 @@ case-insensitive), so e.g. `a14 a20` would mean to move the viewport to (14,20).
 You may mix and match these, so `a22 3` is valid and means to move to x 22 and
 y 3 tiles down from the current position.
 
-`time` is in milliseconds and determines how long the move will take to
+`duration` is in milliseconds and determines how long the move will take to
 complete.
 
 By default, a viewport move will be queued behind any ongoing moves, and the
@@ -309,11 +313,61 @@ vanilla's `viewport move` moves the viewport. Do not mix and match them.
 This command blocks until all queued viewport moves have completed.
 
 
-### `ViewportStop`
+### `ViewportHalt`
 
-`ichortower.ECC_ViewportStop`
+`ichortower.ECC_ViewportHalt`
 
-This command immediately halts and empties the viewport move queue.
+This command immediately halts any ongoing viewport moves and empties the
+viewport move queue.
+
+
+## Ambient Light Control
+
+Although vanilla has the `ambientLight` command which lets you set the ambient
+light color and intensity at any time, it is merely immediate and there is no
+way to transition smoothly. These commands give you the ability to fade it
+gradually and queue the operations, just like with the viewport control
+commands; you can use this to help simulate things like sunsets.
+
+
+### `AmbientLightShift`
+
+`ichortower.ECC_AmbientLightShift <red> <green> <blue> <duration> [override] [wait]`
+
+This command sets up a gradual ambient light shift.
+
+`red`, `green`, and `blue` should be integers from 0 to 255, representing the
+RGB values of the color that will be **subtracted** from white to generate the
+game tint, just as it is with vanilla's `ambientLight` command.
+
+**Note:** The game's draw code has a special case for when all three values of
+the ambient light color are 255 (which would normally mean full darkness): this
+is treated as full brightness instead, the same as `0 0 0`. I recommend
+avoiding this value, and using `254 254 254` instead if you need pitch black;
+it's close enough and won't cause flashing in and out of darkness.
+
+`duration` is in milliseconds and determines how long the shift will take to
+complete.
+
+Like with `ViewportMove`, by default, the shift will be queued behind any
+ongoing shifts, and the command will not block. Just like that command, you can
+give the optional argument `override` to first empty the queue before starting,
+and you can give the optional argument `wait` to block until the queue empties.
+
+
+### `AmbientLightAwait`
+
+`ichortower.ECC_AmbientLightAwait`
+
+This command blocks until all queued ambient light shifts have completed.
+
+
+### `AmbientLightHalt`
+
+`ichortower.ECC_AmbientLightHalt`
+
+This command immediately halts all ongoing ambient light shifts and empties
+the light shift queue.
 
 
 ## World Control

src/AmbientLight.cs

@@ -0,0 +1,144 @@
+using Microsoft.Xna.Framework;
+using StardewValley;
+using StardewValley.Extensions;
+using StardewModdingAPI.Events;
+using System.Collections.Generic;
+
+using Log = ichortower.TowerCore.Log;
+using Main = ichortower.TowerCore.Main;
+using SEvent = StardewValley.Event;
+
+namespace ichortower.ECC;
+
+/*
+ *
+ * Event commands for adjusting the ambient light of the event map over time.
+ * Vanilla has `ambientLight` but it's merely instant, so this lets you do
+ * gradual transitions (e.g. for a sunset effect).
+ *
+ */
+
+internal class AmbientLight
+{
+
+    public static void command_AmbientLightShift(Event evt, string[] args, EventContext context)
+    {
+        bool queueMode = true;
+        string error;
+        if (!ArgUtility.TryGetInt(args, 1, out int red, out error, "int red") ||
+                !ArgUtility.TryGetInt(args, 2, out int green, out error, "int green") ||
+                !ArgUtility.TryGetInt(args, 3, out int blue, out error, "int blue") ||
+                !ArgUtility.TryGetInt(args, 4, out int duration, out error, "int duration")) {
+            context.LogErrorAndSkip(error);
+            return;
+        }
+        for (int i = 5; i < args.Length; ++i) {
+            if (args[i].EqualsIgnoreCase("override")) {
+                queueMode = false;
+            }
+            else if (args[i].EqualsIgnoreCase("wait")) {
+                evt.InsertNextCommand($"{Main.ModId}_AmbientLightAwait");
+            }
+            else {
+                context.LogError($"unknown argument '{args[i]}'",
+                        willSkip: false);
+            }
+        }
+        if (!queueMode) {
+            // this also clears the queue
+            StopAmbientLightWatcher();
+        }
+        ambientLightQueue.Add(new AmbientLightShift(new Color(red, green, blue), duration));
+        StartAmbientLightWatcher();
+        ++evt.CurrentCommand;
+    }
+
+    public static void command_AmbientLightAwait(Event evt, string[] args, EventContext context)
+    {
+        if (ambientLightQueue.Count == 0) {
+            ++evt.CurrentCommand;
+        }
+    }
+
+    public static void command_AmbientLightHalt(Event evt, string[] args, EventContext context)
+    {
+        StopAmbientLightWatcher();
+        ++evt.CurrentCommand;
+    }
+
+
+    /*
+     * Implementation details
+     */
+
+    private static List<AmbientLightShift> ambientLightQueue = new();
+
+    private static System.EventHandler<UpdateTickedEventArgs> ambientLightWatcher = null;
+
+    private static void StartAmbientLightWatcher()
+    {
+        if (ambientLightWatcher != null) {
+            return;
+        }
+        Log.Debug("Starting ambientLight watcher");
+        ambientLightWatcher = AmbientLightFunction;
+        ichortower.TowerCore.Main.Helper.Events.GameLoop.UpdateTicked += ambientLightWatcher;
+    }
+
+    private static void AmbientLightFunction(object sender, UpdateTickedEventArgs e)
+    {
+        if (!ichortower.TowerCore.Game.IsActive()) {
+            return;
+        }
+        if (Game1.eventOver || !Game1.eventUp || ambientLightQueue.Count == 0) {
+            StopAmbientLightWatcher();
+            return;
+        }
+        int now = (int)Game1.currentGameTime.TotalGameTime.TotalMilliseconds;
+        AmbientLightShift head = ambientLightQueue[0];
+        if (head.StartMs == 0) {
+            head.StartMs = now;
+            head.Start = Game1.ambientLight;
+            Log.Debug($"starting shift {head.Start} -> {head.End}");
+            return;
+        }
+        if (now >= head.StartMs + head.Duration) {
+            Log.Debug("ambientLight shift complete");
+            Game1.ambientLight = head.End;
+            ambientLightQueue.RemoveAt(0);
+            return;
+        }
+        float t = (float)(now - head.StartMs) / (float)head.Duration;
+        int r = (int)Utility.Lerp((float)head.Start.R, (float)head.End.R, t);
+        int g = (int)Utility.Lerp((float)head.Start.G, (float)head.End.G, t);
+        int b = (int)Utility.Lerp((float)head.Start.B, (float)head.End.B, t);
+        Game1.ambientLight = new Color(r, g, b);
+    }
+
+    private static void StopAmbientLightWatcher()
+    {
+        ambientLightQueue.Clear();
+        if (ambientLightWatcher is null) {
+            return;
+        }
+        Log.Debug("Stopping ambientLight watcher");
+        ichortower.TowerCore.Main.Helper.Events.GameLoop.UpdateTicked -= ambientLightWatcher;
+        ambientLightWatcher = null;
+    }
+
+}
+
+internal class AmbientLightShift
+{
+    public Color Start = Color.White;
+    public Color End = Color.White;
+    public int Duration = 0;
+    public int StartMs = 0;
+
+    // doesn't set Start and StartMs because those are read when the queue starts the shift
+    public AmbientLightShift(Color target, int duration)
+    {
+        End = target;
+        Duration = duration;
+    }
+}

src/Main.cs

@@ -20,6 +20,7 @@ public override void Entry(IModHelper helper)
 
             List<Type> types = new() {
                 typeof(ichortower.ECC.Actor),
+                typeof(ichortower.ECC.AmbientLight),
                 typeof(ichortower.ECC.Stream),
                 typeof(ichortower.ECC.Viewport),
                 typeof(ichortower.ECC.World),

src/Viewport.cs

@@ -41,22 +41,12 @@ internal class Viewport
      */
     public static void command_ViewportMove(Event evt, string[] args, EventContext context)
     {
-        if (args.Length < 4) {
-            context.LogErrorAndSkip("requires at least three arguments (x y time)");
-            return;
-        }
         bool queueMode = true;
         string err = "";
-        if (!TryGetTarget(args[1], out int xDest, out ViewportMoveType xType, out err)) {
-            context.LogErrorAndSkip($"failed to parse x coordinate: {err}");
-            return;
-        }
-        if (!TryGetTarget(args[2], out int yDest, out ViewportMoveType yType, out err)) {
-            context.LogErrorAndSkip($"failed to parse y coordinate: {err}");
-            return;
-        }
-        if (!int.TryParse(args[3], out int duration)) {
-            context.LogErrorAndSkip($"failed to parse duration from '{args[3]}'");
+        if (!TryGetTarget(args[1], out int xDest, out ViewportMoveType xType, out err) ||
+                !TryGetTarget(args[2], out int yDest, out ViewportMoveType yType, out err) ||
+                !ArgUtility.TryGetInt(args, 3, out int duration, out err, "int duration")) {
+            context.LogErrorAndSkip(err);
             return;
         }
         for (int i = 4; i < args.Length; ++i) {
@@ -187,10 +177,9 @@ private static void ViewportFunction(object sender, UpdateTickedEventArgs e) {
             return;
         }
         // FIXME also do the raindrop position adjustment
-        Game1.viewport.X = (int)Utility.Lerp((float)head.StartX, (float)head.EndX,
-                (float)(now - head.StartMs) / (float)head.Duration);
-        Game1.viewport.Y = (int)Utility.Lerp((float)head.StartY, (float)head.EndY,
-                (float)(now - head.StartMs) / (float)head.Duration);
+        float t = (float)(now - head.StartMs) / (float)head.Duration;
+        Game1.viewport.X = (int)Utility.Lerp((float)head.StartX, (float)head.EndX, t);
+        Game1.viewport.Y = (int)Utility.Lerp((float)head.StartY, (float)head.EndY, t);
     }
 
     private static void StopViewportWatcher()