Use a IA

Descarregar os modelos

Todos os modelos treinados da BonkTools (football e mbappa, ataque, defesa e guarda-redes), os formatos dos ficheiros e os casos de teste para conferir a sua implementação.

Downloads

Football

ModeloFicheiroCasos de testeSituação
Atacante / 1x1 (182 milhões de passos, observação v2)football-1x1.policy.jsoncasosO que jogava nas salas 1x1 e como atacante na sala 2x2
Guarda-redes (22,4 milhões de passos, observação "gk1")football-guarda-redes.policy.jsoncasosExperimental: no simulador sofre menos golos que o nosso guarda-redes por regras (8,2% x 11,5% dos lances), mas nunca foi para a sala (lá jogava o guarda-redes por regras)

Mbappa (mapa "Mbappa Clean", motor clássico)

ModeloFicheiroCasos de testeSituação
Atacante (53,6 milhões de passos, observação v3)mbappa-atacante.policy.jsoncasosO que jogava na sala do mbappa 1x1 e como atacante na 2x2
Guarda-redes (200 mil passos, observação v3)mbappa-guarda-redes.policy.jsoncasosExperimental: rede treinada para o guarda-redes da sala 2x2. Ficou em teste e não foi para a sala (lá o guarda-redes usava a rede do atacante + regras de segurança)
Defensor (4,5 milhões de passos, observação v1)mbappa-defensor.policy.jsoncasosExperimental: especialista treinado só em lances de defesa, para jogar em dupla com o atacante. Não melhorou a dupla e não ficou na sala

Para começar rápido

FicheiroO que é
sala-exemplo.zipSala pronta com o modo "desafie a IA" (MODO=ia) usando o atacante de football; traz também o código dos outros modelos (src/ia/)
ia-kit.zipKit de treino em Python para treinar o seu

Licença: MIT. Use, modifique e redistribua; só mantenha o aviso de licença e não diga que é afiliado ao bonk.io.

Football: atacante / 1x1

O formato policy.json

json
{
  "format": "bonktools-rl-policy/1",
  "obsSize": 39,
  "obsVersion": 2,
  "actionTable": [0, 4, 6, 2, 10, 8, 9, 1, 5, 16, 20, 22, 18, 26, 24, 25, 17, 21],
  "activation": "tanh",
  "layers": [
    { "in": 39,  "out": 256, "w": "<base64>", "b": "<base64>" },
    { "in": 256, "out": 256, "w": "<base64>", "b": "<base64>" },
    { "in": 256, "out": 18,  "w": "<base64>", "b": "<base64>" }
  ],
  "timesteps": 182053103,
  "exportedAt": "2026-09-29T16:48:34Z"
}
CampoSignificado
obsSize, obsVersionQuantos números a rede espera (39 = versão 2 da observação)
actionTableAs 18 ações como teclas do bonk.io: esquerda 1, direita 2, cima 4, baixo 8, chute 16
layersAs camadas: w são os pesos (out × in, linha a linha) e b o bias, em float32 little-endian codificados em base64
activationtanh nas camadas escondidas; a última é linear (dá 18 "notas", os logits)

Para cada camada: y = W·x + b, e tanh(y) se não for a última. As 18 notas finais dizem o quanto a IA "quer" cada ação.

Casos de teste

json
{
  "state":  { "ball": {...}, "discs": [null, {...}, {...}], "ftu": 37 },
  "selfId": 1, "oppId": 2, "mirror": false,
  "obs":    [0.12, -0.4, ...],      // os 39 números esperados
  "logits": [1.23, -0.5, ...],      // as 18 notas esperadas
  "prev":   5,                      // decisão anterior (ou null)
  "decided": 3,                     // a ação decidida eixo a eixo
  "bits":   2                       // as teclas a apertar (já espelhadas se mirror)
}

Monte a observação do state, rode a rede, decida com prev e compare. A observação precisa bater exatamente (os valores são arredondados para float32 antes do limite de ±2); as notas, até a 4ª casa decimal.

Como atacante no 2x2

O mesmo modelo jogava como atacante na sala 2x2 (a IA ao lado de um guarda-redes). Ele vê o jogo como 1x1: a cada decisão, o "adversário" é o humano mais perto da bola. Com a bola no próprio campo, uma regra simples segurava o atacante à frente, sem disputar a bola com o guarda-redes.

Football: guarda-redes

Mesmo formato (bonktools-rl-policy/1) e a mesma decisão eixo a eixo, mas com outra observação: a "gk1" (obsVersion 101, 27 números), no eixo do guarda-redes (o próprio golo fica à esquerda). Ela traz o guarda-redes, a bola, os dois adversários mais perto da bola, o companheiro (o atacante) e a previsão de onde a bola cruza a linha do golo.

ts
// goleiro-rl.ts
import { teamMirror } from './features.js';

/**
 * Observação "gk1" do GOLEIRO de football treinado por RL (obsVersion 101, 27 números), exatamente como no treino.
 * Confira com os casos de teste publicados junto com o modelo. Eixo canônico do goleiro (o PRÓPRIO gol fica à esquerda).
 */
export const GK_OBS_VERSION = 101;
export const GK_OBS_SIZE = 27;

const CENTER_X = 33.18;
const CENTER_Y = 22.73;
const LINE_X = 2 * CENTER_X - 64.0 + 1.6; // linha do goleiro, 1,6 à frente do próprio gol
const HALF_W = 33.0;
const HALF_H = 22.7;
const PLAYER_MAX_SPEED = 11.7;
const BALL_MAX_SPEED = 20.0;

interface Body { x: number; y: number; xv?: number; yv?: number; kickReady?: boolean }
export interface GkState { ball?: Body | null; discs?: Array<Body | null | undefined> | null }

export function gkObs(state: GkState, gk: number, team: number, humans: number[], bot: number | null): Float64Array {
  const m = teamMirror(team);
  const get = (i: number | null): Body | null => (i !== null && i >= 0 ? state.discs?.[i] ?? null : null);
  const c = (b: Body | null | undefined): [number, number, number, number] =>
    !b ? [CENTER_X, CENTER_Y, 0, 0] : m ? [2 * CENTER_X - b.x, b.y, -(b.xv ?? 0), b.yv ?? 0] : [b.x, b.y, b.xv ?? 0, b.yv ?? 0];
  const me = get(gk);
  const [sx, sy, sxv, syv] = c(me);
  const [bx, by, bxv, byv] = c(state.ball);
  const px = (x: number): number => (x - CENTER_X) / HALF_W;
  const py = (y: number): number => (y - CENTER_Y) / HALF_H;
  const o: number[] = [px(sx), py(sy), sxv / PLAYER_MAX_SPEED, syv / PLAYER_MAX_SPEED, me?.kickReady ? 1 : 0,
    px(bx), py(by), bxv / BALL_MAX_SPEED, byv / BALL_MAX_SPEED,
    (bx - sx) / 10, (by - sy) / 10, Math.min(Math.hypot(bx - sx, by - sy), 40) / 10];
  const hs = humans.map((h) => {
    const [hx, hy, hxv, hyv] = c(get(h));
    return [Math.hypot(hx - bx, hy - by), hx, hy, hxv, hyv] as const;
  });
  hs.sort((a, b) => a[0] - b[0]);
  while (hs.length < 2) hs.push([40, CENTER_X + 20, CENTER_Y, 0, 0]);
  for (const [d, hx, hy, hxv, hyv] of hs.slice(0, 2)) {
    o.push((hx - bx) / 10, (hy - by) / 10, hxv / PLAYER_MAX_SPEED, hyv / PLAYER_MAX_SPEED, Math.min(d, 40) / 10);
  }
  const [tx, ty] = c(get(bot));
  o.push(px(tx), py(ty));
  const cross = predictCross(bx, by, bxv, byv, Math.max(sx, LINE_X));
  if (cross) o.push(1, (cross[0] - CENTER_Y) / HALF_H, Math.min(cross[1], 3) / 3);
  else o.push(0, 0, 1);
  return Float64Array.from(o, (v) => Math.max(-5, Math.min(5, Math.fround(v))));
}

const BALL_Y_MIN = 7.79;
const BALL_Y_MAX = 37.67;

/** Rebate y nas paredes de cima/baixo (a bola quica). */
function reflectY(y: number): number {
  const lo = BALL_Y_MIN, span = BALL_Y_MAX - BALL_Y_MIN;
  const t = (((y - lo) % (2 * span)) + 2 * span) % (2 * span);
  return lo + (t <= span ? t : 2 * span - t);
}

/** (y, tempo) em que a bola cruza x = xLine vindo para o gol; null se não vem. */
export function predictCross(bx: number, by: number, bxv: number, byv: number, xLine: number): [number, number] | null {
  if (bxv > -1.0 || bx <= xLine) return null;
  const t = (bx - xLine) / -bxv;
  return [reflectY(by + byv * t), t];
}

Para jogar: decide(policy.logits(gkObs(estado, idGoleiro, time, idsAdversarios, idCompanheiro)), anterior) e actionToBits(acao, teamMirror(time)), com o mesmo policy.ts do atacante.

Os casos de teste trazem state, gk, team, humans (adversários), bot (companheiro), obs, logits, prev, decided e bits.

Mbappa: atacante, guarda-redes e defensor

O mbappa é outro jogo: o mapa "Mbappa Clean" no motor clássico do bonk.io (visão de lado, gravidade, pulo, a bola quica muito, golos em gaiolas). A receita é a mesma (PPO, currículo, self-play, física real), mas com outra observação e outras ações.

Formato bonktools-rl-mbappa/1

Igual ao do football, com duas diferenças:

  • actions no lugar de actionTable: 18 trios [horizontal, vertical, pesado]. Horizontal: 0 nada, 1 ←, 2 →. Vertical: 0 nada, 1 ↑ (pula), 2 ↓ (desce rápido no ar). Pesado: segurar X.
  • Decisão pelo argmax (a ação de maior nota), uma a cada 100 ms.
VersãoNúmerosO que vê
v1 (o defensor)26Bola, eu e o adversário (posição, velocidade, no chão, pesado, vivo) e a bola em relação a mim, ao adversário e às duas gaiolas
v238v1 + onde a bola vai cair, previsão da bola em 0,3 s e 0,6 s e uma memória (teclas da decisão anterior, quanto tempo segurando ↑, quanto tempo no ar)
v3 (atacante e guarda-redes)43v2 + o medidor do X dos dois, se o adversário está pesado e se a bola está em cima de uma das gaiolas

Eixo canônico: o agente sempre ataca para a direita. No mbappa quem espelha é o azul (no football é o vermelho).

O código

ts
// mbappa.ts
import { readFileSync } from 'node:fs';

/**
 * A IA do mbappa (mapa "Mbappa Clean", motor clássico do bonk.io) rodando em JS puro: a observação exata do treino
 * (v1: 26 números; v2: 38, com previsão da bola e memória; v3: 43, + o medidor do X dos dois, o X do oponente e a bola
 * em cima de uma das gaiolas) e a rede (MLP tanh, argmax). Confira com os casos de teste publicados junto com cada
 * modelo: uma observação diferente faria o bot jogar mal sem erro nenhum.
 */

/** Estado do motor clássico: posições em unidades do jogo, y cresce para baixo. */
export interface ClassicState {
  ball: { x: number; y: number; xv: number; yv: number };
  /** `heavy` = segurando X; `stamina` = medidor do X (0..1000: gasta 10/quadro segurando, recarrega 5). */
  discs: Record<string, { x: number; y: number; xv: number; yv: number; team: number; heavy: boolean; stamina?: number }>;
  scores: (number | null)[];
  ftu: number;
}

export const MBAPPA_POLICY_FORMAT = 'bonktools-rl-mbappa/1';
const TEAM_BLUE = 3;
const MIRROR = 73.0;
const GROUND = 43.1;
const LEFT_LINE = 8.9;
const RIGHT_LINE = 64.1;
const ATTACK: [number, number] = [RIGHT_LINE + 1.5, 40.0];
const DEFEND: [number, number] = [LEFT_LINE - 1.5, 40.0];
const LEFT = 1, RIGHT = 2, UP = 4, DOWN = 8, HEAVY = 16;
const FPS = 30;
const BALL_GROUND = 43.4;
const BALL_GRAVITY = 20.0;
export const MBAPPA_OBS_SIZES: Record<number, number> = { 1: 26, 2: 38, 3: 43 };
const STAMINA_MAX = 1000;
const ROOF_X = 9.5, ROOF_Y = 34.6; // bola em cima do teto da gaiola da esquerda (eixo canônico)
/** Medidor do X (0..1); sem o campo, cheio (como no treino). */
const staminaOf = (d: { stamina?: number }): number => Math.min(Math.max((typeof d.stamina === 'number' ? d.stamina : STAMINA_MAX) / STAMINA_MAX, 0), 1);

/** Memória do jogador (v2): teclas do último passo, quadros segurando ↑, quadros no ar. */
export interface MbappaMemory {
  keys: number;
  upFrames: number;
  airFrames: number;
}
export const newMemory = (): MbappaMemory => ({ keys: 0, upFrames: 0, airFrames: 0 });
export function updateMemory(m: MbappaMemory, keys: number, frames: number, airborne: boolean): void {
  m.keys = keys;
  m.upFrames = keys & UP ? m.upFrames + frames : 0;
  m.airFrames = airborne ? m.airFrames + frames : 0;
}

type Body = { x: number; y: number; xv: number; yv: number };
const predictBall = (b: Body, t: number): [number, number] => [b.x + b.xv * t, Math.min(b.y + b.yv * t + 0.5 * BALL_GRAVITY * t * t, BALL_GROUND)];
function landingTime(b: Body): number {
  const dy = BALL_GROUND - b.y;
  if (dy <= 0) return 0;
  return (-b.yv + Math.sqrt(b.yv * b.yv + 2 * BALL_GRAVITY * dy)) / BALL_GRAVITY;
}
const canon = (x: number, xv: number, mirrored: boolean): [number, number] => (mirrored ? [MIRROR - x, -xv] : [x, xv]);
export const onGround = (d: { y: number; yv: number }): boolean => d.y >= GROUND - 0.15 && Math.abs(d.yv) < 0.5;
const clip = (v: number): number => Math.max(-5, Math.min(5, v));

/** Observação do ponto de vista de `me` (time `team`), no eixo canônico (o agente sempre ataca para a direita). */
export function buildObs(state: ClassicState, me: number, opp: number, team: number, mem: MbappaMemory | null = null, version = 1): number[] {
  const mirrored = team === TEAM_BLUE;
  const b = state.ball;
  const [bx, bxv] = canon(b.x, b.xv, mirrored);
  const by = b.y, byv = b.yv;
  const d = state.discs[String(me)];
  const o = state.discs[String(opp)];
  const W = 36.5, H = 10.0, V = 30.0;
  let mx: number, mxv: number, my: number, myv: number, mheavy: number, mground: number;
  if (d) {
    [mx, mxv] = canon(d.x, d.xv, mirrored);
    my = d.y; myv = d.yv; mheavy = d.heavy ? 1 : 0; mground = onGround(d) ? 1 : 0;
  } else {
    mx = bx; mxv = 0; my = GROUND; myv = 0; mheavy = 0; mground = 1;
  }
  let ox: number, oxv: number, oy: number, oyv: number, oground: number, alive: number;
  if (o) {
    [ox, oxv] = canon(o.x, o.xv, mirrored);
    oy = o.y; oyv = o.yv; oground = onGround(o) ? 1 : 0; alive = 1;
  } else {
    ox = MIRROR - mx; oxv = 0; oy = GROUND; oyv = 0; oground = 1; alive = 0;
  }
  const [ax, ay] = ATTACK;
  const [dx, dy] = DEFEND;
  const base = [
    (bx - 36.5) / W, (by - GROUND) / H, bxv / V, byv / V,
    (mx - 36.5) / W, (my - GROUND) / H, mxv / V, myv / V, mheavy, mground,
    (bx - mx) / W, (by - my) / H, (bxv - mxv) / V, (byv - myv) / V,
    (ox - mx) / W, (oy - my) / H, oxv / V, oyv / V, oground, alive,
    (ox - bx) / W, (oy - by) / H,
    (ax - bx) / W, (ay - by) / H,
    (dx - bx) / W, (dy - by) / H,
  ];
  if (version >= 2) {
    const cb = { x: bx, y: by, xv: bxv, yv: byv };
    const tLand = landingTime(cb);
    const [lx] = predictBall(cb, tLand);
    const [p3x, p3y] = predictBall(cb, 0.3);
    const [p6x, p6y] = predictBall(cb, 0.6);
    const m = mem ?? newMemory();
    let left = !!(m.keys & LEFT), right = !!(m.keys & RIGHT);
    if (mirrored) [left, right] = [right, left];
    base.push(
      (lx - mx) / W, Math.min(tLand, 3.0) / 1.5,
      (p3x - mx) / W, (p3y - my) / H, (p6x - mx) / W, (p6y - my) / H,
      (right ? 1 : 0) - (left ? 1 : 0), m.keys & UP ? 1 : 0, m.keys & DOWN ? 1 : 0, m.keys & HEAVY ? 1 : 0,
      Math.min(m.upFrames / FPS, 1.0), Math.min(m.airFrames / FPS, 2.0) / 2.0,
    );
  }
  if (version >= 3) {
    base.push(
      d ? staminaOf(d) : 0, o ? staminaOf(o) : 0, o && o.heavy ? 1 : 0,
      bx < ROOF_X && by < ROOF_Y ? 1 : 0, bx > MIRROR - ROOF_X && by < ROOF_Y ? 1 : 0,
    );
  }
  return base.map((v) => clip(Math.fround(v)));
}

/** Teclas do jogo para a jogada (eixo canônico; espelhado: ← e → trocam). */
export function keysFor(action: number, actions: readonly (readonly [number, number, boolean | number])[], mirrored: boolean): number {
  const [h, v, heavy] = actions[action]!;
  let k = 0;
  if (h === 1) k |= mirrored ? RIGHT : LEFT;
  else if (h === 2) k |= mirrored ? LEFT : RIGHT;
  if (v === 1) k |= UP;
  else if (v === 2) k |= DOWN;
  if (heavy) k |= HEAVY;
  return k;
}

interface LayerJson {
  in: number;
  out: number;
  w: string;
  b: string;
}
export interface MbappaPolicyJson {
  format: string;
  obsSize: number;
  obsVersion?: number;
  actions: [number, number, boolean][];
  activation: string;
  layers: LayerJson[];
  timesteps?: number;
  exportedAt?: string;
}

function floats(b64: string, n: number): Float32Array {
  const buf = Buffer.from(b64, 'base64');
  if (buf.length !== n * 4) throw new Error(`política inválida: ${buf.length / 4} valores, esperado ${n}`);
  const out = new Float32Array(n);
  for (let i = 0; i < n; i++) out[i] = buf.readFloatLE(i * 4);
  return out;
}

export class MbappaPolicy {
  readonly actions: [number, number, boolean][];
  readonly timesteps: number;
  readonly obsVersion: number;
  private readonly layers: { in: number; out: number; w: Float32Array; b: Float32Array }[];
  private mem = newMemory();
  private lastKeys: number | null = null;

  constructor(json: MbappaPolicyJson) {
    if (json.format !== MBAPPA_POLICY_FORMAT) throw new Error(`formato de política desconhecido: ${String(json.format)}`);
    if (json.activation !== 'tanh') throw new Error(`ativação não suportada: ${json.activation}`);
    this.actions = json.actions;
    this.timesteps = json.timesteps ?? 0;
    const byOrder = Object.entries(MBAPPA_OBS_SIZES).find(([, n]) => n === json.obsSize)?.[0];
    this.obsVersion = json.obsVersion ?? Number(byOrder ?? 1);
    if (MBAPPA_OBS_SIZES[this.obsVersion] !== json.obsSize) throw new Error(`política com ${json.obsSize} entradas: observação desconhecida`);
    this.layers = json.layers.map((l) => ({ in: l.in, out: l.out, w: floats(l.w, l.in * l.out), b: floats(l.b, l.out) }));
    if (this.layers[0]?.in !== json.obsSize) throw new Error('política inválida: a primeira camada não bate com obsSize');
  }

  static load(path: string): MbappaPolicy {
    return new MbappaPolicy(JSON.parse(readFileSync(path, 'utf8')) as MbappaPolicyJson);
  }

  /** A jogada mais provável (argmax dos logits). */
  act(obs: readonly number[]): number {
    let x = Float32Array.from(obs);
    this.layers.forEach((l, li) => {
      const y = new Float32Array(l.out);
      for (let o = 0; o < l.out; o++) {
        let s = l.b[o]!;
        const row = o * l.in;
        for (let i = 0; i < l.in; i++) s += l.w[row + i]! * x[i]!;
        y[o] = li < this.layers.length - 1 ? Math.tanh(s) : s;
      }
      x = y;
    });
    let best = 0;
    for (let i = 1; i < x.length; i++) if (x[i]! > x[best]!) best = i;
    return best;
  }

  /** Partida nova: zera a memória. */
  resetMemory(): void {
    this.mem = newMemory();
    this.lastKeys = null;
  }

  /**
   * As teclas que SAÍRAM de verdade neste passo, quando quem usa a rede trocou a jogada dela (sala 2x2 do mbappa: o
   * atacante cede o lance ao goleiro, 11/10): a memória do próximo passo registra o que o jogador fez, como no treino.
   */
  noteKeys(keys: number): void {
    this.lastKeys = keys;
  }

  /**
   * Teclas para `me` (time `team`) neste estado, chamado a cada `frames` quadros (100 ms = 3, o passo do treino): a
   * memória registra as teclas da decisão anterior e se o jogador está no ar agora (a mesma ordem do treino).
   */
  keys(state: ClassicState, me: number, opp: number, team: number, frames = 3): number {
    if (this.obsVersion >= 2 && this.lastKeys !== null) {
      const d = state.discs[String(me)];
      updateMemory(this.mem, this.lastKeys, frames, !!d && !onGround(d));
    }
    const k = keysFor(this.act(buildObs(state, me, opp, team, this.mem, this.obsVersion)), this.actions, team === TEAM_BLUE);
    this.lastKeys = k;
    return k;
  }
}

Uso: policy.keys(estado, eu, adversario, time) a cada 3 quadros (100 ms) devolve as teclas a apertar e cuida da memória sozinho. Chame resetMemory() a cada partida nova.

Casos de teste do mbappa

Cada caso traz state (formato ClassicState), me, opp, team, mem ([teclas, quadrosSegurandoCima, quadrosNoAr]), obs, action (o argmax) e bits (as teclas). Monte a observação com buildObs(state, me, opp, team, {keys, upFrames, airFrames}, versao), rode act() e compare.