角色能力是通过一个回调接口Girl实现的。 每一个角色都对应一个Girl的子类。 Girl本身定义在libsaki/table，其子类定义在libsaki/girl。


FAQ

  • 如何修改现有角色的一个技能？
    • 参考libsaki/girl里的各种现有技能，照葫芦画瓢。
  • 如何创建新角色？
    • 第一步：在mjpancake/qrc/qml/js/girlnames.js中修改availIds， 使新角色的ID出现在选人列表里。
    • 第二步：创建新的Girl子类和对应的Girl::Id枚举
    • 第三步：在Girl::create()里将新类与ID枚举关联起来。
    • 第四步：在Girl子类中实现新人物的技能。


测试方法

复盘

libsaki/util/debug_cheat.h中有三个宏开关：

  • LIBSAKI_CHEAT_ROUND 开启后从指定的一局，以指定的种子复盘
    • 具体参数通过下方由#ifdef包围的几个变量指定
    • 牌谱左下方「玄学码」中，左半部分为起家决定前的初始种子， 右半部分为当前局开始时的种子状态 （多数情况下用右半部分）
  • LIBSAKI_CHEAT_PRINCESS 开启后固定配牌与摸牌
    • 具体参数通过下方由#ifdef包围的几个vector指定
    • 指定配牌小于 13 张时，剩下的随机补全
    • 指定自摸牌山小于 70 张时，剩下的由平时的牌山算法生成
    • 此模式下所有配牌挂失效
  • LIBSAKI_CHEAT_AI 开启后所有 AI 自摸切

所有的 CHEAT 模式都是后门模式。 后门开启时，不保证逻辑正常 —— 也就是说开了 CHEAT 以后出现的一切异常（包括内存错误）都不是 bug。

自动化测试

mjpancake目录下有一个 Qt 项目libsaki-test.pro， 是一个简单的测试程序，只有命令行输出。 主要调用libsaki/test里的东西，常用于跑新角色的 4 AI 战， 保证最基本的「不崩溃、没有死循环」。 libsaki/test里的东西还处于早期草稿阶段， 与「方便的自动测试体系」还离得很远。


Girl ID 的分配规律

京狗的 ID 是 0。

所有 71 届 IH 的出场人物都使用 71xxyz 的 6 位数 ID。 其中 xxyz 意义如下：

  • xx 代表县或赛区的抽签号码，例如长野是 33，奈良是 24。
  • y 代表县排名，例如清澄是 1，龙门渕是 2。
  • z 代表团体战出场位置，先锋到大将分别对应 1 到 5

举例：魔王 713315，鸭子 712415，红帽 715215，笨淡 710115。

出场位置不明的，或者学校未参加团体战的，或者学校县排名不明的， 使用 71xx0w 形式，其中 xx 为县抽签号码，w 代表制作序号。

61 届 IH 出场人物能用 61xxyz 格式的也都用这个格式。

其余角色用 99wwww 格式，wwww 代表无特殊意义的序列号，按顺序分配。


回调函数及其被调用时机

函数名 调用时机 主要用于实现
onDice 掷骰子前 掷骰子前发动的挂
onDraw 摸牌前 控制自己或他家进张
onChooseFirstDealer 起家被选出前 卷饼起家


绝大多数能力都是通过重写onDraw实现的——在摸牌前干涉牌山，从而搞事情。

配牌挂是借助Princess实现的，我们会在发牌姬的文档中详细说明。

Girl继承自TableObserver，在Table初始化时会自动被注册， 同时Girl的onTableEvent会被保证在其它任何TableObserver之前被调用。 这点可以灵活运用。


如何为角色添加 IRS

Table作为正常的麻将逻辑，只能处理打牌、鸣牌等正常的操作， 不应该知道除此之外的，IRS 的处理方式。 因此每当Table收到 IRS 操作，都会转发给对应的Girl处理。

Table判断一个行动是否为 IRS 的依据是「Girl是否提交过 IRS 委托」。 为了保证Table能在Girl写得不好的情况下也能始终回归到正常的麻将上去， 我们设计了这种叫「IRS 委托」的消耗品。 一枚 IRS 委托对应一次由Girl提出的 IRS 转发请求， 转发完成后这份委托的思念会被遗忘，Table会变回正常的麻将。 有时一次主动技能需要对应多次 IRS 行动（比如点加号再点选复选框）， 这和情况下Girl就需要在处理完一次 IRS 后立马将下一份委托要求交给Table。

目前 IRS 只能在两种时机插入：掷骰子前与摸牌后。 也就是说Girl只能在这两种时机提出委托请求。

有关 IRS 的用法，参考淡、霞、爽、堇、怜的代码。