Skip to content

Implement Native Lua Vector Datatype - #5297

Open
MohabCodeX wants to merge 1 commit into
multitheftauto:masterfrom
MohabCodeX:feat/native-lua-vector
Open

Implement Native Lua Vector Datatype#5297
MohabCodeX wants to merge 1 commit into
multitheftauto:masterfrom
MohabCodeX:feat/native-lua-vector

Conversation

@MohabCodeX

@MohabCodeX MohabCodeX commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Replaces #1728
Fixes #321

This is basically the last part of the OOP/vector optimization work from #5278, #5279, #5280 and #5290. It completes the native vector idea that was originally started by @Pirulax in #1728.

The main goal here was to make vectors actual native Lua values instead of relying on userdata/metatables and C function calls. With these changes in place, OOP element properties are now faster than procedural calls (6ms vs. 41ms), while native vector math is 12.6× faster than legacy OOP vectors, getting close to raw CPU performance.

What changed

  • Added vector / LUA_TVEC as a native 128-bit 4D floating point type in the Lua runtime.
  • Arithmetic such as +, -, *, /, ^, unary - and length calculations now have VM fast paths, without going through metamethods or C functions.
  • Supports .x, .y, .z, .w, numeric indexing ([1] to [4]) and swizzling like .xy, .xyz, etc.
  • Native vectors are supported by CScriptArgReader, CLuaArgument event serialization and the JSON converters.
  • Added the usual constructors and helper functions through the global vector library.

Lua API

Creating a vector:

vector vector ( float x, float y, float z [, float w = 0.0 ] )

x, y and z are required. w is optional and defaults to 0.0.

Example:

local pos = vector(0, 5, 3)
local target = pos + vector.forward * 10

print("Target position: " .. target)
print("Distance: " .. pos:distance(target))

Available methods

Both method and static versions are available:

  • vec:dot(otherVec) / vector.dot(v1, v2)
  • vec:cross(otherVec) / vector.cross(v1, v2)
  • vec:length() / vector.length(v)
  • vec:lengthSquared() / vector.lengthSquared(v)
  • vec:normalize() / vector.normalize(v)
  • vec:distance(otherVec) / vector.distance(v1, v2)
  • vec:distanceSquared(otherVec) / vector.distanceSquared(v1, v2)

Constants:

  • vector.zero = vector(0, 0, 0, 0)
  • vector.one = vector(1, 1, 1, 1)
  • vector.forward = vector(0, 1, 0, 0)
  • vector.right = vector(1, 0, 0, 0)
  • vector.up = vector(0, 0, 1, 0)

Benchmarks

500,000 operations per test:

Test Inline OOP Native SIMD vector Improvement
Vector arithmetic (+, -, *) 2,918 ms 230 ms 12.7x
Vector math (:dot, :length) 263.6 ms 56.3 ms 4.7x
Component reads (.x, .y, .z) 695.3 ms 21.3 ms 33x
Total 3,877 ms 307.3 ms 12.6x

Sounds a bit unrealistic? Yeah, test it yourself :)))
vector_benchmark.zip

For comparison, running around 1.5 million synchronous operations in a single frame previously froze the game for roughly 4 seconds and triggered the black loading screen. With native vectors, the same workload causes only a frame drop of around a second or less, so normal gameplay shouldn't be affected.

- Add LUA_TVEC as first-class 128-bit 4D float vector in Lua core runtime
- Implement in-VM fast-path arithmetic (OP_ADD, OP_SUB, OP_MUL, OP_DIV, OP_UNM, OP_LEN)
- Support fast field indexing, direct component assignment, and swizzling
- Add value-based table key hashing and vector equality comparisons
- Provide core vector library with helper math methods and unpack support
- Integrate LUA_TVEC into CScriptArgReader, CLuaArgument, and CLuaArguments
Replaces multitheftauto#1728
Fixes multitheftauto#321
@MohabCodeX MohabCodeX changed the title feat(lua): implement native 4d vector datatype with simd acceleration Implement Native Lua Vector Datatype Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Vectors are incredibly slow

1 participant