شبیه‌ساز مسابقه‌ی چوگان، ورزش تیمی سنتی ایران، برای ربات‌های خودمختار. دو تیم، هر کدام با چهار ربات، در یک زمین مجازی با فیزیک واقعی بازی می‌کنند. پس از شروع مسابقه هیچ انسانی ربات‌ها را کنترل نمی‌کند؛ همه‌چیز را کد Python شما تصمیم می‌گیرد و داور مصنوعی گل، خطا و زمان را اداره می‌کند.
هر تیم کدی می‌نویسد که چهار ربات آن را هدایت می‌کند. ربات‌های تیم آبی B1 تا B4 و ربات‌های تیم زرد Y1 تا Y4 نام دارند (در شبیه‌ساز به‌صورت قرمز و آبی نمایش داده می‌شوند). هر ربات GPS، قطب‌نما، چهار حسگر فاصله، گیرنده‌ی توپ و فرستنده/گیرنده‌ی تیمی دارد و فقط سرعت چرخ چپ و راست خودش را تعیین می‌کند. هیچ دکمه‌ی «شوت» یا «پاس» وجود ندارد؛ هر تعامل با توپ فیزیکی است.
مسابقه دو نیمه‌ی ۲ دقیقه‌ای دارد. هر گل معتبر یک امتیاز است و تیمی که گل بیشتری بزند برنده است. امتیاز جداگانه‌ای برای مالکیت توپ، پاس، زیبایی کد یا مصاحبه داده نمی‌شود؛ فقط نتیجه‌ی مسابقه. تیم‌ها در دو رده‌ی کاملاً جدای U14 و U19 بازی می‌کنند. در U14 یک قابلیت ویژه به نام Coach Board وجود دارد که در U19 نیست.
تصاویر از نسخه‌ی Windows شبیه‌ساز (Showcase v1) و راهنمای دانش‌آموزی v1.3 گرفته شده‌اند. برخی صفحه‌ها هنوز نام قدیمی «CHOGAN» را روی خود دارند؛ نام رسمی لیگ CHOVGAN است. ترتیب پیشنهادی یادگیری: Rules & Guide ← Robot Lab ← Training ← Competition.
فایل CHOGAN_Showcase_Windows.exe را از بخش دانلود بگیرید (حدود ۱۲۰ مگابایت) و آن را در یک پوشه مثلاً Chogan قرار دهید. نیاز به نصب ندارد؛ روی آن دوبار کلیک کنید. اگر ویندوز پیام آبی «Windows protected your PC» داد، روی More info و سپس Run anyway بزنید.
شبیه‌ساز با صحنه‌ی ورزشگاه و منوی سمت چپ باز می‌شود: Competition، Training، Robot Lab، Rules & Guide، Settings، About، Exit. اول Rules & Guide را بخوانید، در Robot Lab با «Open live sensor practice» حسگرها را ببینید و در Training تمرین کنید. برای مسابقه Competition را بزنید و در صفحه‌ی Select Competition Division روی Select U14 یا Select U19 کلیک کنید (مطابق رده‌ی ثبت‌نامی تیم).
کد تیم یک پوشه به نام chovgan_team است با فایل‌های robot.py (راه‌انداز)، chovgan_robot.py (کمکی SDK)، robot1.py تا robot4.py (کد چهار بازیکن) و در صورت نیاز utils.py. شبیه‌ساز برای هر ربات یک بار robot.py را اجرا می‌کند و این فایل از روی نام ربات (مثلاً B3) کلاس بازیکن مناسب را انتخاب می‌کند. روی ربات چهارپا، «left wheel motor» و «right wheel motor» کنترل‌های مجازی حرکت‌اند که شبیه‌ساز به راه رفتن و چرخیدن ترجمه می‌کند.
در Competition مراحل MATCH و TEAMS را کامل کنید تا به STRATEGY (03) برسید. در Code workflow یکی از دو گزینه‌ی One team file یا One file per robot را انتخاب کنید، سپس در پنل تیم خود روی Select strategy file بزنید و فایل یا ZIP تیم را بدهید. پیام‌های زیر انتخاب‌گر را بخوانید: تا وقتی «Manifest / SDK / controllers: not verified» نشان می‌دهد، کد شما اعتبارسنجی نشده است. «Built-in match strategy available» یعنی راهبرد داخلی شبیه‌ساز، نه کد شما. بعد از تأیید، Next: Ready Check را بزنید. کد باید حتماً داخل شبیه‌ساز اجرا شود؛ اجرای robot.py در یک پنجره‌ی معمولی Python شیء Robot را نمی‌سازد.
پوشه‌ی chovgan_team/، فایل team_name.txt (نام تیم در یک خط) و در صورت تمایل logo.png را با هم در یک فایل ZIP فشرده کنید. پوشه‌ها باید مستقیم در سطح اول ZIP باشند، نه داخل یک پوشه‌ی دیگر. محل و مهلت آپلود را کمیته فنی اعلام می‌کند.
ChovganTeam.zip
chovgan_team/
robot.py # راه‌انداز: بازیکن درست را انتخاب می‌کند
chovgan_robot.py # کمکی مشترک ChovganRobot
robot1.py # بازیکن ۱
robot2.py # بازیکن ۲
robot3.py # بازیکن ۳
robot4.py # بازیکن ۴
utils.py # اختیاری: توابع مشترک
team_name.txt # نام تیم
logo.png # اختیاریfrom controller import Robot
from robot1 import ChovganPlayer1
from robot2 import ChovganPlayer2
from robot3 import ChovganPlayer3
from robot4 import ChovganPlayer4
PLAYERS = {1: ChovganPlayer1, 2: ChovganPlayer2,
3: ChovganPlayer3, 4: ChovganPlayer4}
robot = Robot()
number = int(robot.getName()[1:]) # "B3" -> 3
player = PLAYERS[number](robot)
player.run()robot.py آن‌ها را درست import می‌کند؛ team_name.txt واقعاً متنی است (نه team_name.txt.txt)؛ ZIP بدون خطا باز می‌شود؛ پوشه‌ی اضافی یا پوشه‌ی controllers/ وجود ندارد؛ بسته‌ی controller خود شبیه‌ساز را داخل ZIP نگذاشته‌اید.یک تیم چهار رباتی کامل (دروازه‌بان، مدافع، دو مهاجم) مطابق API رسمی Chovgan SDK 1.0، به‌علاوه‌ی یک ران‌تایم محلی که همان API را روی یک زمین دوبعدی اجرا می‌کند؛ بنابراین کد را همین امروز، بدون شبیه‌ساز اصلی، اجرا می‌کنید و حرکت ربات‌ها و گل‌ها را می‌بینید.
Chovgan-BaseCode.zip را بگیرید و باز کنید. فقط Python 3.10 یا جدیدتر لازم است؛ هیچ کتابخانه‌ای نصب نمی‌شود.
در پوشه‌ی chovgan_base ترمینال باز کنید و بزنید:
python local_runtime/run_local.py --realtimeتیم شما (آبی) مقابل حریف داخلی بازی می‌کند؛ زمین به‌صورت متنی رسم می‌شود و داور گل، شروع مجدد و «عدم پیشرفت» را اعلام می‌کند. بدون --realtime بازی با بیشترین سرعت اجرا و فقط نتیجه چاپ می‌شود.
فایل‌های robot1.py تا robot4.py را عوض کنید؛ توابع کمکی (go_to، face_ball، drive) در utils.py هستند. با --yellow chovgan_team تیم را مقابل خودش بیازمایید.
فقط chovgan_team/ و team_name.txt را ZIP کنید؛ پوشه‌ی local_runtime را نه.
utils.py قابل تنظیم است.Blue = chovgan_team
Yellow = built-in opponent
[referee 13.3s] {"event": "goal", "team": "B", "score": {"B": 1, "Y": 0}}
[referee 26.6s] {"event": "goal", "team": "B", "score": {"B": 2, "Y": 0}}
[referee 120.0s] {"event": "half_time", "score": {"B": 4, "Y": 0}}
...
FINAL Blue 8 - 0 Yellow
match log written to last_match.jsonchovgan_base/
chovgan_team/ # <- این پوشه تحویل داده می‌شود
robot.py # راه‌انداز: B3 -> ChovganPlayer3
chovgan_robot.py # کلاس کمکی ChovganRobot (همه‌ی دستگاه‌ها)
robot1.py # دروازه‌بان
robot2.py # مدافع
robot3.py # مهاجم (پشت توپ می‌رود و هل می‌دهد)
robot4.py # مهاجم دوم (همان کلاس، شریک ۳)
utils.py # drive / go_to / face_ball / ثابت‌های زمین
team_name.txt
local_runtime/ # شبیه‌ساز محلی (در ZIP تحویلی نمی‌رود)
controller/ # ماژول controller با همان API رسمی
run_local.py # اجرای ۸ کنترلر + داور ساده
README.mdبر پایه‌ی «راهنمای برنامه‌نویسی دانش‌آموزی Chovgan، نسخه‌ی ۱.۳ (Chovgan SDK 1.0 — API نهایی دانش‌آموزی، ۱۷ اکتبر ۲۰۲۶)». هر جلسه حدود ۹۰ دقیقه. U14 می‌تواند جلسه‌های ۱ تا ۷ را عمیق‌تر کار کند؛ U19 همه‌ی جلسه‌ها به‌علاوه‌ی چالش پیشرفته. فایل کامل راهنما در بخش دانلود هست.
دانش‌آموز بتواند یک مسابقه‌ی Chovgan را از شروع تا نتیجه شرح دهد و نقش داور مصنوعی را توضیح دهد.
آزمونک کوتاه: چه کسی شروع مجدد را کنترل می‌کند؟ آیا تیم می‌تواند ربات خودش را جابه‌جا کند؟ چه چیزی گل حساب می‌شود؟
from controller import Robot برنامه را به ربات شبیه‌ساز وصل می‌کند.getDevice("left wheel motor") موتور را با نام دقیق پیدا می‌کند؛ setPosition(float("inf")) موتور را در حالت کنترل سرعت می‌گذارد.robot.step(32) تا به‌روزرسانی بعدی شبیه‌سازی صبر می‌کند (۳۲ میلی‌ثانیه). robot.getTime() زمان شبیه‌سازی به ثانیه.from controller import Robot
TIME_STEP = 32
robot = Robot()
left = robot.getDevice("left wheel motor")
right = robot.getDevice("right wheel motor")
left.setPosition(float("inf"))
right.setPosition(float("inf"))
start = robot.getTime()
while robot.step(TIME_STEP) != -1:
if robot.getTime() - start < 2.0:
left.setVelocity(3.0); right.setVelocity(3.0)
else:
left.setVelocity(0.0); right.setVelocity(0.0)setVelocity فقط سرعت را درخواست می‌کند؛ حلقه‌ی robot.step(...) باید همچنان بچرخد.left.setVelocity(3.0); right.setVelocity(3.0) # جلو
left.setVelocity(-3.0); right.setVelocity(-3.0) # عقب
left.setVelocity(3.0); right.setVelocity(-3.0) # چرخش درجا
left.setVelocity(2.0); right.setVelocity(4.0) # مسیر منحنیdrive(v, w) بنویسید که سرعت جلو و سرعت چرخش را به سرعت دو چرخ تبدیل کند و خروجی را به بازه‌ی −۱۰ تا +۱۰ محدود کند.robot.getName() نام ربات را می‌دهد: حرف اول تیم (B یا Y) و عدد شماره‌ی بازیکن. هرگز "B1" را در کد ثابت ننویسید.distancesensor front، back، left، right. مقدار کوچک‌تر معمولاً یعنی مانع نزدیک‌تر؛ عدد سانتی‌متر نیست.enable(32) فعال شود.front = robot.getDevice("distancesensor front")
front.enable(TIME_STEP)
while robot.step(TIME_STEP) != -1:
if front.getValue() < 300:
left.setVelocity(0.0); right.setVelocity(0.0)
else:
left.setVelocity(3.0); right.setVelocity(3.0)gps.getValues() سه مقدار می‌دهد: x، y و ارتفاع؛ مختصات زمین، نه طول و عرض جغرافیایی.compass.getValues() یک بردار جهت می‌دهد، نه زاویه‌ی درجه. محاسبه‌ی زاویه با math.atan2 گام پیشرفته و اختیاری است.gps = robot.getDevice("gps"); gps.enable(32)
compass = robot.getDevice("compass"); compass.enable(32)
while robot.step(32) != -1:
x, y, height = gps.getValues()
v = compass.getValues()
heading = math.atan2(v[0], v[1]) + math.pi / 2ball receiver مشاهدات توپ را در یک صف (FIFO) می‌گذارد: جهت محلی توپ (getEmitterDirection) و قدرت سیگنال (getSignalStrength). سیگنال قوی‌تر معمولاً یعنی توپ نزدیک‌تر.nextPacket() را صدا بزنید وگرنه همان پیام تکرار می‌شود.direction[0] همیشه یعنی «چپ»؛ قرارداد محورها را در شبیه‌ساز بررسی کنید.ball = robot.getDevice("ball receiver"); ball.enable(32)
while robot.step(32) != -1:
if ball.getQueueLength() > 0:
direction = ball.getEmitterDirection()
strength = ball.getSignalStrength()
ball.nextPacket()team emitter و team receiver فقط بین ربات‌های یک تیم کار می‌کنند؛ ارسال پیام به تیم حریف ممنوع است.sender = robot.getDevice("team emitter")
receiver = robot.getDevice("team receiver"); receiver.enable(32)
message = {"robot": robot.getName(), "status": "ready"}
sender.send(json.dumps(message))
while receiver.getQueueLength() > 0:
data = json.loads(receiver.getString()); receiver.nextPacket()supervisor receiver (فقط خواندنی) می‌توانید پیام‌های داور را بخوانید. قالب نهایی فیلدها را کمیته فنی منتشر می‌کند؛ راهبرد را به کلیدهای حدسی وابسته نکنید.ChovganRobot در chovgan_robot.py متدهای آماده دارد: get_gps_coordinates()، get_compass_heading()، get_sonar_values()، is_new_ball_data() / get_new_ball_data()، is_new_team_data() / get_new_team_data()، send_data_to_team(value).from chovgan_robot import ChovganRobot, TIME_STEP
class MyChovganRobot(ChovganRobot):
def run(self):
while self.robot.step(TIME_STEP) != -1:
if self.is_new_ball_data():
ball = self.get_new_ball_data()
print("Ball strength:", ball["strength"])robot.py) و چهار کلاس راهبرد (robot1.py تا robot4.py). همه‌ی بازیکن‌ها همان حسگرها را دارند؛ تفاوت فقط در منطق است.utils.py بگذارید؛ از import دایره‌ای پرهیز کنید.controller: کد بیرون از شبیه‌ساز اجرا شده است.nextPacket() را فراموش کرده‌اید.robot4.py و نگاشت شماره‌ها را بررسی کنید."gps" "compass"
"ball receiver" "supervisor receiver"
"team emitter" "team receiver"
"distancesensor front" "distancesensor back"
"distancesensor left" "distancesensor right"
"left wheel motor" "right wheel motor"
TIME_STEP = 32 ms | motor speed: -10 .. +10 | team message <= 4096 bytesاین خلاصه برای فهم سریع است؛ متن کامل و رسمی را از بخش دانلود بگیرید. در صورت اختلاف، آخرین نسخه‌ی رسمی منتشرشده توسط کمیته فنی معتبر است.
به‌روزترین نسخه‌ی فایل‌ها همیشه ابتدا در کانال کمیته داوران منتشر می‌شود.
برای دریافت فایل‌ها، اطلاعیه‌ها و پرسیدن سؤال از کمیته داوران جوین شوید.