Context Menu

如何扩展和使用沙盒上下文菜单。

上下文菜单是沙盒游戏模式中的一个菜单，它提供了调整太阳光照或重新生成等运行时设置。 该菜单可以通过默认按键 C 进行访问，按下即可切换开启或关闭。

直接通过 Lua 就可以在上下文菜单中添加或移除设置！

tip

你可以在沙盒的 GitHub 上查看上下文菜单的源代码。

添加新条目

Client/Index.lua

-- Adds new items to the Context Menu
--  It can be called multiple times with the same ID to append more items to the same category
---@param id string             Unique ID used to identify this category
---@param title string          Category title
---@param items table           Table of items
function Sandbox.ContextMenu.AddItems(id, title, items)

items 参数是一个表列表，每个 type 的格式如下：

checkbox

{
    id = "id-of-item",
    type = "checkbox",
    label = "my check box",
    callback = function(value)
        Console.Log("Checkbox value changed to: " .. value)
    end
},

range

{
    id = "id-of-item",
    type = "range",
    label = "slide me!",
    min = 0,
    max = 1440,
    value = 720,
    step = 1,
    callback = function(value)
        Console.Log("Range value changed to: " .. value)
    end
},

button

{
    id = "id-of-item",
    type = "button",
    label = "press me",
    callback = function()
        Console.Log("Button pressed!")
    end
},

select_image

{
    id = "id-of-item",
    type = "select_image",
    label = "select the image",
    options = {
        { id = "id-opt-01", name = "Opt 01", image = "package://your-package/01.jpg" },
        { id = "id-opt-02", name = "Opt 02", image = "package://your-package/02.jpg" },
    },
    value = function()
        return "id-opt-1"
    end,
    callback = function(value)
        Console.Log("Select Image changed to: " .. value)
    end
}

select

{
    id = "id-of-item",
    type = "select",
    label = "select the option",
    options = {
        { id = "id-opt-01", name = "Opt 01" },
        { id = "id-opt-02", name = "Opt 02" },
    },
    value = "id-opt-1",
    callback = function(value)
        Console.Log("Select changed to: " .. value)
    end
}

color

{
    id = "id-of-item",
    type = "color",
    label = "select the color",
    value = function()
        return my_current_color:ToHex(false)
    end,
    callback = function(value)
        Console.Log("Color changed to: " .. value)
    end
},

tip

The value and options properties can be either a direct value, or a function to be dynamically fetched when the entry is added to the Context Menu!

tip

The id property is optional, and can be useful when you want to update the value of an existing item programmatically.

移除条目

Client/Index.lua

-- Removes the items from the Context Menu
---@param id string             Unique ID used to identify this category
function Sandbox.ContextMenu.RemoveItems(id)

Updating Entries

Client/Index.lua

-- Updates an existing Context Menu item value
---@param id string             Unique ID used to identify this item
function Sandbox.ContextMenu.SetItemValue(item_id, value)

Adding Entries to an Entity/Tool Gun

Custom Entities and Base Pickable (e.g. Weapon) have the ability to have custom Context Menu entries shown automatically when they are selected or picked up.

When selecting an Entity

To add entries when an entity is selected, you need to define the selected_context_menu_items property on the Class of the Entity, with the same format as the items parameter of the AddItems function.

You can use the current selected entity set in Sandbox.ContextMenu.selected_entity to dynamically get/set values related to the selected entity in the Context Menu entries, for example:

Client/CustomEntity.lua

MyEntityClass.selected_context_menu_items = {
    {
        id = "my_entity_input",
        type = "text",
        label = "text",
        placeholder = "enter the text",
        callback = function(value)
            Sandbox.ContextMenu.selected_entity:CallRemoteEvent("SetMyValue", Reliability.Reliable, value)
        end,
        value = function()
            return Sandbox.ContextMenu.selected_entity:GetValue("MyValue")
        end,
    }
}

When picking up an Entity

You can also define custom entries for Base Pickable classes, that will automatically show when picking up them. To do that, you need to define the picked_context_menu_items property on the Class of the Pickable:

Client/CustomPickable.lua

MyGun.picked_context_menu_items = {
    {
        id = "my_gun_value",
        type = "range",
        label = "my value",
        min = 0,
        max = 100,
        step = 1,
        callback = function(value)
            MyGun.my_value = value
        end,
        value = function()
            return MyGun.my_value
        end
    }
}

Opening/Closing

Client/Index.lua

-- Opens the Context Menu
function Sandbox.ContextMenu.Open()

-- Closes the Context Menu
function Sandbox.ContextMenu.Close()

Examples

You can find examples and how it works deeply at the ContextMenu.lua file.

此外，你还可以在 BalloonGun 中看到一个动态向上下文菜单添加条目的实际运行示例。