From bbfae0cc673d3abdc21224c53e09b209ee4688a2 Mon Sep 17 00:00:00 2001 From: sfan5 Date: Thu, 9 Sep 2021 16:51:35 +0200 Subject: Dynamic_Add_Media v2 (#11550) --- doc/lua_api.txt | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) (limited to 'doc/lua_api.txt') diff --git a/doc/lua_api.txt b/doc/lua_api.txt index e99c1d1e6..3a1a3f02f 100644 --- a/doc/lua_api.txt +++ b/doc/lua_api.txt @@ -5649,22 +5649,33 @@ Server * Returns a code (0: successful, 1: no such player, 2: player is connected) * `minetest.remove_player_auth(name)`: remove player authentication data * Returns boolean indicating success (false if player nonexistant) -* `minetest.dynamic_add_media(filepath, callback)` - * `filepath`: path to a media file on the filesystem - * `callback`: function with arguments `name`, where name is a player name - (previously there was no callback argument; omitting it is deprecated) - * Adds the file to the media sent to clients by the server on startup - and also pushes this file to already connected clients. - The file must be a supported image, sound or model format. It must not be - modified, deleted, moved or renamed after calling this function. - The list of dynamically added media is not persisted. +* `minetest.dynamic_add_media(options, callback)` + * `options`: table containing the following parameters + * `filepath`: path to a media file on the filesystem + * `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, + it will not be cached on the client (optional, default false) + * `callback`: function with arguments `name`, which is a player name + * Pushes the specified media file to client(s). (details below) + The file must be a supported image, sound or model format. + Dynamically added media is not persisted between server restarts. * Returns false on error, true if the request was accepted * The given callback will be called for every player as soon as the media is available on the client. - Old clients that lack support for this feature will not see the media - unless they reconnect to the server. (callback won't be called) - * Since media transferred this way currently does not use client caching - or HTTP transfers, dynamic media should not be used with big files. + * Details/Notes: + * If `ephemeral`=false and `to_player` is unset the file is added to the media + sent to clients on startup, this means the media will appear even on + old clients if they rejoin the server. + * If `ephemeral`=false the file must not be modified, deleted, moved or + renamed after calling this function. + * Regardless of any use of `ephemeral`, adding media files with the same + name twice is not possible/guaranteed to work. An exception to this is the + use of `to_player` to send the same, already existent file to multiple + chosen players. + * Clients will attempt to fetch files added this way via remote media, + this can make transfer of bigger files painless (if set up). Nevertheless + it is advised not to use dynamic media for big media files. Bans ---- -- cgit v1.2.3