竞技场：AI世界杯 ⚽🏆

欢迎来到绿茵赛场！AI世界杯是一款 2 对 2 的竞技足球编程游戏。它最特别的地方在于：场上奔跑的球员、场边指挥的教练，全都不是普通角色，而是一个个由你的代码"注入灵魂"的 AI Agent（智能体）。

你可以把 AI Agent 理解为一个"会自己思考、自己行动"的程序小人。你不需要用鼠标一步步操控它，而是提前写好一套决策逻辑（例如"如果我有球就射门，否则就去追球"），然后 AI Agent 就会在比赛中不停地按照这套逻辑自动做出判断和动作。你的代码写得越聪明，你的 AI Agent 踢得就越好——这正是"AI世界杯"这个名字的由来。

1.1 你要指挥的三类 AI Agent（Three Agents）

在这场比赛里，你的代码将同时操控三个 AI Agent。它们分工不同，请先记住它们各自的角色：

• ⚽ 两名球员 AI Agent（Mates，球场单位）：这是真正在场上跑动、争球的两名球员。特别之处在于，每名球员都在自己独立的"线程"里运行你的代码——你可以简单理解为：两名球员像两个同时开工的小机器人，各想各的、各跑各的，互不等待。它们围绕场上唯一的一颗球进行追逐、抢断、传球和射门。
• 🎽 一名教练 AI Agent（Coach，即英雄 hero，运行在主线程）：教练不下场踢球，而是站在场边纵观全场。它运行在"主线程"上，可以随时读取全场信息，并使用各种即时技能去帮助自家球员、或干扰对手。教练是你的"大脑指挥中枢"。
• 🧤 一名自动守门员（Auto-keeper）：双方各有一名把守球门的守门员。它不是 AI Agent，没有人给它写代码——它的行为是系统固定的。你需要做的不是控制它，而是想办法"智胜"它，把球从它手里送进门。

1.2 编程语言（Languages）

本竞技场支持用 Python 和 C++ 两种语言来编写 AI Agent 的逻辑。两种语言的游戏思路完全一致——都是"为球员写线程处理函数，为教练写主循环"，只是语法写法不同。

本篇文档中的每一段示例代码，都会同时给出 Python 和 C++ 两个版本，你可以点击代码框上方的语言标签来切换查看。初学者建议先从 Python 入手，它的写法更接近自然语言、更容易读懂；熟悉之后再尝试 C++ 也会很轻松。

目标非常简单，和真实足球一样：把球打进对方球门，让自己的进球数比对手多。下面我们把"比赛怎么进行""怎么算赢"一条条讲清楚。

2.1 比赛流程（Two Rounds）

一场比赛分为两个回合（就像足球的上下半场），每个回合时长为 params.halfTime 秒。两个回合分别编号为第 0 回合和第 1 回合（程序里习惯从 0 开始数）：

• 🔴 红队在第 0 回合（上半场）开球。
• 🔵 蓝队在第 1 回合（下半场）开球。

之所以让两队轮流开球，是为了公平——开球方会先碰到球，稍占一点便宜，两回合各开一次就抵消了。

2.2 胜负判定规则（Win Conditions）

当第二回合结束的那一刻，系统会立即按下面的顺序判定谁赢：

2.3 粉丝支持度（Fan Support）

观众来看球，最爱看的是积极进攻的足球。所以游戏设计了一个"粉丝支持度"机制来奖励主动进攻的一方。比赛过程中，双方都会不断积累粉丝支持度，它会直接显示为你教练 AI Agent（英雄）的生命值数字——数字越高，说明你的球队踢得越受欢迎。

以下行为会为你积累支持度：

你控制两名球员 AI Agent。前面说过，每名球员都在自己独立的线程里运行你的处理函数。比赛开始时，这个处理函数会为每名球员各自调用一次；一旦调用，函数里的循环就会一直跑到比赛结束（球员永远不会死亡，也不会重生），所以你通常会在函数里写一个 while 无限循环，让球员不停地思考和行动。

3.1 启动球员线程（Spawn Handler）

要让球员 AI Agent 动起来，你必须先"注册"一个处理函数，告诉系统："每当一名球员登场，就用这个函数来控制它。"注册的方式是调用 hero.on("spawn-mate", 函数名)。

下面是一段最基础的球员逻辑："有球就射门，没球就追球。"

def onSpawnMate(mate):
    while True:
        if mate.hasBall:
            mate.shoot()        # 有球就射门
        else:
            mate.chaseBall()    # 没球就追球

hero.on("spawn-mate", onSpawnMate)

auto onSpawnMate(auto mate) {
    while (true) {
        if (mate.hasBall) {
            mate.shoot();       // 有球就射门
        } else {
            mate.chaseBall();   // 没球就追球
        }
    }
}

int main() {
    hero.on("spawn-mate", onSpawnMate);
    return 0;
}

3.2 基础指令（Move Commands）

球员 AI Agent 的移动和测距，靠下面两个基础指令：

3.3 抢断能力 clash（The One Mate Ability）

mate.clash() 是球员 AI Agent 唯一的主动技能：从敌方持球者脚下把球抢过来。它的冷却时间是 params.clashCooldown 秒，而且每次尝试都会消耗冷却——也就是说，无论你抢成功还是失败，都得等冷却结束才能再抢一次。

3.4 出球 roll（传球和射门是同一个动作！）

mate.roll(x, y, power) 是把球踢出去的唯一方式。这里有一个非常重要的设定：在本游戏里，"传球"和"射门"其实是同一个动作——都是把球朝某个点滚出去，区别只在于你瞄准的是队友、还是球门。

其中 power（力量）决定球滚多远：

# 最大射程 = power × params.rollRangeFactor
# 如果 power 超过 params.maxPower，会被自动限制到上限
mate.roll(x, y, power)

// 最大射程 = power × params.rollRangeFactor
// 如果 power 超过 params.maxPower，会被自动限制到上限
mate.roll(x, y, power);

• 🧱 球会在上下墙壁反弹——所以"撞墙传球"（bank pass，像台球擦库一样）是合法且免费的战术，可以用来绕过对手。
• ⚡ 出球成功时永远不会被阻塞：哪怕你正被一群人围住（混战 scrum），持球者也总有一次瞬间把球踢出去的机会，不会被卡死。
• ⏳ 你无法在 params.selfRecaptureDelay 秒内接回自己刚踢出的球。过了这段短暂时间后，"踢一脚给自己"的直塞式自传球（把球往前捅一下再追上去）是允许的。

3.5 宏指令（Convenience Macros）

为了让你少写代码，游戏内置了一批常用的"宏指令"——它们其实是把常见操作打包好的快捷方法，直接调用即可：

3.6 球员属性（Read-Only Properties）

下面这些属性是只读的（你只能读取、不能修改），用来了解球员当前的状态，方便你的代码做判断：

要踢好球，得先搞懂"球是怎么被抢到、被守住、被拦截的"。这一节的规则决定了控球权的归属，非常值得细读。

4.1 粘球与控球免疫（Sticky & Immunity）

球是"粘"的：一颗无人控制的自由球，只要进入了某名球员的 params.captureRadius 范围，就会自动"吸附"到那名球员脚下，变成他控球。之后，持球者会一直控着球，直到发生下面三种情况之一：他主动出球（roll）、被敌方成功抢断（clash）、或者被守门员扑住。

4.2 释放气泡与拦截（Release Bubble & Interception）

释放气泡（Release Bubble）：一颗刚被踢出、正在滚动的球，在它离开释放点、飞行距离还没达到 params.rollReleaseRadius 之前，任何人都无法接住它（连守门员也不行）。这就好比球刚出脚时外面罩着一层保护泡泡。因此，即使对手就贴在你身边，你也能安全地把球踢出去。而与之相对，一颗完全静止的球，任何时候都可以被捡走。

拦截（Interception）：只要你的球员站在滚球的路径上、并且位于释放气泡之外的位置，球飞过来就归你了。由于球的运动轨迹是直线，你完全可以通过 hero.ball 提供的位置和速度信息 (x, y, vx, vy)，用数学算出球接下来会经过哪里，从而提前跑位去拦截。

红队始终防守左侧球门，蓝队始终防守右侧球门。当球进入某个球门区域（params.gates）时就算进球——而且不管球是谁踢进去的！

每次进球之后（以及每个回合刚开始时），所有球员的位置和技能冷却都会重置回初始阵型，球会被重新放到球场中央，并朝开球方偏移一小段距离 params.kickoffOffset——这样开球方就会确定性地先碰到球。

每个球门都由一名 NPC 守门员把守。它不是 AI Agent，没有人给它写代码——它的行为是系统固定的、完全可预测的。而"可预测"恰恰是你的机会：只要摸清它的规律，就能设计出稳定的破门方法。

解围超级长传（Clearance）Super Kick

守门员拿到球并持球 params.keeperHoldTime 秒之后，会以 params.superKickSpeed 的极快速度，朝离它最近的、且没被眩晕的自家球员射出一道超级长传——直线飞行、中途不减速。关于这道解围球，有几点要知道：

• 🚫 敌方无法拦截飞行途中的解围球（它太快了，还带着"不可拦截"的特性）。
• 🐢 当球飞到接应球员所在的距离时，会降速为普通滚球；如果它撞到墙壁反弹，之后就变回一颗普通的自由球，此时又可以被争抢了。
• 🤝 如果接应的球员本来就已经在守门员的 params.captureRadius 范围内，球会被直接交到他脚下，省去飞行过程。

主线程运行的就是你的教练 AI Agent。和场上跑动的球员不同，教练不亲自碰球，而是像一位真正的主教练那样站在场边：它能看见场上发生的一切，并适时使用各种即时技能（每个技能都有自己独立的冷却时间），从战术层面影响比赛走向。教练是你统筹全局、临场调度的"指挥中枢"。

7.1 教练方法（Methods）

7.2 四大教练技能（Abilities）

教练 AI Agent 有四个技能，两个用来"增益自己人"，两个用来"干扰对手"：

7.3 全场感知（Sensing, 只读）

教练能读取全场信息，这些都是只读属性，是你做决策的"眼睛"：

7.4 教练示例代码（Example）

下面这段教练逻辑做了两件聪明事：帮被眩晕的队友吹哨解控，以及在对方持球时压迫拖慢对手。

while True:
    # 谁被眩晕了，就吹哨帮他解除
    for m in hero.myMates:
        if m.isStunned and hero.abilityReady("whistle"):
            hero.whistle(m)

    # 敌方持球时，用压迫拖慢对手
    carrier = hero.ball.owner
    if carrier and carrier.color != hero.color and hero.abilityReady("press"):
        hero.press(carrier)

    hero.wait(0.3)

int main() {
    while (true) {
        // 谁被眩晕了，就吹哨帮他解除
        for (int i = 0; i < hero.myMates.size(); i++) {
            auto m = hero.myMates[i];
            if (m.isStunned && hero.isReady("whistle")) {
                hero.whistle(m);
            }
        }
        // 敌方持球时，用压迫拖慢对手
        auto carrier = hero.ball.owner;
        if (carrier && carrier.color != hero.color && hero.isReady("press")) {
            hero.press(carrier);
        }
        hero.wait(0.3);
    }
    return 0;
}

把球员 AI Agent、教练 AI Agent、守门员这三套系统串起来，一套稳健、适合新手起步的 AI世界杯思路大致如下：

1. 先启动线程：代码里务必写上 hero.on("spawn-mate", ...)，否则球员 AI Agent 根本不会动——这是最容易忘、也最致命的一步。
2. 球员分工：用 mateId 区分角色——比如一人主攻、抢球射门，一人拉边接应或回防。每个角色都要处理 hasBall，防止后卫乌龙。
3. 靠传球推进：记住持球会变慢、追赶者总能追上，所以别硬带球——多用 passTo / cross，甚至撞墙传球来撕开防线。
4. 抢断先看免疫：调用 clash 前先查对手的 isImmune，避免对免疫者抢断而害自己眩晕。
5. 攻破守门员：守门员追球移动，先把它引离球门中心，再射向远门柱空档；进攻时可以配合 hero.distract() 拖慢它。
6. 教练辅助时机：进攻反击时用 inspire 给自家球员提速；防守时用 press 拖慢敌方持球者；自家球员被抢断眩晕时，立刻 whistle 解控。
7. 追求攻势：多传球、多射门、尽量把球压在对方半场——这些都在积累粉丝支持度，会在打平时救你一命。

你可以通过 params 对象访问下面所有参数。以下均为默认值——如果文档过时，实际比赛可能采用不同数值，请以游戏内实时的 params 为准。

场地与球门Field & Gates

球员与移动Mates & Movement

抢断与控球Clash & Possession

出球（滚球）Roll

守门员Keeper

教练技能Coach Abilities

粉丝支持度Fan Activity