\u00bb The basic architecture<\/h2>\n
To get started\u00a0let’s review the basic architecture diagram\u00a0from the previous article:<\/p>\n
![\"\"](\"http:\/\/smartfoxserver.com\/blog\/wp-content\/uploads\/2018\/05\/sfs2x-unity-combo.png\")
<\/p>\n
In this solution SmartFoxServer 2X acts as the main connection point for all clients, managing the session’s life cycle, providing the lobby and match making services etc., and orchestrating the creation and destruction of Unity servers.<\/p>\n
Unity\u00a0engines are attached to game Rooms to handle their game logic and removed when the match is over and the relative room is destroyed. In some cases, like for virtual worlds and MMOs, Unity engines\u00a0can handle a larger portions of the world, based on the characteristics and size of the game map. In that case we will map a larger portion of the virtual world to as single Room.<\/p>\n
In order to start a new game we create a Room and join all the players inside. Then\u00a0 when clients are ready to start, we’ll spawn a new headless Unity server and tell each player to connect to it. This means that\u00a0clients will\u00a0use a maximum of 2 simultaneous connections, one toward SFS2X and the other toward the Unity server. With this approach\u00a0everyone will be able to receive events from SFS2X (lobby updates, chat\/buddy messages etc.) while the game is running.<\/p>\n
\u00bb\u00a0Headless Unity<\/h2>\n
Running Unity as a server is a bit uncommon compared to the normal use cases but it’s actually a very powerful solution for multiplayer games. In particular, the ability to create a server that runs on the same engine as the client is very convenient as we can share assets (e.g. game maps) and work with the same language and\u00a0environment\u00a0used for both sides.<\/p>\n
In our use case we’ll be running “headless” Unity servers which means that Unity instances will not create a new\u00a0desktop window and thus perform no rendering at all, as it is not needed on the server side.<\/p>\n
To do this we just need to build our project as an executable for the OS used on the server side, and add a few parameters\u00a0when launching it from\u00a0command line.<\/p>\n
How do I build my client\/server Unity game exactly?<\/h3>\n
In this article we’re not going to develop a specific game.\u00a0It would be beyond the scope of the tutorial and you can find innumerable videos and resources to learn how to create multiplayer games in Unity.<\/p>\n
What we’re going to do, however, is we will describe how the Unity client and server are built and the server part is integrated with SmartFoxServer 2X. For the sake of example we can imagine to be building a multiplayer air-hockey game: we want it to be a 2D top down view that supports the browser via WebGL.<\/p>\n
In order to write the client and server\u00a0portions of the game we can use two different approaches:<\/p>\n
1) Client and server logic in the same project<\/strong><\/p>\n We can code both the client and server portions in the same Unity project and then activate\u00a0<\/em>one\u00a0side via an external parameter. This is done by passing a command line argument to the Unity executable\u00a0that is\u00a0launched from the SFS2X side.<\/p>\n PROS<\/strong>:<\/p>\n CONS<\/strong>:<\/p>\n 2) Separate projects for client and server sides<\/strong><\/p>\n This is probably the best approach for medium and large sized games as you can keep concerns and resources separated.<\/p>\n PROS<\/strong>:<\/p>\n CONS<\/strong>:<\/p>\n Now that we have a clearer picture of how to work with the client and server portions in Unity, it’s time to see how we can put it all together from the SmartFoxServer side.<\/p>\n In our example game we want to use a one-Unity-per-Room approach so that every game is managed by a\u00a0separate Unity engine. To do this we can attach a custom Extension to each SFS2X game Room that will take care of running the Unity server.<\/p>\n Under our AirHockeyGame\/<\/em> extension folder we deploy\u00a0the Extension file (.jar file) and we create a Unity\/\u00a0<\/em>subdirectory were we can deploy the server side Unity engine. In our case we’re working with macOS<\/strong> where both the executable and\u00a0relative assets are bundled in a single file.<\/p>\n Under Windows<\/strong> and Linux<\/strong> the build\u00a0is comprised of two elements: the executable and\u00a0a folder\u00a0containing all the necessary assets. Make sure to copy both under the Unity\/<\/em>\u00a0directory.<\/p>\n Running multiple Unity on the same machine<\/strong><\/p>\n For the sake of simplicity we will run the game servers on the same machine where SFS2X runs.\u00a0This, in turn, requires to allocate a different TCP (or UDP) port number for each instance\u00a0as it’s not possible for two apps to listen on the same port.<\/p>\n To do this we’ll use a simple PortManager<\/strong> class that allocates and deallocates a port value\u00a0so we\u00a0can pass it to the Unity engine itself.<\/p>\n The code\u00a0should be\u00a0straightforward:\u00a0we keeps track of a series of numeric “slots” starting at 7000 (our initial port number) that can be taken\u00a0and returned when the we’ve finished with the job.\u00a0Notice the\u00a0use of the\u00a0synchronized<\/em>\u00a0mutator\u00a0to make sure the class works with concurrent requests. We instantiate this class in the main Zone Extension<\/strong> of the game so that all Rooms can work with the same PortManager<\/strong>.<\/p>\n Launching server side processes<\/strong><\/p>\n Next we can move onto the core of the solution which is launching the Unity engines from our Room Extension:<\/strong><\/p>\n at the top of the class we define the path to our Unity executable relative to the SFS2X\/<\/em> top folder. Under Windows<\/strong> and Linux<\/strong> you just have to point to the path of the executable but under macOS<\/strong> things are a little bit different, due to the bundling system we mentioned before.<\/p>\n To recap:<\/p>\n Next we define an internal private class where the “magic” happens. The UnityRunner<\/strong> class implements Runnable<\/em>\u00a0and it\u00a0is\u00a0invoked by a separate thread that waits for the Process to complete its\u00a0job and do some clean up before shutting down.<\/p>\n In the UnityRunner<\/strong> constructor we obtain a port value for the Unity instance and store it in the Room’s variables. Normally we would need to call getApi().setRoomVariables()<\/strong> method to update all clients, but we’re still in the init()<\/strong> method of our Extension where the server is not even accepting connections. In this situation it is fine to bypass the API and add variables directly (in any other situation, you would use the API instead).<\/p>\n The variable is going to be readable by clients when they join the Room, and it will be used to connect to the game server.<\/p>\n To run the Unity executable we use the convenient ProcessBuilder<\/a> class from the JDK which allows to run system commands with any number of parameters. Let’s see them in detail:<\/p>\n If we need to pass more parameters to the Unity server we can keep adding more custom commands preceded by a double dash (–) or any other similar convention. Just keep in mind that a single dash (-) is already used by the internal Unity commands and should be avoided.<\/p>\n Reading the command line parameters from Unity\u00a0can be\u00a0done via the System.Environment<\/strong> object:<\/p>\n Back to our Extension\u00a0code we\u00a0launch the process by calling the start()<\/strong> method on the ProcessBuilder<\/strong> instance and finally we call waitFor()<\/strong> to keep the new thread in pause until the process (i.e. Unity engine)\u00a0is\u00a0done.<\/p>\n The try\/catch<\/em> block takes care of potential runtime issues, such as a missing executable, in case we made some mistake with the deployment, and in the finally<\/em> block takes care of releasing the port number before returning.<\/p>\n Life cycle of a Unity engine<\/strong><\/p>\n In this example we use the init()<\/strong> method of our Extension to bootstrap the Unity server instance so that it is ready as soon as the Room is created. An alternative to this approach would be to create the Room without starting the Unity server and wait for all the players to join before we launch it.<\/p>\n Both ways are perfectly valid and it all comes down to how our game works. For instance, a game that doesn’t need to wait for all players will use the first method and viceversa.<\/p>\n Similarly there can be different strategies to stop the Unity engine:<\/p>\n Now that we have explored the basics of creating and managing Unity instances from a SmartFoxServer Extension, you may be wondering how resource intensive this could be, especially when we want to run hundreds of games simultaneously.<\/p>\n Unfortunately there is\u00a0no clear-cut answer. The amount of resources (CPU and RAM especially) is heavily dependent on the complexity and type of game: in particular the number of players per room, the size and complexity of the game world, the physics, the amount of updates per second, they all contribute to the overall usage of resources.<\/p>\n Additionally there are the technical specifications of the machine running this system, which can also be highly variable.<\/p>\n As usual the best way to estimate the\u00a0performance of a system is to benchmark it. In our case we can\u00a0run one or more\u00a0Unity servers and monitor the usage of CPU, RAM and network. Then we can extrapolate how many Unity engines\u00a0can be run on our dedicated machine.<\/p>\n Supposing\u00a0the tests\u00a0give us a\u00a0limit of approximately\u00a050 engines per server (=\u00a050 game rooms), how can we scale up our system to deal with a higher demands?<\/p>\n As you may expect the answer is to run multiple servers to host more Unity\u00a0engines. Both approaches can be cloud-based and since most cloud providers offer Java API to automate operations in their environment, it can be convenient to integrate such API in the server side Extension to be able to\u00a0manage\u00a0on-demand servers.<\/p>\n This means that we can directly manage instances in our Extension code, creating new servers via the cloud API and removing them when they are no longer needed. This approach may sound complicated but in actuality most cloud\u00a0vendors\u00a0provide high level API that can add or remove a new server with a couple of lines of code.<\/p>\n We have explored the fundamental concepts to build an hybrid game server that takes advantage of both SmartFoxServer and Unity.<\/p>\n![\"\"](\"http:\/\/smartfoxserver.com\/blog\/wp-content\/uploads\/2018\/05\/unity-one-project.png\")
<\/p>\n\n
\n
![\"\"](\"http:\/\/smartfoxserver.com\/blog\/wp-content\/uploads\/2018\/05\/unity-two-projects.png\")
<\/p>\n\n
\n
\u00bb\u00a0Managing Unity engines<\/h2>\n
![\"\"](\"http:\/\/smartfoxserver.com\/blog\/wp-content\/uploads\/2018\/05\/roomsunity.png\")
To be able to run Unity from SmartFoxServer we will need to deploy the Unity executable to our Extension folder, for example like this:<\/p>\n![\"\"](\"http:\/\/smartfoxserver.com\/blog\/wp-content\/uploads\/2018\/05\/sfs2x-unity-deploy.png\")
<\/p>\n\r\npackage sfs2x.extension.unity;\r\n\r\npublic class PortManager\r\n{\r\n\tprivate int portBaseValue = 7000;\r\n\tprivate int maxPorts = 100;\r\n\t\r\n\tprivate boolean [] ports = new boolean [maxPorts];\r\n\t\r\n\tpublic PortManager()\r\n\t{\r\n\t\tinitPorts();\r\n\t}\r\n\t\r\n\t\r\n\tprotected synchronized void initPorts()\r\n\t{\r\n\t\tfor (int i = 0; i < maxPorts; i++)\r\n\t\t{\r\n\t\t\tports[i] = false;\r\n\t\t}\r\n\t}\r\n\t\r\n\tpublic synchronized int getAvailablePort()\r\n\t{\r\n\t\tfor (int i = 0; i < maxPorts; i++)\r\n\t\t{\r\n\t\t\tif (ports[i] == false)\r\n\t\t\t{\r\n\t\t\t\tports[i] = true;\r\n\t\t\t\treturn portBaseValue + i;\r\n\t\t\t}\r\n\t\t}\r\n\t\t\r\n\t\tthrow new RuntimeException("All ports are currently taken. Cannot start a new server-side Unity instance");\r\n\t}\r\n\r\n\tpublic synchronized void releasePort(int value)\r\n\t{\r\n\t\tports[value - portBaseValue] = false;\r\n\t}\r\n}\r\n<\/pre>\n\r\npackage sfs2x.extension.unity;\r\n\r\nimport com.smartfoxserver.v2.extensions.SFSExtension;\r\n\r\npublic class AirHockeyZoneExtension extends SFSExtension\r\n{\r\n\tprivate PortManager pManager;\r\n\t\r\n\t@Override\r\n\tpublic void init()\r\n\t{\r\n\t\tpManager = new PortManager();\r\n\t}\r\n\t\r\n\tpublic PortManager getPortManager()\r\n\t{\r\n\t\treturn pManager;\r\n\t}\r\n}\r\n<\/pre>\n\r\npackage sfs2x.extension.unity;\r\n\r\nimport java.io.File;\r\nimport java.io.IOException;\r\n\r\nimport com.smartfoxserver.v2.extensions.SFSExtension;\r\nimport com.smartfoxserver.v2.entities.User;\r\nimport com.smartfoxserver.v2.entities.data.ISFSObject;\r\n\r\npublic class AirHockeyRoomExtension extends SFSExtension\r\n{\r\n\tString unityExe = "OSXBuild";\r\n\tString workingDir = new File("extensions\/AirHockey\/Unity\/OSXBuild.app\/Contents\/MacOS\/").getAbsolutePath();\r\n\tThread launcherThread;\r\n\t\r\n\tprivate class UnityRunner implements Runnable\r\n\t{\r\n\t\tprivate int tcpPort;\r\n\t\t\r\n\t\tpublic UnityRunner(int port)\r\n\t\t{\r\n\t\t\tthis.tcpPort = port;\r\n\t\t\t\r\n\t\t\ttry\r\n\t\t\t{\r\n\t\t\t\tgetParentRoom().setVariable(new SFSRoomVariable("port", port));\r\n\t\t\t}\r\n\t\t\tcatch(Exception ex)\r\n\t\t\t{\r\n\t\t\t\ttrace(ex);\r\n\t\t\t}\r\n\t\t}\r\n\t\t\r\n\t\t@Override\r\n\t\tpublic void run()\r\n\t\t{\r\n\t\t\ttry\r\n\t\t\t{\r\n\t\t\t\tString cmd = workingDir + "\/" + unityExe;\r\n\r\n\t\t\t\tProcessBuilder processBuilder = new ProcessBuilder(cmd, "-batchmode", "-logFile", workingDir + "\/unity.log", "--serverPort", String.valueOf(tcpPort)); \r\n\t\t\t\tprocessBuilder.directory(new File(workingDir));\r\n\t\t\t\t\r\n\t\t\t\tProcess proc = processBuilder.start();\r\n\t\t\t\tint exit = proc.waitFor();\r\n\t\t\t\ttrace("Unity process terminated with code: " + exit);\r\n\t\t\t}\r\n\t\t\tcatch(IOException ex)\r\n\t\t\t{\r\n\t\t\t\ttrace("Error launching Unity executable: " + ex);\r\n\t\t\t\tex.printStackTrace();\r\n\t\t\t}\r\n\t\t\tcatch (Exception ex) \r\n\t\t\t{\r\n\t\t\t\ttrace("Unexpected exceptions: " + ex);\r\n\t\t\t}\r\n\t\t\tfinally\r\n\t\t\t{\r\n\t\t\t\t((AirHockeyZoneExtension) getParentZone().getExtension()).getPortManager().releasePort(tcpPort);\r\n\t\t\t}\r\n\t\t}\r\n\t}\r\n\r\n\t@Override\r\n\tpublic void init()\r\n\t{\r\n\t\tAirHockeyZoneExtension ext = (AirHockeyZoneExtension) getParentZone().getExtension();\r\n\t\tint tcpPort = ext.getPortManager().getAvailablePort();\r\n\t\t\r\n\t\tlauncherThread = new Thread(new UnityRunner(tcpPort), "unity-worker:" + tcpPort);\r\n\t\tlauncherThread.start();\r\n\r\n\t\ttrace("UnityLauncher started");\r\n\t}\r\n\r\n\t@Override\r\n\tpublic void destroy()\r\n\t{\r\n\t\tsuper.destroy();\r\n\t\t\r\n\t\tif (launcherThread.isAlive())\r\n\t\t\tlauncherThread.interrupt();\r\n\t\t\r\n\t\ttrace("UnityLauncher stopped");\r\n\t}\r\n}\r\n<\/pre>\n\n
\n
\r\n\tprivate int readServerPortFromCommandLine()\r\n\t{\r\n\t\tstring[] args = System.Environment.GetCommandLineArgs();\r\n\r\n\t\tfor (int i = 0; i < args.Length; i++) \r\n\t\t{\r\n\t\t\tif (args[i] =="--serverPort" && args.Length - 1) \r\n\t\t\t{\r\n\t\t\t\treturn int.Parse(args[i + 1]);\r\n\t\t\t}\r\n\t\t}\r\n\r\n\t\treturn -1;\r\n\t}\r\n<\/pre>\n
\n
\nTo simplify the deployment of this example we would recommend copying the extension’s jar in the extensions\/__lib__\/<\/strong> folder. This enables all classes to be loaded in the same classloader and make cross-extension communication easier.\n<\/div>\n\n
\u00bb\u00a0Performance and scalability<\/h2>\n
\nWe can explore\u00a0a couple of ways to do this:<\/p>\n\n
\u00bb Next steps<\/h2>\n