Initial Setup

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

Optional Prerequisite

We strongly recommend you join our developer Discord server! Our developer server is a great place to showcase your work, chat with other developers, quickly get technical questions answered, and much more.

You can join our developer Discord server here: https://discord.gg/hytopia

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:

# Install the HYTOPIA SDK package globally (If you haven't already)
bun install -g hytopia

# 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 a HYTOPIA project from the SDK
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.

If you receive an error or warning when running your game for the first time that includes a message like Failed to initialize WebRTC , you can resolve this by running bun pm trust mediasoup in your project. This will install mediasoup to support WebRTC networking in local development.

On some operating systems this may fail. If so, you can safely ignore the lack of WebRTC support in local development, your local game server will fall back to using Websockets instead.

4. Play!

• Go to hytopia.com/play
• When prompted for a server URL, enter https://localhost:8080.

• Explore and enjoy your first HYTOPIA game!

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://hytopia.com/play - you should now be able to connect without issues.

Brave Browser: If you have tried visiting https://localhost:8080 in a new tab, it loads, but you still can't connect through https://hytopia.com/play, if you're using a browser like Brave, or any browser with a built-in firewall, you can try disabling it for https://hytopia.com/play - this in most all cases will resolve connectivity with localhost on Brave and similar browsers.

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

Next Steps

Create Your First Game

Learn how to use the HYTOPIA SDK to build a simple game!