Initial Setup

Before we begin building our first game, we need to setup our local developer environment and a sample project. Follow these steps.

1. Install Bun

HYTOPIA uses Bun as its JavaScript runtime.

Mac or Linux - Bun Install

# Open your terminal and run:
curl -fsSL https://bun.sh/install | bash

Windows - Bun Install

# Open your terminal and run:
powershell -c "irm bun.sh/install.ps1 | iex"

2. Create and initialize your project

Open your terminal and run:

# Navigate to your desired directory
cd ~/Desktop

# Create a new project directory
mkdir hytopia-demo
cd hytopia-demo

# Make sure we have the latest Bun version
bun upgrade

# Initialize the HYTOPIA project
bunx hytopia init

You should see a log confirming successful initialization. If you received an error on the bunx step to initialize the project, you likely need to upgrade your bun installation, run bun upgrade in your terminal.

3. Run the project

Start your HYTOPIA game server with:

# Run our game, --watch hot reloads the server on code changes.
bun --watch index.ts

This runs index.ts, the entry point of your game. Your server is now live at https://localhost:8080.

4. Play!

• Go to play.hytopia.com.

• When prompted for a server URL, enter https://localhost:8080.

• Explore and enjoy your first HYTOPIA game!

The boilerplate game you should see if you followed all of the steps successfully.

Note: If you are continually prompted to enter a server url or receive another error when connecting to your server, your browser is likely blocking the self-signed SSL certificate used for localhost.

You can quickly resolve this by visiting https://localhost:8080 in a new tab. You'll likely be prompted with a warning saying this website is insecure (Due to the self-signed certificate for local development). Click "Advanced" or "Continue to website" depending on the browser - this will cause your browser to allow connections to your local server. The page should load with just "OK" text shown.

Now, return to https://play.hytopia.com - you should now be able to connect without issues.