LogoLogo
  • Get Started
  • Getting Started
    • Initial Setup
    • Create Your First Game
    • API Reference
    • Build Your First World Map
    • Multiplayer Testing
    • Use Templates & Examples
    • Styling & Assets
      • Modeling Guidelines
      • Texturing Guidelines
      • Default Assets
  • Build Faster With AI Tools
  • SDK Guides
    • Assets
    • Audio & SFX
      • Audio Manager
    • Blocks & Chunks
      • Block Types
      • Block Type Registry
      • Chunks
      • Chunk Lattice
    • Camera
    • Chat & Commands
    • Debugging
    • Entities
      • Animations
      • Block Entities
      • Colliders & Hitbox
      • Child Entities
      • Entity Controllers
        • Base Entity Controller
        • Pathfinding Entity Controller
        • DefaultPlayer Entity Controller
        • Simple Entity Controller
      • Entity Manager
      • Model Entities
      • Movement & Pathfinding
      • Player Controlled Entities
    • Events
    • Input & Controls
    • Lighting
      • Ambient Light
      • Light Manager
      • Point Lights
      • Spot Lights
      • Sun Light (Directional)
    • Mobile
    • Persisted Data
    • Players
      • Player Manager
      • Persisted Player Data
    • Plugins
    • Physics
      • Colliders
      • Collision Groups
      • Debugging
      • Gravity
      • Raycasts
      • Rigid Bodies
    • User Interface
      • Overlay UI
      • Scene UIs
      • Scene UI Manager
    • Worlds
      • Map Data Format
  • Helpful Resources
    • HYTOPIA Architecture & Platform Overview
    • Useful Third-Party Tools
Powered by GitBook
On this page
  • Optional Prerequisite
  • 1. Install Bun
  • 2. Create and initialize your project
  • 3. Run the project
  • 4. Play!
  • Next Steps
Export as PDF
  1. Getting Started

Initial Setup

PreviousGet StartedNextCreate Your First Game

Last updated 16 days ago

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:

1. Install Bun

HYTOPIA uses 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!

  • 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.

Next Steps

Go to

You can quickly resolve this by visiting 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 - 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 , if you're using a browser like Brave, or any browser with a built-in firewall, you can try disabling it for - this in most all cases will resolve connectivity with localhost on Brave and similar browsers.

https://discord.gg/hytopia
Bun
hytopia.com/play
https://localhost:8080
https://hytopia.com/play
https://hytopia.com/play
https://hytopia.com/play

Create Your First Game

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

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