Squashed 'framework/core/' changes from de20e8b4..4c42c858

4c42c858 Merge pull request #59 from congcoi123/develop
5f353735 refactor: minor changes
0f3c86a0 Merge pull request #60 from congcoi123/feature/SP-X_Enhance_Java_Docs
00a041fd docs: minor change
18f4fd23 docs: fix java-docs and minor issues
851c074d docs(SP-X): enhance java-docs
3ac971c9 fix: minor issue
656dd95b fix: unable to start server
2ddc385e feat: add channels
0dd17fd2 fix: revert changes on allocating byte buffers
2569a576 fix: datagram channel cache should be used to write messages
2b48a310 feat: it no longer supports multiple UDP ports, instead the cache size will be used

git-subtree-dir: framework/core
git-subtree-split: 4c42c8587933022a29dca846a0218838b99b8991

Author: tengamesinc

CHANGELOG.md

@@ -72,3 +72,9 @@
 ## 0.6.2 2025-05-11 Feature release
 - Fixed several issues related to concurrency
 - Allowed dynamically declaring behaviors for packets processing with annotations
+
+## 0.6.3 2025-06-01 Feature release
+- Fixed several bugs
+- Stopped supporting multiple UDP ports, instead it is using datagram channel cache to enhance performance
+- New feature and events added: Channel which allows broadcasting to subscribed players
+

LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2016-2023 kong <congcoi123@gmail.com>
+Copyright (c) 2016-2025 kong <congcoi123@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -45,6 +45,9 @@ EventAccessDatagramChannelRequestValidation
 EventAccessDatagramChannelRequestValidationResult
 EventAccessKcpChannelRequestValidation
 EventAccessKcpChannelRequestValidationResult
+EventBroadcastToChannel
+EventChannelCreated
+EventChannelWillBeRemoved
 EventConnectionEstablishedResult
 EventDisconnectConnection
 EventDisconnectPlayer
@@ -56,6 +59,8 @@ EventPlayerJoinedRoomResult
 EventPlayerLoggedinResult
 EventPlayerReconnectedResult
 EventPlayerReconnectRequestHandle
+EventPlayerSubscribedChannel
+EventPlayerUnsubscribedChannel
 EventReceivedMessageFromPlayer
 EventRoomCreatedResult
 EventRoomWillBeRemoved

VERSION

@@ -1 +1 @@
-20250511.0.6.2
+20250601.0.6.3

configuration.example.xml

@@ -21,8 +21,7 @@
 			<Port name="tcp" type="tcp">8032</Port>
 			<Port name="websocket" type="websocket">8033</Port>
 			<Port name="kcp" type="kcp">20003</Port>
-			<!-- It supports multiple ports, separated by commas -->
-			<Port name="udp" type="udp">20004,20005,20006</Port>
+			<Port name="udp" type="udp" cacheSize="10">20004</Port>
 			<Port name="http" type="http">9999</Port>
 		</Sockets>
 		<Properties>

pom.xml

@@ -5,7 +5,7 @@
 
     <groupId>io.github.congcoi123</groupId>
     <artifactId>tenio-core</artifactId>
-    <version>0.6.2</version>
+    <version>0.6.3</version>
     <packaging>jar</packaging>
 
     <name>${project.groupId}:${project.artifactId}</name>

src/main/java/com/tenio/core/ApplicationLauncher.java

@@ -1,7 +1,7 @@
 /*
 The MIT License
 
-Copyright (c) 2016-2023 kong <congcoi123@gmail.com>
+Copyright (c) 2016-2025 kong <congcoi123@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -29,14 +29,39 @@ of this software and associated documentation files (the "Software"), to deal
 import com.tenio.core.configuration.constant.CoreConstant;
 import com.tenio.core.configuration.constant.Trademark;
 import com.tenio.core.monitoring.system.SystemInfo;
+import com.tenio.core.server.Server;
 import com.tenio.core.server.ServerImpl;
 import java.util.Arrays;
 import java.util.Objects;
 import org.apache.logging.log4j.core.tools.picocli.CommandLine;
 import org.apache.logging.log4j.util.Strings;
 
 /**
- * The application will start from here.
+ * The main entry point for launching the game server application.
+ * This class handles the initialization and startup of the server, including
+ * configuration loading, system monitoring setup, and server instance creation.
+ *
+ * <p>Key features:
+ * <ul>
+ *   <li>Command-line argument parsing</li>
+ *   <li>Configuration file loading</li>
+ *   <li>System monitoring initialization</li>
+ *   <li>Server instance creation and startup</li>
+ *   <li>Logging system configuration</li>
+ * </ul>
+ *
+ * <p>Command-line options:
+ * <ul>
+ *   <li>The first parameter: Path to the configuration file (default: configuration.xml)</li>
+ * </ul>
+ *
+ * <p>Note: This class is designed to be the single entry point for the application
+ * and should not be instantiated multiple times.
+ *
+ * @see Bootstrapper
+ * @see Server
+ * @see SystemInfo
+ * @since 0.3.0
  */
 public final class ApplicationLauncher extends SystemLogger {
 

src/main/java/com/tenio/core/api/ServerApi.java

@@ -1,7 +1,7 @@
 /*
 The MIT License
 
-Copyright (c) 2016-2023 kong <congcoi123@gmail.com>
+Copyright (c) 2016-2025 kong <congcoi123@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -26,6 +26,7 @@ of this software and associated documentation files (the "Software"), to deal
 
 import com.tenio.common.data.DataCollection;
 import com.tenio.core.configuration.constant.CoreConstant;
+import com.tenio.core.entity.Channel;
 import com.tenio.core.entity.Player;
 import com.tenio.core.entity.Room;
 import com.tenio.core.entity.define.mode.ConnectionDisconnectMode;
@@ -37,11 +38,13 @@ of this software and associated documentation files (the "Software"), to deal
 import com.tenio.core.entity.manager.RoomManager;
 import com.tenio.core.entity.setting.InitialRoomSetting;
 import com.tenio.core.exception.AddedDuplicatedRoomException;
+import com.tenio.core.exception.CreatedDuplicatedChannelException;
 import com.tenio.core.handler.event.EventPlayerLoginResult;
 import com.tenio.core.network.entity.protocol.Response;
 import com.tenio.core.network.entity.session.Session;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
 /**
@@ -351,6 +354,81 @@ default void switchSpectatorToParticipant(Player player, Room room, int targetSl
    */
   void removeRoom(Room room, RoomRemoveMode removeRoomMode);
 
+  /**
+   * Creates a new channel.
+   *
+   * @param id          a unique value and should not be duplicated
+   * @param description the description of channel
+   * @throws CreatedDuplicatedChannelException when a channel which has its id to be already
+   *                                           registered is added onto server.
+   * @since 0.6.3
+   */
+  void createChannel(String id, String description) throws CreatedDuplicatedChannelException;
+
+  /**
+   * Creates a new channel.
+   *
+   * @param id a unique value and should not be duplicated
+   * @throws CreatedDuplicatedChannelException when a channel which has its id to be already
+   *                                           registered is added onto server.
+   * @since 0.6.3
+   */
+  default void createChannel(String id) throws CreatedDuplicatedChannelException {
+    createChannel(id, null);
+  }
+
+  /**
+   * Removes a channel from management.
+   *
+   * @param id the channel's id
+   * @since 0.6.3
+   */
+  void removeChannel(String id);
+
+  /**
+   * A player subscribes to a channel.
+   *
+   * @param channel an instance of {@link Channel}
+   * @param player an instance of {@link Player}
+   * @since 0.6.3
+   */
+  void subscribeToChannel(Channel channel, Player player);
+
+  /**
+   * A player unsubscribes from a channel.
+   *
+   * @param channel an instance of {@link Channel}
+   * @param player an instance of {@link Player}
+   * @since 0.6.3
+   */
+  void unsubscribeFromChannel(Channel channel, Player player);
+
+  /**
+   * A player unsubscribes from all channels.
+   *
+   * @param player an instance of {@link Player}
+   * @since 0.6.3
+   */
+  void unsubscribeFromAllChannels(Player player);
+
+  /**
+   * Broadcasts a message to a channel.
+   *
+   * @param channel an instance of {@link Channel}
+   * @param message an instance of {@link DataCollection}
+   * @since 0.6.3
+   */
+  void broadcastToChannel(Channel channel, DataCollection message);
+
+  /**
+   * Retrieves all channels that a player is subscribing to.
+   *
+   * @param player an instance of {@link Player}
+   * @return a map of subscribing {@link Channel}
+   * @since 0.6.3
+   */
+  Map<String, Channel> getSubscribedChannelsForPlayer(Player player);
+
   /**
    * Sends a message from a player to all recipients in a room.
    *
@@ -378,18 +456,20 @@ default void sendPrivateMessage(Player sender, Player recipient, DataCollection
   /**
    * Retrieves the current available UDP port.
    *
-   * @return an {@code integer} value of UDP port
+   * @return an {@code integer} value of UDP port if available, otherwise returns
+   * {@link CoreConstant#NULL_PORT_VALUE}
    * @since 0.3.0
    */
-  int getCurrentAvailableUdpPort();
+  int getUdpPort();
 
   /**
    * Retrieves the current available KCP port.
    *
-   * @return an {@code integer} value of KCP port if available, otherwise returns {@link CoreConstant#NULL_PORT_VALUE}
+   * @return an {@code integer} value of KCP port if available, otherwise returns
+   * {@link CoreConstant#NULL_PORT_VALUE}
    * @since 0.6.0
    */
-  int getCurrentAvailableKcpPort();
+  int getKcpPort();
 
   /**
    * Retrieves the current available KCP Convey Id.

src/main/java/com/tenio/core/api/implement/ServerApiImpl.java

@@ -1,7 +1,7 @@
 /*
 The MIT License
 
-Copyright (c) 2016-2023 kong <congcoi123@gmail.com>
+Copyright (c) 2016-2025 kong <congcoi123@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -24,12 +24,11 @@ of this software and associated documentation files (the "Software"), to deal
 
 package com.tenio.core.api.implement;
 
-import com.tenio.common.configuration.Configuration;
+import com.tenio.common.data.DataCollection;
 import com.tenio.common.logger.SystemLogger;
 import com.tenio.core.api.ServerApi;
-import com.tenio.core.configuration.constant.CoreConstant;
-import com.tenio.core.configuration.define.CoreConfigurationType;
 import com.tenio.core.configuration.define.ServerEvent;
+import com.tenio.core.entity.Channel;
 import com.tenio.core.entity.Player;
 import com.tenio.core.entity.Room;
 import com.tenio.core.entity.define.mode.ConnectionDisconnectMode;
@@ -40,6 +39,7 @@ of this software and associated documentation files (the "Software"), to deal
 import com.tenio.core.entity.define.result.PlayerLeftRoomResult;
 import com.tenio.core.entity.define.result.PlayerLoggedInResult;
 import com.tenio.core.entity.define.result.RoomCreatedResult;
+import com.tenio.core.entity.manager.ChannelManager;
 import com.tenio.core.entity.manager.PlayerManager;
 import com.tenio.core.entity.manager.RoomManager;
 import com.tenio.core.entity.setting.InitialRoomSetting;
@@ -48,12 +48,12 @@ of this software and associated documentation files (the "Software"), to deal
 import com.tenio.core.exception.CreatedRoomException;
 import com.tenio.core.exception.PlayerJoinedRoomException;
 import com.tenio.core.exception.RemovedNonExistentPlayerException;
-import com.tenio.core.network.configuration.SocketConfiguration;
 import com.tenio.core.network.entity.session.Session;
 import com.tenio.core.server.Server;
 import java.io.IOException;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Map;
 import java.util.Objects;
 import java.util.Optional;
 
@@ -137,11 +137,18 @@ public void logout(Player player, ConnectionDisconnectMode connectionDisconnectM
 
     try {
       if (player.containsSession() && player.getSession().isPresent()) {
+        // check process on method InternalProcessorServiceImpl#processSessionWillBeClosed
         player.getSession().get().close(connectionDisconnectMode, playerDisconnectMode);
       } else {
+        // unsubscribe it from all channels
+        unsubscribeFromAllChannels(player);
+        // player should leave room (if applicable) first
+        if (player.isInRoom()) {
+          leaveRoom(player, PlayerLeaveRoomMode.LOG_OUT);
+        }
         getEventManager().emit(ServerEvent.DISCONNECT_PLAYER, player, playerDisconnectMode);
         String removedPlayer = player.getIdentity();
-        getPlayerManager().removePlayerByIdentity(player.getIdentity());
+        getPlayerManager().removePlayerByIdentity(removedPlayer);
         debug("DISCONNECTED PLAYER", "Player ", removedPlayer, " was removed");
         player.clean();
       }
@@ -318,17 +325,48 @@ public void removeRoom(Room room, RoomRemoveMode removeRoomMode) {
   }
 
   @Override
-  public int getCurrentAvailableUdpPort() {
-    return server.getDatagramChannelManager().getCurrentAvailableUdpPort();
+  public void createChannel(String id, String description) {
+    getChannelManager().createChannel(id, description);
   }
 
   @Override
-  public int getCurrentAvailableKcpPort() {
-    Configuration configuration = server.getConfiguration();
-    if (Objects.isNull(configuration.get(CoreConfigurationType.NETWORK_KCP))) {
-      return CoreConstant.NULL_PORT_VALUE;
-    }
-    return Integer.parseInt(((SocketConfiguration) (configuration.get(CoreConfigurationType.NETWORK_KCP))).port());
+  public void removeChannel(String id) {
+    getChannelManager().removeChannel(id);
+  }
+
+  @Override
+  public void subscribeToChannel(Channel channel, Player player) {
+    getChannelManager().subscribe(channel, player);
+  }
+
+  @Override
+  public void unsubscribeFromChannel(Channel channel, Player player) {
+    getChannelManager().unsubscribe(channel, player);
+  }
+
+  @Override
+  public void unsubscribeFromAllChannels(Player player) {
+    getChannelManager().unsubscribe(player);
+  }
+
+  @Override
+  public void broadcastToChannel(Channel channel, DataCollection message) {
+    getChannelManager().broadcast(channel, message);
+  }
+
+  @Override
+  public Map<String, Channel> getSubscribedChannelsForPlayer(Player player) {
+    return getChannelManager().getSubscribedChannelsForPlayer(player);
+  }
+
+  @Override
+  public int getUdpPort() {
+    return server.getDatagramChannelManager().getUdpPort();
+  }
+
+  @Override
+  public int getKcpPort() {
+    return server.getDatagramChannelManager().getKcpPort();
   }
 
   @Override
@@ -357,4 +395,8 @@ private PlayerManager getPlayerManager() {
   private RoomManager getRoomManager() {
     return server.getRoomManager();
   }
+
+  private ChannelManager getChannelManager() {
+    return server.getChannelManager();
+  }
 }

src/main/java/com/tenio/core/bootstrap/BootstrapHandler.java

@@ -1,7 +1,7 @@
 /*
 The MIT License
 
-Copyright (c) 2016-2023 kong <congcoi123@gmail.com>
+Copyright (c) 2016-2025 kong <congcoi123@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal