Merge pull request #778 from MihailRis/render-ui-to-texture

rendering UI to texture

doc/en/scripting/builtins/libgui.md

@@ -40,6 +40,37 @@ gui.get_locales_info() -> table of tables {
 
 Returns information about all loaded locales (res/texts/\*).
 
+## Frames
+
+```lua
+-- A replacement for menu:reset() to close the pause menu, deactivating the main UI frame.
+gui.close_menu()
+
+-- Creates a frame.
+gui.create_frame(
+    -- Global frame id (not related to the UI 'id' property).
+    id: str,
+    -- The texture to render the frame to.
+    -- If the string is empty, the frame is rendered to the screen.
+    output_texture: str,
+    -- Frame size. For example: {640, 480}
+    size: vec2
+) -> Element, Document
+
+-- Returns the id of the active frame (not the element id).
+gui.get_active_frame() -> str
+
+-- Sets the active frame, receiving user input.
+-- An empty string specifies the null frame capturing the cursor.
+gui.set_active_frame(
+    -- ID of the frame created via gui.create_frame
+    id: str,
+    -- Function providing the cursor position in the frame.
+    -- Used for custom projection (e.g., in 3D)
+    [optional] cursorLocator
+)
+```
+
 ```lua
 gui.clear_markup(
     -- markup language ("md" - Markdown)

doc/ru/scripting/builtins/libgui.md

@@ -40,6 +40,37 @@ gui.get_env(document: string) -> table
 gui.get_locales_info() -> table
 ```
 
+## Фреймы
+
+```lua
+-- Замена для menu:reset() для закрытия меню паузы, деактивирующая основной фрейм UI.
+gui.close_menu()
+
+-- Создаёт фрейм.
+gui.create_frame(
+    -- Глобальный id фрейма (не связан с UI свойством 'id').
+    id: str,
+    -- Текстура, в которую будет производиться рендер фрейма.
+    -- В случае пустой строки рендер производится на экран.
+    output_texture: str,
+    -- Размер фрейма. Например: {640, 480}
+    size: vec2
+) -> Element, Document
+
+-- Возвращает id активного фрейма (не id элемента).
+gui.get_active_frame() -> str
+
+-- Устанавливает активный фрейм, получающий пользовательский ввод.
+-- Пустая строка указывает null-фрейм, при котором захватывается курсор.
+gui.set_active_frame(
+    -- id фрейма, созданного через gui.create_frame
+    id: str,
+    -- Функция-поставщик позиции курсора во фрейме.
+    -- Используется для пользовательской проекции (например в 3D)
+    [опционально] cursorLocator
+)
+```
+
 ## Разметка
 
 ```lua
@@ -109,4 +140,4 @@ gui.template(
 ```lua
 -- Корневой UI документ.
 gui.root: Document
-```
+```

res/layouts/pages/pause.xml

@@ -1,5 +1,5 @@
 <panel size='400' color='0' interval='1' context='menu'>
-    <button onclick='menu:reset()'>@Continue</button>
+    <button onclick='gui.close_menu()'>@Continue</button>
     <button onclick='menu.page="content?mode=world"'>@Content</button>
     <button onclick='menu.page="settings"'>@Settings</button>
     <button onclick='app.close_world(true)'>

res/scripts/stdlib.lua

@@ -232,6 +232,22 @@ _GUI_ROOT = Document.new("core:root")
 _MENU = _GUI_ROOT.menu
 menu = _MENU
 gui.root = _GUI_ROOT
+gui.main_frame_id = "core:main"
+
+function gui.close_menu()
+    if menu then
+        menu:reset()
+    end
+    gui.set_active_frame("")
+end
+
+local __gui_create_frame = gui.create_frame
+function gui.create_frame(id, output, size)
+    __gui_create_frame(id, output, size)
+
+    local document = Document.new(id)
+    return document.root, document
+end
 
 do
     local status, err = pcall(function()
@@ -435,9 +451,12 @@ function __vc_on_hud_open()
         if menu.page ~= "" then
             if not menu:back() then
                 menu:reset()
+                gui.set_active_frame("")
             end
         elseif hud.is_inventory_open() then
             hud.close_inventory()
+        elseif gui.get_active_frame() then
+            gui.set_active_frame("")
         else
             hud.pause()
         end

src/engine/Engine.cpp

@@ -302,6 +302,9 @@ void Engine::startPauseLoop() {
 }
 
 void Engine::renderFrame() {
+    if (input->isCursorLocked() != (gui->getActiveFrame() == nullptr)) {
+        input->toggleCursor();
+    }
     screen->draw(time.getDelta());
 
     DrawContext ctx(nullptr, *window, nullptr);

src/frontend/hud.cpp

@@ -207,9 +207,6 @@ Hud::Hud(Engine& engine, LevelFrontend& frontend, Player& player)
 }
 
 Hud::~Hud() {
-    if (input.isCursorLocked()) {
-        input.toggleCursor();
-    }
     // removing all controlled ui
     for (auto& element : elements) {
         onRemove(element);
@@ -342,9 +339,6 @@ void Hud::update(bool visible) {
     if (!gui.isFocusCaught()) {
         processInput(visible);
     }
-    if ((isMenuOpen || inventoryOpen) == input.isCursorLocked()) {
-        input.toggleCursor();
-    }
 
     if (blockUI) {
         voxel* vox = chunks.get(blockPos.x, blockPos.y, blockPos.z);
@@ -395,6 +389,7 @@ void Hud::openInventory(bool playerInventory) {
         inventoryView->bind(inventory, &content);
         add(HudElement(HudElementMode::INVENTORY, inventoryDocument, inventoryView, false));
     }
+    gui.setActiveFrame(GUI::CORE_MAIN);
 }
 
 std::shared_ptr<Inventory> Hud::openInventory(
@@ -548,6 +543,7 @@ void Hud::closeInventory() {
         }
     }
     cleanup();
+    gui.setActiveFrame("");
 }
 
 void Hud::add(const HudElement& element, const dv::value& argsArray) {
@@ -710,9 +706,11 @@ void Hud::setPause(bool pause) {
     
     if (!pause && menu.hasOpenPage()) {
         menu.reset();
+        gui.setActiveFrame("");
     }
     if (pause && !menu.hasOpenPage()) {
         menu.setPage("pause");
+        gui.setActiveFrame(GUI::CORE_MAIN);
     }
 }
 

src/frontend/screens/LevelScreen.cpp

@@ -56,6 +56,7 @@ LevelScreen::LevelScreen(
     auto& assets = *engine.getAssets();
     auto menu = engine.getGUI().getMenu();
     menu->reset();
+    gui.setActiveFrame("");
 
     auto player = level->players->get(localPlayer);
     assert(player != nullptr);
@@ -239,7 +240,7 @@ void LevelScreen::update(float delta) {
     
     auto menu = gui.getMenu();
     bool inputLocked =
-        menu->hasOpenPage() || hud->isInventoryOpen() || gui.isFocusCaught();
+        gui.getActiveFrame() || hud->isInventoryOpen() || gui.isFocusCaught();
     bool paused = hud->isPause();
     if (!paused) {
         world.updateTimers(delta);

src/graphics/core/Framebuffer.cpp

@@ -89,6 +89,10 @@ Texture* Framebuffer::getTexture() const {
     return texture.get();
 }
 
+std::shared_ptr<Texture> Framebuffer::getSharedTexture() const {
+    return texture;
+}
+
 uint Framebuffer::getWidth() const {
     return width;
 }

src/graphics/core/Framebuffer.hpp

@@ -13,7 +13,7 @@ class Framebuffer : public Bindable {
     uint width;
     uint height;
     uint format;
-    std::unique_ptr<Texture> texture;
+    std::shared_ptr<Texture> texture;
 public:
     Framebuffer(uint fbo, uint depth, std::unique_ptr<Texture> texture);
     Framebuffer(uint width, uint height, bool alpha=false);
@@ -33,6 +33,8 @@ public:
     /// @brief Get framebuffer color attachment
     Texture* getTexture() const;
 
+    std::shared_ptr<Texture> getSharedTexture() const;
+
     /// @brief Get framebuffer width
     uint getWidth() const;
     /// @brief Get framebuffer height

src/graphics/ui/GUI.cpp

@@ -1,13 +1,14 @@
 #include "GUI.hpp"
 
 #include <algorithm>
-#include <iostream>
 #include <utility>
 
 #include "assets/Assets.hpp"
+#include "debug/Logger.hpp"
 #include "elements/Label.hpp"
 #include "elements/Menu.hpp"
 #include "elements/Panel.hpp"
+#include "elements/Frame.hpp"
 #include "elements/UINode.hpp"
 #include "engine/Engine.hpp"
 #include "frontend/UiDocument.hpp"
@@ -26,13 +27,15 @@
 #include <algorithm>
 #include <utility>
 
+static debug::Logger logger("gui");
+
 using namespace gui;
 
 GUI::GUI(Engine& engine)
     : engine(engine),
       input(engine.getInput()),
       batch2D(std::make_unique<Batch2D>(1024)),
-      container(std::make_shared<Container>(*this, glm::vec2(1000))) {
+      container(std::make_shared<Frame>(*this, CORE_MAIN, "")) {
     container->setId("root");
     uicamera =
         std::make_unique<Camera>(glm::vec3(), engine.getWindow().getSize().y);
@@ -63,6 +66,8 @@ GUI::GUI(Engine& engine)
         std::dynamic_pointer_cast<gui::UINode>(container),
         nullptr
     );
+    addFrame(container);
+    activeFrame = container;
 }
 
 GUI::~GUI() = default;
@@ -117,12 +122,19 @@ void GUI::updateTooltip(float delta) {
 }
 
 /// @brief Mouse related input and logic handling
-void GUI::actMouse(float delta, const CursorState& cursor) {
+void GUI::actMouse(Frame& frame, float delta, const CursorState& cursor) {
     float mouseDelta = glm::length(cursor.delta);
     doubleClicked = false;
     doubleClickTimer += delta + mouseDelta * 0.1f;
 
-    auto hover = container->getAt(cursor.pos);
+    auto cursorPos = cursor.pos;
+    if (cursorLocator) {
+        cursorPos = cursorLocator();
+        if (activeFrame) {
+            cursorPos.y += activeFrame->getPos().y;
+        }
+    }
+    auto hover = frame.getAt(cursorPos);
     if (this->hover && this->hover != hover) {
         this->hover->setMouseEnter(false);
     }
@@ -157,13 +169,13 @@ void GUI::actMouse(float delta, const CursorState& cursor) {
     }
 
     for (auto it = mouseOver.begin(); it != mouseOver.end(); ) {
-        auto node = it->lock();
+        auto mouseOverNode = it->lock();
-        if (node) {
+        if (mouseOverNode) {
-            if (node->isInside(cursor.pos)) {
+            if (mouseOverNode->isInside(cursorPos)) {
                 ++it;
                 continue;
             }
-            node->setMouseOver(false);
+            mouseOverNode->setMouseOver(false);
         }
         it = mouseOver.erase(it);
     }
@@ -172,10 +184,10 @@ void GUI::actMouse(float delta, const CursorState& cursor) {
         if (pressed == nullptr && this->hover) {
             pressed = hover;
             if (doubleClickTimer < doubleClickDelay) {
-                pressed->doubleClick(cursor.pos.x, cursor.pos.y);
+                pressed->doubleClick(cursorPos.x, cursorPos.y);
                 doubleClicked = true;
             } else {
-                pressed->click(cursor.pos.x, cursor.pos.y);
+                pressed->click(cursorPos.x, cursorPos.y);
             }
             doubleClickTimer = 0.0f;
             if (focus && focus != pressed) {
@@ -192,7 +204,7 @@ void GUI::actMouse(float delta, const CursorState& cursor) {
             focus = nullptr;
         }
     } else if (!input.clicked(Mousecode::BUTTON_1) && pressed) {
-        pressed->mouseRelease(cursor.pos.x, cursor.pos.y);
+        pressed->mouseRelease(cursorPos.x, cursorPos.y);
         pressed = nullptr;
     }
 
@@ -232,14 +244,16 @@ void GUI::actFocused() {
 
 void GUI::act(float delta, const glm::uvec2& vp) {
     container->setSize(vp);
-    container->act(delta);
+    for (auto& pair : frames) {
+        pair.second->act(delta);
+    }
     auto prevfocus = focus;
 
     updateTooltip(delta);
 
     const auto& cursor = input.getCursor();
-    if (!cursor.locked) {
+    if (!cursor.locked && activeFrame) {
-        actMouse(delta, cursor);
+        actMouse(*activeFrame, delta, cursor);
     } else {
         if (hover) {
             hover->setMouseEnter(false);
@@ -262,7 +276,7 @@ void GUI::postAct() {
     }
 }
 
-void GUI::draw(const DrawContext& pctx, const Assets& assets) {
+void GUI::draw(const DrawContext& pctx, Assets& assets) {
     auto ctx = pctx.sub(batch2D.get());
 
     auto& viewport = ctx.getViewport();
@@ -280,11 +294,14 @@ void GUI::draw(const DrawContext& pctx, const Assets& assets) {
     uicamera->setAspectRatio(viewport.x / static_cast<float>(viewport.y));
 
     auto uishader = assets.get<Shader>("ui");
-    uishader->use();
     uishader->uniformMatrix("u_projview", uicamera->getProjView());
+    uishader->use();
 
     batch2D->begin();
-    container->draw(ctx, assets);
+    for (auto& [outputTexture, frame] : frames) {
+        frame->updateOutput(assets);
+        frame->draw(ctx, assets);
+    }
 
     if (hover) {
         engine.getWindow().setCursor(hover->getCursor());
@@ -337,6 +354,30 @@ void GUI::add(std::shared_ptr<UINode> node) {
     container->add(std::move(node));
 }
 
+void GUI::addFrame(std::shared_ptr<Frame> frame) {
+    const auto& id = frame->getFrameId();
+    frames[id] = std::move(frame);
+}
+
+void GUI::setActiveFrame(const std::string& id, vec2supplier cursorLocator) {
+    this->cursorLocator = std::move(cursorLocator);
+    if (id.empty()) {
+        activeFrame = nullptr;
+        return;
+    }
+    const auto& found = frames.find(id);
+    if (found == frames.end()) {
+        logger.error() << "attempted to make non-existing frame '" << id
+                       << "' as active";
+        return;
+    }
+    activeFrame = found->second;
+}
+
+std::shared_ptr<gui::Frame> GUI::getActiveFrame() const {
+    return activeFrame;
+}
+
 void GUI::remove(UINode* node) noexcept {
     container->remove(node);
 }

src/graphics/ui/GUI.hpp

@@ -61,13 +61,14 @@ namespace gui {
     class UINode;
     class Container;
     class Menu;
+    class Frame;
 
     /// @brief The main UI controller
     class GUI {
         Engine& engine;
         Input& input;
         std::unique_ptr<Batch2D> batch2D;
-        std::shared_ptr<Container> container;
+        std::shared_ptr<Frame> container;
         std::shared_ptr<UINode> hover;
         std::shared_ptr<UINode> pressed;
         std::shared_ptr<UINode> focus;
@@ -75,11 +76,14 @@ namespace gui {
         std::shared_ptr<UiDocument> rootDocument;
         std::unique_ptr<FontStylesScheme> syntaxColorScheme;
         std::unordered_map<std::string, std::shared_ptr<UINode>> storage;
+        std::shared_ptr<Frame> activeFrame;
 
         std::unique_ptr<Camera> uicamera;
         std::shared_ptr<Menu> menu;
         std::queue<runnable> postRunnables;
         std::vector<std::weak_ptr<UINode>> mouseOver;
+        std::unordered_map<std::string, std::shared_ptr<Frame>> frames;
+        vec2supplier cursorLocator;
 
         float tooltipTimer = 0.0f;
         float doubleClickTimer = 0.0f;
@@ -87,11 +91,12 @@ namespace gui {
         bool doubleClicked = false;
         bool debug = false;
 
-        void actMouse(float delta, const CursorState& cursor);
+        void actMouse(Frame& frame, float delta, const CursorState& cursor);
         void actFocused();
         void updateTooltip(float delta);
         void resetTooltip();
     public:
+        static inline std::string CORE_MAIN = "core:main";
         static constexpr int CONTEXT_MENU_ZINDEX = 999;
 
         GUI(Engine& engine);
@@ -115,7 +120,7 @@ namespace gui {
         /// @brief Draw all visible elements on main container 
         /// @param pctx parent graphics context
         /// @param assets active assets storage
-        void draw(const DrawContext& pctx, const Assets& assets);
+        void draw(const DrawContext& pctx, Assets& assets);
 
         void postAct();
 
@@ -123,6 +128,14 @@ namespace gui {
         /// @param node UI element
         void add(std::shared_ptr<UINode> node);
 
+        void addFrame(std::shared_ptr<Frame> frame);
+
+        void setActiveFrame(
+            const std::string& id, vec2supplier cursorLocator = nullptr
+        );
+
+        std::shared_ptr<Frame> getActiveFrame() const;
+
         /// @brief Remove node from the main container
         void remove(UINode* node) noexcept;
 

src/graphics/ui/elements/Frame.cpp

@@ -0,0 +1,64 @@
+#include "Frame.hpp"
+
+#include "assets/Assets.hpp"
+#include "graphics/core/Batch2D.hpp"
+#include "graphics/core/Framebuffer.hpp"
+#include "graphics/core/DrawContext.hpp"
+#include "graphics/core/Texture.hpp"
+#include "frontend/UiDocument.hpp"
+#include "window/Window.hpp"
+#include "../GUI.hpp"
+
+using namespace gui;
+
+static inline constexpr int MAX_TEXTURE_SIZE = 2048;
+
+gui::Frame::Frame(GUI& gui, std::string id, std::string outputTexture)
+    : Container(gui, {}),
+      fbo(nullptr),
+      outputTexture(std::move(outputTexture)) {
+    frameId = std::move(id);
+}
+
+gui::Frame::~Frame() = default;
+
+void gui::Frame::draw(const DrawContext& pctx, const Assets& assets) {
+    if (outputTexture.empty()) {
+        Container::draw(pctx, assets);
+        return;
+    }
+    if (fbo == nullptr) {
+        return;
+    }
+    glm::ivec2 size = getSize();
+    if (size.x <= 0 || size.y <= 0 ||
+        size.x > MAX_TEXTURE_SIZE || size.y > MAX_TEXTURE_SIZE) {
+        return;
+    }
+    // ui uses flipped camera with matrix based on main viewport
+    setPos({0, pctx.getViewport().y - size.y});
+    
+    auto ctx = pctx.sub();
+    ctx.setFramebuffer(fbo.get());
+    display::clear();
+    Container::draw(ctx, assets);
+    ctx.getBatch2D()->flush();
+}
+
+void gui::Frame::updateOutput(Assets& assets) {
+    if (fbo && (fbo->getWidth() != size.x || fbo->getHeight() != size.y)) {
+        fbo->resize(size.x, size.y);
+        assets.store(fbo->getSharedTexture(), outputTexture);
+    } else if (fbo == nullptr) {
+        fbo = std::make_unique<Framebuffer>(size.x, size.y, true);
+        assets.store(fbo->getSharedTexture(), outputTexture);
+    }
+}
+
+const std::string& gui::Frame::getOutputTexture() const {
+    return outputTexture;
+}
+
+const std::string& gui::Frame::getFrameId() const {
+    return frameId;
+}

src/graphics/ui/elements/Frame.hpp

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "Container.hpp"
+
+class Framebuffer;
+class UiDocument;
+
+namespace gui {
+    class Frame final : public Container {
+    public:
+        Frame(GUI& gui, std::string id, std::string outputTexture);
+        virtual ~Frame();
+
+        void draw(const DrawContext& pctx, const Assets& assets) override;
+
+        void updateOutput(Assets& assets);
+
+        const std::string& getOutputTexture() const;
+
+        const std::string& getFrameId() const;
+    private:
+        std::string frameId;
+        std::unique_ptr<Framebuffer> fbo;
+        std::string outputTexture;
+    };
+}

src/graphics/ui/gui_util.cpp

@@ -78,6 +78,7 @@ void guiutil::alert(
     }));
     menu.addPage("<alert>", panel, true);
     menu.setPage("<alert>");
+    gui.setActiveFrame(GUI::CORE_MAIN);
 }
 
 void guiutil::confirm(
@@ -155,6 +156,7 @@ void guiutil::confirm(
     panel->refresh();
     menu->addPage("<confirm>", container, true);
     menu->setPage("<confirm>");
+    gui.setActiveFrame(GUI::CORE_MAIN);
 }
 
 void guiutil::confirm_with_memo(
@@ -201,4 +203,5 @@ void guiutil::confirm_with_memo(
     panel->refresh();
     menu->addPage("<confirm>", panel, true);
     menu->setPage("<confirm>");
+    gui.setActiveFrame(GUI::CORE_MAIN);
 }

src/logic/PlayerController.cpp

@@ -3,6 +3,7 @@
 
 #include <algorithm>
 #include <cmath>
+#include <glm/gtc/constants.hpp>
 
 #include "BlocksController.hpp"
 #include "content/Content.hpp"
@@ -28,17 +29,19 @@
 #include "window/input.hpp"
 #include "world/Level.hpp"
 
-const float INTERACTION_RELOAD = 0.160f;
+namespace {
-const float STEPS_SPEED = 2.2f;
+    const float INTERACTION_RELOAD = 0.160f;
-const float CAM_SHAKE_OFFSET = 0.0075f;
+    const float STEPS_SPEED = 2.2f;
-const float CAM_SHAKE_OFFSET_Y = 0.031f;
+    const float CAM_SHAKE_OFFSET = 0.0075f;
-const float CAM_SHAKE_SPEED = STEPS_SPEED;
+    const float CAM_SHAKE_OFFSET_Y = 0.031f;
-const float CAM_SHAKE_DELTA_K = 10.0f;
+    const float CAM_SHAKE_SPEED = STEPS_SPEED;
-const float ZOOM_SPEED = 16.0f;
+    const float CAM_SHAKE_DELTA_K = 10.0f;
-const float CROUCH_ZOOM = 0.9f;
+    const float ZOOM_SPEED = 16.0f;
-const float RUN_ZOOM = 1.1f;
+    const float CROUCH_ZOOM = 0.9f;
-const float C_ZOOM = 0.1f;
+    const float RUN_ZOOM = 1.1f;
-const float CROUCH_SHIFT_Y = -0.2f;
+    const float C_ZOOM = 0.1f;
+    const float CROUCH_SHIFT_Y = -0.2f;
+}
 
 CameraControl::CameraControl(Player& player, const CameraSettings& settings)
     : player(player),
@@ -249,17 +252,18 @@ void PlayerController::onFootstep(const Hitbox& hitbox) {
 }
 
 void PlayerController::updateFootsteps(float delta) {
+    const float pi = glm::pi<float>();
     auto hitbox = player.getHitbox();
     if (hitbox && hitbox->grounded) {
         const glm::vec3& vel = hitbox->velocity;
         float f = glm::length(glm::vec2(vel.x, vel.z));
         stepsTimer += delta * f * STEPS_SPEED;
-        if (stepsTimer >= M_PI) {
+        if (stepsTimer >= pi) {
-            stepsTimer = fmod(stepsTimer, M_PI);
+            stepsTimer = fmod(stepsTimer, pi);
             onFootstep(*hitbox);
         }
     } else {
-        stepsTimer = M_PI;
+        stepsTimer = pi;
     }
 }
 

src/logic/scripting/lua/libs/libgui.cpp

@@ -16,6 +16,7 @@
 #include "graphics/ui/elements/TrackBar.hpp"
 #include "graphics/ui/elements/InlineFrame.hpp"
 #include "graphics/ui/elements/ModelViewer.hpp"
+#include "graphics/ui/elements/Frame.hpp"
 #include "graphics/ui/gui_util.hpp"
 #include "graphics/ui/markdown.hpp"
 #include "graphics/core/Font.hpp"
@@ -1149,6 +1150,62 @@ static int l_set_syntax_styles(lua::State* L) {
     return 0;
 }
 
+static int l_create_frame(lua::State* L) {
+    if (engine->isHeadless()) {
+        return 0;
+    }
+    std::string id = lua::require_string(L, 1);
+    std::string outputTexture = lua::require_string(L, 2);
+    auto size = lua::tovec2(L, 3);
+
+    auto& gui = engine->getGUI();
+    auto frame = std::make_shared<gui::Frame>(gui, id, outputTexture);
+    frame->setSize(std::move(size));
+    auto& assets = *engine->getAssets();
+    auto document = std::make_shared<UiDocument>(
+        id, UiDocScript {}, frame, nullptr
+    );
+    assets.store(document, id);
+    gui.addFrame(std::move(frame));
+    return 0;
+}
+
+static int l_set_active_frame(lua::State* L) {
+    if (engine->isHeadless()) {
+        return 0;
+    }
+    std::string id = lua::require_string(L, 1);
+    vec2supplier cursorLocator = nullptr;
+    if (lua::isfunction(L, 2)) {
+        auto lambda = lua::create_lambda(L);
+        cursorLocator = [lambda]() -> glm::vec2 {
+            auto table = lambda({});
+            if (!table.isList()) {
+                throw std::runtime_error("invalid value returned from locator");
+            }
+            glm::vec2 pos {};
+            table.at(0).get(pos.x);
+            table.at(1).get(pos.y);
+            return pos;
+        };
+    }
+    auto& gui = engine->getGUI();
+    gui.setActiveFrame(id, std::move(cursorLocator));
+    return 0;
+}
+
+static int l_get_active_frame(lua::State* L) {
+    if (engine->isHeadless()) {
+        return 0;
+    }
+    auto& gui = engine->getGUI();
+    auto frame = gui.getActiveFrame();
+    if (frame == nullptr) {
+        return 0;
+    }
+    return lua::pushstring(L, frame->getId());
+}
+
 const luaL_Reg guilib[] = {
     {"get_viewport", lua::wrap<l_gui_getviewport>},
     {"getattr", lua::wrap<l_gui_getattr>},
@@ -1162,6 +1219,9 @@ const luaL_Reg guilib[] = {
     {"alert", lua::wrap<l_gui_alert>},
     {"load_document", lua::wrap<l_gui_load_document>},
     {"set_syntax_styles", lua::wrap<l_set_syntax_styles>},
+    {"create_frame", lua::wrap<l_create_frame>},
+    {"set_active_frame", lua::wrap<l_set_active_frame>},
+    {"get_active_frame", lua::wrap<l_get_active_frame>},
     {"__reindex", lua::wrap<l_gui_reindex>},
     {nullptr, nullptr}
 };