Chat & Commands

Oftentimes, games send chat messages to all players or to a specific set of players to relay important information. Additionally, chat commands are common in games as well, triggering specific behaviors or altering settings when players or a game admin enters some command in chat.

The HYTOPIA SDK allows you to fully control programmatically sending chat messages as well as defining your own chat commands with callbacks.

All chat and chat command functionality is accessed through an instance of the ChatManager class. This singleton is automatically created for each world instance and is accessible via world.chatManager.

A simple example of using chat messages to welcome and tell a player how to play when they join our game.

Sending Chat Messages

There's 2 different ways to send chat messages. The first is broadcasting, which will be received by all players, and the second is sending messages only to a specific player.

Here's a quick example.

startServer(world => {
  world.on(PlayerEvent.JOINED_WORLD, ({ player }) => {
    // only the player that just joined will receive this message
    world.chatManager.sendPlayerMessage(player, 'Welcome to our game!');    
    
    // Send another message to the player on the next line of chat,
    // providing a third hex color argument to change the message color
    world.chatManager.sendPlayerMessage(player, 'Have fun!', '00FF00');
  });
  
  // Send a message every second to all connected players.
  setInterval(() => {
    world.chatManager.sendBroadcastMessage('Another second has passed!');
  }, 1000);
});

Listening For Chat Messages

You can specify a callback for anytime a message is sent by a player, or your game.

This can be done with chat manager events and an event listener!

Here's a quick example.

startServer(world => {
  world.chatManager.on(ChatEvent.BROADCAST_MESSAGE, ({ player, message, color }) => {
    if (player) {
      console.log(`Player ${player.username} sent a new public message: ${message}`);
    } else {
      console.log(`The game sent a new message public message: ${message}`);
    }
  });
});

Creating Chat Commands

Registering chat commands, often preceded with / (but not required), is a great way to add quick functionality to your game, create your own admin level commands like /ban, and more.

You can register a new chat command with world.chatManager.registerCommand()

Here's a quick ping/pong example of chat commands.

startServer(world => {
  // Simple ping/pong command
  // args will be an array of space separated words following /ping
  // IE, "/ping hello world" would give args = ['hello', 'world']
  // Note: "hello /ping" will not work, since our message
  // must start with /ping to register as an invoked command.
  world.chatManager.registerCommand('/ping', (player, args, message) => {
    world.chatManager.sendPlayerMessage(player, 'pong!');
  });
  
  // Alternative ping command, showing that we don't need
  // to use "/"
  world.chatManager.registerCommand('ping', (player, args, message) => {
    world.chatManager.sendPlayerMessage(player.'No / pong!');
  });
});

It's important to note that only one callback can be registered to the same command at a time. If you invoke world.chatManager.registerCommand() with a previously registered command, the previously set callback will be discarded and the callback provided to the most recent invocation of world.chatManager.registerCommand() will be used.

Lastly, you can unregister commands altogether with world.chatManager.unregisterCommand()

Diving Deeper

The ChatManager class is constantly evolving. You can find the latest ChatManager API Reference here.

If there are features that we don't currently support for the ChatManager that you'd like to see added to the HYTOPIA SDK, you can submit a feature request here.