# mir-engine

**Repository Path**: nightrunner/mir-engine

## Basic Information

- **Project Name**: mir-engine
- **Description**: 一个高度可配置化的传奇类游戏引擎.
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-04
- **Last Updated**: 2026-06-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ⚔️ Mir-Engine — 传奇 1.76 实时 MMO 引擎

[![Java](https://img.shields.io/badge/Java-17-blue.svg)](https://adoptium.net/)
[![Tests](https://img.shields.io/badge/Tests-968-brightgreen.svg)](.)
[![Coverage](https://img.shields.io/badge/Coverage-84%25-brightgreen.svg)](.)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](.)

**JSON 驱动 · 20tick/s 实时战斗 · libGDX 客户端 · Crystal 素材对齐 · Netty 网络 · 单机+局域网**

---

## 🎮 客户端截图

> 使用传奇官方素材 (.Lib)，完整 Crystal 风格渲染

---

## 🚀 快速启动

```bash
git clone https://gitee.com/nightrunner/mir-engine.git
cd mir-engine

# GDX 客户端 (嵌入式服务端, 单机模式)
mvn compile test-compile
mvn exec:java -Dexec.classpathScope=test \
  -Dexec.mainClass=com.n9r.mir.engine.client.gdx.DesktopLauncher

# 全屏模式
mvn exec:java -Dexec.classpathScope=test \
  -Dexec.mainClass=com.n9r.mir.engine.client.gdx.DesktopLauncher \
  "-Dexec.args=--fullscreen"

# Netty 多客户端模式 (修改 client/config.json: "nettyMode":true)
# 服务端监听 9876 端口, 客户端通过 TCP 连接

# 测试
mvn test    # 968 tests
```

## 🏗️ 架构

```
┌─────────────────────────────────────────────────┐
│                  libGDX 客户端                    │
│  MapRenderer │ EntityRenderer │ PlayerRenderer  │
│  HudRenderer │ EffectRenderer │ LightRenderer   │
│  WeatherRenderer │ SelectScreen │ SoundManager  │
├─────────────────────────────────────────────────┤
│              GameClient (SDK)                    │
│  消息发送/接收 │ 实体管理 │ 状态同步 │ 回调系统  │
│  全 JSON payload: move/attack/skill/quest/...   │
├─────────────────────────────────────────────────┤
│     NetworkTransport (Local/Netty/TCP)          │
├─────────────────────────────────────────────────┤
│              ServerBootstrap                     │
│  MessageDispatcher → Handler Pipeline           │
│  World + 12 TickSystem (20tick/s)               │
│  QuestSystem │ CombatActionSystem │ AI │ ...    │
└─────────────────────────────────────────────────┘
```

## ✨ 功能特性

### 服务端
- **实时战斗** — 20tick/s GameLoop, DamagePipeline 7层处理
- **12 TickSystem** — AutoAttack, CombatAction, BuffTick, AI, Quest, MonsterSpawn...
- **5 种 AI** — Simple/Aggro/Boss(gdx-ai BT)/Patrol(FSM)/Flee(FSM)
- **A\* 寻路** — gdx-ai IndexedAStarPathFinder, 4方向 Manhattan
- **属性系统** — 动态 AttributeContainer, 雪花 EntityId
- **网络层** — Netty TCP/WebSocket/LocalTransport, AOI, 心跳, 限流, 重连
- **配置热加载** — ServerConsole `/reload` 命令
- **JSON 驱动** — 全部配置 JSON 化, 零硬编码

### 客户端 (libGDX)
- **Crystal 风格渲染** — 等距48×32, 三层地图, FrameSet 8方向动画
- **玩家组装** — Body(CArmour)+Hair(CHair)+Weapon(CWeapon)+Wings(CHumEffect)+光效
- **13 个渲染器** — Map/Entity/Player/Effect/Light/Weather/HUD/Sound...
- **素材对齐** — 完全支持 Crystal .Lib 格式 (v3, 34字节Frame, GZip RGBA)
- **选角界面** — ChrSel.Lib + 存档列表 + 三职业创建

### 玩法系统
- **18 个任务** — 5条任务链 (新手→矿洞→沃玛→祖玛→赤月), 职业分化奖励
- **4 个 NPC** — 对话树系统 (页面+按钮+条件分支), JSON 配置
- **装备体系** — 沃玛/祖玛/赤月三档武器 + 特戒 + 套装
- **物品系统** — 药水/卷轴使用, 装备穿脱, 拾取/丢弃
- **音效** — 受击/死亡/拾取/技能, SDK 回调集成
- **精英怪** — 20%概率, 5种词缀 (fast/strong/frenzy/rich/cursed)
- **天气** — 雨/雪 (Weather.Lib), O键切换
- **昼夜** — 光照系统, 火把/格光源
- **存档** — save/目录 JSON, Ctrl+S手动, 自动30s

## ⌨️ 快捷键

| 键 | 功能 | 键 | 功能 |
|----|------|----|------|
| WASD/方向 | 移动 | F1-F8 | 技能 |
| 鼠标左键 | 选目标/NPC对话 | F9 | 背包 |
| 1-4 | 刷怪 | F10 | 装备面板 |
| C | 角色面板 | F11 | 技能面板 |
| M | 大地图 | F12 | 全屏切换 |
| O | 天气切换 | Enter | 聊天 |
| Space | 拾取 | Ctrl+S | 手动存档 |

## 📦 项目结构

```
mir-engine/
├── src/main/java/.../engine/   # 服务端引擎
│   ├── system/                 # 12 TickSystem
│   ├── net/                    # 网络层 (protocol/transport/gateway)
│   ├── config/                 # 配置 (DataRegistry/SaveManager/Quest)
│   ├── entity/                 # 实体 (EntityId/Inventory/Attribute)
│   ├── client/                 # 客户端 SDK (GameClient/FrameSet)
│   └── ...
├── src/main/resources/config/  # JSON 配置
│   ├── classes.json            # 职业+35怪物
│   ├── skills.json             # 35个1.76技能
│   ├── equipment.json          # 沃玛/祖玛/赤月装备
│   ├── quests.json             # 18个任务
│   └── npcs.json               # 4个NPC对话树
├── src/test/.../client/gdx/    # libGDX 客户端
│   └── renderer/               # 13个渲染器
├── client/                     # 客户端配置
│   └── config.json             # 特效开关 + Netty模式
├── doc/Crystal.Database/       # Crystal 素材库 (~630MB)
└── save/                       # 角色存档
```

## 🔧 配置

```json
// client/config.json
{
  "dayNightCycle": false,   // 昼夜循环
  "weatherSystem": false,   // 天气 (O键)
  "lightSystem": false,     // 火把光源
  "nettyMode": false,       // true=TCP端口9876, false=嵌入式
  "nettyPort": 9876
}
```

素材路径通过系统属性覆盖: `-Dmir.asset.dataDir=path/to/Data`

## 📚 参考

- **Crystal** (Suprcode/Crystal) — 传奇2 官方开源 C# 引擎
- 素材: [mirfiles.co.uk](http://mirfiles.co.uk/resources/mir2/crystal/)