From 663df4c7a7e0ca27973911bd9b81eb060d5f61fc Mon Sep 17 00:00:00 2001
From: luk3yx <luk3yx@users.noreply.github.com>
Date: Wed, 18 Jun 2025 11:36:03 +1200
Subject: [PATCH] Document flow.get_context, make embedding with player
 optional

---
 doc/experimental.md | 29 ++++++++++++++++++++++++++---
 embed.lua           |  3 +--
 test.lua            |  7 ++++---
 3 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/doc/experimental.md b/doc/experimental.md
index 8f54923..69b3c84 100644
--- a/doc/experimental.md
+++ b/doc/experimental.md
@@ -98,9 +98,8 @@ local parent_form = flow.make_gui(function(player, ctx)
     return gui.VBox{
         gui.Label{label = "Hello world"},
         other_form:embed{
-            -- Passing in the player is required for now. You must use the same
-            -- player object that you get sent by flow to avoid breakages in
-            -- the future if this becomes optional.
+            -- You can optionally pass in the player object to support older
+            -- versions of flow (before 2025-06-17).
             player = player,
 
             -- A name for the embed. If this is specified, the embedded form
@@ -177,3 +176,27 @@ Notes:
    is still supported for compatibility (and there may be uses for it, such as
    sanitising field values). Be careful not to accidentally use the wrong
    callback.
+
+## Getting a reference to the current player and context
+
+If you're making a custom widget, it might be useful to get a reference to
+`ctx` and `player` so you don't have to pass them in manually.
+
+```lua
+local function HelloWorld(def)
+    local ctx, player = flow.get_context()
+    return gui.Label{
+        label = "Hello, " .. player:get_player_name() .. "!\n" ..
+            "some_value=" .. ctx.some_value,
+        style = def.style,
+    }
+end
+
+local form = flow.make_gui(function(player, ctx)
+    ctx.some_value = 123
+    return HelloWorld{style = {font_size = "*2"}}
+end)
+```
+
+`flow.get_context()` will error when called outside a build function (as you
+should not normally do this).
diff --git a/embed.lua b/embed.lua
index d1222ee..9712920 100644
--- a/embed.lua
+++ b/embed.lua
@@ -89,9 +89,8 @@ end
 local change_ctx = ...
 
 return function(self, fields)
-    local player = fields.player
     local name = fields.name
-    local parent_ctx = flow.get_context()
+    local parent_ctx, player = flow.get_context()
     if name == nil then
         -- Don't prefix anything if name is unspecified
         return self._build(player, parent_ctx)
diff --git a/test.lua b/test.lua
index 1ec325e..583d91b 100644
--- a/test.lua
+++ b/test.lua
@@ -977,7 +977,8 @@ describe("Flow", function()
     end)
 
     describe("Flow.embed", function()
-        local embedded_form = flow.make_gui(function(_, x)
+        local embedded_form = flow.make_gui(function(p, x)
+            assert.equals("test", p:get_player_name())
             return gui.VBox{
                 gui.Label{label = "This is the embedded form!"},
                 gui.Field{name = "test2"},
@@ -998,7 +999,7 @@ describe("Flow", function()
             test_render(function(p, _)
                 return gui.HBox{
                     gui.Label{label = "asdft"},
-                    embedded_form:embed{player = p, name = "theprefix"},
+                    embedded_form:embed{name = "theprefix"},
                     gui.Label{label = "ffaksksdf"}
                 }
             end, gui.HBox{
@@ -1016,7 +1017,7 @@ describe("Flow", function()
             test_render(function(p, _)
                 return gui.HBox{
                     gui.Label{label = "asdft"},
-                    embedded_form:embed{player = p},
+                    embedded_form:embed{},
                     gui.Label{label = "ffaksksdf"}
                 }
             end, gui.HBox{