@lily-cooperative/custom-farm 0.0.0-stage → 0.33.4

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Custom Farm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This repository also contains third-party game art and fonts under their own
+licenses. The MIT license above covers the plugin source code only, not those
+assets. See THIRD_PARTY_LICENSES.md and ASSET_SOURCES.md before redistributing.

package/README.md

@@ -1,3 +1,341 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 自定义农场 · custom-farm
+
+桌宠在**任务栏上沿**种地：18 种作物、任意多棵（不能重叠）、浇水会干、太久不浇会枯萎、
+有的作物能反复收；收下来的东西**掉在地上**，桌宠要走过去捡，捡起来才进背包。
+
+## 版本与依赖
+
+| 项目 | 要求 |
+|---|---|
+| 当前扩展版本 | `0.33.4` |
+| Coopanion | `>= 0.2.13`，World API `6` |
+| Node.js | `>= 22` |
+| Electron | `^45.1.0`（overlay 依赖） |
+| WPF 回退 | Windows PowerShell 5.1 |
+| npm 包 | `@lily-cooperative/custom-farm` |
+
+`package.json` 声明的运行依赖只有 Electron；Coopanion 宿主本身由应用提供，不通过 npm 安装。扩展通过 `cortico.kind = "world"` 和 `cortico.api = 6` 声明宿主兼容性。
+
+> **平台说明（重要）**
+>
+> - **Windows 10/11**：桌面图层默认 Electron/HTML；WPF 作为 Electron 不可用时的回退。独立背包和 WebUI 可用。
+> - **macOS / Linux**：核心 World、WebUI 和 Electron/HTML overlay 可用，但**没有实机测试**；WPF 独立背包不支持。
+> - 欢迎反馈 macOS/Linux 的安装与运行问题：[GitHub Issues](https://github.com/LilyCooperative/Coopanion_Custom_Farm/issues)。
+
+> **素材说明**：当前贴图仅做示意，请自行替换 `assets/sprites/`。免费包/AI 图/作者要求见 **[../ASSETS.md](../ASSETS.md)**。
+
+数值是内置静态数据（生长点、`repeat_level`、`lifespan`）。
+当前贴图在 `Pet\assets\sprites\`；换图不用改代码（文件名保持 `<前缀>_<帧号>.png`）。刷新是纯代码 tick，只有「缺水 / 成熟 / 需要吃东西」才 pushEvent；「新的一天」要 `dailyEvent=true` 才推（默认关）。
+
+> 公开分发前请先确认 `assets/` 里的第三方素材许可；详见仓库根目录的 `THIRD_PARTY_LICENSES.md` 和 `ASSET_SOURCES.md`。
+
+## 1. 玩法
+
+| 要素 | 说明 |
+|---|---|
+| 种多少 | 任意多棵，上限 `maxPlants`（默认 12）。默认**允许轻微重叠**（`cropGapScale`=0.8）；设 1 就按贴图宽度**刚好不重叠**（统一 2 倍缩放，像素宽 = 屏幕上真实占位） |
+| 位置 | 每棵有 `x`（0 最左、1 最右，占工作区宽度）；播种时由桌宠指定或世界随机挑。草地**永远铺满整条底边**（贴图循环），`farmCells`（12~48）缩放草地/作物/野草贴图和草地厚度；所有作物/野草位置按中心比例缩放。缩放后落到可种范围（屏幕/农田）外的作物删除并退 1 包种子；缩小时新野地补杂草，也能种。桌宠按缩放后的 x 找作物 |
+| 生长 | 每棵按等级攒生长点，等级数/总点数/能收几次都取自游戏表（见 `src/crops.js`）。1 个游戏日 = `realMinutesPerDay` 真实分钟；**桌宠关掉/电脑睡眠期间不补天**，回到游戏最多补 `maxStepDays`（默认 1）个游戏日，不会一觉醒来跳几十天 |
+| 水分 | 土越湿长得越快；干透后 `wiltMinutes` 内不浇就**枯萎**（不单独推事件），枯了浇不活，重种会把它拔掉 |
+| 收割 | **产物掉在地上**（`drops`），每次产量按游戏表的 `min_count~max_count` 随机；落地时会往左右弹一小段；要用 `farm_collect` 捡进背包。番茄收 4 次、草莓 5 次，收完退回 `repeatLevel` 继续长；**土豆/玉米/南瓜/胡萝卜只能收 1 次，收完就拔掉**。桌宠查田时能看见「最近田里的变化」（谁因为什么没的） |
+| 背包 | `inventory` 记每种产物数量；HUD 显示件数 |
+| 事件 | `farm.ripe`（哪几棵熟了 + 位置）、`farm.dry`（缺水）、`farm.state`（吃东西）；`farm.day` 默认关，`dailyEvent=true` 才推 |
+
+作物表（`src/crops.js`，内置静态数据）：
+
+| 作物 | 阶段 | 总生长点 | 游戏里几天熟 | 能收几次 | 每次产量 | 本机现实时长 |
+|---|---:|---:|---:|---:|---:|---:|
+| 土豆 potato | 5 | 1440 | 5 天 | 1 | 2~4 | 40 分钟 |
+| 胡萝卜 carrot | 5 | 1440 | 5 天 | 1 | 1~3 | 40 分钟 |
+| 番茄 tomato | 6 | 2016 | 7 天 | **4** | 2~4 | 56 分钟 |
+| 草莓 strawberry | 6 | 2304 | 8 天 | **5** | 2~4 | 64 分钟 |
+| 玉米 corn | 6 | 2304 | 8 天 | 1 | 2 | 64 分钟 |
+| 南瓜 pumpkin | 6 | 2592 | 9 天 | 1 | 1 | 72 分钟 |
+| 小白菜 bok_choy | 5 | 1152 | 4 天 | 1 | 1~2 | 32 分钟 |
+| 小萝卜 radish | 5 | 1152 | 4 天 | 1 | 1~2 | 32 分钟 |
+| 甜菜根 beetroot | 5 | 1728 | 6 天 | 1 | 1~2 | 48 分钟 |
+| 大蒜 garlic | 4 | 1440 | 5 天 | 1 | 1~2 | 40 分钟 |
+| 花椰菜 cauliflower | 5 | 1728 | 6 天 | 1 | 1 | 48 分钟 |
+| 红洋葱 red_onion | 4 | 1728 | 6 天 | 1 | 1~2 | 48 分钟 |
+| 黄瓜 cucumber | 6 | 2016 | 7 天 | **3** | 1~3 | 56 分钟 |
+| 红辣椒 red_chili | 6 | 1728 | 6 天 | **4** | 2~3 | 48 分钟 |
+| 蓝莓 blueberry | 6 | 2592 | 9 天 | **3** | 2~4 | 72 分钟 |
+| 茄子 eggplant | 6 | 2304 | 8 天 | **3** | 1~2 | 64 分钟 |
+| 菠萝 pineapple | 6 | 2880 | 10 天 | 1 | 1 | 80 分钟 |
+| 西瓜 watermelon | 6 | 2880 | 10 天 | 1 | 1 | 80 分钟 |
+
+> 生长点按 288/游戏日换算；天数、价格是内置数值。
+「本机现实时长」= 天数 × `realMinutesPerDay`（默认 8）；1 个游戏日多长由该设置决定。
+
+## 2. 工具
+
+| 工具 | 用途 |
+|---|---|
+| `farm_status` | 每棵的位置/等级/进度/水分/是否可收或枯萎 + 背包 + 地上的掉落物 + **最近田里的变化（少了哪棵、为什么）** |
+| `farm_stand` | 站到某个位置，`at` **必填**（`pet_move_to` 回执里的百分比 / 100） |
+| `farm_plant` | 在脚下种一棵（`crop` 可选，`x` 可选）；**消耗 1 包对应种子**，没有种子会让你先买 |
+| `farm_water` | 浇水（**要走到跟前**，先 pet_move_to + farm_stand），不填 `plot` 就浇脚下这片 |
+| `farm_harvest` | 收脚下这棵熟的，**产物掉地上**；回执会提示背包里可卖多少 |
+| `farm_collect` | 把脚下的掉落物捡进背包 |
+| `farm_consume` | 吃掉背包里的作物/杂草收获物或消耗品，缓解「饥饿」这类状态（要主人在状态自定义里配好消耗行为） |
+| `farm_craft` | 按「道具合成表」消耗背包材料合成道具；不填 `recipe` 就列出所有表 |
+| `farm_shop` | 看商店：列出所有设了购买价的种子/消耗品/装饰（买价、卖价） |
+| `farm_buy` | 买设了购买价的道具（种子/消耗品/装饰）；买来先进背包 |
+| `farm_sell` | 卖背包里有出售价的道具；没设出售价的不能卖 |
+| `farm_place` | 把装饰道具放到地上（`item`、`x`）；上层装饰会清掉落点杂草，下层不会 |
+| `farm_bag` | 打开背包面板（独立 WPF 窗口） |
+
+### 种子与商店（价格来自游戏 `item_tbitem`）
+
+种植消耗种子，种子买来先进背包（`inventory[seed_*]`）。新开局/老存档升级发一小包：
+土豆 3、胡萝卜 1、番茄 1、草莓 1（老存档只发一次，`seedsGranted`）。
+
+| 作物 | 种子买 | 种子卖 | 产物卖 |
+|---|---:|---:|---:|
+| 土豆 | 30 | 6 | 35 |
+| 番茄 | 120 | 24 | 70 |
+| 草莓 | 150 | 30 | 90 |
+| 玉米 | 55 | 11 | 115 |
+| 南瓜 | 100 | 20 | 370 |
+| 胡萝卜 | 20 | 4 | 40 |
+| 甜菜根 | 40 | 8 | 65 |
+| 蓝莓 | 70 | 14 | 95 |
+| 小白菜 | 25 | 5 | 50 |
+| 花椰菜 | 55 | 11 | 90 |
+| 黄瓜 | 45 | 9 | 70 |
+| 茄子 | 50 | 10 | 85 |
+| 大蒜 | 25 | 5 | 45 |
+| 菠萝 | 90 | 18 | 160 |
+| 小萝卜 | 20 | 4 | 35 |
+| 红辣椒 | 35 | 7 | 60 |
+| 红洋葱 | 40 | 8 | 65 |
+| 西瓜 | 120 | 24 | 220 |
+
+**种子不够时自己补**：种地或回执发现种子 ≤1 包，直接 `farm_buy` 补 1~2 包，不用问主人；一次最多 2 包、最多花一半金币。已取消 `farm.buy` 自动唤醒。
+**枯死/枯萎的作物自己铲**：走到跟前 `farm_plant` 拔掉重种，不用问主人。
+
+**卖东西只在两个时机开口**：刚收获 或 钱不够买种子时（回执会提示可卖多少），先问主人再卖。
+背包窗口的「商店」页也能直接买种子（价格就列在每行上）。
+
+### 走过去的协议
+
+```
+farm_status                 → 3 号玉米熟了，在 62%；地上有个番茄在 40%
+pet_move_to {x: 0.62}      → 沿屏幕底边走过去
+farm_stand {at: 0.62, plot: 3}
+farm_harvest  {plot: 3}    → 产物掉在 62%
+farm_collect               → 捡进背包（图层会播"吸到身上"）
+```
+
+## 3. 文件
+
+| 文件 | 作用 |
+|---|---|
+| `src/crops.js` | **游戏默认数据**：18 种作物的等级/生长点/重复收获/收几次/贴图前缀（自动生成，别手改；自定义页的改动覆盖它） |
+| `src/shop.js` | **游戏默认价格**：产物买卖价、种子买卖价、家具价（来自 `item_tbitem`） |
+| `src/catalog.js` | 农场目录：读 `custom.json`、编译作物/杂草/地面、导入 PNG、把改动写回 CROPS/SEEDS/价格表 |
+| `src/catalog-state.js` | 运行期目录（`live`）：作物、杂草类型、地面、物品图标，给 farm.js 只读 |
+| `src/farm.js` | 纯逻辑：位置与重叠、生长、水分与枯萎、收割与掉落、捡取、种子、背包、v1/v2→v3 迁移 |
+| `src/world.js` | World：12 个工具、tick、3 个事件、原子落盘、webUi（含自定义面板的数据面）、背包命令 |
+| `src/index.js` | WorldDefinition + describe |
+| `src/ENV_PROMPT.md` | 给桌宠的环境提示词（自主行动、三事件、省 token） |
+| `dist/webui.js` / `.css` | 「农场自定义」面板（纯 ESM，无构建步骤） |
+| `tools/selftest.mjs` | 165 项断言（不装 Coopanion 也能跑） |
+| `tools/reset-farm.ps1` | 重开局 |
+
+## 4. 调参（`worlds.farm`）
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `pointsPerDay` | 288 | 每个游戏日的生长点（**由游戏数据反推，别乱改**） |
+| `realMinutesPerDay` | 8 | 1 游戏日 = 多少真实分钟（**这个是我定的**，想快就调小） |
+| `maxStepDays` | 1 | 一次刷新最多推进几个游戏日。关机/睡眠回来只补这一天，防止"存档跳天 + 田全枯"；设大 = 允许离线生长 |
+| `maxPlants` | 12 | 同时最多几棵 |
+| `zoom` / `screenWidth` / `spriteGapPx` | 2 / 2048 / 4 | 用来把贴图像素宽换算成最小 x 间距（要和图层一致） |
+| `cropGapScale` / `cropGapPct` | 0.8 / 0 | 间距倍率（1 = 刚好不重叠）；`cropGapPct >0` 时直接按屏宽百分比强制最小中心距 |
+| `farmCells` | 48 | 农田整体大小（12~48 格，48=满宽）。底边草地始终铺满/循环；缩放草地/作物/野草贴图和厚度，所有位置按中心比例缩放。缩放后落到可种范围外的作物删除并退 1 包种子；缩小时新野地补杂草且可种 |
+| `dryPerDay` / `wiltDays` | 0.15 / 2.2 | 每个游戏日蒸发多少水分 / 干透多久枯萎（游戏日） |
+| `waterGain` | 1.0 | 浇一次补多少水分（1 = 浇满） |
+| `startCoins` | 120 | 新开局金币（老存档不动） |
+| `tickIntervalMs` | 5000 | 刷新间隔（固定节拍，不是随机刻；只影响状态/事件及时性，不改变生长速度） |
+
+## 5. 验证
+
+```powershell
+node tools/selftest.mjs     # 165 项
+node tools/gen-describe.mjs # 改了工具/事件后
+```
+
+覆盖：不重叠判定、任意数量、生长与成熟事件、收割只掉不进包、走远了捡不到、
+多次收获（番茄收 4 次后拔掉）、枯萎与拔掉重种、浇水、种子（没种子不能种/买种子进背包/种下扣 1 包/
+种子能卖/钱不够提示可卖/一次买多种只扣总价/种子用完时新的一天推补货询问）、背包、存档迁移（v2→v3、老存档补种子）、
+写盘失败要报错、**离线/睡眠回来只补 `maxStepDays` 天（不跳天、不抽干土）**、**田地大事记（收满/拔枯/缩放删掉都记账）**。
+
+### 已知事故：关机一晚，存档跳了几十天、田全枯
+
+原因：`advance()` 用"上次 tick 的时间戳"算游戏时间，桌宠关掉/电脑睡眠后第一次 tick 会把整段真实时间**一次补完**。
+`realMinutesPerDay=8` 时关 5.4 小时 = 40 个游戏日；`60` 时关 12 小时 = 12 天。天一跳，水也一次扣光，作物随后全部枯死。
+
+修法：`advance()` 单次最多推进 `maxStepDays`（默认 1）个游戏日，剩下的不补；桌宠查田时用「最近田里的变化」
+说明每棵是怎么没的。`selftest` 新增 3 条时间断言 + 5 条大事记断言。
+
+## 6. 坑
+
+1. 改完代码必须 `POST /api/run/restart`（`/api/worlds/restart` 不重新 import）。
+2. World 的 `stop()` 会存档：重开局要 disable → 删 → enable，或直接用 `reset-farm.ps1`。
+3. **PowerShell 变量名大小写不敏感**这条坑在这个项目里出现过两次（`$leaf`/`$LEAF`、`$shots`/`$Shots`）。
+4. 生成代码别用普通模板字符串写 `'\n'`（会被提前解释成真换行）。
+
+## 7. 待做
+
+- **做饭**：背包里的作物拿去做菜（番茄炒蛋、南瓜派…游戏里都有配方表 `item_tbitem`）。
+- 虫害 / 鸟灾 / 稻草人（游戏里有 `sprite_crop_wither_*` 和灾害配置）。
+
+## 7.5 WebUI 设置
+
+`webUi()` 的 `config` 现在只有一组参数，出现在 WebUI「自定义农场」页的**配置**页签里（改完下一次 tick 生效）：
+
+| 组 | 内容 |
+|---|---|
+| `world:farm/field` | 新开局金币、是否写图层 |
+
+- 农田大小、作物上限/间距/大小、时间和浇水已经搬到「农场自定义」页（农场 / 农作物 / 生态几栏），保存在 `custom.json` 的 `settings`/`status.water` 里；游戏配置页只留上面这些较少改的项。
+
+> 浇水三项（蒸发 / 补水 / 枯萎天数）已搬到 **7.6 的「生态」**，不再出现在配置页；旧的 `worlds.farm.dryPerDay/waterGain/wiltDays` 只作为第一次生成 `custom.json` 时的默认值。
+
+## 7.6 「农场自定义」页
+
+
+同一页的**农场自定义**页签（`panels: [{ id: 'customize' }]` + `dist/webui.js`），最上面是「设置模板」，下面五块用横线隔开：
+
+- **设置模板 ZIP**：把当前 `custom.json` 和 `assets\sprites\cust_*.png` 打包下载；导入会覆盖全部设置和贴图，但**不会清空存档**（田地/背包/金币不变）。导入前建议先导出备份；如果新模板删掉了存档里正在种的作物，田里会按新设置重新解释。
+- 模板里也带一份 `template.json`（格式/版本/导出时间），导入时会校验；文件名形如 `custom-farm-template-20261028-0230.zip`。
+- 模板包含 `custom.json` 里的农场/作物/杂草/状态/道具/合成表，以及**面板里的设置覆盖**（农田大小、作物上限/密度/大小、时间/浇水）。不含存档；游戏配置页剩下的野草/金币/图层开关仍按本机配置走。
+
+
+| 区块 | 能做什么 |
+|---|---|
+| **农场** | 从 3 张 Grok 内置长条地板里选（默认 0 号，96px 长条按原宽自动重复铺满，最后一列裁切）；**地表高度（像素，2~40，默认 4，约到桌宠鞋底）**；添加/删除自己的 PNG；**农田整体大小（格）** |
+| **农作物** | 增删作物；阶段数 2~8；每阶段（N-1 段）成长天数；各阶段 / 种子 / 收获物贴图；内置作物可「恢复默认」。**最多同时种几棵、作物间距倍率/最小间距、农作物/杂草大小倍率、掉落物大小倍率**；价格/能不能吃/吃掉效果在「道具自定义」页 |
+| **杂草** | 增删杂草；阶段数 2~8；每阶段天数；出现权重（按权重占比决定出现概率）；**图层（上=和作物/桌宠同前台层；下=背景层、作物后方）**；可选收获物名字 / 价值 / 贴图；内置三种（野草、变种、伊甸花）可恢复默认。**野草上限、开局补草数量、每游戏日出现概率、播种铲草半径** |
+| **生态** | 一个游戏日 = 多少真实分钟、单次最多推进几个游戏日、刷新间隔、是否每天推「新的一天」；**浇水三项**（每游戏日蒸发 / 一次浇水补水 / 干透后枯萎天数） |
+| **浇水特效 / 枯萎** | **浇水特效动画**：植株上方落水帧序列 + 地面水花帧序列，各自可增删帧、改帧间隔；**枯萎作物贴图**：换图 / 用默认。浇水数值在「生态」 |
+
+- 数据存在 `%LOCALAPPDATA%\Programs\Coopanion\data\home\companion\data\farm\custom.json`；
+  上传的 PNG 复制到 `Pet\assets\sprites\cust_*.png`（overlay 只认 `.png`，单张 ≤ 4MB、≤ 2048×2048）。
+- 自定义作物默认**只收一次**（没有多次收获字段）；种子的买价/卖价在「道具自定义」的种子栏设置。
+- 田里还种着/长着的时候不让删（会报错）；至少留一种作物。
+- 面板的贴图预览走 `invokeBinary('sprite')`，选贴图走 `ctx.pickPath`（本机原生文件框）。
+- 浇水特效写在 `state.waterFx`（`pour` / `burst` 帧名数组 + `pourMs` / `burstMs`），枯萎贴图写在 `state.wither`；overlay 读到空数组就不播那一组，读不到或文件不在就退回内置素材。
+- 页签的标题来自 `webUi().panels[].title`；`package.json` 的 `cortico.webUiClient` / `webUiStyle` 指向 `dist/`。
+
+## 7.7 「状态自定义」页
+
+同一页的另一个页签（`panels: [{ id: 'status', title: '状态自定义' }]`），用来定义自己的数值/开关状态：
+
+
+| 元素 | 说明 |
+|---|---|
+| **数值状态** | 名字、最小值/最大值、初始值、每游戏日变化（可负，比如饱食度 -5/天）、单位；卡片里可以直接「设为」当前值 |
+| **开关状态** | 只有「初始生效」；作为条件的目标（比如「饥饿」） |
+| **条件** | 当 `[数值状态] [< <= > >= == !=] [阈值]` 成立时，让 `[目标开关]` 生效；多条规则指向同一个开关时按「或」处理 |
+| **消耗行为** | 触发状态生效（开关生效 / 数值 > 0）且冷却到了，就从选中的道具里吃掉 `count` 个，并把 `变化量` 加到指定数值状态（例如 `饥饿 → 吃番茄×1 → 饱食度 +25`）；关掉「自动消耗」就只推事件提醒桌宠 |
+| **添加示例** | 一键加「饱食度」0~100、初始 100、每天 -5，「饥饿」，条件 `饱食度 < 30 → 饥饿`，以及消耗行为 `饥饿 → 吃番茄等作物 ×1 → 饱食度 +25`（0.5 天冷却，自动） |
+
+- 定义存在 `custom.json` 的 `states` / `rules` / `consume`；当前值存在存档 `state.states`，冷却进度存在 `state.stateActions`，重启/离线都保留。
+- 每次 tick 按游戏日漂移、重算条件，然后跑消耗行为；自动消耗成功会推 `farm.state` 事件（「饥饿生效：吃掉了番茄×1，饱食度 +25」）。
+- 手动「设为」会立刻按条件重算并落盘（不用等下一拍）；改状态名/删除状态时，引用它的条件和消耗行为会自动清理。
+- 数值状态只负责漂移和作为条件来源；开关状态由条件规则决定（没有规则指向它时保留手动值）。
+- 桌面宠物也可以不等冷却、主动用 `farm_consume {item:'tomato'}` 吃一个；同一套消耗行为决定吃哪些道具、加多少状态。
+
+## 7.8 「道具自定义」页
+
+`panels: [{ id: 'items', title: '道具自定义' }]`，四栏用横线隔开：
+
+
+| 区块 | 能做什么 |
+|---|---|
+| **种子道具** | 自动读取「农场自定义」里每种作物的种子；设**买价 / 卖价**。买价 0 = 商店不出现；卖价 0 = 不能卖 |
+| **农作物道具** | 自动读取收获物（含杂草产物）；**卖出价改到这里**；可勾「可以被消耗」，并设置吃掉后改哪个数值状态、变化量 |
+| **消耗品道具** | 自己加/删；设名字、缩略图、买价/卖价、吃掉后的状态效果（可多条） |
+| **装饰道具** | 自己加/删；设名字、缩略图、**摆放贴图**、买价/卖价、**图层（上/下）**；**这个装饰单独的贴图大小倍率（0.3~3）**。买/合成后去「背包」页点「放置」，或让桌宠用 `farm_place` 放到任意 `x`。**上层**和杂草同层，会清掉落点杂草，可盖住作物/下层装饰；**下层**在农作物后方，不清草 |
+
+### 食材与菜品（Grok 图标）
+
+| 道具 | 买价 | 卖价 | 说明 |
+|---|---:|---:|---|
+| `rice_ear` 稻穗 | 8 | 2 | 商店食材；合成大米 |
+| `rice` 大米 | 15 | 4 | 稻穗合成 |
+| `egg` 鸡蛋 | 6 | 2 | 商店食材 |
+| `meat` 鲜肉 | 22 | 6 | 商店食材 |
+| `egg_fried_rice` 蛋炒饭 | — | 35 | **不能购买**，只能合成 |
+| `item_15` 番茄炒蛋 | — | 30 | **不能购买**，只能合成（旧道具改图标） |
+
+合成表：
+
+- 稻穗 ×1 → 大米 ×1
+- 鸡蛋 ×1 + 大米 ×1 → 蛋炒饭 ×1
+- 鸡蛋 ×1 + 番茄 ×1 → 番茄炒蛋 ×1
+> 删除道具、作物或杂草时，会一并清理：**背包里的该道具、农场里已摆放的该装饰、地上的掉落物、引用它的合成表**，以及这个条目上传的 cust_* 贴图。内置共享贴图（例如所有装饰共用的图标文件）不会被删，避免误删别的条目。
+
+- 价格/效果/图标存在 `custom.json` 的 `items`；种子/农作物条目跟作物自动同步，价格和效果不会被覆盖。
+- 商店只列 `buy > 0` 的道具；`sell` 为 0 的道具 `farm_sell` 会报「没有设置出售价值，不能卖」。
+- 农作物/消耗品的 `effects` 是吃掉时优先应用的效果；没配效果才退回「状态自定义 → 消耗行为」里的效果。
+- 装饰摆放后记在 `state.furniture`（`sprite` 用上传的摆放贴图），overlay 会画在地面上；没有摆放贴图时会拒绝放置。
+- 删除自定义消耗品/装饰时，合成表里引用它的材料/产物会一起删掉；种子/农作物不能在这里删（去农场自定义删作物）。
+
+## 7.9 「道具合成表」页
+
+`panels: [{ id: 'recipes', title: '道具合成表' }]`：
+
+
+- 每张表 **1~4 个材料**（道具 + 数量）→ **1 个产物**（道具 + 数量）；可增删改。
+- 材料/产物从「道具自定义」现有的道具里选；不存在会保存失败。
+- 桌宠用 `farm_craft {recipe:"recipe_1"}` 合成：先检查背包材料，够了就扣材料、加产物；不填 `recipe` 会列出所有表。
+- 合成表存在 `custom.json` 的 `recipes`。
+
+## 7.10 背包 / 商店
+
+商店页改成和背包一样的**图标格**（4 列，64px 格子 / 48px 图标）：每格右下角原来是数量，商店显示**买价**（如 `￥100`）；
+点一下买 1 个，物品名 / 卖价在 tooltip 里。数量随道具页的买价自动变；没设买价的道具不会出现在商店。
+WebUI 设置页把「背包」和「商店」拆成两个页签，商店紧挨在背包右边。
+
+
+
+## 7.11 「环境提示词」页
+
+设置页最右边原来的「自定义农场」页签改名为 **「环境提示词」**（`promptDocs` 的 `title`）。它不是作物/价格表单，而是发给桌宠的 `src/ENV_PROMPT.md`：
+
+- **静态文字**：改前面的作物、价格、阶段、道具设置**不会自动改这一页**；具体数字以 `farm_status` / `farm_shop` 的实时回执为准。为了避免误导，原来的写死作物表/价格表已经删掉。
+- **吃饭与状态**：新增一节，明确告诉桌宠：看到「饥饿」或饱食度偏低时先提醒主人，主人同意后用 `farm_consume` 吃一个；不要自己改状态数值。想让它主动维持饱食度，直接在这一节加/改句子。
+- **状态对桌宠的影响**：也写在这一页（语气、提醒时机、先问主人还是直接吃）。状态的范围、阈值、触发条件仍在「状态自定义」；这里只负责“看到状态后怎么做”。
+- 顶部用 HTML 注释给主人说明这一页的用途/不会自动同步/如何写吃饭提示；注释在渲染后通常不显示。
+- 保存后下一次对话 / 唤醒生效；页面内容仍然是 Markdown，可以直接改。
+
+
+## 7.12 背包页 / 游戏配置 / 图标继承
+
+
+- 设置页**最左边**是「背包」页（`panels: [{ id: 'bag' }]`），「商店」页紧挨在它右边；背包页四栏用横线隔开：
+  - **背包**：4 列图标格，数量 + 卖价；`卖 1` / `全卖`；装饰道具还有 `放置` 按钮。
+  - **放置**：点「放置」后出现坐标输入（0~100%），预览里用虚线和半透明贴图标出落点；确定后才真正扣背包并放下。
+  - **农场预览**：按当前田地的 x 坐标画出作物和装饰；下层装饰在作物后，上层装饰在作物前。
+  - **农场里的道具**：和背包一样的图标格，**每一株作物 / 每一个装饰单独一张卡，不按类型合并**；卡片显示所在横坐标（如 `农作物 · 12%`）。点某张卡的图标，预览只高亮这一株/这个装饰；农作物「铲除」、装饰「回收」都只作用于这一个实例。
+  - **手动合成**：选配方、填数量，显示每种材料的「拥有 / 需要」和产物；材料够就点「合成」，直接扣材料、加产物（和 `farm_craft` 用同一批合成表）。
+  - 数据从 `#bagInvoke` 的 `state` 读取；买卖/合成/放置/铲除/回收都走同一套后端，和 WPF 背包一致。
+- **商店**独立页：只列 `buy > 0` 的道具，显示 `￥买价`；`买 1` 进背包。
+- 设置页原来的「配置」页签显示为 **「游戏配置」**（宿主的配置页文案是固定的，客户端 bundle 在农场页把它改成这个标题；现在只剩新开局金币 / 图层开关）。
+- **右键菜单的「背包」入口及其图标已移除**：不再修改 `cortico-world-desktop-pet` 的安装文件，也没有配置开关。需要 WPF 背包时用 `farm_bag` 工具或手动运行 `bag\bag.ps1`；设置页的 WebUI 背包仍然可用。WPF 背包里装饰道具仍可放到 50%；WPF 商店和背包使用同一套 64px 图标格 / 48px 图标。
+- **装饰图层**：道具页每个装饰可选「上」或「下」；上层画在 weeds 层（和杂草同层，在桌宠/作物上方，落点清草），下层画在 background 层、作物之前（在农作物后方，不清草）。可同时叠放，不互相阻挡。
+- 「道具自定义」里的种子/农作物卡片**图标自动继承**作物设置里的种子/产物贴图（改农场自定义的贴图后，道具页图标跟着变；不需要再单独上传）。装饰道具的「放置」已从道具页移到背包页。
+
+## 可迁移 / 打包
+
+扩展里没有任何写死的绝对路径：`src/paths.js` 从扩展自身位置推出 `<Pet>\overlay\`、`<Pet>\bag\`、`<Pet>\assets\`。
+整个 `Pet` 文件夹拷到另一台机器，跑 `scripts\install.ps1` 就能用（详见 `..\docs\PACKAGE.md`）。
+扩展被复制（而不是 link）时，用环境变量 `PET_HOME` 或 World 配置项 `petRoot` 指定 `<Pet>` 在哪。
+
+## 素材许可
+
+地面、大树、稻草人来自 **Grok 重绘**；18 种作物来自 **Farm Crops - Growth Stages Pixel Art Pack**（IDRK15599）；野草来自 **Free Pixel Grass & Bushes Pack**（vigi game）。完整许可与限制见 [THIRD_PARTY_LICENSES.md](../THIRD_PARTY_LICENSES.md)。免费作物包允许个人/商业使用，但不能把素材包原样转售或再分发。
+

package/assets/LICENSES/FarmCrops_GrowthPack_16x16_v1.2.txt

@@ -0,0 +1,30 @@
+Farm Crops - Growth Stages Pixel Art Pack (16x16)
+
+[18] hand-drawn crops with seed packets, seeds and 6-7 growth stages.
+Free to use in personal and commercial games.
+
+Perfect for farming sims, cooking games and management games.
+
+What's included
+- [18] crops: seed packet, seeds, 6-7 growth stages, harvest icon
+- Regrowing crops (tomato, strawberry, chili...) with an extra
+  "harvested" frame
+- Individual PNGs, full sprite sheet, x[10] previews, README
+- Matches my Fruits & Vegetables Pixel Art Pack (link below)
+
+Details
+- Frame size for crops growth: [16x32]
+- Frame size for packets and crops: [16x16]
+- Format: PNG, transparent background
+- Works with Godot, Unity, GameMaker and any engine that supports PNG
+- All hand-drawn in Aseprite. No generative AI.
+
+License
+- Free for personal and commercial use
+- Credit appreciated, not required
+- You may modify the sprites for your own projects
+- Please don't resell or redistribute the assets as-is
+
+Matching fruit & veg sprites: https://irdk15599.itch.io/cute-vegetables-furits-16x16
+
+by IDRK15599

package/assets/LICENSES/Free Pixel Grass and Bushes Pack.txt

@@ -0,0 +1,2 @@
+Thank you for using this file. The license allows for personal and commercial use, but you do not have the right to sell the product separately.
+Please support me to publish more free packs.