跳至正文
版本：最新版 - a1.169.2 ⚖️

兼容性版本

如何将你的包更新到新的兼容性版本

兼容性版本旨在确保你的包在未来的破坏性更改更新中不会损坏。

它通过强制该包在兼容模式下运行代码来实现，这意味着破坏性更改将保持与以前相同的运行方式。

例如，在 1.139 更新中，所有远程事件方法在事件参数之前都新增了一个 reliability 参数。假设你有以下在该更新之前编写的代码：

-- 1.139 之前：事件名称，紧接着是参数
Events.BroadcastRemote("MyEvent", "hello", 123)

在 1.139 之后，相同的调用必须将 Reliability 作为第二个参数传递：

-- 自 1.139 起：事件名称，可靠性，然后是参数
Events.BroadcastRemote("MyEvent", Reliability.Reliable, "hello", 123)

这是一项破坏性更改，因为旧代码会将 "hello" 作为可靠性参数传递。通过兼容性版本，只要 Package.toml 中的 compatibility_version 仍设置为旧版本（例如低于引入变更的 1.139 的 1.138），你的脚本就可以像更新前一样继续工作。

提示

兼容模式是一项旨在让古老且缺乏维护的包/游戏模式能够继续运行更长时间的功能。但所有已弃用的兼容模式都会不定期地从代码库中移除。所以请始终保持你的包处于最新状态！

所有更新​

要使用以下功能，你必须将 Package.toml 中包的 compatibility_version 设置至少更新为该版本（等于或大于该版本）。

版本 1.144​

此更新更改了所有 AddSkeletalMeshAttached 方法的接口，为其添加了 4 个新参数并更改了参数的顺序。

新参数为：socket、relative_location、relative_rotation 和 animation_path。

现在可以将骨骼网格体附加到特定的骨骼插槽上，并带有相对位置和旋转，还可以在其上设置自定义动画或动画蓝图。从而实现扩展功能，例如在附加的骨骼网格体上使用自定义的运行时重定向。

所有受影响的类为：

版本 1.139​

在此版本中，我们为远程事件引入了可靠性的概念。

现在你可以选择你的远程事件应该是以 Reliable（可靠，确保按顺序到达，正如一直以来的默认设置）还是 Unreliable（不可靠，不确保到达，且可能以不同的顺序到达）的方式发送。

这对于发送非常频繁且对游戏玩法非关键的事件特别有用，例如粒子、动画、声音，你不在乎其中一些是否丢失。

提示

Unreliable 消息的发送效率更高，因为它们不需要在到达前进行存储、重新排序和重新发送。 Reliable 消息虽然保证到达，但如果你发送得太多或者网络较差，它们可能会导致性能问题。

事件​

所有 Events 远程函数在 args... 之前都获得了一个新参数：reliability（可靠性）。

此外，Events.BroadcastRemoteDimension() 将参数 dimension 移动到了 event_name 之后。

在兼容模式下（即将其设置为 1.138 或更低），Events 远程调用不包含新的 reliability 参数。

实体事件​

所有 Base Entity 远程函数在 args... 之前同样获得了一个新参数：reliability（可靠性）。

在兼容模式下（即将其设置为 1.138 或更低），Entity 远程调用不包含新的 reliability 参数。

版本 1.103​

TextRender​

TextRender 已重命名为 Text3D。并且创建了一个新的 TextRender 实体。要使用新的 TextRender 实体，你必须将你的 compatibility_version 至少更新到 1.103。

在兼容模式下（即将其设置为 1.102 或更低版本），TextRender 仍将指向旧的 TextRender 类，该类现已重命名为 Text3D。

版本 1.65​

Events.Unsubscribe()​

Events.Unsubscribe 现在仅退订本地事件（使用 Events.Subscribe 订阅的事件）。如果你想退订远程事件（使用 Events.SubscribeRemote 订阅的事件），请使用 Events.UnsubscribeRemote()

在兼容模式下（即将其设置为 1.64 或更低），Events.Unsubscribe 仍会同时退订本地和远程事件。

版本 1.55​

Assets.GetX()​

之前，任何 Assets.GetX() 方法都返回一个字符串数组。现在它返回一个表数组，其中至少包含 key 字段。在 资产元数据页面 中查看有关此更改的更多信息。

Before
for _, asset in pairs(Assets.GetStaticMeshes("nanos-world")) do
	local key = asset
end
After
for _, asset in pairs(Assets.GetStaticMeshes("nanos-world")) do
	local key = asset.key
	local my_meta_data = asset.my_meta_data
	local my_random_value = asset.my_random_value
	-- ...
end

版本 1.54​

Level.CallLevelBlueprintEvent()​

之前，Level.CallLevelBlueprintEvent() 需要一个包含函数名和参数并用空格连接分隔的字符串。现在它采用了接收可变数量参数的新方法，并且还会返回函数的返回值。

Client.GetPackages()​

之前，Client.GetPackages() 会返回服务器在客户端运行的所有包。现在它的行为与 Server.GetPackages() 完全相同，拥有一个过滤器作为参数，并在返回时提供更多信息。

版本 1.49​

Package.GetName()​

之前，Package.GetName() 返回的是在 Package.toml 中定义的标题。现在它已被标准化，将返回包的路径（包的真实名称）。此外，Package.GetPath() 已被弃用，让位于 Package.GetName()。

Server.GetMap()​

之前，Server.GetMap() 返回 Config.toml 中定义的地图资产。现在由于我们可以加载地图包，它将开始返回地图包的名称。在兼容模式下，它仍将返回地图资产。如果你想继续获取地图资产，请改用新方法 Server.GetMapAsset()。

Server.GetPackages()​

此前，Server.GetPackages(only_loaded) 会返回包含所有包名称的字符串列表。现在它增加了一个新参数（package_type_filter），并返回一个包含包信息的表列表：

local packages = Server.GetPackages(only_loaded, package_type_filter)
--[[
	{
		{
			["title"] = "Awesome Package",
			["name"] = "awesome-package",
			["type"] = PackageType.Script,
			["version"] = "1.0.0",
			["author"] = "Myself",
		},
		...
	}
--]]

版本 1.33​

Input.GetScriptingKeyBindings() 和 Input.GetGameKeyBindings()​

之前这些方法返回的表格式为（示例）：

-- 按键绑定 = 按键
{
	Jump = "SpaceBar",
	Crouch = "LeftControl",
	Fire = "LeftMouseButton",
}

现在它返回的格式为（示例）：

-- 按键绑定 = { 按键, 按键, ... }
{
	Jump = { "SpaceBar", "O" },
	Crouch = { "LeftControl" },
	Fire = { "LeftMouseButton", "Enter" },
}

版本 1.29​

Database:Select()​

以前 Database:Select 是一个异步方法，从 1.29 开始它改为了同步方法，不再包含回调参数。若需要异步版本，请使用 Database:SelectAsync。

Database:Execute()​

之前 Database:Execute 是一个异步方法，自 1.29 起它作为一个同步方法工作，不再有回调参数。若需要异步版本，请使用 Database:ExecuteAsync。

版本 1.22​

在 1.22 版本中，我们引入了兼容性版本的概念。除此之外，我们只遇到了一个破坏性更改：

Events.Subscribe()​

Events.Subscribe 现在仅退订/订阅本地事件（通过 Events.Call 调用的事件）。如果你想订阅远程事件（通过 Events.CallRemote 或 Events.BroadcastRemote 调用的事件），请使用 Events.SubscribeRemote。

在兼容模式下（即将其设置为 1.21 或更低），Events.Subscribe 仍会同时订阅本地和远程事件。