Wizards of Lua

The Art of Spell Crafting

---

Vec3 - Manipulating Location and Motion

An instance of the Vec3 class represents a ‘3-dimensional Vector’.

Mostly a 3-dimensional vector is used to denote a position in the 3-dimensional world space or a constant velocity of an object inside that space.

However, a vector can be used for many other ‘things’ that can be described by 3 independent numerical values.

To create a vector you can call the Vec3 function:

myvec = Vec3( 1, 2, 3)

This creates a vector called ‘myvec’ with the component values x=1, y=2, z=3.

Here is an overview of the Vec3 properties:

Here is an overview of the Vec3 functions:

Properties

Below you find short descriptions about each of the properties and some examples about how to use them in your spells.

x : number

The X-component of the vector

y : number

The Y-component of the vector

z : number

The Z-component of the vector

Functions

Below you find short descriptions about each of the functions and some examples about how to use them in your spells.

add (other) -> Vec3

Returns a new vector that is the result of adding the other vector to the current vector.

Example

Adding two vectors.

local p1 = Vec3( 1, 0, 8)
local p2 = Vec3( -1, 2, 3)
local p3 = p1:add( p2)

Since add() is also used as __add of Vec3’s metatable, you can shorten the above example by using the + operator.

local p1 = Vec3( 1, 0, 8)
local p2 = Vec3( -1, 2, 3)
local p3 = p1 + p2

chunk () -> number, number

The ‘chunk’ function interprets this vector as world coordinate, converts them into chunk coordinates, and returns them as a multi-value result.

Example

Converting the spell’s world coordinates into chunk coordinates.

local chunkX, chunkZ = spell.pos:chunk()

dotProduct (other) -> Vec3

Returns the ‘dot’ product of the current vector and the other vector.

Example

Creating the dot-product of two vectors.

local p1 = Vec3( 5, 4, 3)
local p2 = Vec3( 2, 4, 6)
local p3 = p1:dotProduct( p2)

Since dotProduct() is also used in __mul of Vec3’s metatable, you can shorten the above example by using the * operator.

local p1 = Vec3( 5, 4, 3)
local p2 = Vec3( 2, 4, 6)
local p3 = p1 * p2

invert () -> Vec3

Returns an inverted version of the current vector.

Example

Inverting a vector.

local p1 = Vec3( 5, 2 , -1)
local p2 = p1:invert()

Since invert() is also used as __unm of Vec3’s metatable, you can shorten the above example.

local p1 = Vec3( 5, 2 , -1)
local p2 = - p1

magnitude () -> Vec3

Returns the length of the current vector.

Example

Getting the length of a vector.

local p = Vec3( 2, 3, 4)
local len = p:magnitude()

normalize () -> Vec3

Returns a normalized version of the current vector, which means a vector with a magnitude of 1 meter and pointing into the same direction as the original vector.

Example

Normalizing a vector.

local vec = Vec3( 2, 3, 4)
local normalizedVec = vec:normalize()

scale (factor) -> Vec3

Returns a copy of current vector, scaled by the given factor.

Example

Scaling a vector by 3.

local p1 = Vec3( 11, 22, 33)
local p2 = p1:scale( 3)

Since scale() is also used as __mul of Vec3’s metatable, you can shorten the above example.

local p1 = Vec3( 11, 22, 33)
local p2 = p1 * 3

sqrMagnitude () -> Vec3

Returns the squared length of the current vector.

Example

Getting the ‘squared’ length of a vector.

local p = Vec3( 2, 3, 4)
local slen = p:sqrMagnitude()

substract (other) -> Vec3

Returns a new vector that is the result of substracting the other vector from the current vector.

Example

Substracting two vectors.

local p1 = Vec3( 5, 4, 3)
local p2 = Vec3( 2, 4, 6)
local p3 = p1:substract( p2)

Since substract() is also used as __sub of Vec3’s metatable, you can shorten the above example by using the - operator.

local p1 = Vec3( 5, 4, 3)
local p2 = Vec3( 2, 4, 6)
local p3 = p1 - p2

tostring () -> string

Returns a string with the following format ‘(x, y, z)’.

Example

Printing the vector using tostring().

local p = Vec3( 11, 22, 33)
print( p:tostring() )

Since tostring() is also used as __tostring of Vec3’s metatable, you can shorten the above example.

local p = Vec3( 11, 22, 33)
print( p)