额外功能

沙盒游戏模式的一些额外功能和概念

沙盒游戏模式还提供了其他几个子系统，可以通过脚本进行使用和扩展，例如：

沙盒 WebUI

你可以通过 Sandbox.HUD 变量直接访问沙盒 WebUI。

教程

教程 UI 可以显示标题、简短描述以及按键。它会被工具枪系统自动调用，用于显示当前装备工具的操作说明。

你也可以在自己的包中使用它来向玩家提供说明：

Client/Index.lua

-- 显示带有标题、描述和按键列表的教程 UI
-- 每个按键可以是按键绑定名称（例如“开火”）或原始按键名称（例如“E”）
Sandbox.Tutorials.Show("My Tool", "Helps you build awesome things", {
	{ key = "Fire", text = "生成方块" },
	{ key = "E", text = "旋转方块" },
})

-- 隐藏教程 UI
Sandbox.Tutorials.Hide()

SpawnHistory

这是一个服务器端系统，用于追踪每个玩家生成的全部物品。它通过将信息附加到生成的物品上来实现，因此你可以检查是谁（以及在何时）生成了特定物品。

你可以在服务器端调用这些函数将物品添加到玩家的历史记录中，以便他们可以通过按 X 来撤销。

Server/Index.lua

-- 向玩家的历史记录添加一个物品
Sandbox.SpawnHistory.AddItemToHistory(player, my_prop)

-- 销毁玩家历史记录中指定位置的物品（如果 index 为 nil，则销毁最后一个）
-- 如果销毁了物品，则返回 true，否则返回 false
local destroyed = Sandbox.SpawnHistory.DeleteItemFromHistory(player, nil)

-- 更新物品的所有权数据
-- 例如在物品被修改且我们需要更新新所有者的情况下
Sandbox.SpawnHistory.UpdateItemOwnership(other_player, my_prop)

提示

通过调用 Sandbox.SpawnHistory.AddItemToHistory()，实体上将设置一个 "SpawnedBy" 值，该值将与所有客户端同步，并包含以下数据：

{
	player_name = "...", -- 玩家名称
	player_steam_id = "...", -- 玩家 Steam ID
	time = 123, -- 生成的时间 (Server.GetTime())
}

通知

虽然游戏内置已经有了一个通知系统（Client.ShowNotification()），但沙盒提供了一个更高级的通知系统，允许你显示只展示一次的“教程类”通知：

Client/Index.lua

-- 在屏幕上添加通知。参数：
--   type       NotificationType  要显示的通知类型
--   id         string            用于存储通知是否已向玩家显示过的唯一 ID
--   message    string            要显示的信息
--   duration   number            通知显示的持续时间（秒）
--   delay      number            显示通知前等待的时间（秒）
--   force      boolean?          是否强制显示，无论之前是否已经显示过
Sandbox.Notifications.Add(NotificationType.Info, "my_package_welcome", "欢迎！按 Q 打开生成菜单", 5, 2)

PersistentConfig

我们创建了一个系统，用于在使用工具枪（或任何其他自定义工具）时帮助持久化配置。我们的工具枪使用它来在不同会话之间持久化在上下文菜单中修改的配置：

Client/Index.lua

-- 保存类配置
Sandbox.PersistentConfigSystem.SaveConfig("MyToolGun", "power", 50)

-- 获取类配置
local power = Sandbox.PersistentConfigSystem.GetConfig("MyToolGun", "power")

EntityInput

这是一个由我们的实体使用的系统，用于将自定义输入绑定到实体上的动作：

Client/Index.lua

-- 注册按键绑定（玩家可以在设置中重新映射）
Input.Register("MyEntityActivate", "E")

-- 使用按键绑定名称向实体添加输入绑定（回调接收该实体）
Sandbox.EntityInputSystem.AddEntityBinding(my_entity, "activate", "MyEntityActivate", function(entity) end, function(entity) end)

-- 从实体移除输入绑定
Sandbox.EntityInputSystem.RemoveEntityBinding(my_entity, "activate")

在内部，只需为你想要的任何实体类定义 input_bindings，即可自动工作。这将在选择实体时向上下文菜单暴露需要设置的输入绑定。例如，在沙盒的 Thruster 实体（继承自 Prop 的类）中：

Client/MyEntity.lua

-- 此实体的输入绑定
Thruster.input_bindings = {
	{
		label = "activate / deactivate",
		callback_pressed = function(entity)
			entity:CallRemoteEvent("SetActive", Reliability.Reliable, true)
		end,
		callback_released = function(entity)
			entity:CallRemoteEvent("SetActive", Reliability.Reliable, false)
		end,
	},
	{
		label = "toggle",
		callback_pressed = function(entity)
			entity:CallRemoteEvent("SetActive", Reliability.Reliable, not entity:GetValue("Active"))
		end,
	},
}