写给新桌游开发者
===================

从core的提交 ``8483eba`` 开始，Freekill可以用来创建三国杀之外的全新桌游了。
底层为此进行了比较大的重构，让新的桌游可以聚焦于自己的逻辑和数据，而复用Freekill提供的通用性功能（登录登出、重连旁观等等）。

在开始之前，我们先结合实际对整体开发思路做一个总览。

桌游是针对在桌边或任何由数名玩家面对面于同一空间玩的游戏的泛称，其基本上就是几名玩家利用固定配件，按照一定的规则进行游玩（一般是回合制的）。比如一盒中国象棋：

- 配件：盒子中有一块塑料棋盘布、32颗棋子。不玩时这盒棋一般收纳在一边。
- 游戏准备：对弈之前，需要先有两名玩家和一张桌子，并将棋具取出放在一旁。
- 游戏开始之前：双方先约定好具体使用哪种玩法，比如可以玩象棋、翻棋、揭棋，甚至是朝鲜族象棋（可以用一样的棋具玩，但规则不同）
- 游戏开始：玩家根据规则将棋子按初始状态摆好。
- 游戏进行：玩家根据规则对弈。
- 游戏结束：当规则中某种游戏结束的情况满足时游戏结束。玩家将棋具整理好放在一边。
- 结束之后：玩家可以重新摆好棋子，再次开始游戏，也可以就此散场。

这样的例子能在Freekill中找到类比。首先，集齐人员和场地、人员离场等都由Freekill本体提供支持。
基于Freekill的桌游需要聚焦的点在于：

1. 定义该桌游的静态数据，在运行中这些数据不会被改变（可以类比为固定的棋具）
2. 定义该桌游的动态数据，在运行中这些数据会不断改变（例如棋盘状态）
3. 编写桌游的游戏规则代码，让程序代替人脑运行规则
4. 编写桌游的界面，让人类通过界面操作桌游

这四个步骤是Freekill的基本思想。在今后的实际开发中我们基本上也会按顺序去一步步实现它们。
之后的文档也将结合中国象棋这一例子说明桌游的开发方法。

中国象棋的成品请见 https://gitee.com/notify-ctrl/chess-games 。文档主要对其中的代码进行解说，
因此请先将其clone到拓展包目录中，让创建房间时可以选象棋模式。

.. note::

   可新月杀不是更复杂、更完善吗？很遗憾由于历史原因，新月杀比较耦合，有很多搞特殊的地方。
   底层是经过尽力重构后才在一定程度上将新月杀与通用代码分离开来的。

   顺便桌游功能仍处于早期，肯定有设定不周到的地方。本文档仅针对现状进行说明。

以下是象棋例子的一系列说明，旨在说明Freekill是如何支持制作新桌游的。

- :doc:`begin-and-engine`
- :doc:`roombase`
- :doc:`gamelogic`
- :doc:`client`
- :doc:`surrender`
- :doc:`xiangqi-fin`

.. comment

  但是不是已经有桌游模拟器（TTS）可以玩几乎所有桌游了吗？为什么还要用Freekill创建新桌游呢？以下是一些比较：
  （然而这段话没必要出现在文档正文）

  - TTS需要购买；Freekill开源免费
  - 手机可以玩Freekill
  - TTS有图就能玩；无需代码，使用Freekill实现一款桌游需要了解代码（比开发新月杀拓展更难）
  - TTS需要玩家自己遵守规则；Freekill通过代码实现了桌游的结算，玩家按照界面提示进行交互即可
  - Freekill可以在服务端统计胜率，以及更多自定义信息（TODO：然而目前没有胜率之外的信息）
  - Freekill的联机体验比TTS更加流畅，支持局域网、自建服务端等
  - Freekill可以与人机对战（然而新月杀并没有实现ai；至少Freekill为桌游开发者留出了ai接口）

.. toctree::
   :titlesonly:
   :hidden:

   begin-and-engine.rst
   roombase.rst
   gamelogic.rst
   client.rst
   surrender.rst
   xiangqi-fin.rst
   qml.rst