Add configurable vector size build option

Support building with either 3 or 4 component vectors via -Dvector-size flag.
Default is 4 for better SIMD alignment. CI tests both configurations.

Author: mxpv

.github/workflows/ci.yml

@@ -46,6 +46,7 @@ jobs:
         key: zig-cache-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('build.zig', 'build.zig.zon') }}
 
     - run: zig build test --summary all
+    - run: zig build test -Dvector-size=3 --summary all
 
     - run: zig build luau-compile -- --help
     - run: zig build luau-analyze -- --help

CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- Configurable vector size build option (`-Dvector-size=3` or `4`, default 4)
+
 ### Changed
 - Updated Luau dependency from version 0.684 to 0.686
 

README.md

@@ -266,6 +266,14 @@ const greeting = result.ok.?;
 > [!WARNING]
 > This library is still evolving and the API is not stable. Backward incompatible changes may be introduced up until the 1.0 release. Consider pinning to a specific commit or tag if you need stability.
 
+## 🔧 Build Configuration
+
+### Vector Size
+By default, luaz is built with 4-component vectors. To customize:
+```bash
+zig build -Dvector-size=3  # Build with 3-component vectors
+```
+
 ## 🛠️ Using Luau Tools
 
 The build system provides prebuilt Luau tools that can be invoked directly:

build.zig

@@ -25,15 +25,23 @@ pub fn build(b: *std.Build) !void {
 
     const opts = .{
         .cover = b.option(bool, "coverage", "Generate test coverage (requires kcov)") orelse false,
+        .vector_size = b.option(u8, "vector-size", "Luau vector size (3 or 4, default 4)") orelse 4,
     };
 
+    // Validate vector size
+    if (opts.vector_size != 3 and opts.vector_size != 4) {
+        std.log.err("Invalid vector size: {}. Must be either 3 or 4", .{opts.vector_size});
+        return error.InvalidVectorSize;
+    }
+
     // Luau VM lib
     const luau_vm = blk: {
         const mod = b.createModule(.{ .target = target, .optimize = optimize });
 
         try addSrcFiles(b, mod, "luau/VM/src", flags);
 
         mod.addCMacro("LUA_USE_LONGJMP", "1");
+        mod.addCMacro("LUA_VECTOR_SIZE", b.fmt("{d}", .{opts.vector_size}));
 
         mod.addIncludePath(b.path("luau/VM/include"));
         mod.addIncludePath(b.path("luau/VM/src"));
@@ -57,6 +65,7 @@ pub fn build(b: *std.Build) !void {
 
         try addSrcFiles(b, mod, "luau/CodeGen/src", flags);
 
+        mod.addCMacro("LUA_VECTOR_SIZE", b.fmt("{d}", .{opts.vector_size}));
         mod.addIncludePath(b.path("luau/CodeGen/include"));
         mod.addIncludePath(b.path("luau/Common/include"));
         mod.addIncludePath(b.path("luau/VM/src"));
@@ -175,6 +184,7 @@ pub fn build(b: *std.Build) !void {
             .file = b.path("src/handler.cpp"),
             .flags = flags,
         });
+        mod.addCMacro("LUA_VECTOR_SIZE", b.fmt("{d}", .{opts.vector_size}));
         mod.addIncludePath(b.path("luau/VM/include"));
         mod.addIncludePath(b.path("luau/Common/include"));
         mod.addIncludePath(b.path("src"));
@@ -219,6 +229,7 @@ pub fn build(b: *std.Build) !void {
             .file = b.path("src/handler.cpp"),
             .flags = flags,
         });
+        unit_tests.root_module.addCMacro("LUA_VECTOR_SIZE", b.fmt("{d}", .{opts.vector_size}));
         unit_tests.root_module.addIncludePath(b.path("luau/VM/include"));
         unit_tests.root_module.addIncludePath(b.path("luau/Common/include"));
         unit_tests.root_module.addIncludePath(b.path("src"));

src/stack.zig

@@ -792,13 +792,24 @@ test "push and pop vector types" {
     const lua = try Lua.init(&std.testing.allocator);
     defer lua.deinit();
 
-    const vec3 = @Vector(3, f32){ 1.0, 2.0, 3.0 };
-    push(&lua.state, vec3);
-    try expect(lua.state.isVector(-1));
-    const popped_vec3 = pop(lua, @Vector(3, f32)).?;
-    try expectEq(popped_vec3[0], 1.0);
-    try expectEq(popped_vec3[1], 2.0);
-    try expectEq(popped_vec3[2], 3.0);
+    if (State.VECTOR_SIZE == 3) {
+        const vec = @Vector(3, f32){ 1.0, 2.0, 3.0 };
+        push(&lua.state, vec);
+        try expect(lua.state.isVector(-1));
+        const popped_vec = pop(lua, @Vector(3, f32)).?;
+        try expectEq(popped_vec[0], 1.0);
+        try expectEq(popped_vec[1], 2.0);
+        try expectEq(popped_vec[2], 3.0);
+    } else {
+        const vec = @Vector(4, f32){ 1.0, 2.0, 3.0, 4.0 };
+        push(&lua.state, vec);
+        try expect(lua.state.isVector(-1));
+        const popped_vec = pop(lua, @Vector(4, f32)).?;
+        try expectEq(popped_vec[0], 1.0);
+        try expectEq(popped_vec[1], 2.0);
+        try expectEq(popped_vec[2], 3.0);
+        try expectEq(popped_vec[3], 4.0);
+    }
 
     try expectEq(lua.state.getTop(), 0);
 }