Transform & Entity

Position

get_position

Get an entity's world-space position.

bool get_position(ScriptContext* ctx, EntityHandle entity, float out_position[3]);

Parameter	Type	Description
entity	EntityHandle	Target entity
out_position	float[3]	Output [x, y, z] (caller-allocated)

Returns true if entity exists and has a Transform.

set_position

Set an entity's world-space position.

bool set_position(ScriptContext* ctx, EntityHandle entity, const float position[3]);

Parameter	Type	Description
entity	EntityHandle	Target entity
position	const float[3]	New position [x, y, z]

---

Rotation

get_rotation

Get an entity's rotation as a quaternion.

bool get_rotation(ScriptContext* ctx, EntityHandle entity, float out_rotation[4]);

Parameter	Type	Description
entity	EntityHandle	Target entity
out_rotation	float[4]	Output quaternion [x, y, z, w] (caller-allocated)

set_rotation

Set an entity's rotation.

bool set_rotation(ScriptContext* ctx, EntityHandle entity, const float rotation[4]);

Parameter	Type	Description
entity	EntityHandle	Target entity
rotation	const float[4]	Quaternion [x, y, z, w]

---

Scale

get_scale

bool get_scale(ScriptContext* ctx, EntityHandle entity, float out_scale[3]);

set_scale

bool set_scale(ScriptContext* ctx, EntityHandle entity, const float scale[3]);

---

Full Transform

get_transform

Get the complete transform (position, rotation, scale) in one call.

bool get_transform(ScriptContext* ctx, EntityHandle entity, ScriptTransform* out_transform);

Parameter	Type	Description
entity	EntityHandle	Target entity
out_transform	ScriptTransform*	Output transform struct (caller-allocated)

set_transform

bool set_transform(ScriptContext* ctx, EntityHandle entity, const ScriptTransform* transform);

---

Entity Lifecycle

spawn_entity

Create a new entity at runtime.

EntityHandle spawn_entity(ScriptContext* ctx, const char* name);

Returns the new entity's handle, or NULL_ENTITY_HANDLE on failure.

destroy_entity

Remove an entity from the world.

bool destroy_entity(ScriptContext* ctx, EntityHandle entity);

Returns true if the entity existed and was destroyed.

find_entity_by_name

Find the first entity with a given name.

EntityHandle find_entity_by_name(ScriptContext* ctx, const char* name);

Returns the entity handle, or NULL_ENTITY_HANDLE if not found.

---

Logging

log_message

Print a message to the engine console.

void log_message(ScriptContext* ctx, const char* message);

---

Generic Component Access

has_component_generic

Check if an entity has a component by type name.

bool has_component_generic(ScriptContext* ctx, EntityHandle entity, const char* type_name);

if (ctx->has_component_generic(ctx, entity, "Rigidbody")) {
    // Entity has physics
}

get_component_generic

Get component data as a JSON string.

const char* get_component_generic(ScriptContext* ctx, EntityHandle entity, const char* type_name);

Returns a JSON string (static buffer, do not free), or nullptr if the component doesn't exist.

const char* json = ctx->get_component_generic(ctx, entity, "Transform");
// json = "{\"position\":{\"x\":0,\"y\":5,\"z\":0}, ...}"

set_component_generic

Set component data from a JSON string.

bool set_component_generic(ScriptContext* ctx, EntityHandle entity,
                           const char* type_name, const char* json_data);

ctx->set_component_generic(ctx, entity, "PointLightComponent",
    "{\"color\":{\"x\":1,\"y\":0,\"z\":0},\"intensity\":2.0}");

---

Example: Follow Target

static EntityHandle target;
static float follow_speed = 5.0f;

void OnStart(ScriptContext* ctx) {
    target = ctx->find_entity_by_name(ctx, "Player");
}

void OnUpdate(ScriptContext* ctx) {
    float dt = ctx->get_delta_time();
    float my_pos[3], target_pos[3];

    ctx->get_position(ctx->self, my_pos);
    ctx->get_position(target, target_pos);

    // Move toward target
    for (int i = 0; i < 3; i++) {
        float diff = target_pos[i] - my_pos[i];
        my_pos[i] += diff * follow_speed * dt;
    }

    ctx->set_position(ctx->self, my_pos);
}