# mymir-preview

**Repository Path**: nightrunner/mymir-preview

## Basic Information

- **Project Name**: mymir-preview
- **Description**: mymir(我的传奇)-模块化 MMO 游戏引擎。Java 17 多模块架构，JSON 驱动 20tick/s 实时服务端，libGDX 客户端。Lua+JavaScript 双脚本 Mod 系统，VFS 三层文件覆盖。单机嵌入式或 Netty 联机双模式，附带内置双倍经验等示例 Mod。服务端/客户端SDK/可运行游戏三包独立发布。

- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mymir — 我的传奇

> 精神内核: **我既传奇。** v1.0.0 目标: 热血传奇 1.76。给每个传奇爱好者一个属于自己的世界引擎。不是私服，不做官服。启动即自建服务器，Bot 填充生态，改 JSON 就是策划，装 Mod 就是开发者。**你的传奇，你说了算。**
>
> 引擎以 WoW/TrinityCore 为设计底子（TC OOP 继承 + 组件组合），传奇 1.76 通过 **GamePlugin** 接入。

[![Java](https://img.shields.io/badge/Java-17-blue.svg)](https://adoptium.net/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](.)

---

## 为什么独特

别的 MMO 项目是"框架"——你还需要写游戏逻辑。mymir 是"完整游戏"——启动即可玩，Bot 陪你玩。**没有作弊概念，因为这是你的世界。**

| 系统 | 完成度 |
|------|--------|
| **战斗** | DamagePipeline 9层责任链 + 暴击/命中/防御 + 5种PK模式 + 武器诅咒/幸运 |
| **职业** | 战士/法师/道士，技能树 + 每级缩放 + 装备属性 |
| **社交** | 行会 + 沙巴克攻城 + 结婚 + 好友/仇人 |
| **任务** | 主线链 + 支线随机 + 每日面板 |
| **Bot** | 行为树 + 社交谣言 + LLM伴侣 + 恶霸团 |
| **Mod** | Lua + JavaScript 双引擎 + VFS三层覆盖 + 配置继承 + 管线可插拔 |
| **网络** | Netty TCP / WebSocket + 6档网络模拟 + 网关 |

**不再新增核心玩法** — 钓鱼、挖矿、锻造、坐骑、拍卖行...全走 Mod。核心保持稳定，扩展不进核。

## 10 秒启动

```bash
git clone https://gitee.com/nightrunner/mymir.git && cd mymir
./gradlew :mymir-client-desktop:runClient
```

一个 JVM 启动服务端+客户端+Bot，选角色进入游戏。按 `Ctrl+G` 切换鼠标模式。

```bash
# 法神教恶霸 + 双倍经验 + 网络模拟
./gradlew :mymir-client-desktop:runClient -Pargs="--mod double-xp --gang --net lan"

# 纯客户端连接远程服务器
./gradlew :mymir-client-desktop:runClient -Pargs="--host 192.168.1.100 --port 7100"

# 100个Bot压测
./gradlew :mymir-client-bot:runBot -Pargs="--count 100 --host 192.168.1.100 --port 7100"
```

## 架构: 引擎与游戏分离

```
n9r (通用引擎, 零游戏依赖)
├── n9r-base        — RPG 通用契约 (IUnit/IPlayer/ISpell/IAura... 33 接口)
├── llm             — LlmService / 决策器 (可选)
├── n9r-common      — 数据层: 模板 / 协议 / 属性枚举 / I18N / Mod解析 / 工具
├── n9r-engine      — 引擎核心: Spell/Aura/Combat/Quest/Scene (TC 底子)
└── n9r-server      — 服务进程: Netty / Gateway / 存储 / 装配

mymir (传奇 1.76 游戏实现)
├── mymir-game      — 游戏数据 (data/) + MymirPlugin (GamePlugin SPI) + MymirEffects
├── mymir-common    — 传奇特化共享: 素材解析 (parser/FrameSet/ImageUtils), n9r 层零游戏依赖
├── mir-ref-176     — 1.76 参考数据枚举 (SpellId/Monster/Item)
├── mir-ref-loader  — 枚举 → IDataLoader 桥接 (测试/启动期数据源)
├── mymir-client-core   — 客户端 SDK: GameClient / PanelManager / InputHandler
├── mymir-client-desktop  — 🎮 Crystal 风格客户端 (libGDX 渲染)
├── mymir-client-bot      — 无头 Bot: BotPool / 行为树 / 社交 / LLM
├── mymir-launcher        — 统一启动器 (Swing GUI + CLI)
└── mymir-magicbox        — Web 管理面板

集成测试 (双模块)
├── n9r-it — 日常 push 快速套件 (~50s, 单文件 ≤10s)
└── n9r-it-longtime     — 合并前全量套件 (依赖 core test-jar)
```

```
依赖链:
  n9r-base → n9r-common → n9r-engine → n9r-server
                                  ↑
  mymir-game ─────────────────────┘ (实现 GamePlugin, 引擎不依赖游戏)
```

**铁律: 引擎核心不依赖任何具体游戏。** 游戏通过 `GamePlugin` SPI 接入——装配层在数据加载前回调 `onLoad`，游戏注入数据源 + 战斗公式等扩展。

```java
public class MymirPlugin implements GamePlugin {
    @Override
    public void onLoad(EngineContext ctx) {
        DataRegistry registry = ctx.dataRegistry();
        registry.setDataLoader(new MymirDataLoader());  // 游戏数据
        registry.setCombatFormulaProvider(cs -> ...);   // 1.76 减法公式
    }
}
```

## 核心设计

### TC 实体层次 (OOP 继承 + 组件组合)

```
AbstractUnit (引擎核心, extends SceneEntity, implements IUnitCore)
├── Player       — 玩家逻辑
├── Monster      — 怪物 (AI 行为树)
├── Bot          — Bot 假人 (extends Player)
└── NpcEntity    — NPC (无战斗)
```

`AbstractUnit` 通过 `IUnitCore` 组合 30+ 组件，按领域分子包：`combat` / `aura` / `ai` / `spell` / `movement`。

**铁律:** 单实体操作直接操作组件。范围判选、多实体交互 **必须走 ITickable/Manager**。

### DamagePipeline 责任链

```
[BaseDamage] → [Luck] → [Curse] → [Accuracy] → [Crit] → [Defense] → [Shield] → [Intercept] → [Buff]
```

9 个有序 Handler，可动态增删插入。穿刺伤害绕过指定 handler。`ScriptDamageHandler` 允许 Lua/JS 自定义。`CombatPhase` 三阶段编排：`CooldownPhase → ActionPhase → BuffTickPhase`。

### Spell 两条独立 proc 路径

- **Path A** (`PASSIVE` + `toggleable`): 每刀 `resolveAttack()` 掷 triggerChance → 附加效果 (攻杀/刺杀)
- **Path B** (`TOGGLE`): `getActiveToggle()` 替代普攻 → `castSpell()` (半月弯刀)

### SDK/GDX 分层

```
GDX 按键 → InputHandler(SDK) → PanelManager(SDK) → GdxPanelRenderer(GDX)
```

- **SDK** (mymir-client-core): 纯 Java 逻辑 + 接口，不 import GDX 类型
- **GDX** (mymir-client-desktop): libGDX 实现，单向调用 SDK

### VFS + Mod

```
mods/<mod>/data/xxx.json   ← Mod 覆盖层 (有序列表, 后装覆盖先装, 老滚5 式)
data/ + asset/  ← base 兜底 (无 _default 特殊层)
```

双脚本引擎 (Lua + GraalJS)，`config/mod.json` 控制加载顺序。

### 20 tick/s 分层 TickSystem

```
50ms:  AutoAttack / CombatAction / BuffTick / SkillCD / MoveSystem
250ms: AiThink / HpMpRegen
500ms: QuestSystem / SideQuestSystem
3s:    MonsterSpawn
5s:    SabukWarSystem
```

### 五目录分离

```
data/  — 游戏策划配置 (只读 JSON, 零中文)
config/           — 引擎设置 (logback, resources.json)
素材库外置         — D:/asset (素材根, 配置 config/resources.json vfs.basePath)
                      D:/asset/crystal/ (默认厂商, Lib/Map/Sound ~5.6GB)
                      D:/asset/{mir-176, shanda-classic, ...} (其他厂商)
store/            — 运行时全局状态 (行会, 排行榜)
save/             — 每角色独立存档
```

## 测试

分层铁律 — 各模块只做单元测试，集成测试双模块（core 日常 push / full 合并前）：

```bash
./gradlew :n9r-engine:test              # 单元测试
./gradlew :n9r-it:test                    # 集成测试 core, 每次 push (~50s)
./gradlew :n9r-it-longtime:test           # 全量, 合并前 (~2min)
```

**测试自备数据** — 集成测试用 `TestDataLoader` 硬编码最小数据，不依赖生产/参考数据源。生产数据坏了不影响测试。

## 作为依赖引入

Gradle 单仓多模块 — 工程内依赖即源码输出（无 install 概念）：

```groovy
dependencies {
    implementation project(':n9r-server')   // 服务端装配 (Netty/Gateway/存储)
    implementation project(':mymir-game')   // 传奇 1.76 GamePlugin 实现
}
```

## 许可

MIT — 随意使用。

## 文档

详细系统设计: [`doc/spec/系统索引.md`](doc/spec/系统索引.md) — 00-10 全系统 spec + 设计哲学 + 版本管理。

## TODO 管理

进度跟踪在 [`doc/TODO.md`](doc/TODO.md)（近期完成）+ [`doc/DONE.md`](doc/DONE.md)（归档）。规则：

- **编号**: 每条 TODO 带唯一编号 `NO:{YYYYMMDDHHMM}-{type}`（创建时间戳 + 类型：bug/feature/refactor/data/perf/docs/design/test）
- **状态**: `✅` 完成 / `🔨` 进行中 / `⚠️` 待实机验证 / `⏳` 待办，`(remark: ...)` 备注根因/进展
- **归档**: ✅ 完成即移 DONE.md（TODO 只留未完成条目；每批标注迁移时间，每周整理）
- **人机交互**: 执行期间提出的 TODO 先进草稿区，当前任务完成后统一处理