balatro-mod-dev

Balatro Mod 开发

使用 Steamodded、Lovely 和 SMODS 创建并调试 Balatro Mod。

快速选择 Agent

进行研究或编写代码时，通过 Task 工具启动合适的子 Agent：

需要查找……	使用 Agent	模型	搜索范围
游戏函数实现	game-source-researcher	sonnet	仅限 Balatro_src/
SMODS API 用法／钩子	smods-api-researcher	sonnet	仅限 smods/
其他 Mod 如何实现某功能	mod-pattern-researcher	sonnet	仅限 Mods/ 文件夹
Lovely 补丁语法	lovely-patch-researcher	sonnet	仅限 lovely 文件
项目架构／探索	project-explorer	sonnet	仅限当前项目
按计划编写代码	code-writer	sonnet	仅限当前项目
运行临时脚本获取数据	script-runner	haiku	不适用（执行）
检查代码正确性	code-reviewer	opus	仅限当前项目
综合多来源研究	research-analyst	opus	仅限当前项目
规划复杂实现	strategic-planner	opus	仅限当前项目
检查运行时日志、转储文件和兼容性	debug-inspector	sonnet	仅限 Lovely 日志／转储文件

主 Agent 直接处理： 用户交互、少于 20 行的小改动、呈现结果。

并行： 研究不同来源时，在一条消息中启动多个 Task 调用
顺序： 第二个查询依赖第一个查询的结果时

有关 5 阶段工作流、迭代检索流程和委派规则，请参阅 references/sub-agents.md。

仓库类型识别

自动检测： 将 Mod 清单中的 author 与 Git 远程用户名进行比较。

# Get git remote username
git_user=$(git remote get-url origin 2>/dev/null | sed -E 's|.*[:/]([^/]+)/[^/]+\.git$|\1|' | tr '[:upper:]' '[:lower:]')

# Get mod author from manifest (first author, lowercase)
mod_author=$(jq -r '.author[0] // .author // ""' *.json 2>/dev/null | head -1 | tr '[:upper:]' '[:lower:]')

# Compare: match = own, no match = fork
[[ "$git_user" == "$mod_author" ]] && echo "own" || echo "fork"

类型	检测方式	影响
new	空仓库（无文件）	完整文档、Logger.lua、本地化
own	作者与 Git 用户匹配	完整文档、规范化结构
fork	作者与 Git 用户不同	最小改动，仅临时日志

文件约定

文件	用途	Git
AGENTS.md	Mod 结构、函数、依赖项、限制、快速参考（供 AI Agent 使用）	忽略
mod.config.json	同步／发布脚本的文件列表	忽略
docs/knowledge-base.md	问题与经验总结	忽略

AGENTS.md 的用途： 确保 Agent 之间顺畅交接。另一个 Agent 应能通过单个文件快速了解 Mod 结构、函数、依赖项、限制和仓库类型。

文件放置规则

根目录中只能放置以下 .md 文件：

• README.md、README_zh.md
• CHANGELOG.md、CHANGELOG_zh.md
• AGENTS.md
• LICENSE.md

所有其他 .md 文件都必须放在 docs/ 中

外部参考（无需符号链接）

通过绝对路径直接访问参考代码。无需进行任何设置。

源代码位置（macOS）

资源	路径
游戏源代码（桌面版）	~/Development/GitWorkspace/Balatro_src/desktop/
游戏源代码（移动版）	~/Development/GitWorkspace/Balatro_src/ios_plus/
Steamodded 源代码	~/Development/GitWorkspace/smods/src/
Steamodded Lovely	~/Development/GitWorkspace/smods/lovely/
Lovely 文档	~/Development/GitWorkspace/lovely-injector/
已安装的 Mod	~/Library/Application Support/Balatro/Mods/
Lovely 日志	~/Library/Application Support/Balatro/Mods/lovely/log/

源代码位置（Windows）

资源	路径
游戏源代码	因安装方式而异
已安装的 Mod	%APPDATA%/Balatro/Mods/
Lovely 日志	%APPDATA%/Balatro/Mods/lovely/log/

模式参考

针对具体主题，请阅读以下文件：

主题	参考文件
Lovely.toml 语法	patterns/lovely-patches.md
SMODS 钩子、配置、本地化	patterns/smods-api.md
桌面端与移动端的差异	patterns/mobile-compat.md
UIBox、CardArea、绘制顺序	patterns/ui-system.md
游戏源文件映射与搜索技巧	references/game-files.md
G.GAME、G.STATES、G.P_* 全局变量	references/globals.md
Lua/LuaJIT 陷阱、常见模组问题	references/lua-gotchas.md

新建模组（类型：new）

${CLAUDE_PLUGIN_ROOT}/templates/ 文件夹中的模板：

文件	用途
agents-md-template.md	标准模组的 AGENTS.md 模板
agents-texture-pack-template.md	Malverk 纹理包的 AGENTS.md
mod-config-template.json	脚本配置
gitignore-template	标准 .gitignore
logger-template.lua	集中式日志记录工具

元数据文件：

文件	用途
mod-json-template.json	SMODS 模组清单（{ModName}.json）
manifest-json-template.json	Thunderstore 清单

templates/docs/ 中的用户文档：

文件	用途
description-template.md	docs/ 的简洁 README
NEXUSMODS_DESCRIPTION-template.txt	NexusMods 的 BBCode
knowledge-base-template.md	问题与经验教训

基本模组结构（新仓库）：

{ModName}/
├── main.lua                 # Entry point, mod registration
├── config.lua               # Config defaults (optional)
├── lovely.toml              # Lovely patches (if needed)
├── {ModName}.json           # SMODS mod manifest
├── manifest.json            # Thunderstore manifest
├── mod.config.json          # Script configuration
├── Utils/
│   └── Logger.lua           # Centralized logging
├── localization/
│   ├── en-us.lua            # English (required)
│   └── zh_CN.lua            # Chinese
├── assets/                  # Sprites, shaders
├── scripts/                 # Utility scripts
└── docs/                    # Documentation

可用命令（共 16 个 — 插件自带，自动加载）

• /balatro-mod-dev:familiar - 熟悉此模组（读取 AGENTS.md，梳理架构）
• /balatro-mod-dev:init - 初始化新模组
• /balatro-mod-dev:sync-mod - 启动同步并启用监视模式（启动时运行一次）
• /balatro-mod-dev:bump-version [patch|minor|major] - 增加版本号，更新变更日志
• /balatro-mod-dev:release - 创建发布包（自动从清单检测版本）
• /balatro-mod-dev:fix-sprites <directory> [--preview] - 修复精灵图上的灰色边框
• /balatro-mod-dev:refactor [focus-area] - 检查代码中的冗余、过时的回退逻辑和模块化问题
• /balatro-mod-dev:debug - 通过检查 Lovely 日志验证修复（自动从仓库检测模组键）
• /balatro-mod-dev:test [scenario] - 运行测试场景，并通过 Lovely 日志验证模组行为
• /balatro-mod-dev:draft-pr - 起草 PR 消息（适用于分支仓库）
• /balatro-mod-dev:check - 审查项目健康状况，为缺失的规则搭建框架
• /balatro-mod-dev:update-docs - 检查所有文档的准确性、过时内容、重复内容和冗长度
• /balatro-mod-dev:update-plugin - 根据新知识更新插件
• /balatro-mod-dev:knowledge - 回顾会话工作，记录新发现
• /balatro-mod-dev:compact - 评估现在是否需要压缩上下文
• /balatro-mod-dev:help - 列出所有可用命令和 Agent

子 Agent（共 11 个 — 插件自带）

• game-source-researcher - 查找游戏函数和注入点（sonnet）
• smods-api-researcher - 查找 SMODS API 模式和用法（sonnet）
• mod-pattern-researcher - 查找其他模组实现功能的方式（sonnet）
• lovely-patch-researcher - 查找 Lovely 补丁语法和示例（sonnet）
• project-explorer - 全面探索代码库（sonnet）
• code-writer - 执行实现计划并编写代码（sonnet）
• script-runner - 运行临时脚本并返回结果（haiku）
• code-reviewer - 审查代码的正确性和边缘情况（opus）
• research-analyst - 综合多位研究人员的发现（opus）
• strategic-planner - 为复杂功能制定实现策略（opus）
• debug-inspector - 检查运行时日志、转储文件和模组兼容性（sonnet）

日志记录

对于新仓库/自己的仓库：

使用 Utils/Logger.lua（来自 ${CLAUDE_PLUGIN_ROOT}/templates/logger-template.lua）：

local Logger = require("Utils.Logger")
local log = Logger.create("ModuleName")
log("info", "Initialized")
log("error", "Failed: " .. err)

对于分支仓库/他人的仓库：

仅使用临时日志（提交 PR 前移除）：

pcall(print, "[Debug] checkpoint: " .. tostring(var))

实用脚本

脚本	用途
${CLAUDE_PLUGIN_ROOT}/scripts/sync_to_mods.template.sh	将模组文件同步到游戏的 Mods 文件夹
${CLAUDE_PLUGIN_ROOT}/scripts/create_release.template.sh	创建发布包
${CLAUDE_PLUGIN_ROOT}/scripts/fix_transparent_pixels.py	修复精灵图上的灰色边框

工作流：调试

1. 查看 references/lua-gotchas.md，了解已知问题（FFI cdata、nil 作用域、布尔值规范化）
2. 检查平台（桌面端还是移动端）
3. 在游戏源码中搜索相关函数
4. 查看其他模组的实现
5. 添加日志（自己的模组用 Logger.lua，分支版本用临时日志）
6. 检查 Lovely 日志
7. **如果修复尝试失败 3 次或以上：**调用 research-analyst（opus）汇总所有调试上下文

工作流：更新用户文档

当用户说“更新所有用户文档”时：

1. 检查所有文件：README(_zh).md、CHANGELOG(_zh).md
2. 检查 docs/：description.md、NEXUSMODS_DESCRIPTION.txt
3. 更新 {ModName}.json、manifest.json 中的版本号
4. 确保中英文内容一致