Hathora Phaser 3 Plugin

This plugin extends Phaser's game object factory functions with several additional UI elements which interface with one another and can be leveraged to quickly bootstrap multiplayer lobby menu scenes.

To see a working sample game, check out: Hathora Phaser Sample Game - Fast Food

To learn more about Hathora Cloud, check out: Hathora Cloud Documentation

Usage

Before calling any of the factory functions, you must first install the plugin within your Phaser game directory. You can do so via:

npm install hathora-phaser

With the plugin installed as a Node module, you must then add it to your game's configuration object as follows:

import './style.css'
import { Scene, Game, WEBGL, Scale } from 'phaser';
import { HathoraPhaser, HathoraConnection } from 'hathora-phaser';
import { TitleScene, GameScene } from './scenes';

const config = {
  type: WEBGL,
  scale: {
    width: 1280,
    height: 720,
    mode: Scale.FIT,
    autoCenter: Scale.CENTER_BOTH
  },
  parent: 'game',
  dom: {
    createContainer: true
  },
  physics: {
    default: 'arcade',
    arcade: {
      gravity: { y: 0 },
      // debug: true
    }
  },
  scene: [
    TitleScene,
    GameScene
  ],
  plugins: {
    scene: [
      {
        key: 'HathoraPhaser',
        mapping: 'HathoraPhaser',
        plugin: HathoraPhaser,
        start: true
      }
    ]
  }
  // Important part for using the plugin ☝️
}

new Game(config);

The final step before you can begin composing your scene via the factory functions is to initialize the plugin with your Hathora appId (you can get this by creating a project in your Hathora Console). This code typically would live inside the create() function of your game's boot scene or anywhere it would only be called once, and would look something like this:

this.HathoraPhaser.initialize(
  '[HATHORA_APP_ID]',
  (connection: HathoraConnection) => {
    this.scene.start('scene-game', {
      connection
    });
  },
  (error: any) => {
    console.warn(error);
  },
  true
);

For a full description of all the arguments passed to HathoraPhaser.initialize(), please see the next section! 😎

After initializing the plugin you're free to call it's factory functions to assemble a lobby UI that makes sense for your game. These factory functions come with a default styling, but you can override these styles using their classNames also listed in the next section.

For a full example using all available UI elements, please see this repo.

API

[scene].HathoraPhaser.initialize

Called once, to initialize the plugin.

Parameters

Parameter	Type	Description
appId	string	Your Hathora appId, get it from the console.
connectionCallback	function	A callback function, with a HathoraConnection object as a parameter.
errorCallback	function	A callback function if a connection error occurs, with an error parameter.
useUrl	boolean	Defaults to true, a flag to specify if the URL should be read as a roomId.
defaultVisibility	string	'public' or 'private', represents connection visibility if no toggle.

Example Usage

this.HathoraPhaser.initialize(
  '[HATHORA_APP_ID]',
  (connection: HathoraConnection) => {
    this.scene.start('scene-game', {
      connection
    });
  },
  (error: any) => {
    console.warn(error);
  },
  true
);

[scene].add.haVisibilityToggle

Adds a visibility toggle to the scene which the player can use to specify a new game's visibility.

Parameters

Parameter	Type	Description
x	number	The X coordinate to display the visibility toggle at.
y	number	The Y coordinate to display the visibility toggle at.

CSS Customization

• .ha-toggle: Parent class of the containing <div> (default styling).
• .ha-toggle__switch: Inner <button> classes (default styling).
• (switch class).on: Conditional class to signify the selected <button> element (default styling).

Example Usage

this.add.haVisibilityToggle(250, 250);

[scene].add.haCreateGameButton

Adds a create game button to the scene which if clicked will create a new game room on the server.

Parameters

Parameter	Type	Description
x	number	The X coordinate to display the create game button at.
y	number	The Y coordinate to display the create game button at.
label	string	An optional string to change the button's label text.

CSS Customization

• .ha-btn: Class applied to the <button> element (default styling).

Example Usage

this.add.haCreateGameButton(250, 250, 'Create a New Game');

[scene].add.haRegionSelect

Adds a dropdown menu populated with server regions and their average pings to the connected client.

Parameters

Parameter	Type	Description
x	number	The X coordinate to display the region select dropdown at.
y	number	The Y coordinate to display the region select dropdown at.

CSS Customization

• .ha-select: Class applied to the <select> element (default styling).

Example Usage

this.add.haRegionSelect(250, 250);

[scene].add.haJoinPublicList

Adds a scrollable panel which displays the active public games in the selected region.

Parameters

Parameter	Type	Description
x	number	The X coordinate to display the join public game panel at.
y	number	The Y coordinate to display the join public game panel at.
width	number	The horizontal width to display the join public game panel at.
height	number	The vertical height to display the join public game panel at.
label	string	An optional override for the panel's heading label.
pollRate	number	An optional override for the panel's polling rate in milliseconds.

CSS Customization

• .ha-join-public: Class applied to the parent <div> element (default styling).
• .ha-join-public__header: Class applied to the <header> element of the panel (default styling).
• .ha-join-public__list: Class applied to the scrollable <div> containing individual game rooms (default styling).
• .ha-join-public__list--filled: Conditional class to signify that the list has entries (default styling).
• .ha-join-public__game: Class applied to the individual rows representing a game room (default styling).

Example Usage

this.add.haJoinPublicList(250, 250, 400, 400, 'Find a Game', 500);

[scene].add.haJoinPrivateInput

Adds an input with a join button which allows players to enter a public or private game room by roomId.

Parameters

Parameter	Type	Description
x	number	The X coordinate to display the join private input at.
y	number	The Y coordinate to display the join private input at.
label	string	An optional override for the join button's label.
width	number	An optional width to display the join private input at.

CSS Customization

• .ha-join-private: Class applied to the containing <div> of the element (default styling)
• .ha-text.ha-text--join: Classes applied to the text <input> of the element (default styling)
• .ha-btn.ha-btn--join: Classes applied to the <button> of the element (default styling)

Example Usage

this.add.haJoinPrivateInput(250, 250, 'Join Game', 500);