neu-se / covey.town

Covey.Town

Covey.Town provides a virtual meeting space where different groups of people can have simultaneous video calls, allowing participants to drift between different conversations, just like in real life. Covey.Town was built for Northeastern's Spring 2021 software engineering course, and is designed to be reused across semesters. You can view our reference deployment of the app at app.covey.town, and our project showcase (Fall 2022, Spring 2022, Spring 2021) highlight select student projects.

The figure above depicts the high-level architecture of Covey.Town. The frontend client (in the frontend directory of this repository) uses the PhaserJS Game Library to create a 2D game interface, using tilemaps and sprites. The frontend implements video chat using the Twilio Programmable Video API, and that aspect of the interface relies heavily on Twilio's React Starter App. Twilio's React Starter App is packaged and reused under the Apache License, 2.0.

A backend service (in the townService directory) implements the application logic: tracking which "towns" are available to be joined, and the state of each of those towns.

Running this app locally

Running the application locally entails running both the backend service and a frontend.

Setting up the backend

To run the backend, you will need a Twilio account. Twilio provides new accounts with $15 of credit, which is more than enough to get started. To create an account and configure your local environment:

1. Go to Twilio and create an account. You do not need to provide a credit card to create a trial account.
2. Create an API key and secret (select "API Keys" on the left under "Settings")
3. Create a .env file in the townService directory, setting the values as follows:

Config Value	Description
TWILIO_ACCOUNT_SID	Visible on your twilio account dashboard.
TWILIO_API_KEY_SID	The SID of the new API key you created.
TWILIO_API_KEY_SECRET	The secret for the API key you created.
TWILIO_API_AUTH_TOKEN	Visible on your twilio account dashboard.

Starting the backend

Once your backend is configured, you can start it by running npm start in the townService directory (the first time you run it, you will also need to run npm install). The backend will automatically restart if you change any of the files in the townService/src directory.

Configuring the frontend

Create a .env file in the frontend directory, with the line: NEXT_PUBLIC_TOWNS_SERVICE_URL=http://localhost:8081 (if you deploy the towns service to another location, put that location here instead)

For ease of debugging, you might also set the environmental variable NEXT_PUBLIC_TOWN_DEV_MODE=true. When set to true, the frontend will automatically connect to the town with the friendly name "DEBUG_TOWN" (creating one if needed), and will not try to connect to the Twilio API. This is useful if you want to quickly test changes to the frontend (reloading the page and re-acquiring video devices can be much slower than re-loading without Twilio).

Running the frontend

In the frontend directory, run npm start (again, you'll need to run npm install the very first time). After several moments (or minutes, depending on the speed of your machine), a browser will open with the frontend running locally. The frontend will automatically re-compile and reload in your browser if you change any files in the frontend/src directory.

covey.town's Issues

Disconnecting from an Active Conversation Area.

It seems that if Player1 and Player2 join an active conversation area, and Player1 disconnects, Player2 still sees Player1 on their screen and listed in the town players. If a third player joins the town after Player1 disconnects, they only see Player2 (i.e., they get the updated view), but Player2's screen keeps Player1.

To reproduce the bug:

1. Enter a town X as Player1
2. Enter the town X as Player2
3. Have either player start a conversation area (i.e. specify a topic)
4. Have both players join the conversation area.
5. Have Player1 disconnect.

Player2's screen should still show Player1.

conversation areas naming bug

Consider a scenario wherein a user decides to name a conversation area first after entering it.

1. User presses Space which opens up the popup to enter the Topic of the conversation for the current area.
2. User does not enter any topic in the popup and clicks Cancel.
3. After canceling,

Expected behavior - The user should be able to move freely across the map.
Actual behavior - The user is not able to move their character.

Only after the user enters a topic in the popup is the character allowed to move.

Player Labels Glitching

My group and I noticed that when we enter a Covey.town, the labels start glitching. We'll have multiple tabs open, one for each Player in a same Town, and when we move one Player, the labels will appear delayed in other tabs or won't appear at all. We originally thought this might be due to our implementing a Teleport functionality, but we realized this glitch was also happening on our main branch, were we haven't pushed any teleport functionality. After a discussion with our TA, where he confirmed that the glitch was happening in this repo as well, he suggested we report the issue here.

New entrants pull old entrants to beginning

When I ran the program in class (Tuesday 2/19), whenever a new student added, the people already there were all pulled back to the entry way. I haven't tried recently.

incorrect locations and directions of other players in the town

Incorrect location: when a player is moving, its frontend sends the location of the body to the backend, then other frontends receive this location and use it to update the location of the sprite of this player. Here is the problem: the location of the body is the location of the top left corner of the sprite, while the location of the sprite represents its center, so there will be a mismatch of location on different frontends. To solve this problem, we just need to calculate the location of the center(which is the sprite location rather than the body location) and send it to the backend, then other frontends can receive the correct location.

Always facing front after moving: (see the last line of the code) when a player stops moving, primaryDirection will be undefined, so the frontend will send the default direction "front" to the backend. To solve this problem, we make it sends the rotation of lastLocation rather than "front".

Global Chat - Uses of "space" while in a conversation area

My team and I noticed another bug in the starter code provided to us. When a player joins a town, enters a conversation area (active or not), opens the global chat, and goes to type a message, whenever they press the spacebar, the pop-up for specifying a topic appears. Pausing the game does not fix this issue (the way it did with preventing letter keys from causing Sprite movement during typing).