simian/docs/Scripting.md

Scripting

This page is a starting point for scripting documentation.

Overview

• Scripts live in scripts/ and are executed by AngelScript.
• Predefined API and engine bindings are declared in scripts/as.predefined.

Input Actions

• Query input with IsActionPressed, IsActionDown, IsActionReleased, and GetActionStrength.
• Register and bind at runtime with RegisterAction, BindKeyboard, BindMouseButton, BindGamepadButton, and BindGamepadAxis.
• Enums: Key, MouseButton, GamepadButton, GamepadAxis.

Example:

RegisterAction("boost");
BindKeyboard("boost", Key::LEFT_CONTROL);
BindGamepadButton("boost", 0, GamepadButton::RIGHT_TRIGGER_1);

RegisterAction("zoom");
BindGamepadAxis("zoom", 0, GamepadAxis::RIGHT_TRIGGER, 0.2f, false);

ECS Texture + UV

• Texture and UV helpers live under the ECS:: namespace.
• Texture: AddTexture, SetTextureId, GetTextureId, HasTexture, RemoveTexture.
• UV Transform: AddUVTransform, SetUVScale, SetUVOffset, SetUVRotation, HasUVTransform, RemoveUVTransform.

Example:

uint e = ECS::CreateEntity();
ECS::AddTexture(e, texId);
ECS::AddUVTransform(e, 2.0f, 2.0f, 0.0f, 0.0f, 0.0f);
ECS::SetUVOffset(e, 0.25f, 0.0f);

Asset Manager

• Asset loading can be keyed for editor and scene usage.
• Use Asset::Load* helpers to create assets and reference them by key.

Example:

Asset::LoadTexture("grid", "assets/textures/grid.png");
Asset::LoadShader("toon", "shaders/toon.vs", "shaders/toon.fs");
Asset::LoadCube("unit_cube", 1.0f, 1.0f, 1.0f);
Asset::CreateMaterial("toon_mat", Asset::GetShaderId("toon"), 255, 255, 255, 255);

uint e = ECS::CreateEntity();
ECS::AddModelRenderer(e, int(Asset::GetModelId("unit_cube")), 0xFFFFFFFF, 0.0f);
ECS::SetModelRendererShader(e, Asset::GetShaderId("toon"));
ECS::AddTexture(e, Asset::GetTextureId("grid"));
ECS::AddMaterial(e, Asset::GetMaterialId("toon_mat"));

Key-Value Store (SNKV)

• Databases are stored under user/db/<name>.db.
• Open() returns a handle (0 on failure). Use that handle for all operations.
• TTL values are in milliseconds and are applied relative to the current time.

Example:

uint db = KV::Open("session_cache");
if (db != 0) {
	KV::Put(db, "player", "nick");

	// Expire in 30 seconds
	KV::PutTtl(db, "token", "abc123", 30000);

	string value;
	int64 remainingMs = 0;
	if (KV::GetTtl(db, "token", value, remainingMs)) {
		Print("token=" + value + " remaining=" + remainingMs);
	}

	KV::Close(db);
}

Globals (in-memory)

• Cross-scene, in-memory store for runtime state.
• Uses the same typed overloads as the KV API.
• Values persist while the app is running, but are not saved to disk.
• Get() returns false if the key does not exist or the type does not match.

Example:

Globals::Set("difficulty", 2);
Globals::Set("player_name", "Nina");

int diff = 0;
string name;
if (Globals::Get("difficulty", diff)) {
	Print("difficulty=" + diff);
}
if (Globals::Get("player_name", name)) {
	Print("player=" + name);
}

Examples

• scripts/game.as — demo showing ECS usage, rendering, scenegraph and input actions.

How to document APIs

Add Markdown pages in the docs/ folder. Use relative links and include code fences for examples.