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 (v24 or higher)

HYTOPIA uses Node.js as its JavaScript runtime for development and production. You must use Node.js version 24 or higher.

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@latest

3. Install KTX Software

HYTOPIA automatically optimizes textures using the KTX format. This requires that you install the KTX Software package.

Download Latest KTX Software: https://github.com/KhronosGroup/KTX-Software/releases

4. 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 start

This runs the index.ts file in our project, the entry point of your game. Your server is now live at https://dev-local.hytopia.com:8080.

5. Play!

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

2. When prompted for a server URL, simply hit enter - it will default connect to your local https://dev-local.hytopia.com:8080 server.

3. Next, you will be prompted by the browser to allow connections your device on your local network, you must hit "allow". If you do not allow this, hytopia.com/play can't connect to your local server.

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

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