From 3ec2a0988aca7cba4620b6c22929b91a34ea6eb4 Mon Sep 17 00:00:00 2001
From: rcombs <rcombs@rcombs.me>
Date: Fri, 16 Dec 2022 13:43:30 -0600
Subject: [PATCH] docs: document new user-data property

---
 DOCS/man/input.rst      | 20 ++++++++++++++++++++
 DOCS/man/javascript.rst |  8 ++++++++
 DOCS/man/lua.rst        | 28 ++++++++++++++++++++++++++++
 3 files changed, 56 insertions(+)

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 280e30cc8c..3613fb7dac 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -3256,6 +3256,26 @@ Property list
     (There is no way to ensure synchronization if two scripts try to update the
     same key at the same time.)
 
+``user-data`` (RW)
+    This is a recursive key/value map of arbitrary nodes shared between clients for
+    general use (i.e. scripts, IPC clients, host applications, etc).
+    The player itself does not use any data in it (although some builtin scripts may).
+    The property is not preserved across player restarts.
+
+    This is a more powerful replacement for ``shared-script-properties``.
+
+    Sub-paths can be accessed directly; e.g. ``user-data/my-script/state/a`` can be
+    read, written, or observed.
+
+    The top-level object itself cannot be written directly; write to sub-paths instead.
+
+    Lua scripting has helpers starting with ``utils.user_data_``.
+
+    Converting this property or its sub-properties to strings will give a JSON
+    representation. If converting a leaf-level object (i.e. not a map or array)
+    and not using raw mode, the underlying content will be given (e.g. strings will be
+    printed directly, rather than quoted and JSON-escaped).
+
 ``working-directory``
     The working directory of the mpv process. Can be useful for JSON IPC users,
     because the command line player usually works with relative paths.
diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst
index bdbb04b198..cde14e654e 100644
--- a/DOCS/man/javascript.rst
+++ b/DOCS/man/javascript.rst
@@ -186,6 +186,14 @@ meta-paths like ``~~/foo`` (other JS file functions do expand meta paths).
 
 ``mp.utils.subprocess_detached(t)``
 
+``mp.utils.udata_set(path, val)``
+
+``mp.utils.udata_get(path)``
+
+``mp.utils.udata_del(path)``
+
+``mp.utils.udata_observe(path, type, fn)``
+
 ``mp.utils.get_env_list()``
 
 ``mp.utils.getpid()`` (LE)
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index ae9c14f55f..8a6a165630 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -824,6 +824,34 @@ strictly part of the guaranteed API.
     This is a legacy wrapper around calling the ``run`` command with
     ``mp.commandv`` and other functions.
 
+``utils.udata_set(path, val)``
+    Sets a udata value.
+
+    ``path`` is a path within the ``udata`` property.
+
+    This is a convenience wrapper around ``mp.set_property_native``.
+
+``utils.udata_get(path)``
+    Gets a udata value.
+
+    ``path`` is a path within the ``udata`` property.
+
+    This is a convenience wrapper around ``mp.get_property_native``.
+
+``utils.udata_del(path)``
+    Deletes a udata value.
+
+    ``path`` is a path within the ``udata`` property.
+
+    This is a convenience wrapper around ``mp.del_property_native``.
+
+``utils.udata_observe(path, type, fn)``
+    Observes a udata value.
+
+    ``path`` is a path within the ``udata`` property.
+
+    See ``mp.observe_property`` for further details.
+
 ``utils.getpid()``
     Returns the process ID of the running mpv process. This can be used to identify
     the calling mpv when launching (detached) subprocesses.