Quaternionf

APJS Script API reference for the Quaternionf class.

Type	Name	Interface Description
Variables	w: number	• Function: The w component of the quaternion, representing the scalar part in a 4-dimensional space.
Variables	x: number	• Function: Represents the x component of the quaternion, which is a part of the Quaternionf object used to describe rotations in 3D space.
Variables	y: number	• Function: Represents the y component of the quaternion in a Quaternionf object.
Variables	z: number	• Function: Represents the z component of the quaternion in a Quaternionf object.
Functions	constructor()
Functions	constructor(x?: number, y?: number, z?: number, w?: number)	Parameters • x: - The x component of the quaternion (optional). • y: - The y component of the quaternion (optional). • z: - The z component of the quaternion (optional). • w: - The w component of the quaternion (optional).
Functions	clone(): Quaternionf	• Function: Creates and returns a clone of the current Quaternionf instance. Returns A new Quaternionf object with the same values as the original.
Functions	dot(other: Quaternionf): number	• Function: Returns the dot product of the current quaternion with another quaternion. Parameters • other: - The quaternion to calculate the dot product with. Returns The dot product as a number.
Functions	equals(other: Quaternionf): boolean	• Function: Returns whether this quaternion is equal to the specified quaternion. Parameters • other: - The quaternion to compare with. Returns A boolean indicating whether the two quaternions are equal.
Functions	getAngle(): number	• Function: Returns the rotation angle of the quaternion. Returns The rotation angle in radians.
Functions	getAxis(): Vector3f	• Function: Returns the rotation axis of the quaternion. Returns The rotation axis as a Vector3f object.
Functions	inverse(): this	• Function: Returns an inverted version of the Quaternionf by negating its x, y, and z components. Returns The current instance of Quaternionf with inverted values.
Functions	multiply(other: Quaternionf): Quaternionf	• Function: Multiplies this quaternion by another quaternion other and updates the current quaternion with the result. Parameters • other: - The quaternion to multiply with. Returns This quaternion after multiplication.
Functions	multiplyVector(other: Vector3f): Vector3f	• Function: Returns the result of rotating direction vector other by this quaternion. Parameters • other: - The vector to be rotated. Returns A new Vector3f representing the rotated vector.
Functions	normalize(): Quaternionf	• Function: Normalizes the quaternion, ensuring it has a unit length. If the quaternion's length is zero, it sets the quaternion to (0, 0, 0, 1). Otherwise, it scales the quaternion components so that its length becomes one. Returns The quaternion instance after normalization.
Functions	set(x: number, y: number, z: number, w: number): this	• Function: Sets the quaternion data with the specified x, y, z, and w components. Parameters • x: - The x component of the quaternion. • y: - The y component of the quaternion. • z: - The z component of the quaternion. • w: - The w component of the quaternion. Returns This instance of Quaternionf with updated values.
Functions	toEulerAngles(): Vector3f	• Function: Converts the quaternion to an Euler angle representation in radians. Returns A vector containing the Euler angles (pitch, yaw, roll) in radians.
Functions	toString(): string	• Function: Returns a string representation of the quaternion. Returns A string representation of the quaternion in the format "Quaternionf(x, y, z, w)".
Static Functions	angleBetween(a: Quaternionf, b: Quaternionf): number	• Function: Returns the angle between two quaternions a and b. Parameters • a: - The first quaternion. • b: - The second quaternion. Returns The angle in radians between the two quaternions.
Static Functions	identity(): Quaternionf	• Function: Returns the identity quaternion. Returns The identity quaternion represented as a Quaternionf object.
Static Functions	lerp(a: Quaternionf, b: Quaternionf, t: number): Quaternionf	• Function: Returns a new quaternion linearly interpolated between two quaternions. Parameters • a: The first quaternion. • b: The second quaternion. • t: The interpolation factor, typically ranging from 0 to 1. Returns A new quaternion representing the linear interpolation.
Static Functions	lookAt(forward: Vector3f, up: Vector3f): Quaternionf	• Function: Returns a new Quaternionf that represents the rotation needed to look in the direction of the forward vector with the specified up vector. Parameters • forward: - The forward direction vector. • up: - The upward direction vector. Returns A new Quaternionf representing the orientation.
Static Functions	makeFromAngleAxis(angle: number, axis: Vector3f): Quaternionf	• Function: Returns a new quaternion with the specified angle and axis. Parameters • angle: - The rotation angle in radians. • axis: - The axis of rotation as a Vector3f object. Returns A new Quaternionf representing the rotation.
Static Functions	makeFromEulerAngles(eulerVec: Vector3f): Quaternionf	• Function: Returns a new quaternion using the Euler angles provided in eulerVec (in radians). Parameters • eulerVec: - A Vector3f representing the Euler angles in radians. Returns A new Quaternionf created from the given Euler angles.
Static Functions	rotationFromTo(from: Vector3f, to: Vector3f): Quaternionf	• Function: Returns a rotation quaternion that represents the shortest arc rotation from one direction vector to another. Parameters • from: The initial direction vector. • to: The target direction vector. Returns A quaternion representing the rotation.
Static Functions	slerp(a: Quaternionf, b: Quaternionf, t: number): Quaternionf	• Function: Returns a new Quaternionf spherically linearly interpolated between a and b. Parameters • a: - The starting Quaternionf. • b: - The ending Quaternionf. • t: - The interpolation factor, typically ranging from 0 to 1. Returns A new Quaternionf representing the spherical linear interpolation between a and b.

Examples

constructor()

let obj = new APJS.Quaternionf();

constructor(x?: number, y?: number, z?: number, w?: number)

let obj = new APJS.Quaternionf();

Use Case

Example 1 — 3D physics: tap anywhere to apply an upward impulse to a RigidBody object.

@component()
export class TapImpulse extends APJS.BasicScriptComponent {
    @serializeProperty
    impulseStrength: number = 50;

    private rb: APJS.RigidBody;
    private inited = false;
    private startPos!: APJS.Vector3f;
    private startRot!: APJS.Quaternionf;
    private startGravityOn = true;

    private onTouch = (event: APJS.IEvent) => {
        const touch = event.args[0] as APJS.TouchData;
        if (touch.phase === APJS.TouchPhase.Began && this.rb) {
            // Impulse: one-shot force, object falls back under gravity
            this.rb.addForce(
                new APJS.Vector3f(0, this.impulseStrength, 0),
                APJS.ForceMode3D.Impulse
            );
        }
    };

    // RecordStart: reset per Physics3D §"RecordStart Reset for 3D Physics" — full 6-step
    // single-body block (velocity → angularVelocity → position → rotation → useGravity →
    // accumulators). See GameState §"RecordStart / RecordEnd Lifecycle".
    private onRecordStart = (_event: APJS.IEvent) => {
        if (!this.inited) return;
        this.rb.velocity = new APJS.Vector3f(0, 0, 0);
        this.rb.angularVelocity = new APJS.Vector3f(0, 0, 0);
        this.rb.position = new APJS.Vector3f(this.startPos.x, this.startPos.y, this.startPos.z);
        this.rb.rotation = this.startRot;
        this.rb.useGravity = this.startGravityOn;
    };

    onUpdate(dt: number): void {
        if (!this.inited) {
            const obj = this.getSceneObject();
            if (!obj) return;
            this.rb = obj.getComponent("RigidBody") as APJS.RigidBody;
            if (!this.rb) return;
            this.startPos = new APJS.Vector3f(this.rb.position.x, this.rb.position.y, this.rb.position.z);
            this.startRot = this.rb.rotation;
            this.startGravityOn = this.rb.useGravity;
            this.inited = true;

            APJS.EventManager.getGlobalEmitter().on(APJS.EventType.Touch, this.onTouch);
            APJS.EventManager.getGlobalEmitter().on(APJS.EventType.RecordStart, this.onRecordStart);
        }
    }

    onDestroy(): void {
        APJS.EventManager.getGlobalEmitter().off(APJS.EventType.Touch, this.onTouch);
        APJS.EventManager.getGlobalEmitter().off(APJS.EventType.RecordStart, this.onRecordStart);
    }
}

Example 2 — 3D physics: object falls under gravity onto a ground plane. Detects collision via CollisionEvent.Enter on BoxCollider.

@component()
export class GravityCollision extends APJS.BasicScriptComponent {
    private collider: APJS.BoxCollider;
    private collisionCallback: (event: APJS.IEvent) => void;
    private inited = false;
    private hasLanded = false;
    private rb!: APJS.RigidBody;
    private startPos!: APJS.Vector3f;
    private startRot!: APJS.Quaternionf;
    private startGravityOn = true;
    private startCached = false;

    // RecordStart: reset per Physics3D §"RecordStart Reset for 3D Physics" — velocity →
    // angularVelocity → position → rotation → useGravity → script accumulators (hasLanded).
    // See GameState §"RecordStart / RecordEnd Lifecycle".
    private onRecordStart = (_event: APJS.IEvent) => {
        if (!this.startCached || !this.rb) return;
        this.rb.velocity = new APJS.Vector3f(0, 0, 0);
        this.rb.angularVelocity = new APJS.Vector3f(0, 0, 0);
        this.rb.position = new APJS.Vector3f(this.startPos.x, this.startPos.y, this.startPos.z);
        this.rb.rotation = this.startRot;
        this.rb.useGravity = this.startGravityOn;
        this.hasLanded = false;
    };

    onStart(): void {
        APJS.EventManager.getGlobalEmitter().on(APJS.EventType.RecordStart, this.onRecordStart);
    }

    onUpdate(dt: number): void {
        if (!this.inited) {
            const obj = this.getSceneObject();
            if (!obj) return;

            this.collider = obj.getComponent("BoxCollider") as APJS.BoxCollider;
            if (!this.collider) return;
            this.inited = true;

            this.collider.emitCollisionEvent = true;

            this.collisionCallback = (event: APJS.IEvent) => {
                if (!this.hasLanded) {
                    this.hasLanded = true;
                    const infos = event.args[0] as APJS.CollisionInfo[];
                    for (const info of infos) {
                        if (info.otherObject) {
                            console.log("Landed on: " + info.otherObject.name);
                        }
                    }
                }
            };

            // MUST pass collider component, NOT sceneObject
            const emitter = APJS.EventManager.getObjectEmitter(this.collider);
            emitter.on(APJS.CollisionEvent.Enter, this.collisionCallback, this);
        }
        if (!this.startCached) {
            const obj = this.getSceneObject();
            const rb = obj ? obj.getComponent("RigidBody") as APJS.RigidBody : null;
            if (rb) {
                this.rb = rb;
                this.startPos = new APJS.Vector3f(rb.position.x, rb.position.y, rb.position.z);
                this.startRot = rb.rotation;
                this.startGravityOn = rb.useGravity;
                this.startCached = true;
            }
        }
    }

    onDestroy(): void {
        if (this.collisionCallback && this.collider) {
            const emitter = APJS.EventManager.getObjectEmitter(this.collider);
            emitter.off(APJS.CollisionEvent.Enter, this.collisionCallback, this);
        }
        APJS.EventManager.getGlobalEmitter().off(APJS.EventType.RecordStart, this.onRecordStart);
    }
}