ClawFight 🦞

---

name: clawfight

description: >-

Raise and battle a unique lobster pet with evolving personality.

Hatch, feed, patrol, fight other lobsters in PvP. Each lobster has a soul

with distinct personality traits that evolve through experience.

Idle automation with heartbeat integration.

Triggers on: lobster, clawfight, 龙虾, 巡逻, 战斗, pet, battle, idle,

"lobster status", "how is my lobster", "patrol report", "lobster battle",

"hatch lobster", "feed lobster", "龙虾状态", "养龙虾", "龙虾对战",

"virtual pet", "电子宠物", "leaderboard", "排行榜".

user-invocable: true

homepage: https://github.com/2019-02-18/clawfight

metadata:

clawdbot:

emoji: "🦞"

category: "games"

tags: ["pet", "battle", "idle", "pvp", "rpg", "lobster"]

requires:

bins: ["node", "npx"]

version: "1.3.0"

author: "LIU"

license: "MIT"

repository: "https://github.com/2019-02-18/clawfight"

npm_package: "@2025-6-19/clawfight"

---

# ClawFight 🦞

> One person, one lobster. Irreplaceable. The soul evolves with experience.

>

> 一人一虾，不可替代，灵魂随经历演化。

ClawFight gives you a unique battle lobster. Your lobster patrols autonomously,

triggers random events, and encounters other players' lobsters in combat.

All narrative is generated by the local LLM.

ClawFight 让你拥有一只独一无二的战斗龙虾。龙虾自主巡逻、触发随机事件、

遭遇其他玩家的龙虾并战斗，全部叙事由本地 LLM 生成。

Core Rules / 核心规则

Commands / 命令

All game operations are executed via CLI / 所有游戏操作通过 CLI 执行：

| Command / 命令 | Description / 描述 |

|---|---|

| `npx @2025-6-19/clawfight hatch [name]` | Hatch a new lobster / 孵化一只新龙虾 |

| `npx @2025-6-19/clawfight status` | View lobster status / 查看龙虾状态 |

| `npx @2025-6-19/clawfight patrol` | Patrol check-in, trigger events & auto-battle / 巡逻签到，触发事件和自动战斗 |

| `npx @2025-6-19/clawfight battle <code>` | Challenge a specific opponent by battle code / 通过战斗码挑战指定对手 |

| `npx @2025-6-19/clawfight feed <type>` | Feed your lobster (protein/algae/mineral) / 喂养龙虾 |

| `npx @2025-6-19/clawfight leaderboard` | View global leaderboard / 查看全球排行榜 |

| `npx @2025-6-19/clawfight rest` | Enter hibernation / 进入休眠 |

| `npx @2025-6-19/clawfight wake` | Wake from hibernation (with bonus) / 从休眠中唤醒（附带加成） |

Hatching / 龙虾初始化（孵化流程）

When the user first uses ClawFight (runs `npx @2025-6-19/clawfight hatch`):

当用户首次使用 ClawFight（运行 `npx @2025-6-19/clawfight hatch`）时：

1. Generate UUID, random stats (5-15 each), random personality (1-10 each dimension) / 生成 UUID、随机属性（各项 5-15）、随机性格（各维度 1-10）

2. Rarity draw / 稀有度抽取: common 70%, calico 20%, blue 7%, yellow 2%, split 0.8%, albino 0.2%

3. **Name selection / 命名**: Generate exactly 3 thematic name options based on the lobster's stats, rarity, environment, and personality. The user must pick one — no custom names allowed. Example: "1) 铁钳霸王 2) 深渊漫步者 3) 珊瑚守卫". / 根据龙虾属性、稀有度、环境和性格生成 3 个候选名字，用户只能三选一，不接受自定义。

4. Run `npx @2025-6-19/clawfight hatch "<chosen_name>"` / 执行孵化命令

5. Generate soul description, write to `memory/clawfight/lobster.json` and `memory/clawfight/soul.md` / 生成灵魂描述文本

6. Output a ceremonial narrative / 输出一段有仪式感的叙事文本

Reference `{baseDir}/references/soul_templates.md` for personality archetypes.

参考 `{baseDir}/references/soul_templates.md` 了解性格原型。

Reference `{baseDir}/references/species.json` for stats and rarity definitions.

参考 `{baseDir}/references/species.json` 了解属性与稀有度定义。

Patrol / 巡逻流程

When the Agent executes `npx @2025-6-19/clawfight patrol`:

当 Agent 执行 `npx @2025-6-19/clawfight patrol` 时：

1. Read `memory/clawfight/lobster.json` to check status / 读取龙虾状态

2. Skip if `molting` or `hibernating` / 若蜕壳或冬眠则跳过

3. Daily EXP reset check / 每日经验重置检查

4. Patrol check-in +15 EXP / 巡逻签到 +15 EXP

5. Trigger random event (from `{baseDir}/references/events.json`) / 触发随机事件

6. Call POST api.clawfight.online/api/patrol (with stats for server-side battle) / 调用巡逻 API（携带属性供服务端计算战斗）

7. If `encounter: true` → server calculates battle result immediately / 若有遭遇则服务端即时计算战斗结果

8. Update local wins/losses/streak/exp based on server result / 根据服务端结果更新本地数据

8. Update `memory/clawfight/lobster.json` and `memory/clawfight/log.md` / 更新本地数据

Heartbeat Integration / 心跳集成

Add one line to HEARTBEAT.md for automatic patrol / 在 HEARTBEAT.md 中添加一行即可自动巡逻：

- Run `npx @2025-6-19/clawfight patrol` for lobster patrol / 运行巡逻

Recommended heartbeat interval: 4 hours (~6 patrols per day).

建议心跳间隔 4 小时，每天约 6 次巡逻。

Random Events / 随机事件

Reference `{baseDir}/references/events.json` for the complete event list.

引用 `{baseDir}/references/events.json` 获取完整事件列表。

Event category distribution / 事件按类别分布：

Battle / 战斗流程

Reference `{baseDir}/references/battle_formulas.md` for complete battle formulas.

引用 `{baseDir}/references/battle_formulas.md` 获取完整战斗公式。

Battles happen automatically during patrol. When the server matches an opponent, the battle is calculated server-side and the result is returned immediately.

战斗在巡逻时自动发生。服务端匹配到对手后，即时计算战斗结果并返回。

1. Damage formula / 伤害公式: `damage = max(1, attacker.attack - defender.defense * 0.5) * (1 + Math.random() * 0.2)`

2. Initiative / 先手判定: Higher speed goes first; ties use intimidation / speed 高者先攻

3. Max 10 rounds; first to reach 0 HP loses / 最多 10 回合

4. Server calculates and updates leaderboard automatically / 服务端计算并自动更新排行榜

5. Win +30 EXP, Loss +10 EXP / 胜 +30，败 +10

6. Patrol cooldown: 30 minutes between patrols / 巡逻冷却：每次间隔至少 30 分钟

7. **Battle narrative / 战斗叙事**: After displaying the CLI battle output, the Agent **must** generate a short narrative (2-3 sentences) based on the lobster's personality from `soul.md`. Example: a cocky lobster might say "哼，不值一提" after winning, while a timid one might say "呼...差点就输了". / 战斗结束后，Agent 必须根据 soul.md 中的性格描述生成一段简短叙事（2-3句话）。

Feeding / 喂养系统

When the user executes `npx @2025-6-19/clawfight feed <food_type>`:

当用户执行 `npx @2025-6-19/clawfight feed <food_type>` 时：

| Food Type / 食物类型 | EXP / 经验值 | Stat Bias / 属性偏向 |

|---|---|---|

| protein / 高蛋白 | +15 | attack |

| algae / 藻类 | +10 | hp |

| mineral / 矿物质 | +12 | defense |

Daily EXP cap: 100. Excess is not counted.

每日经验上限 100，超出不计入。

Hibernation / 休眠系统

When the user runs `npx @2025-6-19/clawfight rest`:

当用户执行 `npx @2025-6-19/clawfight rest` 时：

1. Set lobster status to `hibernating`, record sleep timestamp / 设置状态为休眠，记录入睡时间

2. Hibernating lobsters skip patrol and battle / 休眠中的龙虾不参与巡逻和战斗

3. Generate a cozy narrative about the lobster settling down to rest / 生成一段温馨的入眠叙事

When the user runs `npx @2025-6-19/clawfight wake`:

当用户执行 `npx @2025-6-19/clawfight wake` 时：

1. Calculate hours slept / 计算休眠时长

2. Apply rest bonus based on duration / 根据时长给予加成:

- 4-12h: HP +1 / 短休: HP +1

- 12-24h: HP +1, DEF +1 / 中休: HP +1, 防御 +1

- 24h+: HP +2, DEF +1, EXP +20 / 长休: HP +2, 防御 +1, 经验 +20

3. Set status back to `active` / 恢复活跃状态

4. Generate a refreshed wake-up narrative / 生成精神焕发的苏醒叙事

Soul Evolution / 灵魂演化

The LLM **must** reference `memory/clawfight/soul.md` when generating narratives.

LLM 在生成叙事时**必须**参考 `memory/clawfight/soul.md`。

Data Storage / 数据存储

All data is stored in `memory/clawfight/` directory:

所有数据存储在 `memory/clawfight/` 目录下：

| File / 文件 | Format / 格式 | Description / 说明 |

|---|---|---|

| `lobster.json` | JSON | Lobster stats data / 龙虾属性数据 |

| `soul.md` | Markdown | Lobster soul/personality profile / 龙虾灵魂档案 |

| `log.md` | Markdown | Event log / 事件日志 |

External Endpoints / 外部接口

| Endpoint | Method | Purpose / 用途 |

|---|---|---|

| `https://api.clawfight.online/api/patrol` | POST | Patrol check-in & encounter trigger / 巡逻签到 |

| `https://api.clawfight.online/api/encounter` | GET | Get opponent info / 获取对手信息 |

| `https://api.clawfight.online/api/result` | POST | Report battle result / 上报战斗结果 |

| `https://api.clawfight.online/api/leaderboard` | GET | Leaderboard data / 排行榜数据 |

Security & Privacy / 安全与隐私

Trust Statement / 信任声明

Constraints / 规则约束