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 Node.js
HYTOPIA uses Node.js as its JavaScript runtime for development and production.
You can install the latest version of Node.js here: https://nodejs.org/en/download/current
2. Install HYTOPIA CLI
HYTOPIA provides a simplified command line interface for various tasks. This is required for HYTOPIA game development and publishing.
HYTOPIA CLI Install
# Open your terminal (mac, linux) or powershell (windows) and run:
npm install -g --force hytopia@latest3. 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.
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.4. Run the HYTOPIA Server
Start your HYTOPIA server using the HYTOPIA CLI:
# Make sure we're in the hytopia-demo directory.
# This command starts your server and hot-reloads it when code changes are made:
hytopia startThis runs the index.ts file in our project, 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 safely ignore this error in local development. Your local game server will fall back to using Websockets instead. This does not effect development in any way.
5. 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://.
Start your HYTOPIA server (from the previous step).
Open a supported browser such as Chrome, Edge, or Safari, etc. (Opera & Firefox are not fully supported and may act unexpectedly.)
Go to https://localhost:8080.
When the browser warns that the site is “Not secure” or “Unsafe”:
click Advanced → Continue (wording may differ).
This makes your browser trust the local development SSL certificate just for your machine.
You should now see something like this:
{"status":"OK","version":"0.9.0","runtime":"node"}, if you do, the certificate is trusted and you're ready for the next step.
6. 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.
Last updated