Added a protocol version compatibility check and fixed setInterruptible() outside event handlers.

The Bot APIs (Java, .NET, Python, TypeScript) now verify the server version from the server
handshake against the Bot API version per SemVer (equal majors; equal minors as well for major
version 0) and fail with a clear error message on a mismatch, instead of the bot silently
standing idle in the battle without scoring.

Also fixed a crash (NPE/assertion) in the Java, .NET, and Python Bot APIs when a bot calls
setInterruptible() outside an event handler; the call is now ignored as there is no current
event to mark as interruptible.

The TypeScript Bot API version is stamped into src/version.ts from the /VERSION file by the
existing syncVersion Gradle task, same mechanism as package.json.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: flemming-n-larsen

CHANGELOG.md

@@ -1,3 +1,20 @@
+## [1.0.3] - TBD (not released yet)
+
+### 🐞 Bug Fixes
+
+- Bot API (Java, .NET, Python):
+    - Fixed a crash when a bot calls `setInterruptible()` outside an event handler. The call is
+      now simply ignored, as there is no current event to mark as interruptible.
+      (The TypeScript Bot API was not affected.)
+
+### 🚀 Improvements
+
+- Bot API (Java, .NET, Python, TypeScript):
+    - A bot now fails with a clear error message when connecting to a server with an incompatible
+      version, instead of appearing to join the battle but standing idle without scoring.
+      Per SemVer, the major versions of the Bot API and server must be equal (and the minor
+      versions as well for major version 0).
+
 ## [1.0.2] - 2026-05-18 - Minor bug fix for GUI
 
 ### 🐞 Bug Fixes

bot-api/dotnet/api/src/internal/BaseBotInternals.cs

@@ -1008,6 +1008,8 @@ private void HandleServerHandshake(string json)
     {
         _serverHandshake = JsonConverter.FromJson<S.ServerHandshake>(json);
 
+        VerifyServerVersionCompatibility(_serverHandshake?.Version);
+
         // Validate bot info before sending bot handshake
         ValidateBotInfo();
 
@@ -1020,6 +1022,43 @@ private void HandleServerHandshake(string json)
         _socket.SendTextMessage(text);
     }
 
+    /// <summary>
+    /// Verifies that the server uses a protocol version compatible with this Bot API.
+    /// Per SemVer, versions are compatible when the major versions are equal; for the 0.x range
+    /// anything may change between minor versions, so there the minor versions must be equal as
+    /// well. Without this check, an incompatible server and Bot API silently misinterpret each
+    /// other's messages, and the bot appears to join the battle but stands idle without ever
+    /// scoring.
+    /// </summary>
+    private void VerifyServerVersionCompatibility(string serverVersion)
+    {
+        var apiVersion = typeof(BaseBotInternals).Assembly.GetName().Version;
+        var server = ParseMajorMinorVersion(serverVersion);
+        if (apiVersion == null || server == null)
+        {
+            return; // a version is unavailable; cannot verify
+        }
+        var incompatible = apiVersion.Major != server.Value.Major ||
+                           (apiVersion.Major == 0 && apiVersion.Minor != server.Value.Minor);
+        if (incompatible)
+        {
+            var message = $"Protocol version mismatch: Bot API version {apiVersion} is not compatible with " +
+                          $"server version {serverVersion}. The major versions must be equal " +
+                          "(and the minor versions as well for major version 0).";
+            Console.Error.WriteLine(message);
+            throw new BotException(message);
+        }
+    }
+
+    private static (int Major, int Minor)? ParseMajorMinorVersion(string version)
+    {
+        if (version == null) return null;
+        var match = System.Text.RegularExpressions.Regex.Match(version, @"^\s*(\d+)(?:\.(\d+))?");
+        if (!match.Success) return null;
+        var minor = match.Groups[2].Success ? int.Parse(match.Groups[2].Value) : 0;
+        return (int.Parse(match.Groups[1].Value), minor);
+    }
+
     private void ValidateBotInfo()
     {
         if (string.IsNullOrWhiteSpace(_botInfo.Name))

bot-api/dotnet/api/src/internal/EventQueue.cs

@@ -90,7 +90,12 @@ internal void ClearEvents()
     /// <param name="interruptible">True if the event can be interrupted, false otherwise</param>
     internal void SetCurrentEventInterruptible(bool interruptible)
     {
-        EventInterruption.SetInterruptible(_currentTopEvent.GetType(), interruptible);
+        var currentEvent = _currentTopEvent;
+        if (currentEvent == null)
+        {
+            return; // not inside an event handler; there is no current event to mark as interruptible
+        }
+        EventInterruption.SetInterruptible(currentEvent.GetType(), interruptible);
     }
 
     private bool IsCurrentEventInterruptible => EventInterruption.IsInterruptible(_currentTopEvent.GetType());

bot-api/java/src/main/java/dev/robocode/tankroyale/botapi/internal/EventQueue.java

@@ -81,7 +81,11 @@ void clearEvents() {
      * @param interruptible true if the event can be interrupted, false otherwise
      */
     void setCurrentEventInterruptible(boolean interruptible) {
-        EventInterruption.setInterruptible(currentTopEvent.getClass(), interruptible);
+        var currentEvent = currentTopEvent;
+        if (currentEvent == null) {
+            return; // not inside an event handler; there is no current event to mark as interruptible
+        }
+        EventInterruption.setInterruptible(currentEvent.getClass(), interruptible);
     }
 
     private boolean isCurrentEventInterruptible() {

bot-api/java/src/main/java/dev/robocode/tankroyale/botapi/internal/WebSocketHandler.java

@@ -241,6 +241,8 @@ private void handleServerHandshake(JsonObject jsonMsg) {
         var serverHandshake = JsonConverter.fromJson(jsonMsg, ServerHandshake.class);
         baseBotInternals.setServerHandshake(serverHandshake);
 
+        verifyServerVersionCompatibility(serverHandshake.getVersion());
+
         // Validate bot info before sending bot handshake
         validateBotInfo();
 
@@ -252,6 +254,44 @@ private void handleServerHandshake(JsonObject jsonMsg) {
         socket.sendText(msg, true);
     }
 
+    /**
+     * Verifies that the server uses a protocol version compatible with this Bot API.
+     * Per SemVer, versions are compatible when the major versions are equal; for the 0.x range
+     * anything may change between minor versions, so there the minor versions must be equal as
+     * well. Without this check, an incompatible server and Bot API silently misinterpret each
+     * other's messages, and the bot appears to join the battle but stands idle without ever
+     * scoring.
+     */
+    private void verifyServerVersionCompatibility(String serverVersion) {
+        var apiVersion = WebSocketHandler.class.getPackage().getImplementationVersion();
+        var api = parseMajorMinorVersion(apiVersion);
+        var server = parseMajorMinorVersion(serverVersion);
+        if (api == null || server == null) {
+            return; // a version is unavailable (e.g. running from class files); cannot verify
+        }
+        boolean incompatible = api[0] != server[0] || (api[0] == 0 && api[1] != server[1]);
+        if (incompatible) {
+            var message = String.format(
+                    "Protocol version mismatch: Bot API version %s is not compatible with server version %s. " +
+                            "The major versions must be equal (and the minor versions as well for major version 0).",
+                    apiVersion, serverVersion);
+            System.err.println(message);
+            throw new BotException(message);
+        }
+    }
+
+    private static int[] parseMajorMinorVersion(String version) {
+        if (version == null) {
+            return null;
+        }
+        var matcher = java.util.regex.Pattern.compile("^\\s*(\\d+)(?:\\.(\\d+))?").matcher(version);
+        if (!matcher.find()) {
+            return null;
+        }
+        var minor = matcher.group(2);
+        return new int[]{Integer.parseInt(matcher.group(1)), minor == null ? 0 : Integer.parseInt(minor)};
+    }
+
     private void validateBotInfo() {
         // If the bot is booted, botInfo might be partially filled by the booter
         // but the bot code must ensure name, version, and authors are present.

bot-api/python/src/robocode_tank_royale/bot_api/internal/event_queue.py

@@ -59,8 +59,10 @@ def set_current_event_interruptible(self, interruptible: bool) -> None:
         Args:
             interruptible: True if the current event can be interrupted; false otherwise.
         """
-        assert self.current_top_event is not None, "No current event to set interruptible state for."
-        EventInterruption.set_interruptible(type(self.current_top_event), interruptible)
+        current_event = self.current_top_event
+        if current_event is None:
+            return  # not inside an event handler; there is no current event to mark as interruptible
+        EventInterruption.set_interruptible(type(current_event), interruptible)
 
     def is_current_event_interruptible(self) -> bool:
         """Checks if the current event can be interrupted by new events with higher priority.

bot-api/python/src/robocode_tank_royale/bot_api/internal/websocket_handler.py

@@ -268,6 +268,8 @@ async def handle_server_handshake(self, json_msg: Dict[Any, Any]) -> None:
         server_handshake: ServerHandshake = from_json(json_msg)  # type: ignore
         self.base_bot_internals.server_handshake = server_handshake
 
+        self._verify_server_version_compatibility(server_handshake.version)
+
         # Validate bot info before sending bot handshake
         self._validate_bot_info()
 
@@ -320,6 +322,48 @@ def _transfer_std_out_to_bot_intent(self) -> None:
             else:
                 self.base_bot_internals.bot_intent.std_err = None
 
+    def _verify_server_version_compatibility(self, server_version: Optional[str]) -> None:
+        """Verifies that the server uses a protocol version compatible with this Bot API.
+
+        Per SemVer, versions are compatible when the major versions are equal; for the 0.x
+        range anything may change between minor versions, so there the minor versions must be
+        equal as well. Without this check, an incompatible server and Bot API silently
+        misinterpret each other's messages, and the bot appears to join the battle but stands
+        idle without ever scoring.
+        """
+        try:
+            from importlib.metadata import version as _package_version
+
+            api_version: Optional[str] = _package_version("robocode-tank-royale")
+        except Exception:
+            return  # version unavailable; cannot verify
+        api = self._parse_major_minor(api_version)
+        server = self._parse_major_minor(server_version)
+        if api is None or server is None:
+            return
+        incompatible = api[0] != server[0] or (api[0] == 0 and api[1] != server[1])
+        if incompatible:
+            message = (
+                f"Protocol version mismatch: Bot API version {api_version} is not compatible "
+                f"with server version {server_version}. The major versions must be equal "
+                f"(and the minor versions as well for major version 0)."
+            )
+            import sys
+
+            print(message, file=sys.stderr)
+            raise BotException(message)
+
+    @staticmethod
+    def _parse_major_minor(version: Optional[str]) -> Optional[tuple[int, int]]:
+        if not version:
+            return None
+        import re
+
+        match = re.match(r"\s*(\d+)(?:\.(\d+))?", version)
+        if not match:
+            return None
+        return int(match.group(1)), int(match.group(2) or 0)
+
     def _validate_bot_info(self) -> None:
         """Validate bot info before sending handshake to server."""
         if self._is_blank(self.bot_info.name):

bot-api/typescript/build.gradle.kts

@@ -24,11 +24,13 @@ tasks {
 
     val syncVersion by registering {
         group = "build"
-        description = "Synchronises package.json version with gradle.properties"
+        description = "Synchronises package.json and src/version.ts version with gradle.properties"
         val pkgFile = file("package.json")
+        val versionTsFile = file("src/version.ts")
         val newVersion = project.version.toString()
         inputs.property("version", newVersion)
         outputs.file(pkgFile)
+        outputs.file(versionTsFile)
         doLast {
             val content = pkgFile.readText()
             val updated = content.replace(
@@ -37,6 +39,14 @@ tasks {
             )
             pkgFile.writeText(updated)
             logger.lifecycle("Updated package.json version to $newVersion")
+
+            val versionTsContent = versionTsFile.readText()
+            val updatedVersionTs = versionTsContent.replace(
+                Regex("""API_VERSION = "[^"]+""""),
+                """API_VERSION = "$newVersion""""
+            )
+            versionTsFile.writeText(updatedVersionTs)
+            logger.lifecycle("Updated src/version.ts version to $newVersion")
         }
     }
 

bot-api/typescript/src/WebSocketHandler.ts

@@ -1,3 +1,4 @@
+import { API_VERSION } from "./version.js";
 import { BotInfo } from "./BotInfo.js";
 import { BotHandshakeFactory } from "./BotHandshakeFactory.js";
 import { EnvVars } from "./EnvVars.js";
@@ -154,6 +155,8 @@ export class WebSocketHandler {
     this.serverHandshake = msg;
     this.callbacks.onServerHandshake?.(msg);
 
+    this.verifyServerVersionCompatibility(msg.version);
+
     // Validate required bot info before sending the bot handshake
     this.validateBotInfo();
 
@@ -204,6 +207,44 @@ export class WebSocketHandler {
   // ---------------------------------------------------------------------------
 
   /** Validates that required bot info fields are set before sending the bot handshake. */
+  /**
+   * Verifies that the server uses a protocol version compatible with this Bot API.
+   * Per SemVer, versions are compatible when the major versions are equal; for the 0.x range
+   * anything may change between minor versions, so there the minor versions must be equal as
+   * well. Without this check, an incompatible server and Bot API silently misinterpret each
+   * other's messages, and the bot appears to join the battle but stands idle without ever
+   * scoring.
+   */
+  private verifyServerVersionCompatibility(serverVersion?: string): void {
+    const api = this.parseMajorMinorVersion(API_VERSION);
+    const server = this.parseMajorMinorVersion(serverVersion);
+    if (api == null || server == null) {
+      return; // a version is unavailable; cannot verify
+    }
+    const incompatible = api[0] !== server[0] || (api[0] === 0 && api[1] !== server[1]);
+    if (incompatible) {
+      const message =
+        `Protocol version mismatch: Bot API version ${API_VERSION} is not compatible with ` +
+        `server version ${serverVersion}. The major versions must be equal ` +
+        "(and the minor versions as well for major version 0).";
+      console.error(message);
+      throw new BotException(message);
+    }
+  }
+
+  private parseMajorMinorVersion(version?: string): [number, number] | null {
+    if (version == null) {
+      return null;
+    }
+    const match = /^\s*(\d+)(?:\.(\d+))?/.exec(version);
+    const major = match?.[1];
+    if (major == null) {
+      return null;
+    }
+    const minor = match?.[2];
+    return [parseInt(major, 10), minor == null ? 0 : parseInt(minor, 10)];
+  }
+
   private validateBotInfo(): void {
     if (this.isBlank(this.botInfo.name)) {
       this.throwMissingPropertyException("name");

bot-api/typescript/src/version.ts

@@ -0,0 +1,7 @@
+/**
+ * The version of this Bot API.
+ *
+ * Do not edit manually — the version is controlled by the /VERSION file in the repository root
+ * and stamped into this file by the Gradle `syncVersion` task (same mechanism as package.json).
+ */
+export const API_VERSION = "1.0.2";