Skip to main content

Beginner's tutorial

The Hathora Cloud Unity Plugin is a comprehensive package that allows you to build and deploy game servers directly through the Unity Editor. The plugin enables you to:

  • Create your dedicated game server build
  • Upload and deploy the build to Hathora Cloud
  • Spin up server instances in 12+ regions
  • Bundles Hathora Cloud C# SDK for programmatic integration
tip

Learn more about the benefits of Hathora Cloud.

Prerequisites​

Unity Version​

Our plugin works best with Unity version 2021.3.28f1 and higher. It will still work fine with earlier version of 2021.3.x, you will just need to downgrade the packaged Universal RP package to fit your specific Unity version.

Required Unity Modules​

You'll need to make sure you have the following modules installed:

  1. Linux Build Support (Mono)
  2. Linux Dedicated Server Build Support

You can install them via Unity Hub (Installs > Click gear icon > Add modules). Note: you'll need to restart Unity after installing new modules.

Required Unity modules step 1

Required Unity modules step 2

Download and install plugin​

1. Download the Hathora Unity plugin.​

Use CasePlugin DownloadDescription
New Unity projectPlugin with demosIncludes demo scenes and the associated packages from Unity Package Manager. Note: when prompted with a warning select "Install/Upgrade" to get relevant packages
Existing Unity projectPlugin onlyIdeal for installing Unity plugin for an existing game. Does not include demo scenes so you can use this plugin without any package dependencies.

2. In your Unity project, add Hathora_Cloud_Unity_plugin_latest.unitypackage as a Custom Package​

Assets
└── Import Package
    └── Custom Package...

4. Using the "Hathora" top menu item, create a new HathoraServerConfig file​

Create an account on Hathora Cloud​

1. Create or login to your Hathora Cloud account using the Editor Inspector on your newly created Hathora Server Config file. Once you click Log in to Hathora Cloud you'll be prompted for a device confirmation, select Confirm to finish logging in.​

2. Create an application in Hathora Cloud by selecting Create new application.​

3. A new browser tab will open up and request an application name.​

4. Once you've created the application, click on Refresh List in the Unity Editor so it will fetch the updated application list.​

Build and configure the game server​

1. Configure Unity Build Settings​

Open File > Build Settings... and make sure that you have one of the demo scenes added. If you don't have any scenes added, you just need to open the scene and then you'll be able to click "Add Open Scenes".

After setting your scene you may close out of the build settings. Note: you do not need to change your platform for server builds, continue reading for more details on generating server builds.

2. Expand Server Build Settings.​

3. Generate a Linux server build for the demo scenes by selecting Generate Server Build. This will also generate a Dockerfile for the build.​

If you want to view or make updates to the generated Dockerfile, you can access it by clicking "Open Dockerfile".

4. View logs for the server build.​

Note: If you run into errors with UnityPlayer.so does not exist, double check that you have installed the required modules.

Deploy the server on Hathora Cloud​

1. Expand Hathora Deployment Configuration.​

2. Click Deploy Application to upload and deploy a new version of your application on Hathora Cloud. For the purposes of the demo, you can use the default configurations.​

3. View logs for the deployment.​

Note: this step may take a few minutes as your server build is uploaded.

Client integration demos​

Included with our Unity plugin are demos for FishNet and Mirror networking solutions. Our demos are meant to help showcase key concepts and integration steps, while also serving as boilerplate and starting points for your own integrations. If you are using Unity NGO, you can check out our similar Unity NGO demo.

For each demo we have 2 paths:

  1. Hello world: manually connecting to a game server (simplest)
  1. Hathora SDK: programmatically integrate your game client using the Hathora Cloud C# SDK (Player auth & Lobby Service)
tip

If you're looking for a sample game to start from, check out our sample Unity games.

If you are looking for a similar demo for Unity NGO, check out our Unity NGO Minimal Sample.

note

Our FishNet demo is the default scene that gets deployed, if you want to deploy and try our Mirror demo, you'll need to update the Build Settings to reorder HathoraDemoScene-Mirror as the first/top scene.

Hello World Demo guide​

This demo skips the Hathora SDK and simply uses Hathora as a Unity net code dedicated game server host. Upload any Unity net code solution to Hathora Cloud.

1. Expand Create Room, specify the region you want a server instance in and click Create Room.​

note

When you select Create Room, Hathora Cloud dynamically provisions a game server instance.

2. Copy the host:ip connection information.​

3. Open the demo scene and inspect the NetworkManager and paste the host and port connection info into the corresponding fields.​

Assets/Hathora/Demos/1-FishNetDemo/HathoraDemoScene-Fishnet
└── Network Manager

4. Run the desired demo scene and click on Hello World.​

Assets/Hathora/Demos/1-FishNetDemo
└── HathoraDemoScene-Fishnet

5. Click Client to connect to the Hathora room specified by the host:port you added.​

Note: you can also enter the connection info via the input instead of configuring in the NetworkManager

note

We will automatically terminate a process if there are no active connections for 5 minutes (i.e. the process is in an idle state for 5 minutes).

6. You are now connected to the server. If other clients were connected, you'd see them too.​

You can press [R] to send a ping RPC to the server, and then you should see corresponding logs in Hathora Console process logs.

Hathora SDK Demo guide​

This demo is more programmatic, it includes example use of the Hathora Cloud C# SDK. Clients can authenticate, create/join rooms, and programatically get connection info using Hathora's lightweight Lobby Service.

1. Click Copy AppId.​

2. Navigate to Hathora Client Config to paste the AppId.​

Assets
└── Hathora
    └── HathoraClientConfig

3. Run the HathoraDemoScene - FishNet and click on Hathora SDKs. Click on Client Auth to start.​

4. Click Create Lobby to create a room (or Get Lobby Info if you have a roomId).​

note

Lobbies are a client-side method for requesting rooms.

5. You now have a roomId. You can either list public lobbies or get the server info to connect.​

6. You may now either list public lobbies or get the connection info to connect to a lobby (host:port).​

Version compatibility​

Our plugin works best with Unity version 2021.3.28f1 or higher.

It does still work for earlier versions of 2021.3.x, but you will need to fix the Universal Render Pipeline (URP) package version. Note that URP is only used for our included demos, so if you simply ignore/delete the Demo folder, you can ignore the URP dependency.

See the following steps to fix URP version:

  1. Window > Package Manager > Remove Universal RP
  2. Find package via Unity Registry. Install Universal RP (should be version compatible with your Unity version)
  3. Edit > Project Settings > Graphics > set Scriptable Render Pipeline Settings to StarterAssetsURP

Troubleshooting​

⚠ Can’t connect to server or connection failed, common causes​

  • Deployment configuration mismatch
    • Port (in Hathora deployment config) doesn’t match port your server is listening on
    • Transport type (in Hathora deployment config) doesn’t match the transport protocol your networking code expects
      • Note: ws:// uses TCP, wss:// uses TLS
  • Server idle timeout
    • By default, server processes in Hathora Cloud will spin down after 5 consecutive minutes of inactivity (no active connections)
      • It is in our roadmap to support customization of the idle timeout
  • Client configuration
    • Incorrect Hathora appId - If you are using multiple applications on Hathora, it’s possible that your appId is incorrect (this will usually lead to a 404 response from Hathora APIs
    • Using hostname instead of IP address - some networking solutions (Mirror, Unity NGO) only support IP addresses rather than hostnames for connections. E.g. convert 1.proxy.hathora.dev to one of a valid IP address dig 1.proxy.hathora.dev in your terminal is an easy way to get IP addresses for a hostname.
  • Server isn't actually waiting for connections
    • Your server build needs to be able to recognize when it is running in server mode, often this is achieved with a command line argument handler that allows you to pass an argument like -mode server to your server.
    • You should have your server log out when it starts in server mode, for our FishNet demo you should see the following in your process logs: Local server is started for Tugboat.
    • 2 things to double check (prior to deploying server):
      • Your NetworkManager is set to "Tugboat" (as FishNet transport), Client Address set to localhost, and Port is set to 7777
        • For Mirror, NetworkManager should be set to "KCP transport", Network Address set to 127.0.0.1, and Port is set to 7777
      • Your Build Settings has the correct scene at the top (for FishNet demo, should be Assets/Hathora/Demos/1-FishNetDemo/HathoraDemoScene-FishNet.unity)

⚠ When a user connects, I see a temporary "Active Connection" in Hathora (for ~1 second), but then disconnects (client fails to connect)​

This likely means that your server deployment isn't properly running in server mode. It could be that the connection transport is incorrectly configured. If you're testing our demos, it could be that your server is expecting FishNet connection, but you're trying to connect from a Mirror client.

See the above section for common solutions.

⚠ I tried copy+pasting a host name (not a pure IP address) into the NetworkManager's Address property, but I'm instantly getting a timeout​

  • Within the Hathora Console details page, ensure the logs parity with what you normally see in Unity to ensure !errors.

  • In the NetworkManager's Tugboat component (from NetworkManager GameObject), ensure the Client Address and Server Port match your room's server:port.

  • Unity NGO and Mirror Networking require raw IP addresses (opposed to host names, like proxy.hathora.dev or localhost). If you only have a host name, try converting to an IP address via dig <hostname> in a bash or zsh terminal. If you use Unity NGO or Mirror, you'll want to programmatically do this, eventually.

⚠ How do I get WebGL to work?​

Check out our guide for setting up WebGL.

⚠ When I tried implementing this tutorial logic into my own game, both Player GameObjects move at the same time from 1 PC - how come?​

For your player controller's Update(), you may want to add if (!IsOwner) return so only the owned network object can be controlled.

⚠ When using both the "Server" + "Client" buttons (Player1 'Host Mode'), both players spawn; Player1 can move their NetworkPlayer and see the movement on Player2 when they pressed the Client button (Player2). Why can I only move Player1 and not Player2?​

Player2 needs **permission_ from the Server to move: If following another guide, you may be using the Network Transform script. While this is server-authoritative and more-secure, the demo makes use of Client Network Transform to give power to the Client for demo purposes and to keep code minimal.

⚠ Why does the other player look like his model isn't using animations; just "gliding" while moving?​

Be sure to add a Network Transform component to your Player! To save bandwidth, uncheck the syncing options you don't need (such as Scale).

⚠ With Unity NGO: When I override OnNetworkSpawn() and check ownership of the Player (as a client), I'm the owner. The next time I call test ping, I'm not! What's going on?**​

This seems to be a Unity NGO bug: The server appears to take ownership a few moments after the client spawns. You can async/await for !IsOwner. This is likely because clients can join before a server kicks in.

Join our developer community!
Discord