FreeKill/doc/diy/01-env.md

# Fk DIY - 环境搭建

> [diy](./index.md) > 环境搭建

* [DIY总览](#diy总览)
* [环境搭建](#环境搭建)
  * [Fk](#fk)
  * [代码编辑器](#代码编辑器)
  * [git](#git)
    * [安装git](#安装git)
* [新增mod](#新增mod)
* [发布mod](#发布mod)
  * [将终端切换为Git Bash](#将终端切换为git-bash)
  * [配置ssh key](#配置ssh-key)
  * [新建git仓库](#新建git仓库)
  * [让他人安装并游玩你的mod](#让他人安装并游玩你的mod)
  * [更新mod](#更新mod)

___

## DIY总览

正如[项目README](../../README.md)所言，FreeKill“试图打造一个最适合diy玩家游玩的民间三国杀”。即便是最开始游戏功能尚未完善，FreeKill也已经具备了对DIY的支持。所有拓展包都列在packages/文件夹下，感兴趣者可以自行查看。

欲为FreeKill进行DIY，需要使用的编程语言为Lua。若您对Lua语言完全不熟悉，推荐去[菜鸟教程](https://www.runoob.com/lua/lua-tutorial.html)速通一遍基本语法。剩下的就基本是在实践中慢慢领会了。

FreeKill本体中自带有标准包和标准卡牌包，可作为DIY时候的例子。事实上，其他DIY包也是像这样子组织的。

接下来讲述如何配置环境。

___

## 环境搭建

### Fk

Fk是游戏本身，也是拓展包运行的平台。事实上这份文档应该与Fk一同发布的，如果您正在阅读这份文档，那么您理应已经接收到了Fk本身。

### 代码编辑器

代码编辑器任选一种即可，但一定要确保以下几点：

- 至少要是一款**代码**编辑器，要有语法高亮功能
- 需要有EmmyLua插件的支持
- 需要默认UTF-8格式保存代码文件

> EmmyLua是一种特别的Lua注释方式，可以为本来弱类型的Lua语言提供类型支持，这对于像FreeKill这种稍有规模的Lua项目是十分必要的。目前能提供开箱即用的EmmyLua插件编辑器主要有IntelliJ IDEA和Visual Studio Code。EmmyLua也能以LSP的方式运行，因此支持LSP的编辑器（这种就多了,比如vim, sublime）也能符合条件。

编辑器的具体安装以及插件配置不在此赘述。

> 出于易用性和免费的考虑，推荐用VSCode进行拓展。下文将以VSCode为编辑器进行进一步说明。

### git

git就不必多介绍了吧，这里说说为什么需要配置git。这是因为在Fk中，拓展包拥有在线安装/在线更新的功能，这种功能都是依托于git进行的，因此如果你打算将自己的拓展包发布出去的话，就需要将其创建git仓库，并托管到git托管网站去。

> 考虑到国内绝大部分人的访问速度，综合国内几家git托管平台，建议使用gitee。

大多数人可能从未用过git，并且git上手的门槛并不低，因此以下会对涉及git的操作进行详尽的解说。

#### 安装git

前往[官网](https://git-scm.com/download/win)下载git，下载64-bit Git for Windows Setup。这样应该会为您下载一个exe安装包。

考虑到官网的下载链接实际上指向github，而且可能连官网的都进不去，所以也考虑[从清华源下载Git](https://mirrors.tuna.tsinghua.edu.cn/github-release/git-for-windows/git/)。

欲验证安装是否完成，可以按下Win+R -> cmd弹出命令行窗口，输入git命令，如果出来一长串英文说明安装成功了。

___

## 新增mod

这只是新增mod的一个例子。当然了，以后有啥要做的实例也会继续用这个拓展包的。

首先前往packages下，新建名为fk_study的文件夹。

再在fk_study下新建init.lua文件，写入以下内容：

```lua
local extension = Package("fk_study")

Fk:loadTranslationTable{
  ["fk_study"] = "fk学习包",
}

return { extension }
```

保存退出，打开Fk，进武将一览。你现在应该能在武将一览里面看到“fk学习包”了，但也仅此而已了，毕竟这还只是个空壳包而已。

至此我们已经创建了最为简单的mod。mod的文件结构如下：

    fk_study
    └── init.lua

___

## 发布mod

一种最常见的发布mod方式是把mod打包成zip，发到公共平台上供玩家下载。这种办法虽然可行，但并不是fk推荐的做法。

> 以下介绍的其实就是新建仓库并推送到gitee的办法，熟悉git者请跳过。

下面着重介绍用git发布mod的办法。使用git进行发布的话，就可以让用户体验在线安装、在线更新等便捷之处。

以下假设你使用vscode进行代码编辑。你是先用vscode打开了整个FreeKill文件夹，再在其中新建文件夹和文件、然后进行编辑的。

菜单栏 -> 终端 -> 新建终端。我们接下来的工作都在终端中完成。

### 将终端切换为Git Bash

启动终端后，终端的内容大概是：

```plain
Mincrosoft Windows 10 [版本号啥的]
xxxxxxxx 保留所有权利。

C:\FreeKill>
```

这个是Windows自带的cmd，我们不使用这个，而是去用git bash。此时终端上面应该有这么一条：

```plain
问题 输出 调试控制台 _终端_      cmd  + v 分屏 删除
                                   注意这个加号
```

这时候点击加号右边那个下拉箭头，选择"Git Bash"。这样就成功的切换到了git bash中，终端看起来应该像这样：

```plain
xxx@xxxxx MINGW64 /c/FreeKill
$
```

### 配置ssh key

你应该已经注册好了自己的gitee账号。首先在Git bash中输入这些命令（#号后面的是命令注释，不用照搬；命令开头的\$符号是模拟shell的界面，不要输入进去）：

```sh
$ cd ~/.ssh
$ ssh-keygen -t rsa -C "你注册用的邮箱地址" # 换成自己真正的邮箱
  # 出来一堆东西，一路点回车就是了
$ cat id_rsa.pub
  # 出来一堆乱七八糟的东西：ssh-rsa <一大堆乱七八糟的内容> <你的邮箱>
$ cd -
```

在cat id_rsa.pub中，出来的那一堆以ssh-rsa的输出，就是这里要用到的“公钥”。然后在gitee中：

1. 点右上角你的头像，点账号设置
2. 点左侧栏中 安全设置 - SSH公钥
3. 此时弹出公钥添加界面，标题任选，下面公钥那一栏中，将刚刚生成的公钥复制粘贴上去
4. 点确定

这样就配置好了ssh公钥。进行验证，在bash中使用命令：

```sh
$ ssh -T git@gitee.com
Hi xxxx! You've successfully authenticated, but GITEE.COM does not provide shell access.
```

输出像Hi xxx!这样的信息，就说明配置成功了。否则需要进一步检查自己的操作，上网查一下吧。

### 新建git仓库

现在终端的工作目录应该还是FreeKill根目录，我们先切换到mod的目录去，然后再在shell中进行一系列操作。

```sh
$ cd packages/fk_study
$ git init # 创建新的空仓库
$ git add .  # 将文件夹中所有的文件都加入暂存区
$ git commit -m "init" # 提交目前所有的文件，这样文件就正式存在于仓库里面了
作者身份未知
*** 请告诉我您是谁。
运行
  git config --global user.email "you@example.com"
  git config --global user.name "Your Name"

来设置您账号的缺省身份标识。如果仅在本仓库设置身份标识，则省略 --global 参数。
```

看来我们初次安装Git，Git还不知道我们的身份呢，不过git已经告诉了配置所需的命令了。运行前一条命令告知自己的名字，运行后一条命令告知自己的邮箱。如此就OK了，然后再commit一次。

然后在gitee中也新建一个仓库，取名为fk_study。接下来回到终端里面：

```sh
$ git remote add origin git@gitee.com:xxx/fk_study # 其中这个xxx是你的用户名
$ git push -u origin master
```

OK了，刷新你新建的那个仓库的页面，可以看到里面已经有init.lua了。此时距离发布mod只有最后一步，那就是把仓库设置为开源。请自行在gitee中设置吧。

### 让他人安装并游玩你的mod

注意到Fk初始界面里面的“管理拓展包”了不？这个就是让你安装、删除、更新拓展包用的。在那个页面里面有个输入框，在浏览器中复制仓库的地址（比如https://gitee.com/xxx/fk_study/ ），粘贴到输入框，然后单击“从URL安装”即可安装拓展包了。

### 更新mod

现在mod要发生更新了，更新内容为一个武将。先在init.lua中新增武将吧。

```lua
local study_sunce = General(extension, "study_sunce", "wu", 4)
Fk:loadTranslationTable{
  ["study_sunce"] = "孙伯符",
}
```

保存，此时注意vscode左侧栏变成了：

    v fk_study
    └── init.lua            M

init.lua后面出现了“M”，并且文件名字也变成了黄色，这表示这个文件已经被修改过了，接下来我们把修改文件提交到仓库中：

```sh
$ git add . # 将当前目录下的文件暂存
$ git commit -m "add general sunce" # 提交更改，提交说明为add general sunce
$ git push # “推”到远端，也就是把本地的更新传给远端
```

不喜欢用命令行的话，也可以用vscode自带的git支持完成这些操作，这里就不赘述了。做完git push后，实际上就已经完成更新了，可以让大伙点点更新按钮来更新你的新版本了。

___

以上介绍了大致的创建mod以及更新的流程。至于资源文件组织等等杂七杂八的问题，请参考已有的例子拓展包。

下一篇： [fk技能类型总览](./02-skilltype.md)