Agones Unity SDK development setup instructions + Agones Unity SDK Re…

…ady test (#3887)

Add instructions on how to set up a local development environment for contributing to agones unity sdk

README.md

@@ -53,6 +53,8 @@ Please read the [contributing](CONTRIBUTING.md) guide for directions on submitti
 
 See the [Developing, Testing and Building Agones](build/README.md) documentation for developing, testing and building Agones from source.
 
+For Agones client SDK development refer to [Developing, Testing, and Building Agones Client SDKs](sdks/README.md).
+
 The [Release Process](docs/governance/release_process.md) documentation displays the project's upcoming release calendar and release process.
 
 Agones is in active development - we would love your help in shaping its future!

sdks/README.md

@@ -0,0 +1,14 @@
+# Agones Client SDKs
+Welcome to the Agones Client SDKs! Here you can find libraries to interface with Agones.
+
+## Developing, Testing, and Building
+For detailed instruction on how to develop each client library please refer to respective `README.md` files.
+
+* [Agones C/C++ Client SDK](cpp/README.md)
+* Agones C# Client SDK (todo)
+* Agones Go Client SDK (todo)
+* [Agones NodeJS Client SDK](nodejs/README.md)
+* [Agones Rust Client SDK](rust/README.md)
+* OpenAPI/Swagger Definitions (todo)
+* [Agones Unity Client SDK](unity/README.md)
+* Agones Unreal Client SDK (todo)

sdks/unity/Agones.asmdef

@@ -1,3 +1,13 @@
 {
-    "name": "Agones"
-}
+    "name": "Agones",
+    "rootNamespace": "",
+    "includePlatforms": [],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": false,
+    "precompiledReferences": [],
+    "autoReferenced": true,
+    "defineConstraints": [],
+    "versionDefines": [],
+    "noEngineReferences": false
+}

sdks/unity/AgonesSdk.cs

@@ -30,8 +30,12 @@ namespace Agones
     /// <summary>
     /// Agones SDK for Unity.
     /// </summary>
-    public class AgonesSdk : MonoBehaviour
+    public class AgonesSdk : MonoBehaviour, IRequestSender
     {
+        /// <summary>
+        /// Handles sending HTTP requests to the Agones sidecar.
+        /// </summary>
+        public IRequestSender requestSender;
         /// <summary>
         /// Interval of the server sending a health ping to the Agones sidecar.
         /// </summary>
@@ -67,6 +71,7 @@ private void Awake()
 
         private void Start()
         {
+            requestSender ??= this;
             HealthCheckAsync();
         }
 
@@ -117,7 +122,7 @@ public async Task<bool> Connect()
         /// </returns>
         public async Task<bool> Ready()
         {
-            return await SendRequestAsync("/ready", "{}").ContinueWith(task => task.Result.ok);
+            return await requestSender.SendRequestAsync("/ready", "{}").ContinueWith(task => task.Result.ok);
         }
 
         /// <summary>
@@ -126,7 +131,7 @@ public async Task<bool> Ready()
         /// <returns>The current GameServer configuration</returns>
         public async Task<GameServer> GameServer()
         {
-            var result = await SendRequestAsync("/gameserver", "{}", UnityWebRequest.kHttpVerbGET);
+            var result = await requestSender.SendRequestAsync("/gameserver", "{}", UnityWebRequest.kHttpVerbGET);
             if (!result.ok)
             {
                 return null;
@@ -144,7 +149,7 @@ public async Task<GameServer> GameServer()
         /// </returns>
         public async Task<bool> Shutdown()
         {
-            return await SendRequestAsync("/shutdown", "{}").ContinueWith(task => task.Result.ok);
+            return await requestSender.SendRequestAsync("/shutdown", "{}").ContinueWith(task => task.Result.ok);
         }
 
         /// <summary>
@@ -155,7 +160,7 @@ public async Task<bool> Shutdown()
         /// </returns>
         public async Task<bool> Allocate()
         {
-            return await SendRequestAsync("/allocate", "{}").ContinueWith(task => task.Result.ok);
+            return await requestSender.SendRequestAsync("/allocate", "{}").ContinueWith(task => task.Result.ok);
         }
 
         /// <summary>
@@ -169,7 +174,7 @@ public async Task<bool> Allocate()
         public async Task<bool> SetLabel(string key, string value)
         {
             string json = JsonUtility.ToJson(new KeyValueMessage(key, value));
-            return await SendRequestAsync("/metadata/label", json, UnityWebRequest.kHttpVerbPUT)
+            return await requestSender.SendRequestAsync("/metadata/label", json, UnityWebRequest.kHttpVerbPUT)
                 .ContinueWith(task => task.Result.ok);
         }
 
@@ -184,7 +189,7 @@ public async Task<bool> SetLabel(string key, string value)
         public async Task<bool> SetAnnotation(string key, string value)
         {
             string json = JsonUtility.ToJson(new KeyValueMessage(key, value));
-            return await SendRequestAsync("/metadata/annotation", json, UnityWebRequest.kHttpVerbPUT)
+            return await requestSender.SendRequestAsync("/metadata/annotation", json, UnityWebRequest.kHttpVerbPUT)
                 .ContinueWith(task => task.Result.ok);
         }
 
@@ -209,7 +214,7 @@ public Duration(int seconds)
         public async Task<bool> Reserve(TimeSpan duration)
         {
             string json = JsonUtility.ToJson(new Duration(seconds: duration.Seconds));
-            return await SendRequestAsync("/reserve", json).ContinueWith(task => task.Result.ok);
+            return await requestSender.SendRequestAsync("/reserve", json).ContinueWith(task => task.Result.ok);
         }
 
         /// <summary>
@@ -243,7 +248,7 @@ private async void HealthCheckAsync()
 
                 try
                 {
-                    await SendRequestAsync("/health", "{}");
+                    await requestSender.SendRequestAsync("/health", "{}");
                 }
                 catch (ObjectDisposedException)
                 {
@@ -255,13 +260,13 @@ private async void HealthCheckAsync()
         /// <summary>
         /// Result of a Async HTTP request
         /// </summary>
-        protected struct AsyncResult
+        public struct AsyncResult
         {
             public bool ok;
             public string json;
         }
 
-        protected async Task<AsyncResult> SendRequestAsync(string api, string json,
+        public async Task<AsyncResult> SendRequestAsync(string api, string json,
             string method = UnityWebRequest.kHttpVerbPOST)
         {
             // To prevent that an async method leaks after destroying this gameObject.
@@ -396,4 +401,4 @@ protected override bool ReceiveData(byte[] data, int dataLength)
         }
         #endregion
     }
-}
+}

sdks/unity/IRequestSender.cs

@@ -0,0 +1,25 @@
+// Copyright 2024 Google LLC
+// All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.Threading.Tasks;
+using UnityEngine.Networking;
+
+namespace Agones
+{
+    public interface IRequestSender
+    {
+        Task<AgonesSdk.AsyncResult> SendRequestAsync(string api, string json, string method = UnityWebRequest.kHttpVerbPOST);
+    }
+}

sdks/unity/README.md

@@ -0,0 +1,14 @@
+# Agones Unity Client SDK
+
+## Contributing
+Thank you for your interest in contributing to the Agones Unity client library. Setting up a local workspace to help develop the Agones Game Server Unity Client SDK involves cloning the Agones source code, having a host Unity project, and allowing the Unity project to run the external tests in the Unity test runner.
+
+### A copy of Agones source code
+If you don't already have a local copy of the Agones source code you can either (1) clone the official [googleforgames/agones repository](https://github.com/googleforgames/agones) for quicker access or (2) create a fork then clone your fork. Make note of where you clone the project to for the next setup steps!
+
+### Setting up the Test Agones Unity SDK Project
+In the directory `test/sdk/unity` there is a Test Agones Unity SDK project. This is the project you should add to your Unity Hub, to be able to develop the Agones Unity SDK. You can then open up the project in the Unity Editor application. Once open in the Unity Editor you can run the Agones Unity SDK test suite.
+
+Please be aware that when making contributions to the Agones Unity SDK you will be making modifications to directly to files under `Packages/Agones Unity SDK/` in Unity. The way this works is because the Test Agones Unity SDK project's `Package/manifest.json` uses a relative path to pull in the code directly from `sdks/unity`. For those new to Unity package development this may not be intuitive!
+
+Tests covering contributions is always encouraged. You are now ready to develop the Agones Unity SDK using the Test Agones Unity SDK project!

sdks/unity/Tests/Runtime/PlayMode/AgonesSdkComplianceTests.cs

@@ -0,0 +1,50 @@
+// Copyright 2024 Google LLC
+// All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.Collections;
+using System.Threading.Tasks;
+using Agones;
+using NUnit.Framework;
+using Tests.TestingEnvironment;
+using UnityEngine;
+using UnityEngine.Networking;
+using UnityEngine.TestTools;
+
+namespace Tests.Runtime.Agones
+{
+    public class AgonesSdkComplianceTests
+    {
+        [UnityTest]
+        public IEnumerator AgonesSdk_Ready_ShouldInteractWithReadyApiEndpoint()
+        {
+            var sut = new GameObject().AddComponent<AgonesSdk>();
+            var spy = new SpyRequestSender();
+            sut.requestSender = spy;
+            yield return null;
+            var task = sut.Ready();
+            yield return AwaitTask(task);
+            Assert.IsTrue(spy.LastApi.Contains("/ready"));
+            Assert.IsTrue(spy.LastJson.Equals("{}"));
+            Assert.AreEqual(spy.LastMethod, UnityWebRequest.kHttpVerbPOST);
+        }
+        private IEnumerator AwaitTask(Task task)
+        {
+            while (!task.IsCompleted)
+                yield return null;
+            if (task.Exception != null)
+                throw task.Exception;
+        }
+    }
+}

sdks/unity/Tests/Runtime/PlayMode/Tests.Runtime.Agones.asmdef

@@ -0,0 +1,23 @@
+{
+    "name": "Tests.Runtime.Agones",
+    "rootNamespace": "",
+    "references": [
+        "UnityEngine.TestRunner",
+        "UnityEditor.TestRunner",
+        "Agones",
+        ""
+    ],
+    "includePlatforms": [],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": true,
+    "precompiledReferences": [
+        "nunit.framework.dll"
+    ],
+    "autoReferenced": false,
+    "defineConstraints": [
+        "UNITY_INCLUDE_TESTS"
+    ],
+    "versionDefines": [],
+    "noEngineReferences": false
+}

sdks/unity/Tests/TestingEnvironment/SpyRequestSender.cs

@@ -0,0 +1,40 @@
+// Copyright 2024 Google LLC
+// All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.Threading.Tasks;
+using Agones;
+using UnityEngine.Networking;
+
+namespace Tests.TestingEnvironment
+{
+    public class SpyRequestSender: IRequestSender
+    {
+        public string LastApi { get; private set; }
+        public string LastJson { get; private set; }
+        public string LastMethod { get; private set; }
+        public async Task<AgonesSdk.AsyncResult> SendRequestAsync(string api, string json,
+            string method = UnityWebRequest.kHttpVerbPOST)
+        {
+            LastApi = api;
+            LastJson = json;
+            LastMethod = method;
+            return new AgonesSdk.AsyncResult
+            {
+                ok = true,
+                json = "{}"
+            };
+        }
+    }
+}

sdks/unity/model/StatusAddresses.cs

@@ -1,3 +1,18 @@
+// Copyright 2024 Google LLC
+// All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 using System;
 using System.Collections.Generic;
 using System.Text;