Add new [screen_fade] WML action (#6864)

* Add new [screen_fade] WML action

It takes (for now) the arguments:
 * red, green, blue = values between 0 and 255
 * alpha = value between 0 and 255
 * duration = time in ms over which to fade

The game display is faded to the given colour over the duration.
It will be left with an overlay of that colour and alpha until
a screen_fade to 0 alpha is performed.

data/lua/wml-tags.lua

@@ -718,6 +718,11 @@ function wml_actions.color_adjust(cfg)
 	wesnoth.interface.color_adjust(cfg.red or 0, cfg.green or 0, cfg.blue or 0)
 end
 
+function wml_actions.screen_fade(cfg)
+	local color = {cfg.red or 0, cfg.green or 0, cfg.blue or 0, cfg.alpha}
+	wesnoth.interface.screen_fade(color, cfg.duration)
+end
+
 function wml_actions.end_turn(cfg)
 	wesnoth.interface.end_turn()
 end

data/scenario-test.cfg

@@ -3888,6 +3888,64 @@ Result:
         [/replace_schedule]
     [/event]
 
+    [label]
+        x,y=15,5
+        text=_"Disco Party"
+    [/label]
+    [event]
+        name=moveto
+        first_time_only=no
+        [filter]
+            x,y=15,5
+        [/filter]
+        [screen_fade]
+            red,green,blue=255,0,0
+            alpha=150
+            duration=200
+        [/screen_fade]
+        [delay]
+            time=50
+        [/delay]
+        [screen_fade]
+            red,green,blue=255,0,0
+            alpha=20
+            duration=250
+        [/screen_fade]
+        [screen_fade]
+            red,green,blue=0,255,0
+            alpha=140
+            duration=200
+        [/screen_fade]
+        [delay]
+            time=50
+        [/delay]
+        [screen_fade]
+            red,green,blue=0,255,0
+            alpha=20
+            duration=250
+        [/screen_fade]
+        [screen_fade]
+            red,green,blue=0,255,255
+            alpha=200
+            duration=250
+        [/screen_fade]
+        [screen_fade]
+            red,green,blue=255,0,255
+            alpha=200
+            duration=250
+        [/screen_fade]
+        [screen_fade]
+            red,green,blue=255,255,0
+            alpha=200
+            duration=250
+        [/screen_fade]
+        [screen_fade]
+            red,green,blue=0,0,0
+            alpha=0
+            duration=250
+        [/screen_fade]
+    [/event]
+
     [label]
         x,y=23,10
         text=_"livingness"

data/schema/core/actionwml.cfg

@@ -865,6 +865,13 @@
 		max=infinite
 		{COLOR_KEYS s_int}
 	[/tag]
+	[tag]
+		name="screen_fade"
+		max=infinite
+		{COLOR_KEYS s_unsigned}
+		{REQUIRED_KEY alpha s_unsigned}
+		{REQUIRED_KEY duration s_unsigned}
+	[/tag]
 	[tag]
 		name="delay"
 		max=infinite

src/scripting/game_lua_kernel.cpp

@@ -3730,6 +3730,19 @@ int game_lua_kernel::intf_get_color_adjust(lua_State *L)
 	return 0;
 }
 
+int game_lua_kernel::intf_screen_fade(lua_State *L)
+{
+	if(game_display_) {
+		auto vec = lua_check<std::vector<uint8_t>>(L, 1);
+		if(vec.size() != 4) {
+			return luaW_type_error(L, 1, "array of 4 integers");
+		}
+		color_t fade{vec[0], vec[1], vec[2], vec[3]};
+		game_display_->fade_to(fade, luaL_checkinteger(L, 2));
+	}
+	return 0;
+}
+
 /**
  * Delays engine for a while.
  * - Arg 1: integer.
@@ -4700,6 +4713,7 @@ game_lua_kernel::game_lua_kernel(game_state & gs, play_controller & pc, reports
 		{"remove_hex_overlay", &dispatch<&game_lua_kernel::intf_remove_tile_overlay>},
 		{"get_color_adjust", &dispatch<&game_lua_kernel::intf_get_color_adjust>},
 		{"color_adjust", &dispatch<&game_lua_kernel::intf_color_adjust>},
+		{"screen_fade", &dispatch<&game_lua_kernel::intf_screen_fade>},
 		{"delay", &dispatch<&game_lua_kernel::intf_delay>},
 		{"deselect_hex", &dispatch<&game_lua_kernel::intf_deselect_hex>},
 		{"highlight_hex", &dispatch<&game_lua_kernel::intf_highlight_hex>},

src/scripting/game_lua_kernel.hpp

@@ -153,6 +153,7 @@ class game_lua_kernel : public lua_kernel_base
 	int intf_remove_event(lua_State *L);
 	int intf_color_adjust(lua_State *L);
 	int intf_get_color_adjust(lua_State *L);
+	int intf_screen_fade(lua_State *L);
 	int intf_delay(lua_State *L);
 	int intf_add_label(lua_State *L);
 	int intf_remove_label(lua_State *L);

utils/emmylua/wesnoth/interface.lua

@@ -123,5 +123,10 @@ function wesnoth.interface.allow_end_turn(reason) end
 ---@param blue integer
 function wesnoth.interface.color_adjust(red, green, blue) end
 
+---Fade the screen to the given colour
+---@param color integer[] RGBA colour value to fade to; A=0 removes fade
+---@param duration integer How long the fade takes to apply, in milliseconds
+function wesnoth.interface.screen_fade(color, duration) end
+
 ---@type table<string, fun()>
 wesnoth.game_display = {}