Zum Hauptinhalt springen
Version: latest - a1.156.0 ⚖️

Compatibility Versions

How to update your packages to the new Compatibility Versions

The Compatibility Version is meant to assure your packages will not break in future breaking changes updates.

It works by forcing that package to run code in a compatibility mode, meaning that breaking changes will keep working as the way it was before.

For example, in the update 1.139 all remote event methods got a new reliability parameter, before the event arguments. Let's say you had this code, written before that update:

-- Before 1.139: event name and then the arguments
Events.BroadcastRemote("MyEvent", "hello", 123)

After 1.139, the same call must pass the Reliability as second parameter:

-- Since 1.139: event name, reliability and then the arguments
Events.BroadcastRemote("MyEvent", Reliability.Reliable, "hello", 123)

This is a breaking change, as the old code would pass "hello" as the reliability. With compatibility version, your scripts keep working as they were before this update, as long as the compatibility_version in your Package.toml is still set to an older version (e.g. 1.138, lower than 1.139 which changed it).

tip

The Compatibility Mode is a feature that aims to keep old and unmaintained packages/game-modes to keep working for a longer time. But from time to time all the deprecated compatibility modes will be removed from the codebase. So always keep your packages up-to-date!

All Updates​

To use the following features, you must update your Package's compatibility_version setting in the Package.toml to at least that version (exact that version or bigger).

Version 1.144​

This update changes all AddSkeletalMeshAttached methods interface, adding 4 new parameters to it and changing the order of the parameters.

The new parameters are: socket, relative_location, relative_rotation and animation_path.

Now it's possible to attach a Skeletal Mesh to a specific bone socket, with a relative location and rotation, and also set a custom animation or animation blueprint on it. Allowing extended capabilities such as using custom runtime retargeting on the attached Skeletal Mesh.

All the affected classes are:

Version 1.139​

In this version, we are introducing the concept of Reliability for Remote Events.

Now you can choose if your remote events should be sent as Reliable (guaranteed to arrive, in order, as it has always been by default) or Unreliable (not guaranteed to arrive and may arrive at different order).

This is specially useful for events that are sent very often and non critical for gameplay, like particles, animations, sounds, where you don't care if some of them get lost.

tip

Unreliable messages are more efficient to send, as they don't need to be stored, re-ordered and resent until they arrive. Reliable messages are guaranteed to arrive, but they can cause performance issues if you are sending too many of them or if the network is bad.

Events​

All the Events remote functions got a new parameter before args...: reliability (Reliability).

Also, Events.BroadcastRemoteDimension() got the parameter dimension moved after event_name.

In compatibility mode (i.e. setting it to 1.138 or below), the Events remote calls don't have the new reliability parameter.

Entity Events​

All the Base Entity remote functions got a new parameter before args...: reliability (Reliability) as well.

In compatibility mode (i.e. setting it to 1.138 or below), the Entity remote calls don't have the new reliability parameter.

Version 1.103​

TextRender​

TextRender was renamed to Text3D. And a new entity TextRender was created. To use the new TextRender entity, you must update your compatibility_version to at least 1.103.

In compatibility mode (i.e. setting it to 1.102 or below) TextRender will still point to the old TextRender class, which is now called Text3D.

Version 1.65​

Events.Unsubscribe()​

Events.Unsubscribe now only unsubscribes to local events (ones subscribed with Events.Subscribe). If you want to unsubscribe to remote events (ones subscribed as Events.SubscribeRemote), please use Events.UnsubscribeRemote()

In compatibility mode (i.e. setting it to 1.64 or below) Events.Unsubscribe still unsubscribes for both Local and Remote events.

Version 1.55​

Assets.GetX()​

Before, any Assets.GetX() method returned an array of strings. Now it returns an array of tables, containing at least the key field on it. See more about this change in the Assets Meta Data page.

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

Version 1.54​

Level.CallLevelBlueprintEvent()​

Before, Level.CallLevelBlueprintEvent() expected a string with the function name and parameters concatenated together separated by spaces. Now it uses the new approach of receiving a variadic amount of parameters and also returns the function return value.

Client.GetPackages()​

Before, Client.GetPackages() returned all packages that the server was running on client side. Now it behaves exactly like Server.GetPackages(), having a filter as parameter and providing more information on return.

Version 1.49​

Package.GetName()​

Before, Package.GetName() was returning the title defined in Package.toml. Now it is standardized and it returns the Path of the Package (the real Name of it). Also Package.GetPath() was deprecated in favor of Package.GetName().

Server.GetMap()​

Before, Server.GetMap() was returning the map asset defined in Config.toml. Now as we can load Map Packages, it will start returning the Map Package name instead. In compatibility mode it will still return the Map Asset. If you want to still keep retrieving the Map asset, please use the new method Server.GetMapAsset() instead.

Server.GetPackages()​

Before, Server.GetPackages(only_loaded) returned a list of strings containing all the package names. Now it has a new parameter (package_type_filter) and returns a list of table with the Packages information:

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

Version 1.33​

Input.GetScriptingKeyBindings() and Input.GetGameKeyBindings()​

Before those methods returned a table in the format (example):

-- KeyBinding = Key
{
	Jump = "SpaceBar",
	Crouch = "LeftControl",
	Fire = "LeftMouseButton",
}

Now it returns in the format (example):

-- KeyBinding = { Key, Key, ... }
{
	Jump = { "SpaceBar", "O" },
	Crouch = { "LeftControl" },
	Fire = { "LeftMouseButton", "Enter" },
}

Version 1.29​

Database:Select()​

Before Database:Select was an async method, and since 1.29 it works as a Sync method, not having the callback parameter anymore. Use Database:SelectAsync for the asynchronous version.

Database:Execute()​

Before Database:Execute was an async method, and since 1.29 it works as a Sync method, not having the callback parameter anymore. Use Database:ExecuteAsync for the asynchronous version.

Version 1.22​

In version 1.22 we introduced the concept of Compatibility Version. Besides that, we've got just one breaking change:

Events.Subscribe()​

Events.Subscribe now only subscribes to local events (ones called as Events.Call). If you want to subscribe to remote events (ones called as Events.CallRemote or Events.BroadcastRemote), please use Events.SubscribeRemote.

In compatibility mode (i.e. setting it to 1.21 or below) Events.Subscribe still subscribes for both Local and Remote events.