# noark3

**Repository Path**: xiaoe/noark3

## Basic Information

- **Project Name**: noark3
- **Description**: 一个由Java实现的游戏服务器端框架，可快速开发出易维护、高性能、高扩展能力的游戏服务器
- **Primary Language**: Java
- **License**: MulanPSL-1.0
- **Default Branch**: master
- **Homepage**: http://www.noark.xyz
- **GVP Project**: No

## Statistics

- **Stars**: 729
- **Forks**: 140
- **Created**: 2018-06-02
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: game-dev

**Tags**: None

## README



# Noark 游戏服务器端框架

<p align="center">
  <a href="http://noark.xyz/" title="Noark">
    <img src="https://img.shields.io/badge/JDK-1.8%2B-green.svg" alt="JDK">
  </a>
  <a href="http://license.coscl.org.cn/MulanPSL">
    <img src="https://img.shields.io/badge/license-MulanPSL-blue" alt="License">
  </a>
  <a href="https://search.maven.org/search?q=g:xyz.noark">
    <img src="https://maven-badges.herokuapp.com/maven-central/xyz.noark/noark-game/badge.svg" alt="Maven">
  </a>
</p>

## 简介

Noark 是一个开源的游戏服务器端框架，旨在帮助开发者快速构建高性能、稳定、可扩展的游戏服务器。框架实现了配置注入、协议映射、模板加载、数据存储、异步事件、延迟任务、内部指令等功能模块，达到了松散耦合的效果，提高了系统的可重用性、可维护性以及可扩展性。

**核心特点：**

- 🎯 **简单易用** - 学习成本低，快速上手
- ⚡ **高性能** - 精心设计的架构，轻松实现高并发
- 🔧 **灵活扩展** - 模块化设计，易于集成第三方技术
- 🛡️ **稳定可靠** - 经过大量生产环境验证

## 技术架构

Noark 框架采用模块化设计，主要包含以下核心模块：

```
noark3
├── noark-core      # 核心框架（IoC、事件、转换器、网络等）
├── noark-codec     # 序列化编解码模块
├── noark-csv      # CSV 模板加载
├── noark-game     # 游戏服务器主框架
└── noark-log      # 日志模块
```

### 核心功能

| 模块 | 功能描述 |
|------|----------|
| **IoC 容器** | 依赖注入、控制反转，支持多种注入方式 |
| **事件系统** | 同步/异步事件、延迟事件、定时事件 |
| **模板加载** | 支持 CSV、JSON 格式的配置文件加载 |
| **网络通信** | 基于 Netty 的 TCP 服务器，支持自定义协议 |
| **线程调度** | 任务队列、线程池管理、执行超时监控 |
| **数据转换** | 强大的类型转换器，支持复杂数据结构 |
| **行为树** | AI 行为树框架，支持复杂逻辑编排 |
| **配置中心** | 支持 Nacos 配置中心集成 |
| **敏感词过滤** | DFA 算法实现的敏感词检测与过滤 |
| **日志系统** | 异步日志输出，支持日志轮转 |

## 快速开始

### 环境要求

- JDK 1.8+ (Noark 3.x)
- JDK 21+ (Noark 4.x)

### Maven 依赖

```xml
<dependency>
    <groupId>xyz.noark</groupId>
    <artifactId>noark-game</artifactId>
    <version>3.4.8.Final</version>
</dependency>
```

### Gradle 依赖

```groovy
implementation "xyz.noark:noark-game:3.4.8.Final"
```

## Hello Kitty 快速入门

按照以下三步走，快速创建第一个游戏服务器：

### A. Application 应用入口

在 `com.company.slg` 包下创建入口类：

```java
package com.company.slg;

import xyz.noark.game.Noark;

public class GameServerApplication {
    public static void main(String[] args) {
        Noark.run(GameServerBootstrap.class, args);
    }
}
```

### B. Bootstrap 启动引导类

创建引导启动类，继承 `BaseServerBootstrap`：

```java
package com.company.slg;

import xyz.noark.game.bootstrap.BaseServerBootstrap;

public class GameServerBootstrap extends BaseServerBootstrap {
    @Override
    protected String getServerName() {
        return "game-server";
    }
}
```

### C. Configuration 配置中心（可选）

用于配置第三方服务类：

```java
package com.company.slg;

import xyz.noark.core.annotation.Configuration;

@Configuration
public class GameServerConfiguration {
    // 配置第三方服务
}
```

### 启动服务器

运行 `main` 方法，即可启动游戏服务器：

```
2018-08-16 18:23:38.178 [main] INFO AbstractServerBootstrap.java:62 - starting game-server service...
2018-08-16 18:23:38.504 [main] INFO ReloadManager.java:41 - loading template data. checkValidity=true
2018-08-16 18:23:38.504 [main] INFO ReloadManager.java:47 - load template data success.
2018-08-16 18:23:38.606 [main] INFO NettyServer.java:119 - game tcp server start on 9527
2018-08-16 18:23:38.607 [main] INFO NettyServer.java:128 - game tcp server start is success.
game-server is running, interval=427.21872 ms
```

## 核心注解

Noark 提供丰富的注解来简化开发：

### 依赖注入

```java
// 服务类
@Service
public class UserService {
    @Autowired
    private ItemService itemService;
}

// 控制器
@Controller
public class PlayerController {
    @Autowired
    private PlayerService playerService;
}
```

### 网络协议处理

```java
@Controller
public class GateController {
    // TCP 协议处理
    @PacketMapping(opcode = 1)
    public LoginResult login(Session session, LoginRequest req) {
        // 处理登录逻辑
        return new LoginResult();
    }

    // HTTP 接口
    @GetMapping("/player/info")
    @ResponseBody
    public PlayerInfo getPlayerInfo(@PlayerId Long playerId) {
        return playerService.getPlayerInfo(playerId);
    }
}
```

### 事件监听

```java
@Controller
public class PlayerEventListener {
    // 登录事件
    @EventListener
    public void handleLoginEvent(LoginEvent event) {
        // 处理登录事件
    }

    // 延迟事件（定时任务）
    @EventListener
    public void handleDailyTask(DailyTaskEvent event) {
        // 处理每日任务重置
    }
}
```

### 定时任务

```java
@Controller
public class ScheduledTasks {
    // 每小时执行
    @Scheduled(cron = "0 0 * * * ?")
    public void hourlyTask() {
        // 执行每小时任务
    }
}
```

## 模板系统

### CSV 模板加载

```java
// 定义模板类
@TplFile("Item.tpl")
public class ItemTemplate {
    @TplAttr(name = "id")
    private int id;

    @TplAttr(name = "name")
    private String name;

    @TplAttr(name = "quality")
    private int quality;
}

// 加载模板
@Autowired
private TemplateLoader templateLoader;

public void loadItems() {
    Map<Integer, ItemTemplate> items = templateLoader.loadAll(ItemTemplate.class, ItemTemplate::getId);
}
```

### JSON 模板加载

```java
@TplFile("item.json")
public class ItemTemplate {
    @TplAttr(name = "id")
    private int id;

    @TplAttr(name = "name")
    private String name;
}
```

## 数据转换器

Noark 内置丰富的类型转换器：

- 基础类型：`int`, `long`, `float`, `double`, `boolean`, `String`
- 集合类型：`List`, `Set`, `Map`, `ArrayList`, `LinkedList`, `HashMap`
- 特殊类型：`Date`, `LocalDate`, `LocalDateTime`, `LocalTime`
- 数值集合：`IntList`, `LongList`, `FloatList`, `DoubleList`
- 其他：`FileSize`, `Point`, `IntPair`, `IntRange`, `TimeRange`

## 行为树 (AI)

Noark 提供行为树框架用于实现 AI 逻辑：

```java
// 构建行为树
BehaviorTree ai = new BehaviorTree(
    new SelectorNode()
        .addChild(new SequenceNode()  // 优先级序列
            .addChild(new MeNoFlowers())    // 没花
            .addChild(new GoToFlowerShop()) // 去花店
            .addChild(new BuyFlowers()))    // 买花
        .addChild(new SequenceNode()  // 备选方案
            .addChild(new NoMoney())        // 没钱
            .addChild(new GoHome()))        // 回家
);

// 执行行为树
ai.tick();
```

## 网络通信

### TCP 服务器

框架基于 Netty 实现高性能 TCP 服务器：

```java
// 自定义协议编解码
public class MyPacketCodec implements PacketCodec {
    @Override
    public NetworkPacket decode(ByteBuf in) {
        // 解码协议
    }

    @Override
    public ByteBuf encode(ByteBuf out, NetworkPacket packet) {
        // 编码协议
    }
}
```

### Session 管理

```java
// 获取玩家 Session
Session session = SessionManager.getSessionByPlayerId(playerId);

// 发送协议
Sender.send(session, opcode, protocol);

// 广播消息
SessionManager.send(opcode, protocol, playerIds);
```

## 配置说明

### 配置文件

在 `resources` 目录下创建 `application.properties`：

```properties
# 服务器配置
server.name=game-server
server.id=1

# 线程配置
thread.pool.size=8
thread.name.prefix=game

# 模板配置
template.path=templates

# 日志配置
log.level=INFO
log.console=true
log.path=logs
```

### Nacos 配置中心

```properties
nacos.enabled=true
nacos.server.addr=localhost:8848
nacos.username=nacos
nacos.password=nacos
```

## 文档与支持

- 官方网站：[https://noark.xyz](https://noark.xyz)
- 开发文档：[http://blog.noark.xyz](http://blog.noark.xyz)
- QQ 交流群：**85750544** (Noark 官方交流群)

## 目标与愿景

我们的目标：**稳定、高性能、可扩展、易维护、提高开发效率**

Noark 不追求取代谁，也不追求超越谁，我们只做我们自己——一个专注于游戏服务器开发的实用框架。

## 开源协议

本项目采用 [MulanPSL](http://license.coscl.org.cn/MulanPSL) 开源协议。

## 贡献者

感谢所有为 Noark 贡献代码的开发者！

---

<p align="center">
  <sub>Noark - 让游戏服务器开发更简单</sub>
</p>