# Actions

## Functions

#### carrom.state

`carrom.state()`: table

Returns `{ in_match, ready }`, and when `ready`: `at_rest`, `aiming`, `turn_known`, `ours`, `aim_angle`, `aim_power`, `mode`, `pucks`, `pockets`.

- each puck is `{ number, x, y, radius, in_play, striker, velocity }` (`velocity` is `{ x, y }`; `striker` marks the striker disc).
- each pocket is `{ x, y, radius }`.

#### carrom.guide

`carrom.guide()`: table|nil

The current aim prediction, or nil when nothing is drawn. Carries `contact` (whether the striker makes contact), `target`, `pocket_radius`, `striker_radius`, the predicted ghost contact, the per-puck `paths` (each `{ number, pocket, pocketed, striker, points }` with `points` a polyline in table coordinates), and `rail_hits` (cushion contact points).

#### carrom.to_screen

`carrom.to_screen(x: number, y: number)`: number|nil, number|nil

Projects a table point to overlay pixels. Returns nil when off-screen or the projection is unavailable.

#### carrom.queue

`carrom.queue()`: table

Returns `{ phase, status, matches, tier }`. `tier` is the selected tier id, or -1.

#### carrom.tiers

`carrom.tiers()`: table

The list of match tiers, each `{ id, name, currency, fee, unlock_level, enterable }`.

#### carrom.queue_select

`carrom.queue_select(id: integer)`: boolean

Selects a tier by id. Returns false when not allowed (no licence, wrong phase).