1. 競技場簡介Intro to the AI World Cup Arena

歡迎來到綠茵賽場！AI 世界盃是一款 2 對 2 的競技足球程式設計遊戲。它最特別的地方在於：場上奔跑的球員、場邊指揮的教練，全都不是普通角色，而是一個個由你的程式碼「注入靈魂」的 AI Agent（智能體）。

你可以把 AI Agent 理解為一個「會自己思考、自己行動」的程式小人。你不需要用滑鼠一步步操控它，而是提前寫好一套決策邏輯（例如「如果我有球就射門，否則就去追球」），然後 AI Agent 就會在比賽中不停地按照這套邏輯自動做出判斷和動作。你的程式碼寫得越聰明，你的 AI Agent 踢得就越好——這正是「AI 世界盃」這個名字的由來。

1.1 你要指揮的三類 AI Agent

在這場比賽裡，你的程式碼將同時操控三個 AI Agent。它們分工不同，請先記住它們各自的角色：

• ⚽ 兩名球員 AI Agent（Mates，球場單位）：真正在場上跑動、爭球的兩名球員。特別之處在於，每名球員都在自己獨立的「執行緒」裡執行你的程式碼——你可以簡單理解為：兩名球員像兩個同時開工的小機器人，各想各的、各跑各的，互不等待。它們圍繞場上唯一的一顆球進行追逐、搶斷、傳球和射門。
• 🎽 一名教練 AI Agent（Coach，即英雄 hero，執行於主執行緒）：教練不下場踢球，而是站在場邊縱觀全場。它執行於「主執行緒」，可以隨時讀取全場資訊，並使用各種即時技能去幫助自家球員、或干擾對手。教練是你的「大腦指揮中樞」。
• 🧤 一名自動守門員（Auto-keeper）：雙方各有一名把守球門的守門員。它不是 AI Agent，沒有人給它寫程式碼——它的行為是系統固定的。你要做的不是控制它，而是想辦法「智勝」它，把球從它手裡送進門。

1.2 程式語言

本競技場支援用 Python 和 C++ 兩種語言來撰寫 AI Agent 的邏輯。兩種語言的遊戲思路完全一致——都是「為球員寫執行緒處理函式，為教練寫主迴圈」，只是語法寫法不同。本文中每一段範例程式碼都同時提供 Python 與 C++ 兩個版本，點擊頁面上方的語言切換即可。建議初學者先從 Python 入手，熟悉之後再嘗試 C++。

2. 遊戲目標與勝負Game Objective — Score to Win

目標非常簡單，和真實足球一樣：把球打進對方球門，讓自己的進球數比對手多。

2.1 比賽流程

一場比賽分為兩個回合（就像足球的上下半場），每個回合時長為 params.halfTime 秒。兩個回合分別編號為第 0 回合和第 1 回合（程式裡習慣從 0 開始數）：

• 🔴 紅隊在第 0 回合（上半場）開球。
• 🔵 藍隊在第 1 回合（下半場）開球。

之所以讓兩隊輪流開球，是為了公平——開球方會先碰到球，稍佔一點便宜，兩回合各開一次就抵消了。

2.2 勝負判定規則

當第二回合結束的那一刻，系統會立即依下面的順序判定誰贏：

2.3 粉絲支持度

觀眾來看球，最愛看的是積極進攻的足球。所以遊戲設計了「粉絲支持度」機制來獎勵主動進攻的一方。比賽過程中，雙方都會不斷累積粉絲支持度，它會直接顯示為你教練 AI Agent（英雄）的生命值數字——數字越高，代表你的球隊踢得越受歡迎。以下行為會為你累積支持度：

3. 球員 AI Agent 控制Mate Control — Your Two Field Agents

你控制兩名球員 AI Agent。每名球員都在自己獨立的執行緒裡執行你的處理函式。比賽開始時，這個處理函式會為每名球員各自呼叫一次；一旦呼叫，函式裡的迴圈就會一直跑到比賽結束（球員永遠不會死亡，也不會重生），所以你通常會在函式裡寫一個 while 無限迴圈，讓球員不停地思考和行動。

3.1 啟動球員執行緒

要讓球員 AI Agent 動起來，你必須先「註冊」一個處理函式，告訴系統：「每當一名球員登場，就用這個函式來控制它。」註冊方式是呼叫 hero.on("spawn-mate", 函式名)。

下面是一段最基礎的球員邏輯：「有球就射門，沒球就追球。」

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

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

void onSpawnMate(Mate* mate) {
    while (true) {
        if (mate->hasBall) {
            mate->shoot();       // 有球就射門
        } else {
            mate->chaseBall();   // 沒球就追球
        }
    }
}

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

3.2 基礎指令

3.3 搶斷能力 clash（球員唯一的主動技能）

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 球員屬性（唯讀）

4. 球與控球機制Ball & Possession

要踢好球，得先搞懂「球是怎麼被搶到、被守住、被攔截的」。這一節的規則決定了控球權的歸屬，非常值得細讀。

4.1 粘球與控球免疫

球是「粘」的：一顆無人控制的自由球，只要進入了某名球員的 params.captureRadius 範圍，就會自動「吸附」到那名球員腳下，變成他控球。之後持球者會一直控著球，直到發生下面三種情況之一：他主動出球（roll）、被敵方成功搶斷（clash）、或被守門員撲住。

4.2 釋放氣泡與攔截

釋放氣泡（Release Bubble）：一顆剛被踢出、正在滾動的球，在它離開釋放點、飛行距離還沒達到 params.rollReleaseRadius 之前，任何人都無法接住它（連守門員也不行）。這就好比球剛出腳時外面罩著一層保護泡泡。因此，即使對手就貼在你身邊，你也能安全地把球踢出去。而與之相對，一顆完全靜止的球，任何時候都可以被撿走。

攔截（Interception）：只要你的球員站在滾球的路徑上、並且位於釋放氣泡之外的位置，球飛過來就歸你了。由於球的運動軌跡是直線，你完全可以透過 hero.ball 提供的位置和速度資訊 (x, y, vx, vy)，用數學算出球接下來會經過哪裡，從而提前跑位去攔截。

5. 進球與開球Goals & Kickoffs

紅隊始終防守左側球門，藍隊始終防守右側球門。當球進入某個球門區域（params.gates）時就算進球——而且不管球是誰踢進去的！

每次進球之後（以及每個回合剛開始時），所有球員的位置和技能冷卻都會重置回初始陣型，球會被重新放到球場中央，並朝開球方偏移一小段距離 params.kickoffOffset——這樣開球方就會確定性地先碰到球。

6. 自動守門員Auto-Keeper — The Fixed NPC

每個球門都由一名 NPC 守門員把守。它不是 AI Agent，沒有人給它寫程式碼——它的行為是系統固定的、完全可預測的。而「可預測」恰恰是你的機會：只要摸清它的規律，就能設計出穩定的破門方法。

解圍超級長傳（Clearance / Super Kick）

守門員拿到球並持球 params.keeperHoldTime 秒之後，會以 params.superKickSpeed 的極快速度，朝離它最近的、且沒被暈眩的自家球員射出一道超級長傳——直線飛行、中途不減速。關於這道解圍球，有幾點要知道：

• 🚫 敵方無法攔截飛行途中的解圍球（它太快了，還帶著「不可攔截」的特性）。
• 🐢 當球飛到接應球員所在的距離時，會降速為普通滾球；如果它撞到牆壁反彈，之後就變回一顆普通的自由球，此時又可以被爭搶了。
• 🤝 如果接應的球員本來就已經在守門員的 params.captureRadius 範圍內，球會被直接交到他腳下，省去飛行過程。

7. 教練 AI Agent（英雄）Coach (Hero) — The Main Thread Agent

主執行緒執行的就是你的教練 AI Agent。和場上跑動的球員不同，教練不親自碰球，而是像一位真正的主教練那樣站在場邊：它能看見場上發生的一切，並適時使用各種即時技能（每個技能都有自己獨立的冷卻時間），從戰術層面影響比賽走向。

7.1 教練方法

7.2 四大教練技能

教練 AI Agent 有四個技能，兩個用來「增益自己人」，兩個用來「干擾對手」：

7.3 全場感知（唯讀）

7.4 教練範例程式碼

下面這段教練邏輯做了兩件聰明事：幫被暈眩的隊友吹哨解控，以及在對方持球時壓迫拖慢對手。

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)

while (true) {
    // 誰被暈眩了，就吹哨幫他解除
    for (auto m : hero.myMates) {
        if (m.isStunned && hero.abilityReady("whistle"))
            hero.whistle(m);
    }
    // 敵方持球時，用壓迫拖慢對手
    auto carrier = hero.ball.owner;
    if (carrier && carrier->color != hero.color && hero.abilityReady("press")) {
        hero.press(carrier);
    }
    hero.wait(0.3);
}

8. 實戰策略Putting It All Together

把球員 AI Agent、教練 AI Agent、守門員這三套系統串起來，一套穩健、適合新手起步的思路大致如下：

• 先啟動執行緒：程式碼裡務必寫上 hero.on("spawn-mate", ...)，否則球員 AI Agent 根本不會動——這是最容易忘、也最致命的一步。
• 球員分工：用 mateId 區分角色——比如一人主攻、搶球射門，一人拉邊接應或回防。每個角色都要處理 hasBall，防止後衛烏龍。
• 靠傳球推進：記住持球會變慢、追趕者總能追上，所以別硬帶球——多用 passTo / cross，甚至撞牆傳球來撕開防線。
• 搶斷先看免疫：呼叫 clash 前先查對手的 isImmune，避免對免疫者搶斷而害自己暈眩。
• 攻破守門員：守門員追球移動，先把它引離球門中心，再射向遠門柱空檔；進攻時可以配合 hero.distract() 拖慢它。
• 教練輔助時機：進攻反擊時用 inspire 給自家球員提速；防守時用 press 拖慢敵方持球者；自家球員被搶斷暈眩時，立刻 whistle 解控。
• 追求攻勢：多傳球、多射門、儘量把球壓在對方半場——這些都在累積粉絲支持度，會在打平時救你一命。

9. 遊戲參數速查Game Parameters

你可以透過 params 物件存取下面所有參數。以下均為預設值——如果文件過時，實際比賽可能採用不同數值，請以遊戲內即時的 params 為準。

場地與球門

球員與移動

搶斷與控球

出球（滾球）

守門員

教練技能

粉絲支持度

🏆 核心速查表Core Cheat Sheet

現在，去 AI 世界盃的賽場上，讓你的 AI Agent 踢出制勝一球吧！🏆