Mobile

Making a game that's playable on mobile phones and tablets is critical to maximize the number of potential players of your game.

HYTOPIA automatically handles most of the mobile requirements for you, all you need to do is customize your game's User Interface for mobile and adjust your UI sizings!

If you want to quickly dive into a code example to understand how mobile works, you can find that here: Basic Mobile UI Example

A demo HYTOPIA game played on mobile.

Mobile & Cross-Platform Play

Mobile compatible HYTOPIA games can be played by anyone through a mobile web browser or on the HYTOPIA mobile app.

Cross-platform play, game state consistency, and other features that are typically pain points when building games that are both mobile & desktop are automatically handled for you.

Players all play together regardless of their device they're playing from and their progress and game state through our persistence layer follows them no matter the device they play on. This means your game can be played on the go through a mobile device, at a desktop computer or laptop, and one day in the future even game consoles!

Movement & Camera Controls

By default, the HYTOPIA game client automatically handles player movement and camera controls.

A movement joystick is controlled by touching and dragging on the left 40% of the screen, whereas the camera is controlled by touching and dragging the right 60% of the screen. For the sake of player familiarity, this control behavior is very similar to other popular games such as Roblox and Fortnite.

Any UI elements within these regions will still normally receive touches. Joystick handlers are attached to the root of the game UI container and events propagate to it on touch. This also allows handy interactions in shooters or other game types for example, where a player may need to press a button to start shooting, hold it to continue shoot, but can simultaneously move their finger on the camera joystick side to control their aim.

You can try out a demo of mobile controls for the game shown here by visiting the following link on your mobile device: https://hytopia.com/games/hygrounds/

Visual example of the mobile control regions.

Mobile UI Buttons & Triggering Inputs

HYTOPIA does not automatically create any UI buttons for a game's mobile controls. This is on purpose and left entirely up to you to implement for the sake of providing you with full control over your game's mobile control needs.

In many cases, you will want to add buttons to control actions such as jump, interactions, and more. You can do this by creating button UI elements that on touch alter the input state of the game. This can be done through the hytopia.pressInput()method, which accepts 2 arguments. The first argument being they input state key you want to update, found here Available Inputs, and the second argument being a boolean indicating if that key is pressed or not. You can take a look at Basic Mobile UI Example for a full demonstration of this.

Keep in mind, the boilerplate project automatically created when using bunx hytopia init to start a new local project will include basic mobile UI controls in the generated assets/ui/index.html . You are free to use this as a starting point for your mobile controls, add to it, remove it etc.

Mobile UI Considerations

Your game will likely need to make tweaks to its original desktop-sized UI in order to work on mobile. While mobile devices will size UI elements automatically, you probably will want to fine tune it, show or hide certain UI elements on mobile, etc.

Usually it's most efficient to develop your regular, non-mobile in game UI first, and adjust it later to work on mobile.

Your mobile UI lives in the same place as your game's standard User Interface. Typically this is your assets/ui/index.html file that you load for a player when they join the game. This pattern is nearly identical to building a standard website that has mobile specific styles or interfaces.

Mobile Device Detection

HYTOPIA makes it simple to detect if the device playing your game is a mobile device.

HYTOPIA will automatically add a .mobile CSS class to the <body> element of the game when it detects the playing device is a mobile device. You can use this to create CSS style selectors that will only be used if the device is a mobile device. This is useful for doing things like showing mobile controls for mobile devices, etc. You can see an example of this in the Basic Mobile UI Examplebelow.

If you need to know if the device is a mobile device or not in Javascript, the globally available hytopia object has an isMobile property. In your client scripts, you can check if hytopia.isMobile is true to determine if the device is a mobile device.

Portrait vs. Landscape Mode

All HYTOPIA games when run on a mobile device will default to landscape mode. You should design your mobile UI to be compatible with landscape mode, not portrait mode.

An image visually showing landscape orientation.

Basic Mobile UI Example

Below is an example of a UI index.html file with mobile specific buttons, that will only show on mobile.

This example shows a jump and interact button, but only if the device being played on is detected as a mobile device.

<script>
  // Handle interact button touch / untouch
  const mobileInteractButton = document.getElementById('mobile-interact-button');
  mobileInteractButton.addEventListener('touchstart', e => {
    e.preventDefault(); // Prevents mobile highlight/select/copy popup behaviors
    mobileInteractButton.classList.add('active'); // more immediate feedback to add/remove active class
    hytopia.pressInput('ml', true);
  });

  mobileInteractButton.addEventListener('touchend', e => {
    e.preventDefault();
    mobileInteractButton.classList.remove('active');
    hytopia.pressInput('ml', false);
  });

  // Handle jump button touch / untouch
  const mobileJumpButton = document.getElementById('mobile-jump-button');
  mobileJumpButton.addEventListener('touchstart', e => {
    e.preventDefault();
    mobileJumpButton.classList.add('active');
    hytopia.pressInput(' ', true);
  });

  mobileJumpButton.addEventListener('touchend', e => {
    e.preventDefault();
    mobileJumpButton.classList.remove('active');
    hytopia.pressInput(' ', false);
  });
</script>

<!--
  Your other in-game UI's, mobile or not mobile specific, can go anywhere else in the file.
  Remember, mobile & non-mobile UI all live in the same file.
-->

<div class="mobile-controls">
  <a id="mobile-interact-button" class="mobile-button">
    <img src="{{CDN_ASSETS_URL}}/icons/target.png" />
  </a>

  <a id="mobile-jump-button" class="mobile-button">
    <img src="{{CDN_ASSETS_URL}}/icons/jump.png" />
  </a>
</div>

<style>
  /* By default, when not on mobile we hide the mobile controls */
  .mobile-controls {
    display: none;
  }

  /*
    We can use the body.mobile class to detect if we're on a mobile device.
    The HYTOPIA game client will always add this class to the body element when running on a mobile device.
  */
  body.mobile .mobile-controls { /* If this css selector matches because we're on mobile, show the mobile controls */
    display: flex;
    gap: 14px;
    position: fixed;
    bottom: 40px;
    right: 40px;
  }

  /* You can configure and style your buttons however you'd like. This is a minimalistic starting point. */
  .mobile-button {
    background-color: rgba(0, 0, 0, 0.5);
    border-radius: 50%;
    align-items: center;
    justify-content: center;
    display: flex;
    width: 50px;
    height: 50px;
    transition: all 0.15s cubic-bezier(0.4, 0, 0.2, 1);
    will-change: transform, background-color;
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
    font-family: 'Inter', sans-serif;
    font-size: 14px;
    font-weight: bold;
    color: rgba(255, 255, 255, 0.8);
    text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.8);
  }
  
  .mobile-button img {
    width: 22px;
    height: 22px;
  }

  .mobile-button.active {
    transform: scale(0.92);
    background-color: rgba(0, 0, 0, 0.75);
    box-shadow: 0 1px 4px rgba(0, 0, 0, 0.3);
  }  
</style>

This example will give the following UI on mobile.

The result of our mobile UI example with a jump and interact button that can be tapped.

Testing Mobile UI On Desktop

You can easily test your mobile UIs through your desktop's browser by enabling mobile view in your browser's developer tools.

Here's a quick step by step guide and demonstration video on how to do this:

1. Open your game as usual through https://play.hytopia.com

2. Now that you're in your game, open your browser's "Developer Tools". This is typically under View -> Developer Tools in the browser dropdown menu, or can be opened by right clicking anywhere on the page and selecting "Inspect" from the popup menu.

3. Depending on the browser and developer tools you're using, You should see an icon somewhere in the newly opened developer tools window that looks like a mobile device or mobile phone, find it and click it.

4. If all went well, you should see the screen layout change to something that looks more mobile sized. Make sure the view is in landscape mode, typically there is a button to rotate from portrait to landscape mode in the developer tools.

5. Lastly, refresh the page so the client reloads and can detect that mobile is now enabled. That's it! You can now test as if you were using a mobile device, but through your desktop web browser for development convenience.

Here's a quick demo video showcasing the above steps while using the Brave web browser. Browser's like Google Chrome and Safari will be very similar.

HYTOPIA Mobile Development Demo

Mobile UI Caveats

The HYTOPIA in-game UI system is built on top of web standards. This means that creating mobile compatible UI's is nearly identical to making a standard web page with mobile compatibility. There are no caveats!

You are free to use any mobile behaviors, css selectors, mobile specific javascript and more to build your mobile UI's. As long as what you use is supported by Chromium (Google Chrome), Safari and Android web browsers, it should work everywhere HYTOPIA games can be played.