Question about native vector math

[bandaloo]

I have been looking for an embeddable scripting language where I don't have to jump thru hoops to avoid many tiny heap allocations and garbage collection pauses for simple vector math. I built Luau on Mac from source and have been playing with the REPL. I saw that Luau supports native vectors from this section in the docs: https://luau-lang.org/performance#native-vector-math

This is really fantastic and one of the big sells of Luau in my opinion; amazing work!

But one thing's not clear to me --- does the runtime perform this optimization automatically for any table that contains 3 floats? It seems Vector3.new is exclusive to Roblox, but the docs provide this example for intersection types: https://luau-lang.org/typecheck#intersection-types

type XCoord = {x: number}
type YCoord = {y: number}
type ZCoord = {z: number}

type Vector2 = XCoord & YCoord
type Vector3 = XCoord & YCoord & ZCoord

local vec2: Vector2 = {x = 1, y = 2}        -- ok
local vec3: Vector3 = {x = 1, y = 2, z = 3} -- ok

But this implies that the runtime won't make use of type annotations to make assumptions about how to represent data:

Luau compiler currently doesn’t use type information to do further optimizations, however early experiments suggest that we can extract further wins.

So, I'm clearly missing something, such the syntax for a vector primitive literal. Is this optimization only available through the Roblox API? Thanks for any help.

[vegorov-rbx]

Runtime doesn't detect this type automatically.
Instead, you need to provide a constructor function that returns the vector value.

For example, when you have created a VM, you register a function to build a vector:

static int lua_vector(lua_State* L)
{
    double x = luaL_checknumber(L, 1);
    double y = luaL_checknumber(L, 2);
    double z = luaL_checknumber(L, 3);
    lua_pushvector(L, float(x), float(y), float(z));
    return 1;
}

// Somewhere after initialization
lua_pushcfunction(L, lua_vector, "vector");
lua_setglobal(L, "vector");

Optionally, in compilation options, you can specify:

lua_CompileOptions copts = defaultOptions();
copts.vectorCtor = "vector";

This will tell the compiler that when it sees a vector(1, 2, 3) call, it can use a built-in fastcall which will return a vector value.
This speed ups vector value definition, but everything will work without it as well.
(there's also an option to register a method like foo.bar using vectorLib+vectorCtor.

To get methods and custom properties to wok on vector values, set a single metatable for vector type.
However, .x/.y/.z field access should work automatically.

[bandaloo]

thanks!