Opencraft 2

Opencraft 2 is an Minecraft-like online game built in Unity. It is intended for supporting experimental research on online game and cloud gaming performance.

Setup

Install Unity 2022 LTS, clone this repository using git clone --recurse-submodules, and open it in Unity. Unity should automatically install required packages. This includes the ParrelSync package, which is useful for testing multiplayer functionality in-editor. The Rider IDE is recommended, it has direct integration with Unity.

The game can be started from Scenes/MainScene. To run select Server & Client in Multiplayer -> Window: PlayMode Tools, then press the play button. Additional configuration can be specified in command line arguments, which can be set in-editor on the Editor Args field of the GameBootstrap -> Editor Cmd Args singleton component.

Builds

Opencraft 2 is built by the Unity editor, using File -> Build Settings with Platform set to Windows, Mac, Linux and Target Platform set to Linux or Windows (Mac is untested). For debugging, analysis, and metric collection the Development Build flag must be set. The builds folder is location under ./Builds/. This folder also contains the Docker files for containerizing Opencraft 2.

Play

Build the game using the instructions in the previous section and save it as Opencraft.exe. To run and play the game, you'll need to run the game with your desired configuration settings. The Builds directory contains three .bat scripts to get you started: Opencraft Server.bat, Opencraft Client.bat, and Opencraft Local.bat. These files require opencraft2.exe to be present, and run the game as a stand-alone server, a client, or a combined server and client, respectively. See the Configuration Deployment section for a more in-depth example of the game's configuration file.

Contributing

See WORKFLOW.md for contribution guidelines and workflow.

Docker

Opencraft 2 can be run as a container. The main game container can be built from the ./Builds/ folder using docker build -t jerriteic/opencraft2:base .. This base image depends on jerriteic/gpu_ubuntu20.04 which allows container application to run graphics applications with NVIDIA GPU hardware acceleration. That container can be built in the same folder using the Dockerfile.ubuntugpu dockerfile.

Docker Requirements

The game container runs a hardware-accelerated 3D graphics application through VirtualGL. This requires extensive configuration to the host platform: 1. Install correct NVIDIA drivers for your platform and GPU. 1. Container is tested on Ubuntu 20.04 on NVIDIA Tesla T4 with proprietary driver version 535. 2. Install Docker + NVIDIA container toolkit 3. On headless hosts, configure display settings according to this guide. 1. Do not reinstall the NVIDIA drivers, skip the step marked Install NVIDIA Driver from CUDA .run shell script.

Running the Container

If the Docker requirements are met, run the container using the following command:

docker run \ --runtime=nvidia \ --name=opencraft_gpu \ --security-opt seccomp=unconfined \ --init \ --net=host \ --privileged=true \ --rm=false \ -e DISPLAY=:0 \ -v /tmp/.X11-unix/X0:/tmp/.X11-unix/X0:ro \ -v /etc/localtime:/etc/localtime:ro \ -v ./logs/:/opencraft2/logs/ \ jerriteic/opencraft2:base \ ./opencraft2.x86_64 -logFile ./logs/opencraft2_log.txt

[!WARNING] Running Docker containers with these flags gives them UNRESTRICTED HOST ROOT ACCESS! Act accordingly.

Parrelsync

ParrelSync allows synchronizing multiple copies of a Unity project. These can be run in parallel to test networked functionality. In ParrelSync -> Preferences, make sure that /UnityRenderStreaming is listed under Optional Folders to Symbolically Link. Then, to create a new ParrelSync clone select Add new clone in ParrelSync -> Clones Manager.

Multiplay

This project supports a single game client acting as a streamed gaming host for many players on guest clients.
Testing Multiplay is easiest using ParrelSync, in the clone's launch arguments in the clone manager add -multiplayRole Guest to run it as a Multiplay guest client.

Signalling Service WebApp

Multiplay functionality requires a signalling service to establish a direct connection between host and guest clients. The signaling service is run as a webapp, the source is available in ./UnityRenderStreaming/WebApp/ and can be build using ./UnityRenderStreaming/pack_webapp.sh which has npm as a dependency. The webapp can be run with a convenience script .Builds/Multiplay_WebApp/start.sh or directly with .\webserver -p <PORT>. The port the webserver listens on must be the same as the signaling port configured using the application command line argument -signalingPort <int>.

Debugging and Analysis

Inspecting existing entities, components, systems, and queries in each existing world can be done using Entities information pages under Window -> Entities. Information not specific to ECS can be found under Window -> Analysis, with the Profiler being particularly important for determining performance impact of various changes. Burst compiled generated code can be viewed in Jobs -> Burst -> Open Inspector, though this is mainly useful for low level optimization work. Multiplayer functionality and behaviour can be visualized using the Window -> Multiplayer -> Window: NetDbg (Browser) tool, which automatically gathers state snapshot metrics from Netcode for Entities connections.

If your Unity or your IDE starts giving strange errors, particularly about packages, it is worth trying Edit > Preferences -> External Tools -> Regenerate project files. As a last resort, Reimport All through the right-click menu in the Project window.

Configuration and Parameters

The Opencraft 2 application can be configured in a variety of ways, with some methods being different in-editor and when run standalone. In editor, the hierarchy of configuration is Deployment Graph>Multiplayer PlayMode Tools >Editor Args.

Command Line Arguments

| Argument | Options | Default | Description | |-----------------------------|------------------------------------------------------------------------------|----------------------------------------------------------|----------------------------------------------------------------------| | -deploymentJson | FilePath | null | Path to a deployment configuration Json file. | | -deploymentID | int | -1 | The ID of this node, used for deployment. | | -remoteConfig | true/false | false | Should this node fetch configuration from a deployment service. | | -deploymentURL | URL | 127.0.0.1 | URL of the deployment service. | | -deploymentPort | int | 7980 | Port of the deployment service. | | -networkTickRate | int | 60 | Rate of network snapshots between servers and clients. | | -simulationTickRate | int | 60 | Rate of simulation steps on both server and clients. | | -maxSimulationStepsPerFrame | int | 4 | Max number of steps per frame when framerate is slow. | | -maxSimulationStepBatchSize | int | 4 | Max number of batched steps when simulation overloaded. | | -maxPredictAheadTimeMS | int | 250 | Duration clients are allowed to predict in advance. | | -disablePrediction | int | false | Disable predicted systems (only affects clients). | | -nographics | true/false | false | Disable the graphics frontend and any related systems. | | -debug | true/false | false | Enable/disable verbose logging. | | -seed | string | "42" | Seed used for terrain generation. | | -playType | ClientAndServer
Client
Server
StreamedClient
SimulatedClient | Client | Mode to start the application in. Can be overriden by remote config. | | -serverUrl | URL | 127.0.0.1 | URL of the game server. | | -serverPort | int | 7979 | Port of the game server. | | -localConfigJson | FilePath | null | Path to a command args Json file. | | -takeScreenshots | true/false | false | Take screenshots at intervals. No effect on Server-only builds. | | -screenshotInterval | int | 5 | Set screenshot interval. | | -screenshotFolder | FilePath | Application.persistentDataPath\screenshots | Set screenshot save location. | | -duration | int | -1 | Exit after a set amount of seconds. | | -startDelay | int | 0 | Seconds to wait before calling the bootstrap. | | -userID | int | 0 | Player's user ID. Acts as a username. | | -signalingUrl | URL | ws://127.0.0.1:7981 | URL of the stream signaling service. | | -multiplayRole | Disabled
Host
CloudHost
Guest | Disabled | Stream gaming role. | | -emulationType | None
Playback
Simulation
Record | None | Player emulation type mode. | | -emulationFile | FilePath | Application.persistentDataPath\recordedInputs.inputtrace | Path to a player emulation trace. | | -numSimulatedPlayers | int | 1 | Number of simulated client worlds when PlayType is SimulatedClient. | | -playerSimulationBehaviour | BoundedRandom
FixedDirection | BoundedRandom | Behaviour that simulated players exhibit. | | -terrainType | string | "default" | Name of TerrainGenerationConfiguration for terrain generation. | | -profiler-enable | true/false | false | Automatically starts the profiler module. | | -profiler-log-file | FilePath | null | Specifies a .raw file to write profiler data to. | | -profiler-maxusedmemory | int | 16000000 | Max memory used by profiler in bytes. Default is 16MB. | | -logStats | true/false | false | Log relevant Profiler statistics to file. | | -statsFile | FilePath | Application.persistentDataPath\stats.csv | What file to log statistics to. |

Deployment Configuration

The deployment service constructs a deployment graph based on a configuration file. The deployment configuration file path is set using the command line argument -deploymentJson <FilePath>. In editor, a json file can be set on the Deployment Config field of the GameBootstrap->Cmd Args Reader singleton component. The Json is expected to follow this formatting (excluding comments):

{ "nodes":[ { "nodeID":0, // ID of this node "nodeIP":"127.0.0.1", // Expected IP of this node, will throw warning if node with nodeID not at this IP. "worldConfigs":[ // List of worlds to deploy on this node { "worldType":"GameServer", // None, Client, Server, SimulatedClient "initializationMode":"Connect", // Create, Start, Connect "multiplayStreamingRoles":"Disabled", // Disabled, Guest, Host, CloudHost "serverNodeID":0, // The ID of the node to connect a client world to "streamingNodeID":-1, // The ID of the node to connect a streamed guest client world to "numSimulatedClients":0, "services":[], // Names of services, handled according to serviceFilterType "serviceFilterType":"Includes", // Includes, Excludes, Only "emulationBehaviours":"None" // None, Playback, Simulation } ] }, { "nodeID":1, "worldConfigs":[ { "worldName": "GameClient", "worldType":"Client", "initializationMode":"Connect", "serverNodeID":0, }, { "worldName": "StreamedClient", "worldType":"Client", "initializationMode":"Create", "multiplayStreamingRoles":"Guest", "streamingNodeID":2, } ] }, { "nodeID":2, "worldConfigs":[ { "worldName": "CloudHostClient", "worldType":"Client", "initializationMode":"Start", "multiplayStreamingRoles":"CloudHost", "serverNodeID":0, "streamingNodeID":2, } ] } ], "experimentActions":[ { "delay": 30, // Trigger these actions after a delay "actions": [ { "nodeID": 1, // ID of node to take actions on "worldNames": ["GameClient", "StreamedClient"], // List of worlds on that node to take actions on "actions": ["Stop", "Connect"] // What action to take on each world, e.g. Stop, Start, Connect }, { "nodeID": 2, "worldNames": ["CloudHostClient"], "actions": ["Connect"] } ] } ] }