This Guide Is All You Need

1 2	竞赛官方qq群：540967785 金足印象qq群：733053456

Preface

本文档参考了SJTU和ZJU两所高校的一些资料进行编写，这是一个不完全的指南文档，有兴趣的可以进行扩写和更新。

今年规则发生了一些改动，积分赛规则改为两次传球，国赛队伍进行3V3排名赛。

Lesson1 Introduction

Target

了解比赛相关的基本知识和
学会查找开源资料
学会阅读内部资料

1.了解RoboCup与SSL（Small Size League）

RoboCup is a competition domain designed to advance robotics and AI research through a friendly competition.

RoboCup is an annual international robotics competition proposed and founded in 1996 (Pre-RoboCup) by a group of university professors (among which Hiroaki Kitano, Manuela M. Veloso, and Minoru Asada). The aim of such a competition consists of promoting robotics and AI research, by offering a publicly appealing, but formidable challenge.

Small Size robot soccer is one of the RoboCup league divisions.

Small Size robot soccer, or F180 as it is otherwise known, focuses on the problem of intelligent multi-agent cooperation and control in a highly dynamic environment with a hybrid centralized/distributed system.

2.SSL系统架构

系统架构

RoboRun

通过SSL-Version共享视觉系统，使裁判机(SOM)接收信息，裁判机对场上机器人(Agent)发出指令(Play)，机器人在对应状态机内执行各自的动作(Skill)

策略机与机器人通信：

Communication

Skill&Agent：

Skill&Agent

SSL策略框架

整个结构是分层的，策略层大概可以这样分层：

顶层是PlayBook，负责根据场上情况来选择合适的战术。其中使用了贝叶斯方法（recursive Bayesian estimation）来评估场上情况；
第二层是Play,存储着制定好的各种战术，包括各种定位球战术，运动战战术。每一个战术都是一个状态机，会根据不同的状态做出不同的动作，满足条件时会跳出。每一个状态内部都定义了每一台机器人的行为，不过也可以选择让机器人维持之前的状态，每个状态内部还定义了机器人的角色匹配规则，在执行这个战术（即PlayBook选择这个战术）时会根据状态内部的规则进行角色匹配。这一层主要用Lua实现；
第三层是Agent,在程序中代表执行动作的个体，也就是一台机器人，Play层的战术会分配给每一个机器人去分别执行。执行战术的人选是在Play层就定好了的，在这一层将动作分配给每一个个体，个体执行分配到的任务，也就是执行SKill层的一个个动作；
第四层是SKill,一个SKill只定义一个机器人的动作，比如射门、传球。这一层提供各种战术动作给Play层，完成战术布置。在这一层内部也有从简单到复杂的层级结构，最基本的SKill（动作）只有跑到一个固定点固定朝向和踢球，复杂的动作比如追踢是由调用简单的底层动作实现的。这一层主要用C++实现；

除了策略部分之外还有一个World Model，维护着环境信息，类似于openAI gym中的environment。这个部分将摄像头和机器人身上的传感器收集到的数据暴露给策略部分中的各个层级，为它们提供信息。这一部分有Lua和C++的接口。

3.掌握简单的入门知识

About Robocup：https://en.wikipedia.org/wiki/RoboCup
About SmallSizeLeague：http://wiki.robocup.org/Small_Size_League
RoboCup official website：http://www.robocup.org/

4.软件下载与配置

软件	作用
VisualStudio2013	编写cpp
Sublime（任一合适编辑器都可，用于Lua脚本编写）	编写lua
Typora（或在VisualStudio Code中配置markdown插件）	编写markdown文档
Version（裁判机视觉软件）	视觉调试
SOM v3.4.2	脚本调试

基本软件配置参考csdn或b站教程，编写配置参考官方文档

文档	作用
SOM-V3.4用户手册	SOM软件配置和使用
SOM v3.4二次开发手册	同上
机器人控制编程	Lua、Cpp基础编写和文件配置教程（含官方函数注释）
iLoboke I 足球机器人用户手册	机器人和系统架构详解
iLobike足球机器人比赛(4V4)	规则详解
SOM-V3.1官方task函数源码包	官方cpp示例文件

==竞赛官方视频号（很重要）：创非凡机器人投稿视频-创非凡机器人视频分享-哔哩哔哩视频 (bilibili.com)==

Lesson2 Hello,Lua

Target

了解SOM文件夹中Lua脚本之间的联系、结构、分类
学会编写基本的Lua脚本
编写一个自己的脚本导入SOM进行调试
了解状态机和元表(table-driving)

了解Lua语言

Lua 是一个小巧的脚本语言，其设计目的是为了嵌入应用程序中，从而为应用程序提供灵活的扩展和定制功能。Lua由标准C编写而成，几乎在所有操作系统和平台上都可以编译，运行。Lua并没有提供强大的库，这是由它的定位决定的。所以Lua不适合作为开发独立应用程序的语言。

Lua有一个同时进行的JIT项目，提供在特定平台上的即时编译功能。Lua脚本可以很容易的被C/C++代码调用，也可以反过来调用C/C++的函数，这使得Lua在应用程序中可以被广泛应用。不仅仅作为扩展脚本，也可以作为普通的配置文件，代替XML,ini等文件格式，并且更容易理解和维护。

Lua由标准C编写而成，代码简洁优美，几乎在所有操作系统和平台上都可以编译，运行。一个完整的Lua解释器不过200k，在目前所有脚本引擎中，Lua的速度是最快的。这一切都决定了Lua是作为嵌入式脚本的最佳选择。

参考wiki：LuatOS 文档

Lua基础教程：【无废话30分钟】Lua快速入门教程 - 4K超清_哔哩哔哩_bilibili

具体写法：足球机器人软件培训（修改lua脚本）_哔哩哔哩_bilibili

A Guide to Lua_Scripts

最常改动的lua脚本位于目录：…\SOM\Team\lua_scripts

FolderName	Description
opponent	针对世界强队和特殊情况的战术脚本
play	定位球（Ref）和普通（Nor）情况下的进攻（Kick）和防守（Def）的战术脚本
skill	具体动作的战术脚本
utils	工具类脚本
worldmodel	物理世界的反馈判断（Judge）
ZeusLua	未知
Config.lua	整场比赛的配置文件
…	…

有限状态机(State Machine)

进入一个状态
从World Model中获取信息，判断下一步进入哪个状态
动作分配
匹配规则

-- 在实现中，每个状态都是一个Lua的table类型变量，
-- 包括switch，match，Kicker、Goalie（各个角色）这些键
["run1"] = {
    -- 状态的跳转函数
    switch = function ()
        -- 从World Model中获取信息，判断下一步进入哪个状态
        if player.toTargetDist("Kicker") < 20 then
            return "run2"
        end
    end,
    -- 分配任务，调用封装的SKill
    Kicker = task.goCmuRush(TargetPos1, 0),
    -- 匹配规则，这样写就是不匹配
    match = ""
},

参考：SOM包已有的脚本

Lesson3 Hello,Cpp

Target

看懂官方task函数源码包中的示例cpp文件
编写一个简单的射门或跑位skill
生成dll放置到SOM包对应路径，并在Lua脚本中调用

A Guide to Cpp

最常改动的dll文件位于目录：…\SOM\Team\user_skills

文件名	作用
机器人控制编程	Lua、Cpp基础编写和文件配置教程（含官方函数注释）
SOM-V3.1官方task函数源码包	官方cpp示例文件（Getball.cpp包含注释）

压缩包内还附带了一些Cpp相关的优质书籍

Cpp基本语法和C11特性本文档暂时不做解释，需要自学。

重点对照示例代码，关注const、左值右值、类型转换、math库、vector库的使用

extern "C"_declspec(dllexport) PlayerTask player_plan(const WorldModel* model, int ...);

PlayerTask player_plan(const WorldModel* model, int ...){
    PlayerTask task;
}
//函数接口

函数	解释
vector2polar(ρ,θ)	极坐标
length()	长度
angle()	角度
point2f	向量类型的变量声明
const	常量
target_pos	目标点
orientate	机器人朝向
needCb	吸球开关
isKick	踢球开关

Lesson4 Miscellaneous

Software Tool

必需	非必需
git/github	cmake
markdown语法	路径规划相关的Cpp算法

Hardware Tool

工具清单	作用
电工胶带	机器人外壳防漏光

Matters Needing Attention

在写C++之前需要在VS中正确配置对应worldmodel_lib.lib链接库文件，具体教程见官方文档及教程。

重点：尽量提升代码的可读性和鲁棒性，避免冗杂和高耦合

~~ps：仿真和实地测试的差距大概相当于你和你女神的距离，孩子~~

Some Ideas

技术挑战赛：面向调参的算法实现

通过Lua脚本调用C++编译生成的dll文件，构建决策树。

在积分赛中，高稳定性和耗时短是最重要的，因此可以考虑一些奇淫技巧。例如提前量传球+最优延迟：

["passball"] = {
	switch = function()
		if CBall2RoleDist("Kicker")>35 and Cbuf_cnt(true,140) then
			return "receive"
		end
	end,
	Kicker   = task.KickerTask("passball2"),
	Receiver = task.GotoPos("Receiver",RobotPosX("Receiver"),RobotPosY("Receiver"),Receiver2Balldir()),
}

当然，这是种很唐的写法，不推荐大量使用Cbuf_cnt()

3V3对抗赛：面向边际问题的算法实现

1.延续积分赛的写法，任务分配时加入goalie，最终在SOM战术包中选择脚本进行排列组合

分析：单个脚本中进行整体状态分析和决策调用，Lua脚本较为冗长，有可能会导致屎山底层的task优先级异常高

2.也可以尝试在单个脚本中通过dofile的方式进行多脚本调用 ~~（一个猜想，不一定对）~~

伪代码示例：if …dofile(…)

dofile("./lua_scripts/opponent/"..json.OPPONENT_NAME..".lua") ` 

function shitlang(name)
    if json.GO_WRITE_SHIT then
	    if name == "someshit" then
		    print("This is a shit")` 
            ... ...
            dofile(filename)
		else
            ... ...

Other Resources

历届Robocup会议论文集（1997-2023）：

https://link.springer.com/conference/robocup

Robocup SSL(Small Soccer League)网站资源：

Rocos，另一家公司
（已知iLoboke源自浙大15年技术架构，该公司及相关学校技术架构大概在上交/浙大17~18年水平）

浙大Github全开源资料主页（包含主控板/机械设计/强化学习框架/视觉处理器和GUI等）

https://github.com/ZJUNlict

Robocup国际队伍开源资料（佐治亚理工）

RobocupSSL Guideline

This Guide Is All You Need

Directory

Preface

Lesson1 Introduction

Target

1.了解RoboCup与SSL（Small Size League）

2.SSL系统架构

3.掌握简单的入门知识

4.软件下载与配置

Lesson2 Hello,Lua

Target

了解Lua语言

A Guide to Lua_Scripts

Lesson3 Hello,Cpp

Target

A Guide to Cpp

Lesson4 Miscellaneous

Software Tool

Hardware Tool

Matters Needing Attention

Some Ideas

技术挑战赛：面向调参的算法实现

3V3对抗赛：面向边际问题的算法实现

Other Resources