Adding PingCore to Your Own Game

A checklist that takes your own Netcode for GameObjects game from the two Unity packages to players joining it on a PingCore fleet.

This checklist takes your Netcode for GameObjects game onto a PingCore fleet. Each item names the Beacon Rush file that does the same job.

Run Beacon Rush on PingCore first if you can. Every panel page and window section below is one you use there.

Before you start

  • Unity 6 with the Linux Dedicated Server Build Support module.

  • A game on Netcode for GameObjects 2.x with Unity Transport.

  • A PingCore workspace with prepaid credit.

1. Install the packages

Install both packages from git, the SDK first. Keep #v0.1.1 at the end of each URL: it pins the release.

  1. Open Window > Package Manager.

  2. Click +, choose Install package from git URL..., enter this and click Install:

    https://github.com/pingcoregaming/pingcore-unity.git?path=/Packages/io.pingcore.sdk#v0.1.1

  3. Do the same with the Editor plugin:

    https://github.com/pingcoregaming/pingcore-unity.git?path=/Packages/io.pingcore.editor#v0.1.1

    You should see PingCore SDK and PingCore Editor at 0.1.0 under In Project, and Window > PingCore in the menu.

To add both in one edit instead, put the two lines in Packages/manifest.json:

{
  "dependencies": {
    "io.pingcore.sdk": "https://github.com/pingcoregaming/pingcore-unity.git?path=/Packages/io.pingcore.sdk#v0.1.1",
    "io.pingcore.editor": "https://github.com/pingcoregaming/pingcore-unity.git?path=/Packages/io.pingcore.editor#v0.1.1"
  }
}

The SDK's connection approval compiles only when Netcode for GameObjects 2.x is in the project. Beacon Rush uses 2.11.2.

2. The game server pieces

On a fleet, your game server talks to PingCore only through the SDK's FleetSdk. The Game Server SDK has the code for each item.

  1. Read the port from -port <n> on the command line (Assets/Game/Hosting/ServerArgs.cs).

  2. Listen on all addresses: bind Unity Transport to 0.0.0.0 on that port (Assets/Game/Networking/BeaconRushNetwork.cs).

  3. Create the SDK once with FleetSdk.Create(), and subscribe to AllocationReceived and AllocationCleared before you start it. It does nothing when the game runs outside PingCore, so one build runs everywhere.

  4. Start it, then write 0 to the players counter before you listen. From that first write on, the game server stays out of rotation until it calls ready. Write players only, never sessions.

  5. Install PingCoreConnectionApproval with HostedAdmissionEvidence and your own IAdmissionGate, then call StartServer (Assets/Game/Hosting/GameServerRuntime.cs, Assets/Game/Admission/BeaconRushAdmissionGate.cs).

  6. Call ReadyAsync once you listen. A game server that writes a counter and never calls ready never gets a player.

  7. Keep players current as players join and leave (Assets/Game/Hosting/PlayersCounterWriter.cs).

  8. End every session. A match arrives on AllocationReceived. When it is over, call EndSessionAsync with its allocation id (Assets/Game/Hosting/HostedMode.cs). If you turn on the claim that lets Quick play seat a lone player on an idle game server, end that session too, including when the player never arrives.

  9. Stop cleanly. From Application.quitting, call NotifyStopping on the approval and NotifyProcessStopping on the SDK.

Give the approval a protocol version of your own and raise it whenever a change breaks compatibility between client and game server builds. A client with another number is refused with protocol_mismatch.

3. The client pieces

The Client SDK has the code for each item.

  1. Keep one client settings asset. Connect in the PingCore window writes your fleet's public app id into it, and creates Assets/PingCore/Resources/PingCoreClientSettings.asset when the project has none. Beacon Rush reads its asset in Assets/Client/ClientBootstrap.cs.

  2. Create one DiscoveryClient per Discovery app (Assets/Client/Flows/ClientServices.cs). It takes only a public dscp_ id.

  3. Show what is missing. Run InfrastructureCheck.RunAsync at launch and after a failed join, and show the report to the player (Assets/Client/UI/ClientUi.Infrastructure.cs).

  4. Get a seat with QuickJoinAsync, ReserveAsync, or SubmitTicketAsync and WaitAsync (Assets/Client/UI/ClientUi.Matchmaking.cs, ClientUi.Browse.cs).

  5. Join with a join ticket. Build it with JoinTicket.ForReservation or TicketHandle.CreateJoinTicket, encode it into Netcode for GameObjects' connection data, set the address and port from Discovery's answer, and call StartClient (Assets/Client/Flows/GameConnection.cs).

4. A Linux Dedicated Server build profile

The plugin builds only from a build profile of your own.

  1. Open File > Build Profiles.

  2. Pick Linux Server and click Add Build Profile.

  3. Add your game server's scenes to it.

    You should see the profile under Build profile in the PingCore window's Ship section. Until it exists, Ship says "This project has no Linux Dedicated Server build profile. Create one in File > Build Profiles: pick Linux Server (Dedicated Server), then Add Build Profile, and set its scenes."

Screenshot: File > Build Profiles with a Linux Server build profile added and its scene list.

Beacon Rush's profile is Assets/Settings/Build Profiles/Beacon Rush Server.asset, with the one scene Assets/Game/Scenes/Server.unity.

5. Your game in the panel

Set the game up with your own name, player counts and resources. Each piece links to the page that covers it.

  • A CDN source for your builds: a manual source on Linux, under a category. See CDN Sources and Push Tokens.

  • The game and its branch, with the branch's Data Source set to that CDN source. See Game Overview and Game Branches.

  • The startup command, in the template set's Command Line config (below). See Template Sets.

  • A container on the public PingCore Ubuntu base image, with a game-port port on TCP + UDP. Unity Transport uses UDP, so a TCP-only port lets the game server start while every player's connection times out. See Containers.

  • A deployment spec whose Port Mapping maps game-port to your port variable. See Deployment.

The startup command and its port variable

  1. On the Command Line config's Configuration tab, set Process Name to your build's executable with ./ in front, for example ./MyGame.x86_64.

  2. Add a variable GAMEPORT with Type Port, Parent Wrapper %USERVAL%, Default Value 7777, and Hide in Web on, so players never edit it.

  3. Set the template to:

    -batchmode -nographics -port %GAMEPORT%

Screenshot: the Command Line config's Variables tab with the GAMEPORT variable.

The process name is the file your build must contain. Build in the PingCore window names the executable after it, and Push refuses a build that does not hold it. Do not add -logFile to the command line: Unity would then write the game server's log to that file instead of standard output.

The port mapping is what puts each game server's own port into GAMEPORT. Any name works, as long as the variable, the template and the mapping use the same one.

6. A fleet

  1. Open Servers > Fleets, click Add Fleet, name it and pick your game, then click Create. See Fleets Overview.

  2. Leave the Agent Settings card as it is. The players counter takes the deployment's player count, sessions is 1, and Agones-compatible SDK is on. Without that switch, FleetSdk stays inactive.

  3. Decide how players get a token. On the fleet's Discovery app, under Player Access, turn on Anonymous player tokens for a game with no login, or Studio-signed player tokens for a game with its own accounts. Both are off on a new app. See Choosing How Players Connect.

7. The PingCore window

The PingCore Window describes each section.

  1. Create an API key under Settings > API Keys with Key Type Brand.

  2. Open Window > PingCore, paste the key into API key (usr_), click Sign in and pick your fleet.

    You should see "This project ships to" and your fleet's name.

  3. Under Ship, pick your build profile, then click Build and Push.

  4. In the panel, open the fleet and click Deploy New. It runs your newest push with no Release (which build runs).

  5. Press Play in your client scene.

Push before you deploy; see Troubleshooting.

What to copy from Beacon Rush, and what to leave

Copy the patterns into your own code:

  • The boot order in Assets/Game/Hosting/DedicatedServer.cs and HostedMode.cs: start, write players, listen, ready.

  • Session ending in HostedMode.cs, including a claimed session whose player never arrived.

  • The admission gate in Assets/Game/Admission/BeaconRushAdmissionGate.cs.

  • The infrastructure banner in Assets/Client/UI/ClientUi.Infrastructure.cs.

  • Quick play's fallback in Assets/Client/Models/QuickPlayPlan.cs.

  • Readable refusals in Assets/Client/Models/ConnectionText.cs, one sentence per reason.

  • One token profile per copy of the game in Assets/Client/Flows/InteractiveProfile.cs (see The Client SDK).

Leave behind:

  • Beacon Rush's values: its protocol version, its queue rush-p2, its 8 players and its executable name BeaconRushServer.x86_64.

  • Beacon Rush's client settings asset. Your project keeps its own. With more than one in the project, Player hosting names the one the plugin uses and asks you to delete the others.

  • Anything that holds a credential. Your project needs no key or token. See Keeping Secrets Out of Your Build.

  • Debug tools in a release build, such as ServerInstrumentation hooks. The same page shows how the build guard keeps them out.

The Quickstart sample

Quickstart, a sample in the SDK package, plays the Beacon Rush client in your own project against the fleet from Run Beacon Rush on PingCore.

It needs both PingCore packages, the built-in render pipeline, Active Input Handling set to Input Manager (Old) or Both, and Netcode for GameObjects 2.11.2 exactly, or it cannot join Beacon Rush game servers. Use a project with no PingCoreClientSettings asset of its own, never SampleGame.

  1. In Window > Package Manager, select PingCore SDK, open the Samples tab and click Import next to Quickstart.

    You should see Assets/Samples/PingCore SDK/0.1.0/Quickstart/ with Quickstart.unity, the client copy in BeaconRush/ (leave it as it is) and QuickstartClientSettings.asset.

  2. In Window > PingCore, sign in and pick your Beacon Rush fleet. Connect writes its app id into QuickstartClientSettings.asset.

  3. Open Quickstart.unity and press Play.

    You should see Quick play and Play on this PC at the top of the menu.

Quick play puts you on a game server alone. Find match needs a second player (Multiplayer Play Mode). Play on this PC hosts a LAN game, which a second copy joins with Direct connect at 127.0.0.1:7777.