If Luau tries to use a value or variable in an operation, such as arithmetic, concatenation, or assignment, but the value isn't the type that the operation expects, then Luau converts (coerces) the value to change its data type. Coercion happens at run time for that operation and doesn't change the value of a variable.
Luau coerces strings to numbers in arithmetic operations. This behavior is built into Luau. If the types are incompatible for arithmetic, Luau throws an error and doesn't run the rest of the script. For example, you can't add a string to a number if the string does not represent a number.
print(100 + "7") -- 107print(100 - "7") -- 93print("1000" + 234) -- 1234print("1000" - 234) -- 766print("hello" + 234) -- error: attempt to perform arithmetic (add) string and number
In concatenation, Luau coerces numbers to strings. To convert a number to a string without using coercion, use the string.format() function.
print("Pi is " .. math.pi) -- 3.1415926535898print("Pi is " .. 3.1415927) -- 3.1415927-- Rounds to three decimal placesprint("Pi is " .. string.format("%.3f", 3.1415927)) -- Pi is 3.142
Some properties expect certain data types, such as an Enum or string, but you can assign a value of a different type to it and Luau converts the value to the type the property expects.
Luau coerces numbers and strings of enum values into the full enum name. For example, you can name the value of the Part.Material property using a number, string, or full enum name, and the print() function always prints the full enum name. It's best practice to be explicit and use the full enum name. For more information on Enums, see Enums.
local part1 = Instance.new("Part")part1.Parent = workspacepart1.Material = 816print(part1.Material) -- Enum.Material.Concretelocal part2 = Instance.new("Part")part2.Parent = workspacepart2.Material = "Concrete"print(part2.Material) -- Enum.Material.Concrete-- This is best practice because it's the most explicitlocal part3 = Instance.new("Part")part3.Parent = workspacepart3.Material = Enum.Material.Concreteprint(part3.Material) -- Enum.Material.Concrete
The Lighting.TimeOfDay property, which defines whether it is night, day, or any other time, is a string representation of the DateTime data type. If you assign a number to Lighting.TimeOfDay, Luau converts it to the string representation of DateTime.
game.Lighting.TimeOfDay = "05:00:00"print(game.Lighting.TimeOfDay) -- 05:00:00game.Lighting.TimeOfDay = 5print(game.Lighting.TimeOfDay) -- 05:00:00