BrowserQuest Deployment and Usage Guide

This guide provides instructions for deploying and running BrowserQuest, a deprecated HTML5/JavaScript multiplayer game experiment.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js: Version 0.8.x or higher (as indicated by older Node.js practices in the source). It is recommended to use a Node.js version manager like nvm to install an older compatible version if you encounter issues with newer versions.
Git: For cloning the repository.

Installation

Clone the repository:

git clone https://github.com/mozilla/BrowserQuest.git
cd BrowserQuest

Install server dependencies: Navigate to the server directory and install the Node.js dependencies.
```
cd server
npm install
```
Install client dependencies: Navigate to the client directory and install the Node.js dependencies.
```
cd ../client
npm install
```
Note: The client/package.json might be missing or contain outdated dependencies. If npm install fails, you may need to manually inspect the client directory for build tools or asset compilation steps. Given the project's age, some client-side dependencies might be handled directly via script tags or older build processes not explicitly defined in a package.json.

Configuration

BrowserQuest uses configuration files within its server directory.

Server Properties: The main server configuration is likely handled by server/js/properties.js. You may need to inspect and modify this file for settings such as:
- port: The port the server listens on.
- host: The host address.
- maxPlayers: Maximum number of players allowed.
- logLevel: Logging verbosity (e.g., Log.INFO, Log.DEBUG).
Example snippet from server/js/properties.js (conceptual, based on Log usage):
```
// Example: Adjust log level
// Log.level = Log.DEBUG;
```
Client-side Configuration: Client-side settings, such as the server host and port to connect to, are likely configured within client/js/gameclient.js or passed dynamically.
```
// client/js/gameclient.js
init: function(host, port) {
    this.connection = null;
    this.host = host; // This will likely be configured when the GameClient is instantiated.
    this.port = port;
    // ...
}
```
The client/js/app.js might also contain logic for connecting to the server, potentially using hardcoded values or values derived from the current URL.

Build & Run

BrowserQuest is primarily a JavaScript project. The "build" step for the client usually involves minification or concatenation, but for local development, it might run directly.

Run Locally (Development)

Start the server: Navigate to the server directory and run the main server file.
```
cd BrowserQuest/server
node js/worldserver.js
```
You should see log messages indicating the server is starting up, for example: log.info(player.name + " has joined "+ self.id); or similar.
Serve the client files: The client-side files are HTML, CSS, and JavaScript. You'll need a simple HTTP server to serve them. Python's http.server (Python 3) or SimpleHTTPServer (Python 2) is a good option.

From the root BrowserQuest directory:
```
# If you have Python 3
python3 -m http.server 8000
# Or if you have Python 2
python -m SimpleHTTPServer 8000
```
Alternatively, you can use npm to install a simple HTTP server:
```
npm install -g http-server
cd BrowserQuest
http-server -p 8000
```
Access the game: Open your web browser and navigate to http://localhost:8000/client/.

Run for Production

For production, you would typically:

Optimize Client Assets: Minify JavaScript, CSS, and images. Tools like UglifyJS, CSSNano, and image optimizers would be used. This project might have a Gruntfile.js or package.json script for this, but it's not immediately apparent from the provided snippets.

Use a Process Manager for the Server: Tools like PM2 or forever can keep your Node.js server running reliably, manage logs, and handle restarts.

# Install PM2 globally
npm install -g pm2
# Start the server with PM2
cd BrowserQuest/server
pm2 start js/worldserver.js --name "browserquest-server"

Use a Production-Ready Web Server: Serve the static client files using a robust web server like Nginx or Apache, configured to serve the client/ directory. This server would also typically act as a reverse proxy for the Node.js WebSocket server.

Deployment

Given the tech stack (Node.js for the server, HTML5/JavaScript for the client), suitable deployment platforms include:

Virtual Private Server (VPS): Such as DigitalOcean, Linode, AWS EC2, or Google Cloud Compute Engine. You would manually set up Node.js, a web server (Nginx/Apache), and a process manager (PM2).
1. Provision a VPS instance.
2. Install Node.js, Git, and Nginx.
3. Clone the repository to the server.
4. Run npm install in both server and client directories.
5. Configure Nginx to:
  - Serve static files from BrowserQuest/client/.
  - Proxy WebSocket connections to the Node.js server (e.g., localhost:8080).
6. Start the Node.js server using PM2.
Platform as a Service (PaaS): While the project is older, platforms that support custom Node.js applications could work, though direct WebSocket support might require specific configurations. Heroku, for example, could host the Node.js server, and you might use a separate service or a buildpack to serve the static client files.

Example Nginx Configuration (Conceptual):

server {
    listen 80;
    server_name yourdomain.com;

    root /path/to/BrowserQuest/client;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location /socket.io/ { # Or whatever your WebSocket endpoint is
        proxy_pass http://localhost:8080; # Port your Node.js server is running on
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400s; # Long timeout for persistent connections
    }
}

Troubleshooting

npm install failures:
- Solution: Check for a package.json in the client directory. If it's missing or empty, client-side dependencies might be handled differently (e.g., directly included via CDN or older build tools). For the server directory, ensure you have a compatible Node.js version. Try installing specific versions of packages if certain ones fail (e.g., npm install <package-name>@<version>).
Server not starting:
- Issue: Error: listen EADDRINUSE
- Solution: The port the server is trying to bind to is already in use. Change the port in server/js/properties.js or kill the process currently using that port.
- Issue: Missing modules.
- Solution: Ensure npm install was run successfully in the server directory. Check the Node.js version compatibility.
Client not connecting to server:
- Issue: "Waiting for server..." or similar messages in the browser console.
- Solution:
  1. Verify the Node.js server is running and accessible on the configured port.
  2. Check the browser's developer console for WebSocket connection errors.
  3. Ensure the host and port configured in client/js/gameclient.js (or wherever it's instantiated) match the server's address.
  4. If using a reverse proxy (like Nginx), ensure it's correctly configured to proxy WebSocket connections.
Game assets not loading:
- Issue: Images, sounds, or other resources are missing.
- Solution: Ensure your HTTP server is correctly serving the client/ directory and that all asset paths are correct relative to the index.html file.
Performance issues:
- Issue: Low FPS, lag.
- Solution: The Renderer (in client/js/renderer.js) has debug information. You might be able to toggle this.isDebugInfoVisible to true to see FPS and other metrics. Ensure your browser is up-to-date. For the server, monitor CPU and memory usage.

How to Deploy & Use mozilla/BrowserQuest