@gathertown/gather-game-client

Gather

A prototype into the metaverse.

Gather

Package Manager	Version	Installation
`yarn`	`3.2.4`	`corepack enable && corepack prepare yarn@3.2.4 --activate`

Please set up Prettier in your favorite editor, and use it. Many editors will have fancy integrations like "reformat on save" that are quite handy. It's quite easy and will take maybe 1 minute to set up, and save you a world of frustration with CI checks about lint.

Use the local dependency and not a global install, because your version may be out of sync with this project's.

# do this
$ npx prettier ...

# not this
$ prettier ...

WebStorm

Instructions for IntelliJ / WebStorm: https://www.jetbrains.com/help/webstorm/prettier.html

Your settings should look something like this:

VS Code

Instructions for VS Code: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode

Your User settings should have no mention of prettier because it'll be controlled at the Workspace level:

You can verify your Workspace settings has reference to the .prettierrc config file:

Debugging

You can make sure the .prettierrc is being read by changing something in the config like semi: false and verifying the document is formatted differently.

Sometimes your IDE and the CI system will dispute over the "correct" formatting. Your source of truth will always be the command line:

$ npx prettier --check path/to/file.ts

# or, to see what the output would be:
$ npx prettier --write path/to/file.ts

Make sure you have the correct version installed in node_modules/prettier (2.5.1) at the time of this writing, just check it against the yarn.lock version:

$ npm pkg get version --prefix node_modules/prettier
"2.5.1"

Here's some steps to help resolve disputes between CLI/CI and your IDE:

Grab a fresh clone (or carefully wipe all node_modules everywhere)
Restart your IDE (it sometimes has a cached version of prettier)
Make sure your IDE is pointing to local prettier binary
Make sure your IDE is using the .prettierrc config
Make sure you have no other personal settings overriding .prettierrc.

Git Hooks

In githooks/ there are some git hooks that automatically merge changes from main down to the more unstable branches. Run npm run install-githooks to install them.

To automatically eslint and prettify your code as you commit it, run npx husky install once to enable a pre-commit git hook. Any time you run git commit after enabling Husky, eslint and prettier will fix up and format staged files. Any changes made during this step will be staged and committed automatically while any errors that occur will cancel the git commit altogether.

Java

Note: you'll need to install Java to run the Firebase emulator. The easiest way to do so with is brew:

$ brew install --cask temurin

Docker

We use Docker for running certain services.

Docker can be downloaded and installed via the following methods:

Via brew: $ brew install docker --cask, OR

Make sure to open Docker from the App menu as that adds the symbolic link to /usr/local/bin

Download via https://www.docker.com/products/docker-desktop/

Docker can be very resource heavy and the defaults can be unforgiving.

You can edit Docker's resource limits in Preferences/Settings:

Go to Docker Desktop -> Preferences
From Preferences -> Resources tab
CPU's: 1-2 total
Memory: 1-2 GB total
Swap: 1 GB
Disk Image Size: 8+ GB (this will fill up fast if more images are pulled)

Firestore

We connect to a shared dev instance of Firestore (gather-town-dev) for local development. Try visiting this page. If you don't have access, reach out to Michael or Kumail to request access.

The local Firestore emulator is mostly used for tests, and should be installed via npm along with other project dependencies.

CockroachDB

We run CockroachDB locally for our database. You can run this command to install (or reinstall) the CRDB binary:

$ gather db:install

Start up the database with gather db:run, or just use gather test:emulator to run the DB and other services needed for tests.

Then run the migrations with gather db:migrate. This will also seed your local DB with data needed for local development.

You can reset your DB and start fresh by running gather db:reset.

Access to staging and prod

If you need access to staging and prod DBs, you'll need access to the stg and prod config in Doppler. File a ticket in Linear assigning the Infra team to request access.

You will also need login credentials to access the DBs. Talk to @andrew (Andrew Smith) to have credentials created. Then set up a .env file under modules/gather-prisma-backend/.env, to look like this:

DATABASE_URL="postgresql://root@localhost:26257/gather"
DATABASE_USER="..."
DATABASE_PASSWORD="..."

Andrew will provide you with a user and password.

Programmatic Access

You can easily access any DB env (test, local, staging, or prod) programmatically. Go to gather-prisma-backend to get started.

Visual editor

You can load a UI editor for the DB in WebStorm. Download the Database Tools and SQL for WebStorm plugin. Then grab a license from our license pool.

Lastly, set up a DB config to connect to your local instance. Go to [Database] > [New]...

And add this config for local DB environment:

Name: gather@local (or whatever you want)
Host: localhost
Port: 26257
User: root
Password: <empty>
Database: gather

And this one for test DB environment:

Name: gather@test (or whatever you want)
Host: localhost
Port: 26258
User: root
Password: <empty>
Database: gather

There's actually multiple "test DBs" that we maintain for running tests in parallel, but when you run a single test file (e.g. through the IDE) it'll connect to gather, and then you can look at the state of the DB data after running the test.

You can do similar for staging and prod, pull the name and password from Doppler's DATABASE_URL variable (staging config, prod config). You will then need to substitute in your own credentials. You can get the full URL like this:

$ gather db:url staging
$ gather db:url prod

From this, you can find the values to input into the WebStorm configuration:

postgres://[user]:[password]@[host]:[port]/[database]

Viewing data

Once you run gather db:migrate, you should see tables show up.

You can double-click on one to view or edit the data in a table format. When you make edits, you can either revert them, or submit them as changes to the DB.

And you can do your usual work like searching or using ORDER BY:

You can also run SQL queries from a console that connects to the DB:

With it, you can run any SQL command. Fastest way to run a command is Search For Action (⌘ ⇧ A) "Execute". Or you can slowly move your mouse and click the green arrow, but that gets annoying over time.

Onboarding guides

You are expected to review the onboarding guides and information on both Prisma (our ORM) and CRDB (our DB).

Livekit Server

We run Livekit Server locally for our Audio/Video SFU. Download the livekit-server binary to run locally:

$ brew install livekit

Running

run yarn start from directory modules/gather-dev-server to start the game/http dev server
run yarn start from directory modules/gather-browser to start the hot loader
see modules/gather-video-sfu/README.md and modules/gather-video-router/README.md for how to run the video system locally

Then visit http://localhost:8080.

Deploying

Look at the deploy dir.

Testing

Tests require some services to be running locally. Run them all in a shared window with gather test:emulator.

Or, you can run them individually:

gather db:run to start CockroachDB locally
gather test:firebase to start the Firebase emulator
gather test:redis to start a Redis server locally
gather test:livekitServer to start a Livekit server locally

Run gather test:run from the root to run all module tests (or gather test:run -a from anywhere)

Run gather test:run [module] for all tests matching a module name / file pattern.

For the most part, you should be running tests from your IDE, because it's the easiest way to run a single test or group of tests or run in a debugger.

Please avoid the jest CLI, even if you're familiar with it, because it fits less well with the engineering workflow at Gather. (Also there's some hacky setup required.)

Read through the Testing Style Guide for guidance on the patterns and principles of testing at Gather. If you're just joining, you will have specific sections suggested to you during the testing onboarding process, so you can follow the prompts in the exercises.

@gathertown/gather-game-client

Gather

Setup

Command Line Tools

Python3 (M1 only)

Node canvas dependencies (M1 only)

Node

Yarn Package Manager

IDE

Doppler

Local setup (run once)

Gather CLI