Koushiball — Bot Editor

Bots

Select a bot or create a new one

Output

Auto-scroll

Select a bot.

Bot API Reference

Contents

Overview State Overview Data Structures GameState BallState PlayerState Constants me Object Movement Throwing Logging & Output

Overview

Your bot is a Lua script. Register one update function with on_update and it runs 4 times a second (every 250 ms).

It is only called while your player is on the field, so me and state.ball are always available.

on_update(function(state, me)
  move_towards(state.ball.x, state.ball.y)
end)

Deploy your bot and it takes over one player in live matches. Every other player is a house bot or competitor. You can deploy up to 5 bots at once.

State Overview

The state object encapsulates full match telemetries. High-level properties include:

state.ball — Match ball position & status
state.players — Array of player slots (check .active)
state.teammates — Slot indices for your team
state.opponents — Slot indices for opposing team
state.score_red / state.score_blue — Team scores
state.play_state — Match status ID
state.time_left — Milliseconds remaining

Data Structures

Complete JSON schema for state entities.

GameState (state)

Root snapshot object provided in on_update(state, me).

{
  tick: number,          // Current simulation tick
  time_left: number,     // Milliseconds remaining in match
  play_state: number,    // 1: WAITING, 2: STARTING, 3: STARTED, 4: ENDED
  score_red: number,     // Red team total score
  score_blue: number,    // Blue team total score
  ball: BallState,       // Ball object on the field
  players: PlayerState[],// Array of 12 player slots (1..12)
  teammates: number[],   // Active slot indices for your team
  opponents: number[]    // Active slot indices for opposing team
}

BallState (state.ball)

Positional and possession metrics for the match ball.

{
  x: number,             // X position in meters (0..25)
  y: number,             // Y position in meters (0..13)
  vx: number,            // X velocity in meters/sec
  vy: number,            // Y velocity in meters/sec
  held: boolean,         // true if carried by a player
  holder: number | null  // Player slot ID holding ball, or null
}

PlayerState (me / state.players[i])

Individual player state on field.

{
  slot: number,          // Player slot ID (1..12)
  active: boolean,       // true if slot is occupied
  id: string,            // Unique player ID
  name: string,          // Bot ID Tag
  team: number,          // 1: RED, 2: BLUE
  x: number,             // X position in meters (0..25)
  y: number,             // Y position in meters (0..13)
  vx: number,            // X velocity in meters/sec
  vy: number,            // Y velocity in meters/sec
  has_ball: boolean,     // true if carrying the ball
  stunned: boolean,      // true if currently stunned
  locked: boolean        // true if locked during pre-play countdown
}

Constants (Global Tables)

Read-only enumeration tables for field bounds and match rules.

{
  TEAM: { RED: 1, BLUE: 2, SPECTATOR: 3 },       // Team IDs
  PLAY_STATE: { WAITING: 1, STARTING: 2, STARTED: 3, ENDED: 4 }, // Match status
  FIELD: { WIDTH: 25, HEIGHT: 13, ENDZONE: 2 }   // Field size in meters
}

me Object

Your own player instance on field. Contains the exact same structure as an entry in state.players (see PlayerState above).

Moving

move_towards(x, y) — Navigate directly toward coordinates (metres).

move(dx, dy) — Directional vector components between -1 and 1.

stop() — Halt movement instantly.

Throwing

shoot_at(x, y) — Throw the ball directly toward target coordinates.

shoot(degrees) — Throw at an angle (0° = right, 90° = down, 180° = left, 270° = up).

Logging & Output

print(...) — Streams log messages directly to the Output panel below the editor while your bot is playing.