营养系统

EmakiCooking 提供一套"类膳食均衡"的营养系统：玩家进食会累积不同类型的营养值，达到或跌破阈值时触发服主自定义的动作。营养系统只提供机制（增减值、阈值边沿触发、持久化），具体的反胃、持续 BUFF、营养衰减等玩法由服主用 CoreLib 动作拼装。

基本信息

项目	值
总开关	`config.yml` → `nutrition.enabled`（默认 `true`）
类型定义目录	`nutrition/<id>.yml`
默认营养类型	`fruit`、`grain`、`protein`、`sugar`、`vegetable`
玩家数据	`data/nutrition/<玩家UUID>.yml`
主要权限	`emakicooking.nutrition.use`、`emakicooking.nutrition.admin`

营养类型定义

每个营养类型对应 nutrition/ 目录下的一个 .yml 文件，文件名（去掉 .yml）作为 id 缺省值。默认发布 5 个类型，可任意增删。

字段	类型	默认值	说明
`id`	string	文件名	营养类型唯一标识。
`display_name`	string	等于 id	显示名。
`min`	double	`0`	下限。
`max`	double	`100`	上限。
`default`	double	等于 `min`	玩家初始值。

解析规则：

若 min 大于 max 会自动纠正（取较小为 min、较大为 max）。
default 会被截断到 [min, max]。
display_name 为空时回退为 id。

默认 nutrition/fruit.yml 示例：

yaml

# 营养类型：水果
# 玩家营养值会被限制在 min ~ max 之间
id: fruit
display_name: "水果"
min: 0
max: 100
default: 0

TIP

单类型阈值、组合阈值、达成/恢复动作、食物到营养的映射都不在 nutrition/*.yml 里，而是配置在 config.yml 的 nutrition: 段。nutrition/*.yml 只定义类型本身的这 5 个字段。

食物到营养的映射

食物吃下后增加哪些营养，配置在 config.yml → nutrition.food_sources（列表）。

字段	说明
`item_sources`	允许的物品来源列表。省略表示不限来源。
`matcher`	通用物品匹配器，只写组件 / PDC / Lore 等非物品源条件。省略表示不加额外条件。见物品匹配器。
`nutrition`	`营养类型id: 增加值` 映射。
`actions`	命中后额外执行的 CoreLib 动作（可选）。

item_sources 与 matcher 是同级并行字段，判定取 AND：两者都写时要同时成立才命中。

物品来源使用 CoreLib 物品来源前缀：minecraft-<id>、craftengine-<id>、itemsadder-<id>、nexo-<id>、oraxen-<id>、mmoitems-<id>、neigeitems-<id>。若 item_sources 与 matcher 同时为空，或 nutrition 与 actions 同时为空，该规则被跳过。

yaml

nutrition:
  food_sources:
    - item_sources:
        - minecraft-apple
        - minecraft-sweet_berries
      nutrition:
        fruit: 20
    - item_sources:
        - minecraft-cake
        - minecraft-cookie
      nutrition:
        sugar: 30
      actions:
        - 'play_sound sound=entity.player.burp volume=1.0 pitch=1.0'
    # 只要没被改过名的蛋糕：两个字段各写一半
    - item_sources:
        - minecraft-cake
      matcher:
        type: component
        component: custom_name
        operator: absent
      nutrition:
        sugar: 40

进食触发链：玩家吃下物品 → CoreLib 识别物品来源 → 匹配 food_sources 规则 → 增加营养值（截断到 min~max）→ 执行规则动作 → 重新评估阈值。原版食物以及通过原版 food 组件实现的 CraftEngine、ItemsAdder、Nexo 食物都走原版进食事件；MMOItems、NeigeItems 通过软依赖单独接入，未安装时不影响运行。

阈值规则

阈值配置在 config.yml → nutrition.thresholds，分单类型（single）和组合（combo）两类。两类都采用边沿触发：达成时执行一次 actions，从满足跌回不足时执行一次 on_recover。

单类型阈值 single

逐个营养类型独立判定。

字段	默认值	说明
`id`	`single_<下标>`	规则 id。
`types`	`[]`（空=全部类型）	参与判定的营养类型。
`value`	`0`	阈值。
`compare`	`>=`	比较运算符。
`actions`	`[]`	达成时执行的动作。
`on_recover`	`[]`	跌回不足时执行的动作。

组合阈值 combo

统计达标的营养类型数量是否达到要求。

字段	默认值	说明
`id`	`combo_<下标>`	规则 id。
`types`	`[]`（空=全部类型）	参与统计的营养类型。
`value`	`0`	每个类型达到该值才算"已达标"。
`compare`	`>=`	比较运算符。
`required_count`	`5`	需要多少个类型同时达标才触发。
`actions`	`[]`	达标数量满足时执行的动作。
`on_recover`	`[]`	达标数从满足跌回不足时执行的动作。

compare 支持的运算符及其全部别名（大小写不敏感，无法识别的值回退为 >=）：

运算符	可写形式
大于等于	`>=`、`gte`、`at_least`、`ge`
大于	`>`、`gt`、`greater`
小于等于	`<=`、`lte`、`at_most`、`le`
小于	`<`、`lt`、`less`
等于	`==`、`=`、`eq`、`equal`、`equals`
不等于	`!=`、`<>`、`ne`、`not_equal`

若 actions 与 on_recover 都为空，该规则被跳过。

反胃与持续 BUFF 的拼装方式

营养服务本身不写死反胃或 BUFF，而是依赖 CoreLib 循环动作拼装：

start_task sequence=<模板> times=<次数> interval=<间隔> key=<唯一key> on_conflict=replace stop_when_offline=true：在达成动作里启动循环（如周期性扣营养、周期性加 BUFF）。
stop_task key=<同一key>：在 on_recover 里取消循环。

循环模板需在 CoreLib 的 config.yml → action.loop.templates 下定义。下面是默认的"五大营养全满则反胃衰减"组合阈值示例：

yaml

nutrition:
  thresholds:
    combo:
      - id: overeat
        types: []          # 空=统计全部营养类型
        value: 100         # 每类达到 100 算"已满"
        compare: ">="
        required_count: 5  # 5 类同时满才触发
        actions:
          - 'send_message text=<red>你吃得太撑了，开始反胃……'
          - 'play_sound sound=entity.player.burp volume=1.0 pitch=0.8'
          - 'give_potion_effect type=NAUSEA level=1 duration=200'
          - 'start_task sequence=nutrition_decay times=999999 interval=40t key=nutrition_overeat:%player_name% on_conflict=replace stop_when_offline=true'
        on_recover:
          - 'stop_task key=nutrition_overeat:%player_name%'

营养操作动作

营养增减、清空、重置、阈值复查与配方奖励动作由 EmakiCooking 注册到 CoreLib ActionRegistry，可在任意 CoreLib 动作链中使用。当前 Action ID 只使用规范名，不再注册旧别名；完整参数见 CoreLib 动作。

操作	Action ID
增加营养值	`cooking_add_nutrition`
扣除营养值	`cooking_remove_nutrition`
设置营养值	`cooking_set_nutrition`
清空营养值	`cooking_clear_nutrition`
重置营养值	`cooking_reset_nutrition`
复查阈值	`cooking_recheck_nutrition_threshold`
执行配方奖励	`cooking_run_recipe_reward`

命令与权限

营养相关命令见命令与权限。营养相关占位符见占位符参考。

持久化

路径：plugins/EmakiCooking/data/nutrition/<玩家UUID>.yml，每个玩家一个文件。
保存时机：定时保存（nutrition.save_interval_seconds，默认 300 秒，0 表示只在退出或关服时保存）、玩家退出时落盘。
玩家加入时加载；重载后会给在线玩家补齐新增类型的默认值。

yaml

schema_version: 1
uuid: <玩家UUID>
name: <玩家名>
nutrition:
  fruit: 60
  vegetable: 40
  protein: 80
  sugar: 20
  grain: 50

配置项一览

配置键	类型	默认值	说明
`nutrition.enabled`	boolean	`true`	营养系统总开关。
`nutrition.save_interval_seconds`	int	`300`	定时落盘间隔（秒），`0` 表示仅退出或关服时保存。
`nutrition.food_sources`	list	见上文	食物到营养的映射。
`nutrition.thresholds.single`	list	见上文	单类型阈值规则。
`nutrition.thresholds.combo`	list	见上文	组合阈值规则。

外部插件接入

营养相关的 Bukkit 事件见事件 API：PlayerNutritionConsumeEvent（消费前，可取消）、NutritionThresholdChangeEvent（阈值达成/恢复，信息型）。

营养系统 ​

基本信息 ​

营养类型定义 ​

食物到营养的映射 ​

阈值规则 ​

单类型阈值 single ​

组合阈值 combo ​

反胃与持续 BUFF 的拼装方式 ​

营养操作动作 ​

命令与权限 ​

持久化 ​

配置项一览 ​

外部插件接入 ​

营养系统

基本信息

营养类型定义

食物到营养的映射

阈值规则

单类型阈值 single

组合阈值 combo

反胃与持续 BUFF 的拼装方式

营养操作动作

命令与权限

持久化

配置项一览

外部插件接入