Add vector2 lua API for 2D vectors

[kromka-chleba]

Goal of the PR

This pull request introduces a new lua API for 2D vectors (vector2)

Does it resolve any reported issue?

Part of this #16921

If you have used an LLM/AI to help with code or assets, you must disclose this.

The whole PR is AI slop.

To do

This PR is Ready for Review

• The game compiles and starts
• Test if this works
• Add testing info
• Read unit tests instead of trusting AI

How to test

Example code

-- example_vector2_corelog.lua
-- Demonstrates common usages of the vector2 API,
-- logging vectors with core.log("error", dump(v))
-- Adjust require path / environment as needed (vector2, core, dump must be available)

local vector2 = vector2
local pi = math.pi

-- Create vectors
local a = vector2.new(3, 4)               -- (3, 4)
local b = vector2.from_polar(2, pi / 4)   -- length 2 at 45°

core.log("action", "a = " .. dump(a))
core.log("action", "b = " .. dump(b))

-- Length and normalization
core.log("action", "length(a) = " .. a:length())
local an = a:normalize()
core.log("action", "normalized a = " .. dump(an) .. " length = " .. an:length())

-- Arithmetic (method or operator)
local sum = a + b                         -- operator overload
core.log("action", "a + b = " .. dump(sum))

local scaled = sum * 0.5                  -- scale by scalar
core.log("action", "scaled (sum * 0.5) = " .. dump(scaled))

-- Polar conversion
local r, theta = scaled:to_polar()
core.log("action", string.format("scaled in polar: r=%.3f, theta=%.3f rad", r, theta))

-- Rotation
local rotated = vector2.rotate(a, pi / 2) -- rotate a by 90° CCW
core.log("action", "a rotated 90° = " .. dump(rotated))

-- Direction & distance
local dir = vector2.direction(a, b)
core.log("action", "direction a -> b = " .. dump(dir) .. " length = " .. dir:length())
core.log("action", "distance(a, b) = " .. vector2.distance(a, b))

-- Parsing and tostring
local parsed, next_pos = vector2.from_string("(1.5, -2.25)")
if parsed then
  core.log("action", "parsed vector: " .. dump(parsed) .. " next_pos: " .. tostring(next_pos))
else
  core.log("action", "failed to parse vector string")
end

-- Area helpers
local vmin, vmax = vector2.sort(vector2.new(0, 0), vector2.new(5, 5))
local inside = vector2.in_area(vector2.new(3, 3), vmin, vmax)
core.log("action", "is (3,3) inside (0,0)-(5,5)? " .. tostring(inside))

-- Random helpers
local rand_dir = vector2.random_direction()
core.log("action", "random unit direction: " .. dump(rand_dir) .. " len=" .. rand_dir:length())

local rand_pos = vector2.random_in_area(vmin, vmax)
core.log("action", "random integer position in area: " .. dump(rand_pos))

-- Utility functions: apply, combine, abs
local abs_a = vector2.apply(a, math.abs)
core.log("action", "abs(a) = " .. dump(abs_a))

local prod = vector2.combine(a, b, function(x, y) return x * y end)
core.log("action", "component-wise product a*b = " .. dump(prod))

-- Zero and check
local z = vector2.zero()
core.log("action", "zero vector: " .. dump(z) .. " is vector2? " .. tostring(vector2.check(z)))

-- Done
local v = vector2.new(1, 2)
core.log("action", dump(v))

Read the documentation and try it out I guess, there are also unit tests.
I could provide some better instructions later.

[appgurueu]

Dunno how to feel about AI slop, but for the sake of it, I took a quick look:

• Why is it inheriting all the deprecations from vector?
• The from/to 3d conversions are a bit nonsensical, imo: There is no practical reason why the extension should always be done with z = 0. I would prefer to avoid such conversions for now.
  • If we are to have them, which axes x and y map to should be variable (and hence which axis is dropped).
  • At which point we might as well omit the constructors and tell people to use vector.new?
• I'm missing polar coordinates and signed angles

[appgurueu]

Oh also: push_v2* should probably be updated to push vectors with the proper metatable.

[kromka-chleba]

Why is it inheriting all the deprecations from vector?

These models love boilerplate code. I will fix it.
Also you mean deprecated upstream or in your not yet merged PR?

The from/to 3d conversions are a bit nonsensical, imo: There is no practical reason why the extension should always be done with z = 0. I would prefer to avoid such conversions for now.

This was actually my idea but then I considered it may be a bit stupid. So it's probably better to let the user decide?

I'm missing polar coordinates and signed angles

I'll look into this.

[kromka-chleba]

Also probably off-topic but when I asked about your AI policy I got this:

<ireallyhateirc> is making a PR made with Github Copilot fine as long as the code works and is documented?
<rubenwardy> our AI policy can be found in the contributing.md
<rubenwardy> tl;dr   (1) you must disclose     (2) it's fine but you are responsible for the change like any other - "but the AI wrote it" is no excuse

Unless this was actually for ContentDB and not Luanti.
As for this change - this is a trivial change and vectors shouldn't be even copyrightable in 2026. I would have written it 90% the same manually but it'd take me instead 1 or 2 days to implement, perhaps with hidden bugs.
I believe it is fine to take such shortcuts so that you can spend your time coding high-impact features and I can spend time writing my game rather than implementing basic API functionality.

[kromka-chleba]

Okay so I hopefully addressed the points about deprecated functionality and bad/misleading conversion functions.
What's left to do is to implement this: polar coordinates and signed angles
Should angles be in radians or degrees?

EDIT: Forgot to address this: push_v2* should probably be updated to push vectors with the proper metatable.
EDIT2: Addressed that, this touches C++ code so my ability to verify correctness is limited. Though I assume it's to convert C++ vectors to Lua vectors and the code seems to be using similar conventions to what 3D vectors use

[kromka-chleba]

Okay so we implemented these polar coordinates and signed angles. I see that the solution for signed angles is a bit verbose and perhaps instead we should use something more compact like this equation? https://wumbo.net/formulas/angle-between-two-vectors-2d/

[appgurueu]

There should be no problem with our AI policy in principle. The only thing this clearly "rips off" is the permissively licensed 3d vector implementation, so I don't think there is a substantial copyright concern here.

Personally reviewing a larger AI generated PR is a bit of a new a thing for me, but so far the quality seems to be acceptable so I don't mind it too much.

Perhaps the only substantial concern is one of PR (as in public relations, not pull request, hah): People who are avidly anti-AI might take an issue with us merging largely AI-generated PRs (even if they are of acceptable quality). 🤷

---

As for the signed angles, the core of the implementation (compute angle of both vectors via atan2, take difference) seems reasonable to me. I don't feel strongly about the "normalization", personally I feel like a simple % (2 * math.pi) would be decent?

---

So it's probably better to let the user decide?

The user ultimately needs to decide on which plane the coordinates lie in, yes. (Judging e.g. by the earlier "vector.flat" PR and similar, I feel like x-z would be pretty decent for many applications with mobs and such, but still there is no simple "general rule" and modders need to be explicit.)

[kromka-chleba]

The API mentions counterclockwise operations for example in vector2.rotate. Is this fine?
Personally I'd expect clockwise rotation. Is this a convention?

[appgurueu]

The API mentions counterclockwise operations for example in vector2.rotate. Is this fine? Personally I'd expect clockwise rotation. Is this a convention?

Rotations in mathematics are typically counterclockwise. So rotating (1, 0) by 90° gives you (0, 1) for example. By these conventions, the formula for the point on the unit circle for a given angle is just x = cos(angle), y = sin(angle), which is what I would expect.

So I think it's fine.

[appgurueu]

Did you review the unit tests yet? The checkbox in your PR description is still unchecked, which has sparked some concerns in the dev IRC (https://irc.luanti.org/luanti-dev/2026-02-17#i_6314948).

(I have reviewed them in full, but just to be sure you should too.)

[kromka-chleba]

Did you review the unit tests yet? The checkbox in your PR description is still unchecked, which has sparked some concerns in the dev IRC (https://irc.luanti.org/luanti-dev/2026-02-17#i_6314948).

I did skim through them but did not do a proper review (was busy IRL).
I could do this today. Though I do not expect any serious problems there if you already approved them?

[appgurueu]

Do it whenever you have the time.

I could do this today. Though I do not expect any serious problems there if you already approved them?

Hopefully not, but I also make mistakes. It is expected that you review code you contribute.

It might also make the second reviewer's job a bit easier if they know there have already been two pairs of eyes on the code.

[kromka-chleba]

Okay I did read all the tests, they look correct and I did check the angle operations, distance logic, etc. manually. Found one case where the test is correct but could be cleaner.

[kromka-chleba]

I'll retest the feature in the game and reread the implementation once again to avoid more complaints towards my precious slop. Though the tests look reasonable and pass, which already means the implementation is fairly decent.

[kromka-chleba]

Looks authentic and still works in the game.

[kromka-chleba]

Will address the review later (not today).

[kromka-chleba]

sfan5 review hopefully addressed.
TODO: recheck if everything works in the game

[sfan5]

lgtm with changes

[Zughy]

I'm sorry but, @kromka-chleba you seriously had to ask Copilot to fix the documentation instead of doing that yourself? Like, the heck, it required not even 5 minutes, this is ridiculous. We did the homework for you, you only had to implement it. I'm honestly baffled and saddened at the same time; don't expect more reviews from me

[kromka-chleba]

I'm sorry but, @kromka-chleba you seriously had to ask Copilot to fix the documentation instead of doing that yourself?

No but I'm lazy. The time to fetch the latest version from git, edit it without making mistakes, and push again would be the same or more.

Like, the heck, it required not even 5 minutes, this is ridiculous.

What difference does it make? I spent 10 seconds on typing a prompt for this trivial change. Doing it manually doesn't make it any more meaningful or correct.
Without Copilot I'd do it with Emacs or sed and I know how to handle git.

We did the homework for you, you only had to implement it.

What homework, I know Lua and I know git. There's nothing to learn here.
Also that's not how it works. My preferred version was plain, duplicated documentation. People wanted me to cover things in a common section and so I did. Then you came and asked me to refine it further, and so I did (well actually the AI did it, doesn't matter).

I'm honestly baffled and saddened at the same time; don't expect more reviews from me

If there's a problem with certain tools in Luanti development then make it your official policy rather than punishing people for implementing features.

I have ADHD which makes it hard to focus on coding and I also have dyslexia which results in dumb typos and painful debugging. Copilot gets shit done and actually makes fewer mistakes than me. Probably also wastes less electricity than me wiggling on my chair for 2 weeks and recompiling buggy human-made code.

Now I wasted 20 minutes typing this post instead of spending time with friends and/or working on my Master's. If using AI is a problem then just disallow AI contributions and I'll stop.

EDIT: Also if the code devs who approved this PR think this was more work to review compared to a 100% human-made PR then say so. I personally believe I'd make similar mistakes or worse and it'd take more or equal time. But yeah, I don't want to give you more work than needed so if this was actually more work then I'll stop with AI PRs.

[Zughy]

then make it your official policy rather than punishing people for implementing features

That's my personal point of view, not Luanti team's as a whole

I have ADHD which makes it hard to focus on coding and I also have dyslexia which results in dumb typos and painful debugging

You had to get rid of "/ vector2.foo" in every line, how does ADHD and dyslexia impact that? Genuinely curious

[kromka-chleba]

You had to get rid of "/ vector2.foo" in every line, how does ADHD and dyslexia impact that? Genuinely curious

ADHD: I've been procrastinating most coding tasks for months and even years. This is because to focus on a task it needs to provide a decent dopamine feedback loop. Artistic tasks provide that, for example 3D modeling in Blender. Ordinary coding also does that, but less. That's why I've been primarily 3D modeling for my game for 2 years instead of coding. I've lately discovered that Github provides a free Copilot Pro for students and I tried it. The prompt-read-verify-correct loop provides dopamine boosts which keep me focused for hours (hyperfocus). Thanks to Copilot got back to the coding tasks I've been procrastinating (mostly luanti games) and also revisited my TODO list of features for Luanti I need for my personal projects.
That's for interesting tasks, for boring tasks and chores it takes between 1-3 hours of wiggling on chair to get started. People with ADHD usually need strong stimuli to get started, for chores that's stress and deadlines. I'm not taking any ADHD medicines because they're both expensive and are not free from side effects, so what's left are behavioral workarounds.
Getting tasks done is my priority, the way leading to that is secondary.

dyslexia: less frequent when I use english, which is not my native language. In coding that boils down to typos such as length -> lenght, width -> widht, etc. I also swap letters p - b, d - t, s - z, etc. Additionally I tend to skip verbs and other syntax features. In coding that results in syntax errors or more complex bugs when the typos are non-trivial. Long debugging sessions waste time and discourage me from coding. Copilot so far makes few mistakes of that type.

So thanks to Copilot I can actually focus on designing the interface and high-level features rather than typing buggy code manually. Reviewing AI code and testing it in the game is also more interesting and stimulating.

EDIT: seems like I did not answer the question in the end due to focus defficiency lol. As for this exact task - prompting this is faster and less error prone. The first obstacle for this exact task would be getting motivation and focus, then I'd need to grep each piece and run the Emacs command for replacement. Misclicking something could result in skipping something or inserting an unneeded character which I could miss during reviewing my own code. I just accepted Copilot is better than me on simple tasks. It's english is also often way better. So faster, less error prone.

[Zughy]

Thanks for clarifying. I've never thought of these tools like helping tools for people with ADHD/dyslexia and I thought that, considering the initial "The whole PR is AI slop", it was only a huge displaying of laziness. I'm sorry for jumping the gun and for what I've said