Kemena3D AngelScript API Reference

Introduction

This is the complete reference for everything a Kemena3D AngelScript script can use: the lifecycle functions the engine calls, the global functions and types the engine exposes (kObject, kVec3), and the standard-library pieces that are available.

For the language itself (syntax, classes, control flow, operators) see the official AngelScript manual. For concepts (assets, components, bytecode, the compile pipeline) see Kemena3D Scripting.

Source of truth: the bindings are registered in Source/src/kscriptbindings.cpp and Source/src/kscriptmanager.cpp. If this document and the code ever disagree, the code wins — and the doc should be updated.

Anatomy of a script

A script is an .as file attached to a kObject (a scene object). It defines any subset of the lifecycle functions below as plain free functions. The engine calls them on the object the script is attached to; inside any of them getSelf() returns that object.

// spin.as — rotate the object around the Y axis every frame
void Update()
{
    kObject@ self = getSelf();
    self.rotate(kVec3(0, 1, 0), 1.5 * getDeltaTime()); // 1.5 rad/sec
}

// spin.as — rotate the object around the Y axis every frame
void Update()
{
    kObject@ self = getSelf();
    self.rotate(kVec3(0, 1, 0), 1.5 * getDeltaTime()); // 1.5 rad/sec
}

Each attached script runs as its own module, so global variables declared in a script are per-object instance state — two objects with the same script do not share globals.

float elapsed = 0.0f; // independent for every object using this script

void Update()
{
    elapsed += getDeltaTime();
}

float elapsed = 0.0f; // independent for every object using this script

void Update()
{
    elapsed += getDeltaTime();
}

You may also declare your own helper functions and (script) classes; only the lifecycle names below are special.

Lifecycle functions

Define any subset. Missing ones are simply skipped. Signatures must match exactly (all are void name()).

Function	When it runs
void Awake()	Once, when play begins, before any `Start()`.
void Start()	Once, after all `Awake()`s, before the first `Update()`.
void Update()	Every frame. Use `getDeltaTime()` for frame-rate independence.
void FixedUpdate()	Every fixed physics step. Use `getFixedDeltaTime()`.
void LateUpdate()	Every frame, after all `Update()`s (e.g. cameras that follow).
void OnEnable()	When the object/script becomes active.
void OnDisable()	When the object/script becomes inactive.
void OnDestroy()	When the object is destroyed / play stops.

void Awake()  { print("Awake: one-time setup"); }
void Start()  { print("Start: everything else is ready"); }
void Update() { /* per-frame gameplay */ }
void OnDestroy() { print("Goodbye"); }

void Awake()  { print("Awake: one-time setup"); }
void Start()  { print("Start: everything else is ready"); }
void Update() { /* per-frame gameplay */ }
void OnDestroy() { print("Goodbye"); }

Let’s proceed to global functions.

Global functions

Signature	Description
kObject@ getSelf()	The object this script is attached to (a handle; may be reused via `@`).
float getDeltaTime()	Seconds since the previous frame (varies). Multiply movement/rotation by this in `Update()`.
float getFixedDeltaTime()	Seconds per fixed step (constant). Use in `FixedUpdate()`.
void print(const string &in)	Writes a line to the editor Console (prefixed `[Script]`).
void log(const string &in)	Identical to `print` — an alias.

void Start()
{
    print("Hello from " + getSelf().getName());
    print("frame dt = " + getDeltaTime());   // numbers concatenate into strings
}

void Start()
{
    print("Hello from " + getSelf().getName());
    print("frame dt = " + getDeltaTime());   // numbers concatenate into strings
}

There is currently no global function to find other objects by name/UUID from a script — a script reaches the scene graph through getSelf() and getParent() only.

Type: `kObject`

A handle to a scene object. Obtain one with getSelf() or getParent(). It is engine-owned, so you hold it as a handle (kObject@) and never construct or delete it.

Identity

Method	Description
string getName() const	The object’s display name.
void setName(const string &in)	Rename the object.
string getUuid() const	The object’s stable unique id.

Transform

Position and scale are in the units you authored. Rotation is exposed as Euler angles in degrees (friendlier than quaternions for gameplay).

Function	When it runs
kVec3 getPosition() const	Local position (relative to parent).
void setPosition(const kVec3 &in)	Set local position.
kVec3 getGlobalPosition() const	World-space position (read-only).
kVec3 getScale() const	Local scale.
void setScale(const kVec3 &in)	Set local scale.
kVec3 getRotation() const	Local rotation as Euler degrees (x=pitch, y=yaw, z=roll).
void setRotation(const kVec3 &in)	Set local rotation from Euler degrees.
void translate(const kVec3 &in)	Move by a delta: `position += delta`.
void rotate(const kVec3 &in axis, float angle)	Rotate incrementally by `angle` radians around `axis` (axis is normalized).

Units gotcha: getRotation/setRotation use degrees, but rotate(axis, angle) uses radians. For continuous spin, prefer rotate with angle = speed * getDeltaTime().