[Basic Type](../groups/Basic Type.Basic Type.md) / Vector2

Vector2 Class ​

Two-dimensional vector

Linear algebra is highly suitable for game development, and here are some brief yet practical introductions. If you are already familiar with it, you can skip it directly.

This is not a formal official on linear algebra. We will only look at how it is applied to game development. If you want to have a broader understanding of mathematics, please refer to https://www.khanacademy.org/math/linear-algebra

🌵 Coordinate System (2D)

In two-dimensional space, coordinates are determined using the horizontal axis (x) and vertical axis (y). A specific position in 2D space is written as a pair of values, such as (9,5)

Note: If you are not familiar with computer graphics, the y-axis points downwards instead of upwards. Because what you may have learned in math class is pointing upwards. However, in most computer graphics applications, the y-axis points downwards.

In this way, any position on the two-dimensional plane can be identified by a pair of numbers. However, we can also consider position (9,5) as the offset from point (0,0) or the origin. Draw an arrow pointing from the origin to that point:

This is a vector. Vectors represent a lot of useful information. In addition to telling us that the point is located at (9,5), we can also consider it as the angle θ (theta) and length (or size) m. In this case, the arrow is a position vector - it represents the position in space relative to the origin.

A very important point to consider about vectors is that they only represent relative direction and magnitude. There is no concept of vector position. The following two vectors are the same:

Both vectors represent points 9 units to the right and 5 units below a starting point. No matter where you draw a vector on the plane, it always represents relative direction and magnitude.

🌵 Vector operation

You can use any method (x and y coordinates or angle and size) to reference vectors, but for convenience, programmers typically use coordinate notation. For example,

Usage example: create a script named NewExample, place it in the object bar, open the script, modify the original content to the following content, press "F", and the button will move to the position of (900500).

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
         if (!SystemUtil.isClient()) return;
         this.test();
     }

     private async test(): Promise<void> {
         let btn = new ButtonUI();

         InputUtil.onKeyDown(Keys.F, async () => {
             let result = new Vector2(900,500)
             if (result) {
                 btn.button.position = result;
             }
         })
     }

 }

 class ButtonUI {
     public button: StaleButton;

     constructor(fun: Function = null) {
         this.creatUI(fun);
     }

     private creatUI(fun: Function = null) {
         // Create a UI object
         let ui = UserWidget.newObject();
         // Add UI to screen
         ui.addToViewport(1);
         // Create a canvas component
         let rootCanvas = Canvas.newObject();
         rootCanvas.size = new Vector2(1920, 1080);
         rootCanvas.position = Vector2.zero;
         // Set Ui's root canvas to rootCanvas
         ui.rootContent = rootCanvas;
         // Create a button at point (0,0)
         this.button = StaleButton.newObject(rootCanvas);
         this.button.position = new Vector2(0, 0);
         this.button.size = new Vector2(100, 100);
         this.button.setNormalImageColorDecimal(0,255,0,255)
         this.button.text = "btn";
         this.button.transitionEnable = true;
         this.button.pressedImagColor = LinearColor.red;
         this.button.visibility = SlateVisibility.Visible;

         this.button.onClicked.add(() => {
             if (fun) {
                 fun();
             }
         })
     }
 }

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
         if (!SystemUtil.isClient()) return;
         this.test();
     }

     private async test(): Promise<void> {
         let btn = new ButtonUI();

         InputUtil.onKeyDown(Keys.F, async () => {
             let result = new Vector2(900,500)
             if (result) {
                 btn.button.position = result;
             }
         })
     }

 }

 class ButtonUI {
     public button: StaleButton;

     constructor(fun: Function = null) {
         this.creatUI(fun);
     }

     private creatUI(fun: Function = null) {
         // Create a UI object
         let ui = UserWidget.newObject();
         // Add UI to screen
         ui.addToViewport(1);
         // Create a canvas component
         let rootCanvas = Canvas.newObject();
         rootCanvas.size = new Vector2(1920, 1080);
         rootCanvas.position = Vector2.zero;
         // Set Ui's root canvas to rootCanvas
         ui.rootContent = rootCanvas;
         // Create a button at point (0,0)
         this.button = StaleButton.newObject(rootCanvas);
         this.button.position = new Vector2(0, 0);
         this.button.size = new Vector2(100, 100);
         this.button.setNormalImageColorDecimal(0,255,0,255)
         this.button.text = "btn";
         this.button.transitionEnable = true;
         this.button.pressedImagColor = LinearColor.red;
         this.button.visibility = SlateVisibility.Visible;

         this.button.onClicked.add(() => {
             if (fun) {
                 fun();
             }
         })
     }
 }

1. Vector Members

The various components of a vector can be directly accessed by name.

Usage example: Access vector

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(9, 5);
        console.log("x:" +a.x+ "  y:"+a.y);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(9, 5);
        console.log("x:" +a.x+ "  y:"+a.y);
     }
}

2. Add Vector

When two vectors are added or subtracted, the corresponding components are added or subtracted:

Example usage: Adding two vectors together

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,3);
        let result = Vector2.add(a,b);
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,3);
        let result = Vector2.add(a,b);
        console.log(result);
     }
}

Note that adding a+b will yield the same result as adding b+a.

3. Scalar multiplication

Vectors represent direction and magnitude. Values that only represent size are called scalars. Scalars use the float type in the editor.

Vectors can be multiplied by scalars:

Usage example: a * b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.multiply(a,3);
        // X=24, Y=6
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.multiply(a,3);
        // X=24, Y=6
        console.log(result);
     }
}

Multiplying a vector by a scalar does not change its direction, only its magnitude. Multiplying with a negative scalar will produce a vector in the opposite direction. This is the method of scaling vectors.

4. Unit vector

A vector of size 1 is called a unit vector. They are sometimes referred to as direction vectors or normals. Unit vectors are useful when you need to track direction.

5. normalization

Vector normalization means reducing its length to 1 while preserving its direction. This is done by dividing each component by its size. This is a common operation, for which a dedicated normalized() method is provided:

Usage example: achieve normalization for a vector.

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.normalize(a);
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.normalize(a);
        console.log(result);
     }
}

Due to the fact that normalization involves dividing by the length of the vector, it is not possible to normalize vectors with a length of 0. Attempting to do so often leads to errors.

6. reflex

The common use of unit vectors is to represent normals. The normal vector is the unit vector arranged vertical to the surface, defining its direction. They are commonly used for lighting, collision, and other operations involving surface.

Usage example: calculate the reflection vector.

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(1,0);
        let result = Vector2.reflect(a,b);
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(1,0);
        let result = Vector2.reflect(a,b);
        console.log(result);
     }
}

7. Dot product

Dot product is one of the most important concepts in vector mathematics, but it is often misunderstood. Dot product is an operation performed on two vectors that returns a scalar. Unlike vectors that contain both magnitude and direction, scalar values only have magnitude.

The mathematical symbol | | A | | represents the size of vector A, and Ax represents the x-component of vector A.

In most cases, using the built-in dot method is the simplest. Please note that the order of the two vectors is not important:

Example usage: Find dot product.

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(1,0);
        let result = Vector2.dot(a,b);
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(1,0);
        let result = Vector2.dot(a,b);
        console.log(result);
     }
}

The dot product is most useful when used with the unit vector, simplifying the first formula to cos (θ). This means that we can use dot product to tell us information about the angle between two vectors:

When using unit vectors, the result will always be between -1 (180 °) and 1 (0 °).

8. Cross product

Like dot product, cross product is an operation on two vectors. However, the result of cross product is a vector with one direction vertical to both. Its size depends on their relative angles. If two vectors are parallel, the result of their cross product will be a zero vector.

The cross product calculation is as follows:

Example usage: Calculate the cross product.

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(1,0);
        let result1 = Vector2.cross(a,b);
        let result2 = Vector2.cross(b,a);
        console.log(result1);
        console.log(result2);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(1,0);
        let result1 = Vector2.cross(a,b);
        let result2 = Vector2.cross(b,a);
        console.log(result1);
        console.log(result2);
     }
}

Order is important. Cross (a, b) will not give the same result as cross (b, a). The obtained vector points in the opposite direction.

Table of contents ​

Properties ​

Accessors ​

Methods ​

Construct a new Vector2 using the given x and y components

Parameters ​

• new Vector2(f)

Set x and y with the given value of f

Parameters ​

Properties ​

x ​

• x: number

The x-component of a vector

y ​

• y: number

The y-component of a vector

Accessors ​

length ​

magnitude ​

• get magnitude(): number

Calculate the length of a vector

Parameters ​

Returns ​

negative ​

normalized ​

sqrLength ​

sqrMagnitude ​

• get sqrMagnitude(): number

Calculate the length square of a vector

Parameters ​

Returns ​

negOne ​

one ​

unitX ​

unitY ​

zero ​

Methods ​

add ​

• add(v): Vector2 other

Add a vector

Parameters ​

Returns ​

Parameters ​

Returns ​

clone ​

• clone(): Vector2 other

Parameters ​

Returns ​

divide ​

Returns ​

• divide(v): Vector2 other

Divide by a vector

Parameters ​

Returns ​

• Static divide(a, b, outer?): Vector2 other

Vector a divided by vector b

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: a/b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,4);
        let result = Vector2.multiply(a,4);
        // X=4, Y=0.5
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,4);
        let result = Vector2.multiply(a,4);
        // X=4, Y=0.5
        console.log(result);
     }
}

Parameters ​

Returns ​

Parameters ​

Returns ​

Multiply by a vector

Parameters ​

Returns ​

• multiply(v): Vector2 other

Multiply by a scalar

Parameters ​

Returns ​

normalize ​

• normalize(): Vector2 other

Normalize the current vector

Parameters ​

Returns ​

Returns ​

Set the current vector to be equal to the specified vector

Parameters ​

Returns ​

• set(x?, y?): Vector2 other

Set the specific component values of the current vector

Parameters ​

Returns ​

strictEquals ​

• strictEquals(other): boolean other

Determine whether the current vector is equal to the specified vector

Parameters ​

Returns ​

subtract ​

• subtract(v): Vector2 other

Subtract a vector

Parameters ​

Returns ​

Parameters ​

Returns ​

toString ​

• toString(): string other

Returns ​

add ​

Add two vectors together

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: a+b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,3);
        let result = Vector2.add(a,b);
        // X=11, Y=5
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,3);
        let result = Vector2.add(a,b);
        // X=11, Y=5
        console.log(result);
     }
}

Parameters ​

Returns ​

angle ​

• Static angle(a, b): number other

Angle between two vectors

Parameters ​

Returns ​

ceil ​

• Static ceil(a, outer?): Vector2 other

Each element of vector a is rounded up

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: upward rounding example

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8.22, 2.69);
        let result = Vector2.ceil(a);
        // X=9, Y=3
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8.22, 2.69);
        let result = Vector2.ceil(a);
        // X=9, Y=3
        console.log(result);
     }
}

clamp ​

• Static clamp(v, min, max): Vector2 other

Set the value of the current vector so that all its components are within the specified range

Parameters ​

Returns ​

clone ​

• Static clone(a): Vector2 other

Clone vector a to obtain a new Vector2 vector

Parameters ​

Returns ​

copy ​

• Static copy(a, outer?): Vector2 other

Obtain a copy of the specified vector

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

cross ​

• Static cross(a, b): number other

Cross product

Parameters ​

Returns ​

distance ​

• Static distance(a, b): number other

Euclidean distance between two vectors

Parameters ​

Returns ​

divide ​

• Static divide(a, b, outer?): Vector2 other

Divide each component of vector a by scalar b

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: a/b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.multiply(a,4);
        // X=2, Y=0.5
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.multiply(a,4);
        // X=2, Y=0.5
        console.log(result);
     }
}

Parameters ​

Returns ​

• Static divide(a, b, outer?): Vector2 other

Vector a divided by vector b

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: a/b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,4);
        let result = Vector2.multiply(a,4);
        // X=4, Y=0.5
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,4);
        let result = Vector2.multiply(a,4);
        // X=4, Y=0.5
        console.log(result);
     }
}

Parameters ​

Returns ​

dot ​

• Static dot(a, b): number other

Dot product

Parameters ​

Returns ​

equals ​

• Static equals(a, b, epsilon?): boolean other

Determine whether two vectors are approximately equivalent in excluding floating-point errors

Parameters ​

Returns ​

floor ​

• Static floor(a, outer?): Vector2 other

Rounding down each element of vector a

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

fromString ​

• Static fromString(str, outer?): Vector2 other

Create Vector2 object through a string

Parameters ​

Returns ​

Example of string format: "X=2, Y=3"

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: create a vector using string

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let result = Vector2.fromString("X=2,Y=3");
        // X=2, Y=3
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let result = Vector2.fromString("X=2,Y=3");
        // X=2, Y=3
        console.log(result);
     }
}

invert ​

• Static invert(a, outer?): Vector2 other

Take the reciprocal of each element vector

Parameters ​

Returns ​

Return Infinity when approaching 0.

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

invertSafe ​

• Static invertSafe(a, outer?, epsilon?): Vector2 other

Take the reciprocal of each element vector

Parameters ​

Returns ​

When approaching 0, return 0

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

lerp ​

• Static lerp(a, b, t, outer?): Vector2 other

Linear interpolation for each element of vector a: a+t * (b-a)

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

magnitude ​

• Static magnitude(a): number other

Vector length

Parameters ​

Returns ​

max ​

• Static max(a, b, outer?): Vector2 other

Take the minimum and maximum values of the x and y elements corresponding to two vectors

Parameters ​

Returns ​

min ​

• Static min(a, b, outer?): Vector2 other

Take the minimum value of x and y elements corresponding to two vectors

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

moveTowards ​

• Static moveTowards(current, target, maxDistanceDelta, outer?): Vector2 other

Move to target

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

multiply ​

• Static multiply(a, b, outer?): Vector2 other

Multiply each component of vector a by scalar b

Parameters ​

Returns ​

• Static multiply(a, b, outer?): Vector2 other

Multiply vector a by vector b

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: a * b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,4);
        let result = Vector2.multiply(a,b);
        // X=24, Y=8
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,4);
        let result = Vector2.multiply(a,b);
        // X=24, Y=8
        console.log(result);
     }
}

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Usage example: a * b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.multiply(a,3);
        // X=24, Y=6
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let result = Vector2.multiply(a,3);
        // X=24, Y=6
        console.log(result);
     }
}

negate ​

• Static negate(a, outer?): Vector2 other

Each element vector takes a negative value

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

normalize ​

• Static normalize(a, outer?): Vector2 other

Vector normalization

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Parameters ​

Returns ​

project ​

• Static project(a, b, outer?): Vector2 other

The projection of vector a onto vector b

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

random ​

• Static random(range?): Vector2 other

Generate a random Vector2 object with uniform distribute on the unit circle

Parameters ​

Returns ​

reflect ​

• Static reflect(inDirection, inNormal, outer?): Vector2 other

reflex

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

rotate ​

• Static rotate(v, radians, outer?): Vector2 other

The vector a rotated by a certain degree

Parameters ​

Returns ​

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

round ​

• Static round(a, outer?): Vector2 other

Each element is rounded to rounding

Parameters ​

Returns ​

set ​

• Static set(a, x, y): Vector2 other

Set the value of vector a

Parameters ​

Returns ​

signAngle ​

• Static signAngle(a, b): number other

The signed angle between vector a and vector b

Parameters ​

Returns ​

sqrMagnitude ​

• Static sqrMagnitude(a): number other

Square of vector length

Parameters ​

Returns ​

squaredDistance ​

• Static squaredDistance(a, b): number other

The squared Euclidean distance between two vectors

Parameters ​

Returns ​

strictEquals ​

• Static strictEquals(a, b): boolean other

Determine whether two vectors are equal

Parameters ​

Returns ​

subtract ​

• Static subtract(a, b, outer?): Vector2 other

Subtract vector b from vector a

outer It is an optional parameter. The function is that when an outer is passed in, the calculation result will be assigned to the outer. (The incoming outer vector cannot be null/undefined)

Example usage: a-b

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,3);
        let result = Vector2.subtract(a,b);
        // X=5, Y=-1
        console.log(result);
     }
}

@Component
 export default class NewExample extends Script {

     protected onStart(): void {
        let a = new Vector2(8,2);
        let b = new Vector2(3,3);
        let result = Vector2.subtract(a,b);
        // X=5, Y=-1
        console.log(result);
     }
}

Parameters ​

Returns ​