netty 高性能游戏服务器框架；ioGame 21.6 真.轻量级网络编程框架发布

属性监听特性

#264 新增属性值变更监听特性

文档 : 属性监听 (yuque.com)

属性可添加监听器，当某些属性值的发生变化时，触发监听器。

使用场景举例

比如玩家的血量低于一定值时，需要触发无敌状态；此时，我们就可以监听玩家的血量，并在该属性上添加一个对应的监听器来观察血量的变化，当达到预期值时就触发对应的业务。

类似的使用场景还有很多，这里就不过多的举例了。属性监听的特点在于属性变化后会触发监听器。

属性监听特点

• 可为属性添加监听器，用于观察属性值的变化。

• 属性可以添加多个监听器。

• 属性的监听器可以移除。

框架已经内置了几个属性实现类，分别是：

• IntegerProperty

• LongProperty

• StringProperty

• BooleanProperty

• ObjectProperty

for example - 添加监听器

当 BooleanProperty 对象的值发生改变时，触发监听器。

 var property = new BooleanProperty(); // 添加一个监听器。 property.addListener((observable, oldValue, newValue) -> {  log.info("oldValue:{}, newValue:{}", oldValue, newValue); }); ​ property.get(); // value is false property.set(true); // 值变更时，将会触发监听器 property.get(); // value is true

当 IntegerProperty 对象的值发生改变时，触发监听器。

 var property = new IntegerProperty(); // add listener monitor property object property.addListener((observable, oldValue, newValue) -> {  log.info("oldValue:{}, newValue:{}", oldValue, newValue); }); ​ property.get(); // value is 0 property.set(22); // When the value changes,listeners are triggered property.get(); // value is 22 ​ property.increment(); // value is 23. will trigger listeners

for example - 移除监听器

下面这个示例，我们将 property 初始值设置为 10，随后添加了一个监听器；当监听器观察到新值为 9 时，就从 observable 中移除自己（这个自己指的是监听器本身），而 observable 则是 IntegerProperty。

 @Test public void remove1() {  IntegerProperty property = new IntegerProperty(10);  // 添加一个监听器  property.addListener(new PropertyChangeListener<>() {  @Override  public void changed(PropertyValueObservable extends Number> observable, Number oldValue, Number newValue) {  log.info("1 - newValue : {}", newValue); ​  if (newValue.intValue() == 9) {  // 移除当前监听器  observable.removeListener(this);  }  }  }); ​  property.decrement(); // value 是 9，并触发监听器  property.decrement(); // value 是 8，由于监听器已经移除，所以不会触发任何事件。 }

下面的示例中，我们定义了一个监听器类 OnePropertyChangeListener 并实现了 PropertyChangeListener 监听器接口。示例中，我们通过 OnePropertyChangeListener 对象的引用来移除监听器。

 @Test public void remove2() {  // 监听器  OnePropertyChangeListener onePropertyChangeListener = new OnePropertyChangeListener();    // 属性  IntegerProperty property = new IntegerProperty();  // 添加监听器  property.addListener(onePropertyChangeListener); ​  property.increment(); // value == 1，并触发监听器  property.removeListener(onePropertyChangeListener); // 移除监听器  property.increment(); // value == 2，由于监听器已经移除，所以不会触发任何事件。 } ​ // 自定义的监听器 class OnePropertyChangeListener implements PropertyChangeListener<Number> {  @Override  public void changed(PropertyValueObservable extends Number> observable, Number oldValue, Number newValue) {  log.info("oldValue:{}, newValue:{}, observable:{}", oldValue, newValue, observable);  } }

属性监听 - 小结

属性监听在使用上是简单的，如果你的业务中有关于属性变化后需要触发某些事件的，可以考虑引用该特性。框架为 int、long、boolean、Object、String 等基础类型提供了对应的属性监听。

属性监听特性支持添加多个监听器，支持移除监听器。

模拟客户端相关

模拟客户端新增与服务器断开连接的方法。

模拟客户端新增是否活跃的状态属性。

 ClientUser clientUser = ...; // 是否活跃，true 表示玩家活跃 clientUser.isActive(); // 关闭模拟客户端连接 clientUser.getClientUserChannel().closeChannel();

获取游戏对外服的数据与扩展相关

文档 获取游戏对外服的数据与扩展 (yuque.com)

RequestCollectExternalMessage 增加 userId 字段。

#265 模拟玩家请求时 - 从游戏对外服中获取在线玩家相关数据

新增 UserHeadMetadataExternalBizRegion，从用户（玩家）所在游戏对外服中获取用户自身的数据，如用户所绑定的游戏逻辑服、元信息 ...等

使用参考

 @Slf4j @RestController @RequestMapping("other") public class OtherController {  static final AtomicLong msgId = GameManagerController.msgId;  /** 为了方便测试，这里指定一个 userId 来模拟玩家 */  static final long userId = GameManagerController.userId; ​  @GetMapping("/notice")  public String notice() {  log.info("other notice");  // 使用协议碎片特性 https://www.yuque.com/iohao/game/ieimzn  StringValue data = StringValue.of("other GM web msg " + msgId.incrementAndGet());  // 模拟请求 : 路由 - 业务数据  RequestMessage requestMessage = BarMessageKit.createRequestMessage(ExchangeCmd.of(ExchangeCmd.notice), data); ​  // 设置需要模拟的玩家  HeadMetadata headMetadata = requestMessage.getHeadMetadata();  headMetadata.setUserId(userId); ​  // 从游戏对外服中获取一些用户（玩家的）自身的数据，如元信息、所绑定的游戏逻辑服 ...等  Optional<HeadMetadata> headMetadataOptional = ExternalCommunicationKit.employHeadMetadata(requestMessage); ​  if (headMetadataOptional.isPresent()) {  // 发起模拟请求  extractedRequestLogic(requestMessage); ​  // 打印从游戏对外服获取的元信息  byte[] attachmentData = headMetadata.getAttachmentData();  ExchangeAttachment attachment = DataCodecKit.decode(attachmentData, ExchangeAttachment.class);  return "other notice 玩家的元信息: %s - %s".formatted(attachment, msgId.get());  } else {  return "other notice 玩家 %s 不在线，无法获取玩家的元信息 - %s".formatted(userId, msgId.get());  }  } ​  private void extractedRequestLogic(RequestMessage requestMessage) {  // 向逻辑服发送请求，该模拟请求具备了玩家的元信息。  BrokerClient brokerClient = MyKit.brokerClient;  InvokeModuleContext invokeModuleContext = brokerClient.getInvokeModuleContext();  invokeModuleContext.invokeModuleVoidMessage(requestMessage);  } }

任务工具相关

TaskListener 接口增加异常回调方法 void onException(Throwable e)，用于接收异常信息；当 triggerUpdate 或 onUpdate 方法抛出异常时，将会传递到该回调方法中。

 @Test public void testException() throws InterruptedException {  AtomicBoolean hasEx = new AtomicBoolean(false);  TaskKit.runOnce(new OnceTaskListener() {  @Override  public void onUpdate() {  // 模拟一个业务异常  throw new RuntimeException("hello exception");  } ​  @Override  public void onException(Throwable e) {  hasEx.set(true);  // 触发异常后，将来到这里  log.error(e.getMessage(), e);  }  }, 10, TimeUnit.MILLISECONDS); ​  TimeUnit.MILLISECONDS.sleep(200);  Assert.assertTrue(hasEx.get()); // true }

业务框架相关 - [common-core]

#266 新增 RangeBroadcast 范围内的广播功能，这个范围指的是，可指定某些用户进行广播。

在执行广播前，开发者可以自定义业务逻辑，如

• 添加一些需要广播的用户

• 删除一些不需要接收广播的用户

• 可通过重写 logic、trick 方法来做一些额外扩展

for example 在某些业务场景下，能让语义更清晰

 // example - 1 new RangeBroadcast(flowContext)  // 需要广播的数据  .setResponseMessage(responseMessage)  // 添加需要接收广播的用户  .addUserId(1)  .addUserId(2)  .addUserId(List.of(3L, 4L, 5L))  // 排除一些用户，被排除的用户将不会接收到广播  .removeUserId(1)  // 执行广播  .execute(); ​ // example - 2 new RangeBroadcast(flowContext)  // 需要广播的数据  .setResponseMessage(cmdInfo, playerReady)  // 添加需要接收广播的用户  .addUserId(1)  // 执行广播  .execute();

[light-game-room] 房间模块

移除 AbstractRoom broadcast 系列方法，开发者可使用 RoomBroadcastFlowContext 接口实现旧的兼容。

移除 AbstractRoom createSend 方法，开发者可使用 ofRangeBroadcast 系列来代替。AbstractRoom 新增 RoomBroadcastEnhance，实现房间内的广播增强，该系列在语义上更清晰。

这里使用一个准备就绪的示例来演示，当有玩家准备时，需要通知房间内的其他玩家

 final RoomService roomService = ...; ​ @ActionMethod(RoomCmd.ready) public void ready(boolean ready, FlowContext flowContext) {  long userId = flowContext.getUserId();  // 得到玩家所在的房间  AbstractRoom room = this.roomService.getRoomByUserId(userId);    // 准备  PlayerReady playerReady = new PlayerReady();  playerReady.userId = userId;  playerReady.ready = ready;    // 通知房间内的所有玩家，有玩家准备或取消准备了  room.ofRangeBroadcast(flowContext)  // 响应数据（路由、业务数据）  .setResponseMessage(flowContext.getCmdInfo(), playerReady)  .execute(); } ​ // 准备或取消准备 @ProtobufClass @FieldDefaults(level = AccessLevel.PUBLIC) public class PlayerReady {  /** 当前操作的玩家 userId */  long userId;  /** true 表示准备 */  boolean ready; }

AbstractRoom 增加 ifPlayerExist、ifPlayerNotExist 方法。

ifPlayerExist 方法

如果玩家在房间内，就执行给定的操作，否则不执行任何操作。

这里演示玩家加入房间的业务

 RoomService roomService = ...; AbstractRoom room = ...; // 如果玩家不在房间内，就创建一个玩家，并让玩家加入房间 room.ifPlayerNotExist(userId, () -> {  // 玩家加入房间  FightPlayerEntity newPlayer = new FightPlayerEntity();  newPlayer.setId(userId);    this.roomService.addPlayer(room, newPlayer); });

ifPlayerNotExist 方法

如果玩家不在房间内，就执行给定的操作，否则不执行任何操作。

这里结合 RangeBroadcast，演示当有新玩家加入房间时，通知房间内的其他玩家。

 AbstractRoom room = ...; // 有新玩家加入房间，通知其他玩家 room.ifPlayerExist(userId, (FightPlayerEntity playerEntity) -> {  FightPlayer fightPlayer = FightMapstruct.ME.convert(playerEntity);  room.ofRangeBroadcast(flowContext)  .setResponseMessage(RoomCmd.of(RoomCmd.playerEnterRoomBroadcast), fightPlayer)  // 排除不需要通知的玩家（当前 userId 是自己）  .removeUserId(userId)  .execute(); });

ioGame 使用趋势数据

关注 ioGame 的游戏服务器开发者持续增多，2022-09 ~ 至今各月的统计数据；

这里的统计信息是关于开发者关注 ioGame 框架相关的，从统计数据中可以看出，由于 ioGame 上手简单，功能强大等优点，得到了众多开发者的关注。如果你想知道 ioGame 有没有人在使用，可以先到这里看下统计数据、开发者的评价与讨论。

https://www.yuque.com/iohao/game/gpxk93#TwVa8

这里展示了每月的统计数据，统计数据来源于语雀后台，这些数据都是真实的、客观存在的、活的。

通过统计数据，我们可以看到每天会有很多开发者在访问 ioGame 的在线文档，并且这些统计数据不是来源于口嗨的，也不是主观创造的。

所以，还在犹豫要不要使用 ioGame 的开发者们，更应该讨论的是 “为什么这些开发者会选择使用 ioGame”，而不是 ioGame 有没有人在使用的问题。

点击我，到语雀后台查看 ioGame 的数据

ioGame 网络游戏服务器框架简介

• 无锁异步化、事件驱动的架构设计；轻量级，无需依赖任何第三方中间件或数据库就能支持集群、分布式
• 通过 ioGame 可以很容易的搭建出一个集群无中心节点、集群自动化、多进程的分布式游戏服务器
• 包体小、启动快、内存占用少、更加的节约、无需配置文件、提供了优雅的路由访问权限控制
• 可同时支持多种连接方式：WS、UDP、TCP... 等；框架已支持全链路调用日志跟踪特性
• 让开发者用一套业务代码，能轻松切换和扩展不同的通信协议：Protobuf、JSON
• 近原生的性能；业务框架在单线程中平均每秒可以执行 1152 万次业务逻辑
• 代码即联调文档、JSR380 验证、断言 + 异常机制 = 更少的维护成本
• 框架具备智能的同进程亲和性；开发中，业务代码可定位与跳转
• 架构部署灵活性与多样性：既可相互独立，又可相互融合
• 可同时与同类型的多个游戏逻辑服通信并得到数据
• 逻辑服之间可相互跨进程、跨机器进行通信
• 支持玩家对游戏逻辑服进行动态绑定
• 能与任何其他框架做融合共存
• 对 webMVC 开发者友好
• 无 spring 强依赖
• 零学习成本
• javaSE

ioGame 的组成

ioGame 由 [网络通信框架] 和 [业务框架] 组成

• 网络通信框架：职责是各服务器之间的网络通信
• 业务框架：职责是业务逻辑的处理方式和编写方式

网络通信框架

SOFABolt 是蚂蚁金融服务集团开发的一套基于 Netty 实现的网络通信框架。

• 为了让 Java 程序员能将更多的精力放在基于网络通信的业务逻辑实现上，而不是过多的纠结于网络底层 NIO 的实现以及处理难以调试的网络问题，Netty 应运而生。
• 为了让中间件开发者能将更多的精力放在产品功能特性实现上，而不是重复地一遍遍制造通信框架的轮子，SOFABolt 应运而生。

Bolt 名字取自迪士尼动画 - 闪电狗，是一个基于 Netty 最佳实践的轻量、易用、高性能、易扩展的通信框架。

业务框架

如果说 sofa-bolt 是为了让 Java 程序员能将更多的精力放在基于网络通信的业务逻辑实现上。而业务框架正是解决业务逻辑如何方便实现这一问题上。业务框架是游戏框架的一部分，职责是简化程序员的业务逻辑实现，业务框架使程序员能够快速的开始编写游戏业务。

业务框架对于每个 action （即业务的处理方法） 都是通过 asm 与 Singleton、Flyweight 、Command 等设计模式结合，对 action 的获取上通过 array 来得到，是一种近原生的方式。

单线程中，业务框架平均每秒可以执行 1152 万次业务逻辑。

 /** 请求 */ @ProtobufClass @FieldDefaults(level = AccessLevel.PUBLIC) public class HelloReq { String name; }

 @ActionController(1) public class DemoAction { @ActionMethod(0) public HelloReq here(HelloReq helloReq) { // 业务数据 var newHelloReq = new HelloReq(); newHelloReq.name = helloReq.name + ", I'm here "; return newHelloReq; } // 注意，这个方法只是为了演示而写的；（ioGame21 开始支持） // 效果与上面的方法一样，只不过是用广播（推送）的方式将数据返回给请求方 @ActionMethod(0) public void here(HelloReq helloReq, FlowContext flowContext) { // 业务数据 var newHelloReq = new HelloReq(); newHelloReq.name = helloReq.name + ", I'm here "; flowContext.broadcastMe(newHelloReq); } // 跨服调用示例，下面分别展示了同步与异步回调的写法 void testShowInvokeModule(FlowContext flowContext) { /* * 框架为跨服请求提供了同步、异步、异步回调的编码风格 api。（ioGame21 开始支持） */ var cmdInfo = CmdInfo.of(1,0); var yourData = ... 你的请求参数 // 跨服请求（异步回调 - 无阻塞）-- 路由、请求参数、回调。 flowContext.invokeModuleMessageAsync(cmdInfo, yourData, responseMessage -> { var helloReq = responseMessage.getData(HelloReq.class); // --- 此异步回调，具备全链路调用日志跟踪 --- log.info("异步回调 : {}", helloReq); }); // 跨服请求（同步 - 阻塞）-- 路由、请求参数。 ResponseMessage responseMessage = flowContext.invokeModuleMessage(cmdInfo, yourData); var helloReq = responseMessage.getData(HelloReq.class); log.info("同步调用 : {}", helloReq); } }

 ┏━━━━━ Debug. [(DemoAction.java:4).hello] ━━━━━ [cmd:1-0 65536] ━━━━━ [逻辑服 [xxx逻辑服] - id:[76526c134cc88232379167be83e4ddfc]] ┣ userId: 1 ┣ 参数: active : HelloReq(id=101, name=塔姆) ┣ 响应: HelloReq(name=塔姆, I'm here ) ┣ 时间: 1 ms (业务方法总耗时) ┗━━━━━ [ioGameVersion] ━━━━━ [线程:User-8-2] ━━━━━━━ [traceId:956230991452569600] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━