兼容性版本

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

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

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

例如，假设你现在运行着以下代码：

-- 发起一个异步 HTTP 请求
HTTP.Request("https://api.nanos.world/", "store/v1/packages/halloween", "GET", "", "application/json", false, {}, function(status, data)
    -- 处理我的数据
end)

然后，在假设的 9.99 更新中，API 发生了变化，使 HTTP.RequestSync 变成了 HTTP.Request，而 HTTP.Request 变成了 HTTP.RequestAsync。 也就是说， 也就是说，你现在需要更新代码以使用 HTTP.RequestAsync，这是一个破坏性更改，因为新函数使用了与以前相同的名称。

有了兼容性版本，你的脚本可以像这次更新之前一样继续工作，因为你的 Package.toml 中的 compatibility_version 仍将被设置为较旧的版本（即 9.98，低于对其进行更改的最新版本 9.99）。

提示

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

所有更新

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

版本 1.144

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

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

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

所有受影响的类为：

• Pawn:AddSkeletalMeshAttached()
• Vehicle:AddSkeletalMeshAttached()
• Pickable:AddSkeletalMeshAttached()

版本 1.139

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

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

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

提示

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

事件

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

• Failed to load method CallRemote (事件) data.
• Failed to load method CallRemotePlayers (事件) data.
• Failed to load method BroadcastRemote (事件) data.
• Failed to load method BroadcastRemoteDimension (事件) data.
• Events.BroadcastRemoteInRadius()（新方法）
• Events.BroadcastRemoteInRadiusDimension()（新方法）

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

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

实体事件

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

• Entity:CallRemoteEvent()
• Entity:CallRemotePlayersEvent()（新方法）
• Entity:BroadcastRemoteEvent()
• Entity:BroadcastRemoteInRadiusEvent()（新方法）

在兼容模式下（即将其设置为 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()

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

local packages = Package.GetPackages(only_loaded, package_type_filter)
--[[
	{
		{
			["title"] = "超棒的包",
			["name"] = "awesome-package",
			["type"] = PackageType.Script,
			["version"] = "1.0.0",
			["author"] = "自己",
		},
		...
	}
--]]

版本 1.33

Input.GetScriptingKeyBindings() 和 Input.GetGameKeyBindings()

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

-- 按键绑定 = 按键
{
	"Jump" = "Spacebar",
	"Crouch" = "Control",
	"Fire" = "LeftMouse",
}

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

-- 按键绑定 = { 按键, 按键, ... }
{
	"Jump" = { "Spacebar", "O" },
	"Crouch" = { "Control" },
	"Fire" = { "LeftMouse", "Return" },
}

版本 1.29

HTTP.Select()

之前 HTTP.Select 是一个异步方法，自 1.29 起它作为一个同步方法工作，不再有回调参数。

Database:Execute()

之前 Database:Execute 是一个异步方法，自 1.29 起它作为一个同步方法工作，不再有回调参数。

版本 1.22

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

Events.Subscribe()

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

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