Separate ephemeral from client caching in core.dynamic_add_media()

doc/lua_api.md

@@ -7375,8 +7375,10 @@ Server
         * `filedata`: the data of the file to be sent [*]
         * `to_player`: name of the player the media should be sent to instead of
                        all players (optional)
-        * `ephemeral`: boolean that marks the media as ephemeral,
+        * `ephemeral`: if true the server will create a copy of the file and
-                       it will not be cached on the client (optional, default false)
+                       forget about it once delivered (optional boolean, default false)
+        * `client_cache`: hint whether the client should save the media in its cache
+                          (optional boolean, default `!ephemeral`, added in 5.14.0)
         * Exactly one of the parameters marked [*] must be specified.
     * `callback`: function with arguments `name`, which is a player name
     * Pushes the specified media file to client(s) as detailed below.

games/devtest/mods/unittests/misc.lua

@@ -52,6 +52,7 @@ local function test_dynamic_media(cb, player)
 	local ok = core.dynamic_add_media({
 		filepath = path,
 		to_player = player:get_player_name(),
+		client_cache = false,
 	}, function(name)
 		if not call_ok then
 			return cb("impossible condition")

src/script/lua_api/l_server.cpp

@@ -551,6 +551,7 @@ int ModApiServer::l_dynamic_add_media(lua_State *L)
 			args.data.reset();
 		getstringfield(L, 1, "to_player", args.to_player);
 		getboolfield(L, 1, "ephemeral", args.ephemeral);
+		args.client_cache = getboolfield_default(L, 1, "client_cache", !args.ephemeral);
 	} else {
 		tmp = readParam<std::string>(L, 1);
 		args.filepath = tmp;

src/server.cpp

@@ -3782,10 +3782,10 @@ bool Server::dynamicAddMedia(const DynamicMediaArgs &a)
 	if (m_env) {
 		NetworkPacket pkt(TOCLIENT_MEDIA_PUSH, 0);
 		pkt << raw_hash << filename;
-		// NOTE: the meaning of a.ephemeral was accidentally inverted between proto 39 and 40,
+		// NOTE: the meaning of this bit was accidentally inverted between proto 39 and 40,
 		// when dynamic_add_media v2 was added. As of 5.12.0 the server sends it correctly again.
 		// Compatibility code on the client-side was not added.
-		pkt << static_cast<bool>(!a.ephemeral);
+		pkt << static_cast<bool>(a.client_cache);
 
 		NetworkPacket legacy_pkt = pkt;
 

src/server.h

@@ -302,6 +302,7 @@ public:
 		u32 token;
 		std::string to_player;
 		bool ephemeral = false;
+		bool client_cache = true;
 	};
 	bool dynamicAddMedia(const DynamicMediaArgs &args);