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
        • Player 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
  • Mobile & Cross-Platform Play
  • Movement & Camera Controls
  • Mobile UI Buttons & Triggering Inputs
  • Mobile UI Considerations
  • Mobile Device Detection
  • Portrait vs. Landscape Mode
  • Basic Mobile UI Example
  • Testing Mobile UI On Desktop
  • Mobile UI Caveats
Export as PDF
  1. SDK Guides

Mobile

PreviousSun Light (Directional)NextPersisted Data

Last updated 1 month ago

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

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.

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.

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.

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.

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

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

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

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

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.

You can try out a demo of mobile controls for the game shown here by visiting the following link on your mobile device:

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

Open your game as usual through

https://hytopia.com/games/hygrounds/
https://play.hytopia.com
HYTOPIA Mobile Development Demo
A demo HYTOPIA game played on mobile.
Visual example of the mobile control regions.
An image visually showing landscape orientation.
The result of our mobile UI example with a jump and interact button that can be tapped.
Available Inputs