# Actions

## Functions

#### soccer.state

`soccer.state()`: table

Returns the match: `in_match`, `started`, `state`, `mode`, `our_turn`, `their_turn`, `animating`, `may_act`, `aim_angle`, `aim_power`, `selected`. When the scoreboard is trustworthy it adds `player_score`, `opponent_score` and `goals_to_win`. When the board is live it adds `at_rest`, `pucks` and `goals`.

- each puck is `{ number, x, y, radius, team, football, selected, on_table }`; `team` is `"ours"`, `"theirs"`, `"loose"` or `"unknown"`, and `football` marks the ball.
- `goals` is `{ attack, defend, half_height }`, each goal centre a `{ x, y }`.

#### soccer.guide

`soccer.guide()`: table|nil

The current aim prediction, or nil when nothing is drawn: `{ aiming, ours, contact, goal, target, struck, ghost, paths }`. Each path is `{ number, team, football, struck, points }`, `points` a polyline in table coordinates.

#### soccer.prediction

`soccer.prediction()`: table

The last resolved prediction: `{ live, ours, reason, goal, angle, power, duration, struck, target }`.

#### soccer.to_screen

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

#### soccer.queue

`soccer.queue()`: table

Returns `{ phase, status, enabled, tier, losing }`. `losing` is true when leaving to lose on purpose.

#### soccer.tiers

`soccer.tiers()`: table

The list of match tiers, each `{ id, name, fee, reward, min_level, goals_needed }`.

#### soccer.queue_select

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

Selects a tier by id. Returns false when not allowed.

#### soccer.forfeit

`soccer.forfeit()`: boolean

Leaves the current match to lose. Returns false when not allowed, or when there is nothing to leave.