Upgrading To Deno & SDK 0.9.0

If you've been developing using a HYTOPIA SDK version < 0.9.0, you will need to follow this guide to understand the development environment changes and new features available in SDK 0.9.0 and beyond.

First off, SDK version 0.9.0 and beyond transitions from using bun as the local development runtime, to instead using deno.

Deno is now used to better mirror HYTOPIA's production environment where we use Deno for game runtimes.

Follow these steps to upgrade your local development environment and any existing projects.

1. Install Deno

Mac or Linux - Deno Install

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

Windows - Deno Install

# Open Windows Powershell and run:
irm https://deno.land/install.ps1 | iex

If you have any issues installing Deno in your Mac, Linux or Windows environment, you can find Deno's installation documentation here.

2. Install HYTOPIA CLI

HYTOPIA provides a simplified set of command line interface tools for various tasks. This is required for HYTOPIA game development and publishing.

If you previously installed HYTOPIA globally using npm or bun, you'll want to uninstall it first.

# Uninstall via bun if you've used bun
bun remove -g hytopia

# Uninstall vai npm if you've used npm
npm uninstall -g hytopia

Now, install the hytopia CLI:

# Open your terminal (mac, linux) or powershell (windows) and run:
deno install -Agrf npm:hytopia@latest

You will need to restart your terminal after doing this. You can do that by closing and reopening your terminal.

3. Running Projects

As of SDK 0.9.0+, HYTOPIA no longer uses the bun to run your project. Instead, this has changed to:

# This is the old way < 0.9.0 used to start a local project for
# development. Bun is no longer used, this command will break in 0.9.0+
bun --watch index.ts

# Instsead, use the following command which uses the HYTOPIA
# CLI to start and develop your project.
hytopia start

4. Upgrading Projects

The HYTOPIA CLI that you installed now has a upgrade-project command. This allows you to upgrade the SDK version of a HYTOPIA project properly.

Here's a few ways you can use it, make sure you're in your projects directory in the command line before running these commands.

# Upgrades to the latest HYTOPIA SDK version
hytopia upgrade-project

# Alternatively, upgrade to a specific HYTOPIA SDK version, such as 0.9.0
hytopia upgrade-project 0.9.0

# Alternatively, upgrade to a specific HYTOPIA SDK version by release tag, such as dev
hytopia upgrade-project dev

5. Initializing New Project

If you're initializing a new project, the command to do that is similar to before, and can be done like so:

# Old way, no longer used
bunx hytopia init

# New way, using HYTOPIA CLI
hytopia init

6. Various Errors & Gotchas

There's a few things we'll need to be aware of when using 0.9.0 and Deno for our runtime environment. If you run into any of these issues, here's how to resolve them.

Importing .json files, such as map.json breaks.

Deno requires that json imports have their import type explicitly specified. Without doing this, deno will complain with errors.

In our existing project, we may have something like this, which will error:

import worldMap from './assets/map.json'

To resolve this, we need to change it to:

import worldMap from './assets/map.json' with { type: 'json' };

Installing Packages

Deno 3rd party package installation from NPM is slightly different than using node or bun.

You can install arbitrary packages from NPM using deno as follows

deno add --npm NPM_PACKAGE_NAME_HERE

Unusual Behavior Or Broken Physics

If you're seeing odd behaviors or broken physics after upgrading your project, this is likely due to a dependency issue. You can fix this by running deno install in your project from the command line.