1. Initial Setup

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

Join Our Developer Community!

We have a very friendly, and very active community of developers! We recommend you join - you can ask questions, help others, share progress for a HYTOPIA game you're creating, and more within our community!

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

0. Install Cursor (Optional, Highly Recommended)

The HYTOPIA code editor and studio tools are built as a plugin for the popular Cursor code editor (IDE). We recommend you use the Cursor IDE for developing your HYTOPIA projects. By using it, you'll be able to use HYTOPIA's developer tools that act as an automatic plugin with Cursor.

Download & Install Cursor: https://cursor.com/

1. Install Bun

HYTOPIA uses Bun as its JavaScript runtime for development.

Mac or Linux - Bun Install

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

Windows - Bun Install

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

2. Create and initialize your project

Open your terminal on Mac/Linux, or Windows Powershell and run:

# Navigate to your desired directory to create a project folder
cd ~/Desktop

# Create a new project folder
mkdir hytopia-demo 

# Navigate into created project folder
cd hytopia-demo

# Initialize a HYTOPIA project. This can take a few minutes the first time.
bunx hytopia init

# If you installed Cursor, when you are prompted to initialize the HYTOPIA MCP
# we strongly recommend you enter "y" for yes. This will install the HYTOPIA
# developer tools as a plugin for Cursor.

You should see a confirmation for 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 HYTOPIA Server

Start your HYTOPIA 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. Trust The HYTOPIA Server SSL Certificate

Next, our browser needs to trust our local HYTOPIA development server. This is because we will connect to it from the HYTOPIA client which uses https:// in the next step. This requires the local server to have a locally trusted SSL certificate for https://.

  1. Start your HYTOPIA server (from the previous step).

  2. Open a supported browser such as Chrome, Edge, or Safari, etc. (Opera & Firefox are not fully supported and may act unexpectedly.)

  3. Go to https://localhost:8080.

  4. When the browser warns that the site is “Not secure” or “Unsafe”:

    1. click Advanced → Continue (wording may differ).

    2. This makes your browser trust the local development SSL certificate just for your machine.

  5. You should now see something like this: {"status":"OK","version":"0.6.33","runtime":"bun"}, if you do, the certificate is trusted and you're ready for the next step.

5. Play!

  • Go to hytopia.com/play - This is the HYTOPIA game client we always use to test/connect development servers.

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

  • Explore and enjoy! You're ready to start building your first HYTOPIA game!

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. For Brave Browser, you can find the setting here:

This, in most 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.

PreviousGet StartedNext2. Create Your First Game

Last updated