配置使用说明

先创建一桌

先引用规则，再改少数字段。通常一小段文本就足够。

在创建房间页面的下拉菜单中选择预设，右侧会填入预设引用和默认房间名“用户名的房间”。保留预设引用，在后面添加要修改的字段，不必复制整份规则，青雀同样如此。自定义房间名和密码分别点“确定”写入配置；确认时不显示过程或成功提示，错误仍会显示。

- path: []
  from: ["青雀"]
- path: [general_config, room_name]
  value: "周末青雀"
- path: [general_config, main_time]
  value: 20
- path: [general_config, reserve_time]
  value: 60

1. 选预设左侧点选规则。重新点选会替换当前编辑文本。
2. 改文本右侧使用 YAML 操作列表；空操作列表 [] 表示配置模板。
3. 校验／预览登录后由服务端校验。展开预览是只读完整配置，返回编辑可恢复原文。
4. 创建房间创建时再次校验；创建者自动入座第一个固定席位，不自动准备。

path / value / from

当前配置格式是操作列表，旧版 base 写法已经停用。

操作从上往下执行，后项覆盖前项。替换的是整个目标值，不会递归合并。from 始终读取服务器里的预设，不读取前面操作产生的工作配置。

- path: []
  from: ["国标"]
- path: [general_config, reserve_time]
  from: ["配置模板", general_config, reserve_time]
- path: [game_configs, 0, multi_win]
  value: false

路径和替换

• 父路径必须存在。对象可新增末级键，但列表不会自动增长；新增列表项时先替换整份列表。
• 改一个字段，就把 path 写到该字段；不要用不完整对象替换整个 params 或整个 GameConfig。
• 每项恰好是 path + value，或 path + from，不能同时填写 value 和 from。
• 各项执行中可以暂时不满足配置约束；全部替换后统一校验。路径本身每一步都必须有效。

YAML 写法

用空格缩进，不用 Tab。布尔值写 true／false；数字下标不要加引号。密码、01 位图、纯数字文字及枚举字符串建议加引号。

- path: []
  from: ["配置模板"]
- path: [general_config, password]
  value: "1234"
- path: [game_configs, 0, kuikae]
  value: "off"
- path: [game_configs, 0, flower]
  value: ""

常用配置示例

展开需要的示例，复制整段；不要把多个“整份预设引用”直接串接。

- path: []
  from: ["众娱"]
- path: [general_config, room_name]
  value: "300 分房"
- path: [calculator_configs, 0, room_end]
  value:
    name: "score"
    params: {target: 300}

- path: []
  from: ["配置模板"]
- path: [general_config, main_time]
  value: 0
- path: [general_config, reserve_time]
  value: 0
- path: [calculator_configs, 0, room_end]
  value:
    name: "round"
    params: {rounds: 8}

- path: []
  from: ["青雀"]
- path: [game_configs, 0, show_after_end]
  value: true

- path: []
  from: ["国标"]
- path: [game_configs, 0, opening_flower]
  value: true
- path: [game_configs, 0, force_flower]
  value: true

- path: []
  from: ["配置模板"]
- path: [game_configs, 0, exchange_rule]
  value: "same"
- path: [game_configs, 0, exchange_count]
  value: 3
- path: [game_configs, 0, exchange_target]
  value: [-1]

- path: []
  from: ["配置模板"]
- path: [game_configs, 0, wildcard]
  value: 2

- path: []
  from: ["配置模板"]
- path: [general_config, max_player]
  value: 2
- path: [general_config, starting_score]
  value: [[0], [0], [0]]
- path: [general_config, seat_orders]
  value: []
- path: [player_configs]
  value:
    - {auto_sort_hand: true, auto_win: false, auto_flower: false, auto_discard: false}
    - {auto_sort_hand: true, auto_win: false, auto_flower: false, auto_discard: false}
- path: [calculator_configs, 0, settlements, win, params]
  value:
    discard_winner: 1
    discard_loser: -1
    discard_bystander: 0
    draw_winner: 1
    draw_loser: -1
    "on": ["win"]
    scorer: "win"
    leave: true

- path: []
  from: ["配置模板"]
- path: [player_configs, 0, auto_win]
  value: true
- path: [player_configs, 0, auto_flower]
  value: true

- path: []
  from: ["配置模板"]
- path: [calculator_configs, 0, scorers, win, params, combinations, 0, score]
  value: 2

总结构与多局配置

所有路径都从 RoomConfig 根部出发；下列字段适用于当前格式。

每局选用哪一份配置

n 取实际局数 round_index 的第一项，从 0 开始；不按牌谱里的 game_id 选择。连庄时 n 不变，继续沿用原配置。两条序列独立循环：

game_configs[general_config.games[n % len(general_config.games)]]
calculator_configs[general_config.calculators[n % len(general_config.calculators)]]

例如 games = [0, 1, 0]，依次选第 0、1、0 份单局配置；calculators = [0, 1] 则独立交替。序列不能空，所指下标必须存在。

- path: []
  from: ["配置模板"]
- path: [game_configs]
  value: [{}, {}]
- path: [game_configs, 0]
  from: ["配置模板", game_configs, 0]
- path: [game_configs, 1]
  from: ["配置模板", game_configs, 0]
- path: [game_configs, 1, allow_chi]
  value: []
- path: [general_config, games]
  value: [0, 1, 0]

calculator_configs 使用同样的方法建立多份，再配置 calculators。不要直接写超出列表长度的下标；示例中的临时空对象会在最终校验前被完整预设替换。

general_config：房间规则

表中默认值来自“配置模板”，不是所有预设的共同默认值。

分数、座位与时间

四人一维分数可写 [[0], [0], [0], [0], [0]]，二人则是三行。多维分数用于需要分别记账的规则；standard 支付只改第一维，free_count 输出维数必须与每行分数维数一致。

固定席位属于房间，局内玩家编号会随轮庄改变。player_configs 按固定席位保存，进入每局时映射到对应局内玩家。一个账号可以控制多个席位。

game_configs：单局规则

以下字段都在 game_configs 的某一项内，例如 [game_configs, 0, dead_wall]。

牌面、位图与固定牌序

flower、transparent、red 对应洗牌前 wall 的声明位置，不是摸牌顺序。位图短于牌山时，后续位置不标记；超出部分忽略；建议写到需要标记的最后一张。一般型和特殊型预设拆解主要处理普通 m/p/s/z；自定义未知花色不等于已有计分器会识别。

开局换牌与虚拟万能牌

换牌在庄家第一次摸牌后、开局补花前进行。每家选择被收齐后才统一移动。庄家 draw 区的牌可换出，换入的一张补到 draw 位置。exchange_target: [-1] 在四人时随机顺／逆／对家，在其他支持人数时随机顺／逆；[1,2,3,0] 表示 0→1→2→3→0。

wildcard 不把任何实体牌变成万能牌，而是假定手牌中另有该数量的虚拟牌。算分按补入普通牌后的拆解处理；组合麻将的组合奖励只用实牌，听牌奖励按补全处理。洁律 B 的替代牌计分是另一套规则，不能用 wildcard 代替。

战术发声

宝牌指示牌

off 完全不翻。其他模式在发牌后翻第一张，暗杠后始终立即翻；immediate 对明杠／加杠也立即翻。after_discard 对明杠／加杠延迟到后续普通 draw、吃、碰、杠或和时释放，不由 tail_draw 释放；不要只按英文名称理解成“discard 事件立刻翻”。

指示牌依次取初始牌序倒数第 6、8、10、12、14 张，最多五次。对应位置已经不是牌山或不存在时静默跳过实际翻牌。里宝牌由立直计分读取相应牌，不是另一个 GameConfig 字段。

公开、暗杠与复式

暗杠完全不向他家公开时，客户端对牌主遮住两端、显示中间两张；存在实际可见或透明牌时按实际数据展示。显示设置不代替规则中的门清、和牌与计分判断。

duplicate 下普通摸牌、补牌都从各自牌山前端取牌；保留牌山单独存放。不能整除时序号较低玩家多分一张。它提供分区牌山；不是跨房间比赛、配对排名或自动复刻平台。

player_configs：按席位自动操作

自动设置改变选择方式，不改变合法行动和计分规则。

player_configs 的第 0 项对应第一个固定席位，不是永远的庄家。一人多席位时每席独立；列表长度必须等于 max_player。首版在建房配置中确定，尚未提供局中修改接口或手动整理牌序操作。

完整／简化牌桌、棋盘显示、音量和放大镜属于客户端显示设置，不写入 RoomConfig；它们不会改变牌局规则。

calculator_configs：计分与结束

日常只修改预设中的局部参数；换算法时要同步检查输入、分组、支付和结束策略。

每种策略都用 name 和 params 表示；即使没有参数，也保留 params: {}。scorers 和 settlements 是“自定义键 → 策略”的字典，不是列表。

名字、算法与显式绑定

下面的 win 是字典中的自定义键；pure_add、standard 是算法名称。settlement.params.scorer 指向 scorer 的键，不会自动按名称配对，也不会自动把全部 scorer 分数累加。

- path: []
  from: ["配置模板"]
- path: [calculator_configs, 0, scorers, win]
  value:
    name: "pure_add"
    params:
      base: 0
      least: 1
      patterns: ["regular_win"]
      combinations:
        - {definition: "模板和牌", display: "和牌", score: 1}
- path: [calculator_configs, 0, settlements, win]
  value:
    name: "standard"
    params:
      "on": ["win"]
      scorer: "win"
      leave: true
      discard_winner: 2
      discard_loser: -2
      discard_bystander: 0
      draw_winner: 3
      draw_loser: -1

同时配置多个被触发的结算策略，会分别处理。没有实现的触发／策略不能仅靠写一个新 name 获得功能；杠专用结算仍未完成。

允许的拆解：scorer.params.patterns

任意花色／更大数字的一般型拆解工具尚未注册为预设 patterns。不能在配置中直接写 general_win 并期待运行。

番种：scorer.params.combinations

番种返回非负整数：真值类为 0/1，数量类为实际数量。番种与 free_count 共用后缀表达式解释器，支持下表中的算术、比较、逻辑、数学取整和栈操作。番种常量仍为非负整数，最终恰好得到一个有限整数。逻辑与比较始终返回 0/1，条件成立时保留数量请用乘法，例如“国标花牌 国标自摸 *”；“国标花牌 2 >=”判断是否至少两张。只能引用已注册名称，不能写 Python 代码。

名称带规则前缀，如 模板和牌、众娱一色、国标清一色。洁律 A／B 共用一份“洁律”定义。完整注册名称见文末索引。

数量项包括国标花牌、幺九刻、数牌幺九刻、四归一，立直宝牌、里宝牌、赤宝牌、钓牌麻雀杠数及众娱字刻／杠归。众娱两项各按数量乘 10 分，旧一至四的条件定义仍可使用；国标旧 xN 条件也仍按 0/1 判断。国标顺刻复合去重后有 57 项；五组等价项只保留一色四同顺、清龙＋一般高、一般高＋喜相逢×2、一般高＋连六×2、三色三同顺＋一般高。其余非等价低阶复合和洁律非线性杠分保留。结算显示 ×N，但 score 已是实际得分，旧日志不重算。

scorer 类型与参数

standard 与 free_count 支付

standard 中五项均为整数倍率，变化=score[0]×倍率；只改记账第一维，公共池及其他维不变。改变人数不会自动重算倍率。

free_count 用五个角色表达式代替整数倍率。a…z 表示 scorer 输出的第 1…26 维，空格分词，按栈顺序计算。最终栈从底到顶就是该角色的记账增减，必须全部为有限整数，维数与 starting_score 每行一致。先前已离场者不再承受负变化，但仍可得正分。

结算允许负数、小数常量和小数中间值，最终每一维须为整数；round 按恰好半数远离零处理。五个角色公式在加载时检查结构和 a～z 名称，执行时再检查数学错误及实际输出维数。番种表达式使用同一组运算符，但最后仅保留一个整数。

其他支付类型

单局结束、局末和整场

立直麻将的配置位置

流程字段、计分参数、番表和结算参数分开存放；不要只改其中一处就视作整套规则已替换。

需要立直规则时，先整份引用“立直麻将”。只把 game.riichi 改成 standard 不会自动建立番种、符、供托和终局规则。当前日麻策略限四人，starting_round 必须为 [局序, 本场数]；末行公共池是供托，需为非负的 1000 倍数。

- path: []
  from: ["立直麻将"]
- path: [calculator_configs, 0, room_end, params, rounds]
  value: 4
- path: [calculator_configs, 0, room_end, params, extension]
  value: false

番与符仍在 combinations 中

条目 params.group 可为 han、fu、yakuman、bonus；宝牌、里宝牌、赤宝牌定义直接返回数量，与其他番种同样乘以单位 score；不再使用 params.count。符数定义使用汉字名称。宝牌不会单独满足起和番数。

- path: []
  from: ["立直麻将"]
- path: [calculator_configs, 0, scorers, win, params, combinations, 7, definition]
  value: "立直断幺九 立直门前清 and"

该下标对应本文生成时的预设；重排番表后请重新在展开预览中确认，不要凭旧下标修改。

预设目录与专用规则

当前共有 11 套预设。表格直接取自本地预设常量，未复制完整番表。

预设名必须精确匹配。洁律A、洁律B 中间没有空格；创建页按钮显示的是服务器实际提供的目录。上表是当前本地版本的初始配置，不表示可任意混搭策略。

几项专用规则

• 青雀：番表较大，优先 from 引用后修改局部路径；保留 group_max 的分组维数和 free_count 公式关系。
• 钓牌麻雀：普通支付用 diaopai，局末也用 diaopai 并通过 params.settlement 引用支付键；可选包牌由 pao 控制，责任按实际日志增量处理。
• 洁律 A／B：共用定义，scorer 的 mode 区分计分；B 的 game_settlement 需引用 B 计分器，不应只将 A 的 mode 改为 B。
• 五子棋：二人、hand_size=0、按中／发交替的非随机牌山、discard=grid、game_end=gomoku，双方 auto_win=true。修改棋盘行列在 discard.params.rows／columns；不是修改麻将牌河布局。点格后若只有一张实际手牌则自动落子，否则继续点选手牌。

三人通用麻将可按 max_player 调整并补齐相关列表；当前没有完整三麻专用预设。开局换牌已经可用；局中修改玩家设置、手动牌序和杠专用支付仍未提供。

常见错误与旧版迁移

先看错误指向的操作序号和路径，不要为绕过类型检查把所有值都改成字符串。

校验分三步：解析 YAML／JSON 和操作格式；逐项定位及替换；检查最终字段、取值及已注册策略。它不保证任意算法、分组和支付公式组合都构成合理玩法。

番种名称索引

在页首搜索字段或番种，可直接定位；也可使用浏览器“查找”。

以下是当前已注册的番种名称，可以作为 definition 的单项或表达式操作数。名称不包含空格；清单用于查名，不替代各规则的番种定义和计分分组。

来源与适用版本

这是当前配置的使用说明，不是旧帮助页的原样副本。

原帮助页：Mahjonglab 配置使用指南。本页参考其快速使用、字段表、计分说明和错误示例的组织方式；配置格式与功能以当前 Mahjonglab2 本地源码为准，旧语法不再沿用。

整理日期：2026-10-28。当前 RoomConfig.version = 1；客户端软件版本与 WebSocket 协议版本不由此字段控制。预设引用读取服务器当前内容，版本号不自动选择历史预设。

新牌谱保存脱敏后的路径操作，并按内容哈希引用开局时的不可变预设快照。多个牌谱可以共享同一份规则，不会逐桌重复保存青雀大表；读取新牌谱时采用归档快照。离线 JSON 目前仍需要归档服务器提供这些快照，旧牌谱没有保存的历史规则不能补造。

本页为单文件 HTML，样式、目录搜索和复制功能均在文件内，不加载外部字体、脚本或图片。保存到本地后可离线阅读；只有打开原帮助页链接时才联网。

维护依据：config/types.py、config/load.py、config/validate.py、config/presets、engine/choice.py、engine/action.py、calculator 各策略与客户端配置编辑说明。文中可复制的配置示例在生成时经过当前配置加载器校验；配置示例校验不代替真实对局和设备验证；部署范围与验证结果见项目的 docs/FIRST_DEPLOYMENT.md。