Agones – Examples

Docs: Custom Controller for Agones Game Servers

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisite

To get started, ensure the following prerequisites are met:

You have a running Kubernetes cluster.
Agones is installed on your cluster. Refer Agones guide.
(Optional) Review Custom Controller code to see the details of this example.

Create a Custom Controller

Let’s create a custom controller on your cluster using the following command:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/custom-controller/deployment.yaml

When you run this command, it quickly sets up your controller by doing four things:

Sets up the appropriate RBAC permissions for the custom controller
Launching two controllers for reliability, with leader election setup between them.

Verify the Controller

To ensure the custom controller is operational, execute the following command. You should see two instances of the controller actively running with the prefix custom-controller:

kubectl get pods -n agones-system

You should see a successful output similar to this:

NAME                                 READY   STATUS    RESTARTS   AGE
custom-controller-74c798cfd8-ld6wk   1/1     Running   0          84s
custom-controller-74c798cfd8-whpp2   1/1     Running   0          84s

Create a Fleet

Let’s create a Fleet using the following command:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/simple-game-server/fleet.yaml

You should see a successful output similar to this :

fleet.agones.dev/simple-game-server created

This has created a Fleet record inside Kubernetes, which in turn creates two ready GameServers that are available to be allocated for a game session.

kubectl get fleet

It should look something like this:

NAME                 SCHEDULING   DESIRED   CURRENT   ALLOCATED   READY     AGE
simple-game-server   Packed       2         3         0           2         9m

You can also see the GameServers that have been created by the Fleet by running kubectl get gameservers, the GameServer will be prefixed by simple-game-server.

NAME                             STATE     ADDRESS            PORT   NODE      AGE
simple-game-server-llg4x-rx6rc   Ready     192.168.122.205    7752   minikube   9m
simple-game-server-llg4x-v6g2r   Ready     192.168.122.205    7623   minikube   9m

For the full details of the YAML file head to the Fleet Specification Guide

Note

The game servers deployed from a Fleet resource will be deployed in the same namespace. The above example omits specifying a namespace, which implies both the Fleet and the associated GameServer resources will be deployed to the default namespace.

Monitor the log events for the custom controller pod

To monitor the logs of the custom controller during the creation, modification, and deletion of game servers, use the following command:

kubectl logs -f deployments/custom-controller -n agones-system

Note: If this controller fails for any reason, we’ve also implemented leader election such that the backup controller will automatically assume the leadership role, ensuring uninterrupted logging of event details.

Cleaning Up

When you’re done with the Agones fleet and the custom controller, it’s a good practice to clean up the resources to prevent unnecessary resource consumption. Follow these steps to remove them:

Remove the Fleet

To delete the Agones fleet you deployed, execute the following command. This will remove the fleet along with all the game server instances it manages:

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/simple-game-server/fleet.yaml

Remove the Custom Controller

To remove the custom controller from your cluster, execute the following command. This will delete the deployment that you created earlier.

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/custom-controller/deployment.yaml

Docs: Build and Run a Simple Game Server that Connects to an Inference Server

Mon, 01 Jan 0001 00:00:00 +0000

Setting up the GenAI Inference Server

You will need a separate GenAI inference server. This example uses the Google for Games GenAI as its inference server. This particular inference server has the request structure for the /chat endpoint:

type GenAIRequest struct {
	Context         string  `json:"context,omitempty"`
	Prompt          string  `json:"prompt"`
}

(Optional) Modify the GenAIRequest Structure

If you need a different request structure for your GenAI endpoint, you will need to clone or fork the Agones repository and modify the above GenAIRequest struct in main.go. Update REPOSITORY in the agones/examples/simple-genai-server/Makefile to your own container registry and run make build && make push from within the agones/examples/simple-genai-server path. Then modify the gameserver_*.yaml to pull the image from your container registry. If you are making a series of changes you may also want to add imagePullPolicy: Always to the container image in gameserver_*.yaml.

Setting up Agones

To set up the Game Servers on a different cluster than the GenAI inference server follow the instructions for creating a cluster.

If you set up a separate cluster for your game servers install Agones. on that cluster, otherwise install Agones into your GenAI inference server cluster.

Setting up the Game Server

To manually interact with GenAiEndpoint via netcat, change the GEN_AI_ENDPOINT value in the gameserver_manualchat.yaml file to your inference server’s endpoint. Optionally, include the GEN_AI_CONTEXT in the same file that will include the context with each chat (post request) that you make to the GenAI endpoint.

To make two clients “chat” to each other, change the GEN_AI_ENDPOINT and SIM_ENDPOINT values in the gameserver_autochat.yaml file to your inference server’s address. You could also create a basic http server that receives requests in the structure noted in the above section, and returns a predetermined set of responses for the chat. When sending requests, GEN_AI_CONTEXT is sent to the GEN_AI_ENDPOINT and SIM_CONTEXT is sent to the SIM_ENDPOINT as part of the GenAIRequest structure. The default values for GEN_AI_CONTEXT and SIM_CONTEXT are empty strings. The conversation starts with a PROMPT that is sent to the GenAI endpoint, which is also an empty string by default. NUM_CHATS determines how many times messages are sent back and forth, with a default value of 1. It’s important to note that the chat between two clients is a rolling conversation, meaning that after completing a conversation of length set by NUM_CHATS, a new conversation starts. This cycle continues until the game server is deleted using the kubectl delete command.

If you want to set up the chat with the npc-chat-api from the Google for Games GenAI, update the gameserver_npcchat.yaml file. Choose between GEN_AI_ENDPOINT or SIM_ENDPOINT and set it to http://genai-api.genai.svc/genai/npc_chat for the NPC service. Mark either GEN_AI_NPC or SIM_NPC as “true” to indicate it’s connected to the NPC service. The NPCRequest to the NPC endpoint only sends the message (prompt), so any additional context outside of the prompt is ignored. FROM_ID is the entity sending messages to NPC, and TO_ID is the entity receiving the message (the NPC ID). A new conversation begins either when it reaches the length NUM_CHATS or when it reaches the STOP_PHRASE, whichever happens first.

type NPCRequest struct {
	Msg    string `json:"message,omitempty"`
	FromId int `json:"from_id,omitempty"`
	ToId   int `json:"to_id,omitempty"`
}

Running the Game Server

Once you have modified the gameserver_*.yaml to use your endpoint(s), apply to your Agones cluster with kubectl apply -f gameserver_autochat.yaml, kubectl apply -f gameserver_manualchat.yaml, or kubectl apply -f gameserver_npcchat.

Note that if your inference server is in a different cluster you’ll want to make sure you’re using the kubectl context that points to your Agones cluster and not the inference cluster.

If you set up the gameserver_autochat.yaml or gameserver_npcchat the chat will be in the game server logs:

kubectl logs -f gen-ai-server-auto -c simple-genai-game-server

In autochat mode, the game server will stay running forever until the game server is deleted. While running, we keep --ConcurrentPlayers slots of players running - each simulated player will initiate a chat and then go until they send --StopPhrase or until --NumChats, whichever comes first, after which a new player will fill the slot.

If you set up the gameserver_manualchat.yaml you can manually send requests to the GenAI endpoint. Retreive the IP address and port:

kubectl get gs gen-ai-server-manual -o jsonpath='{.status.address}:{.status.ports[0].port}'

You can now send requests to the GenAI endpoint:

Note

If you do not have netcat installed (i.e. you get a response of nc: command not found), you can install netcat by running sudo apt install netcat.

nc {IP} {PORT}
Enter your prompt for the GenAI server in the same terminal, and the response will appear here too.

After you’re done you will need to manually delete the game server kubectl delete gs gen-ai-server-manual.

Docs: Deploying and Running SuperTuxKart Server Using Agones

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisite

To get started, ensure the following prerequisites are met:

You have a running Kubernetes cluster.
Agones is installed on your cluster. Refer to the Agones guide for the instructions.
The SuperTuxKart client downloaded for gameplay. Download it from SuperTuxKart
(Optional) Review SuperTuxKart code to see the details of this example.

Create a Fleet

Let’s create a Fleet using the following command:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/supertuxkart/fleet.yaml

You should see a successful output similar to this :

fleet.agones.dev/supertuxkart created

This has created a Fleet record inside Kubernetes, which in turn creates two ready GameServers that are available to be allocated for a game session.

kubectl get fleet

It should look something like this:

NAME           SCHEDULING   DESIRED   CURRENT   ALLOCATED   READY   AGE
supertuxkart   Packed       2         2         0           2       55s

You can also see the GameServers that have been created by the Fleet by running kubectl get gameservers, the GameServer will be prefixed by supertuxkart.

NAME                             STATE       ADDRESS        PORT   NODE                                  AGE
supertuxkart-xfw2g-bwwkb         Ready       34.82.158.69   7421   gke-agon-default-pool-f18c8e90-1f9k   103s
supertuxkart-xfw2g-skdnf         Ready       34.82.158.69   7585   gke-agon-default-pool-f18c8e90-1f9k   103s

For the full details of the YAML file head to the Fleet Specification Guide

Connect to the Game Server

After allocating a GameServer from the fleet and obtaining its status and IP, you’re ready to connect and play. Here’s how to use the server IP and port to join the game with the SuperTuxKart client:

Launch SuperTuxKart: Start the SuperTuxKart client you downloaded earlier by running the executable for your operating system (documentation)

Navigate to Online Play: From the main menu, select the “Online” option and then select “Enter server address” from the available options.

Enter Server Details: In the subsequent screen, you will be prompted to input the IP address and port number in order to join the game. Please enter the IP address and port number obtained from the kubectl get gameservers command.

Join the Game: After entering the server details, proceed to join the server. You should now be connected to your Agones-managed SuperTuxKart game server and ready to play.

Launch the Game with AI Bots: To start the server with AI players, use the <executable-script> --connect-now=<IP:port> --network-ai=<number of AIs> command, substituting <IP:port> with your server’s IP address and port number and <number of AIs> with the desired number of bots. For more information, refer to the SuperTuxKart documentation.

Cleaning Up

After playing SuperTuxKart, it’s a good practice to clean up the resources to prevent unnecessary resource consumption. To delete the Agones fleet you deployed, execute the following command. This will remove the fleet along with all the game server instances it manages:

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/supertuxkart/fleet.yaml

Docs: Deploying and Running Xonotic Server Using Agones

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisite

To get started, ensure the following prerequisites are met:

You have a running Kubernetes cluster.
Agones is installed on your cluster. Refer to the Agones guide for the instructions.
The Xonotic client downloaded for gameplay. Download it from Xonotic
(Optional) Review Xonotic code to see the details of this example.

Create a Fleet

Let’s create a Fleet using the following command:

kubectl apply -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/xonotic/fleet.yaml

You should see a successful output similar to this :

fleet.agones.dev/xonotic created

This has created a Fleet record inside Kubernetes, which in turn creates two ready GameServers that are available to be allocated for a game session.

kubectl get fleet

It should look something like this:

NAME           SCHEDULING   DESIRED   CURRENT   ALLOCATED   READY   AGE
xonotic        Packed       2         2         0           2       55s

You can also see the GameServers that have been created by the Fleet by running kubectl get gameservers, the GameServer will be prefixed by xonotic.

NAME                       STATE   ADDRESS          PORT   NODE                                        AGE
xonotic-7lk8x-hgfrg        Ready   34.71.168.92     7206   gk3-genai-quickstart-pool-3-ba2a705f-wpmc   103s
xonotic-7lk8x-rwhst        Ready   34.71.168.92     7330   gk3-genai-quickstart-pool-3-ba2a705f-wpmc   103s

For the full details of the YAML file head to the Fleet Specification Guide

Connect to the Game Server

After allocating a GameServer from the fleet and obtaining its status and IP, you’re ready to connect and play. Here’s how to use the server IP and port to join the game with the Xonotic server:

Launch Xonotic: Start the Xonotic client you previously downloaded by running the executable for your operating system (documentation).

Multiplayer Mode: From the main menu, select “Multiplayer”.

Server Connection: Choose to join a server manually and input the IP and port number you obtained from the kubectl get gameservers command.

Join the Game: After entering the server details, proceed to join the server. You should now be connected to your Agones-managed Xonotic game server and ready to play.

Cleaning Up

After you’re done playing, it’s a good idea to clean up. To remove the Agones fleet you deployed, execute the following command. This will remove the fleet along with all the game server instances it manages:

kubectl delete -f https://raw.githubusercontent.com/googleforgames/agones/release-1.39.0/examples/xonotic/fleet.yaml