# 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:

```angelscript
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:

```angelscript
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:

```angelscript
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:

```angelscript
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:

```angelscript
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.