Math and time

KILLSCRIPT exposes native Vector2, Vector3 and Quaternion userdata. Their properties and methods are already typed, but TypeScript does not know that Lua can apply +, - and * to those objects. The math helpers express those verified operators without pretending they are JavaScript numbers.

Vector and quaternion operators

import {
  quaternion,
  vector2,
  vector3,
} from "@killscript/sdk/client";

const screenEnd = vector2.add(screenStart, screenOffset);

const target = vector3.add(origin, offset);
const relative = vector3.subtract(target, origin);

const facing = quaternion.multiply(yawRotation, pitchRotation);
const direction = quaternion.rotate(facing, Vector3.forward);

Helper	Generated native operation
`vector2.add(a, b)`	`a + b`
`vector2.subtract(a, b)`	`a - b`
`vector3.add(a, b)`	`a + b`
`vector3.subtract(a, b)`	`a - b`
`quaternion.multiply(a, b)`	`a * b`
`quaternion.rotate(rotation, vector)`	`rotation * vector`

No wrapper object is created. Calls are replaced with native operators during compilation. Continue using native members such as origin.Distance(target), value.normalized, rotation.Angle(other) and Quaternion.lookRotation(...) directly.

Read time

The time wrapper gives the same values as the native Time global with short, context-safe names:

import { time } from "@killscript/sdk/server";

const nowSeconds = time.seconds(); // Time.Seconds
const nowTick = time.tick();       // Time.Tick
const seconds = time.toSeconds(30);

Use ticks for server deadlines and comparisons because they follow simulation progress directly:

const expiresAtTick = time.tick() + time.ceilTicks(2);

function hasExpired(): boolean {
  return time.tick() >= expiresAtTick;
}

Safe duration conversion

The native Time.SecondsToTick() truncates near floating-point boundaries in the current game build. Runtime validation observed these values:

Time.SecondsToTick(0.5) -> 29
Time.SecondsToTick(1.0) -> 59

For a delay or deadline that must last at least the requested duration, use time.ceilTicks(seconds):

const halfSecond = time.ceilTicks(0.5); // 30
const oneSecond = time.ceilTicks(1);    // 60

time.toTicks() intentionally preserves the native truncating behavior. It is appropriate only when that exact conversion is wanted. time.ceilTicks() divides by the current native tick duration and rounds upward.

See Scheduling when the goal is to run a callback rather than compare a deadline manually.