Getting Started with the Match Template

Create a New Project

warning

Make sure you've installed the Prerequisites before continuing.

1. Once you've installed the prebuilt UE for Redwood, launch the editor using the included Start UnrealEditor.bat script.

2. From there, select the REDWOOD category and the Match-based (Redwood) template project. You can customize your project path/name and parameters before selecting Create:

   

3. This will create a new project copying the contents of the template, making changes given the project name you provided. This may take several minutes.

4. Once the project is created and shaders are compiled, you will see the default Lyra level selected:

   

5. Open the Content Browser and open the level /Content/Redwood/Frontend/L_RW_LyraFrontEnd:

   

6. Open the Project Settings in the Edit menu. Scroll down until you see Redwood under Plugins. Change the Director Uri setting to ws://director.localhost:3001:

Configure Hosts File

Redwood uses fictional hostnames to ensure routing happens properly. You need to modify your machine's hosts file to make it so these will route to your development machine. This will require local admin privileges; you may need to request your IT sysadmin to help you. Here's a useful guide on how locate and edit your hosts file with admin privileges. Add these lines to your file and save it:

127.0.0.1 director.localhost
127.0.0.1 director-backend.localhost
127.0.0.1 realm-default.localhost
127.0.0.1 realm-default-backend.localhost

Initial Configuration

As with any new Redwood project, you should create a new config environment; we recommend a lowercase, snake (your_name) or kebab (your-name) case name. We'll be using the name template-match for this guide for the base environment and build on it as we introduce more environments.

1. Create a folder in the RedwoodBackend/config/node folder with your config environment name (i.e. RedwoodBackend/config/node/template-match).

   note

   If you want to put this folder somewhere else (i.e. to be co-located with your UE project YourProjectFolder/Config/Backend/template-match), you need to create/modify the RedwoodBackend/config-settings.json file and add the extraDirs array field:

   {
     // ... any existing fields
     "extraDirs": [
       "C:\\path\\to\\YourProject\\Config\\Backend"
     ]
   }

2. Create a _config.json file in your config environment (i.e. RedwoodBackend/config/node/template-match/_config.json) to specify the parent config environment:

   Evaluation Version

   {
     "parentNames": ["evaluation"]
   }

   Full Version

   {
     "parentNames": ["default"]
   }

3. Create a game.yaml file (i.e. RedwoodBackend/config/node/template-match/game.yaml) to define the different game modes. The below is properly configured and synced with the Content/Redwood/DA_RW_* DataAssets.

   profiles:
     - id: "elimination"
   
       zones:
         main:
           maps:
             - "expanse"
   
       max-players-per-shard: 16
   
       matchmaking-zone-name: "main"
       min-players-for-matchmaking: 1
   
       data:
         Experience: "B_ShooterGame_Elimination"
   
     - id: "control"
   
       zones:
         main:
           maps:
             - "convolution"
   
       max-players-per-shard: 16
   
       matchmaking-zone-name: "main"
       min-players-for-matchmaking: 1
   
       data:
         Experience: "B_LyraShooterGame_ControlPoints"

4. Create a realm/instances/default.yaml file (i.e. RedwoodBackend/config/node/template-match/realm/instances/default.yaml)

5. Generate two UUIDs for realm authentication for the next step. You can do this with an online generator.

   note

   If you've installed NodeJS & Yarn and Redwood dependencies by running yarn in the RedwoodBackend directory, you can run yarn id in the RedwoodBackend directory to generate a UUID.

6. Set the contents of your realm/instances/default.yaml to the below. In this config we're:

   • Specifying new realm auth parameters. The secret shouldn't be shared externally to the studio, and doesn't support the secrets system yet, so you're safe to commit this value in the meantime but otherwise treat it like a secret.
   • Ensuring we use the local game server provider and specifying the path to the UE project file
   • Some updated matchmaking parameters:
     • Changing max-wait-until-make-shallow-match-ms to a smaller value for faster testing
     • Lyra sometimes takes longer than the default 60s ticket-stale-time-ms value, so we made it longer so matchmaking tickets don't go stale before the server finishes starting.

   auth:
     id: "your-first-generated-uuid-here"
     secret: "your-second-generated-uuid-here"
   
   game-servers:
     provider: "local" # this is redundant here since it's the default, but we like to keep it here to prevent later confusion
   
     local:
       project: "C:\\path\\to\\YourProject\\YourProject.uproject"
   
   ticketing:
     matchmaking:
       max-wait-until-make-shallow-match-ms: 15000
       ticket-stale-time-ms: 120000
   note

   Notice that for Windows paths, you need to use double backslashes (\\) instead of single backslashes (\).

Run the Backend (via the Dev Initiator)

There are several ways to run the Redwood Backend. The one with the fastest iteration is the Dev Initiator. This is a NodeJS program that runs each of the services. Running the Dev Initiator is different for Evaluation and Full versions:

Evaluation Version

1. Modify RedwoodBackend/config-settings.json so the defaults.env field uses the configuration environment you created earlier:

   {
     "defaults": {
       "dir": "config/node",
       "env": "template-match"
     }
   }
2. Run the RedwoodBackend/Run Dev.bat script; you can run it from a terminal (make sure to run it from the RedwoodBackend directory) or double click on it from the File Explorer.

Full Version

1. Install NodeJS & Yarn if you haven't yet. You will need node@20 and [email protected] (preferably the latest version of each) (check with node --version and yarn --version).

2. Open a terminal to the RedwoodBackend directory

3. Run yarn to install Redwood dependencies

4. Run yarn dev <config-environment> using the configuration environment you created earlier.

   For example: yarn dev template-match

Several logs will print to the console as the backend initializes; wait until you see All services ready.

Start the Game in PIE (Play In Editor)

It's time to start the game, connect to the backend, and join a match!

1. Back in Unreal, make sure you've selected Play Standalone under the PIE Net Mode (it's the default) and are still in the L_RW_LyraFrontEnd level:

   

2. Press the green play button:

   

3. You should see the Lyra frontend widget with the LOGIN/REGISTER buttons enabled:

   

   warning

   If you see these buttons greyed out/disabled and a label saying Connecting to backend..., there are some a few common issues:

   • You have another application bound to the port 3001
   • You did not configure your hosts file properly to include director.localhost
   • You did not change the Director Uri project setting to include :3001
   • You started PIE before the Dev Initiator hasn't finished initializing. The connection retry logic will get exponentially slower after each retry, so you may need to restart PIE

4. Register to create an account; any username/password works here. We use test and test for quick iteration.

5. Login using the same username/password. The Remember Me functionality is part of the Redwood plugin. It will save a RedwoodSaveGame.sav file in the SaveGames folder with an authentication token to automatically login when the game starts the next time.

   warning

   If you were able to register but the login process seems to hang for more than 5 seconds, you're likely having issues connecting to the Realm Frontend service. The common issues for that are similar:

   • You have another application bound to the port 3011
   • You did not configure your hosts file properly to include realm-default.localhost

6. You should be able to see a PLAY button now:

   

7. Select PLAY; from here, you can either select MATCHMAKING or START LOBBY to create a match. The JOIN LOBBY button will show a list of existing public lobbies.

   note

   It may take awhile for the server to load the first time. You may get a timeout and need to try again. If your ticket keeps going stale, you can increase the ticket-stale-time-ms variable you set earlier and restart the Dev Initiator.

   info

   Server initialization is shorter in a packaged/cooked game. When running with the local game server provider, you're using uncooked content through UnrealEditor.exe. Using the agones game server provider will have the shortest initialization time due always having a warm server already started waiting to get the match details. Hathora's startup time is also quite fast, with their Enterprise tier having the best performance.

success

That's it! You're using Redwood to run a match! Generally speaking, you can continue to build your game as you normally would.

When you're ready to continue learning more about Redwood, here are some follow up topics:

• Learn how to use the Hathora Game Servers
• Deploying to Kubernetes (locally and to the cloud)
• Understanding the Redwood architecture
• Learning more about the available configuration options