Skip to content

atlarge-research/Opencraft-2

Repository files navigation

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"]
			}
		]
	}
]
}

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published