Players
Players are the starting point of a game! A game in HYTOPIA isn't a game without at least one player.
When a player joins your game, an instance of the Player class is uniquely created internally, identifying each player and exposing different features and controls over their experience.
Players have a number of methods and properties they expose, allowing you to create and control a variety of aspects of the player's overall experience. Let's dive in!
Player Lifecycle
When players attempt to join your server, assuming your game is live on HYTOPIA and is not a local development server, they'll automatically go through the following lifecycle.
Join Attempt - The player attempts to connect to your game server by clicking "Play" on the HYTOPIA game list, or visiting a direct link to your game. HYTOPIA's internal services will automatically assign them to a HYTOPIA managed server instance of your game relative to their geographical region and meaningful number of other players in a selected instance to maximize their gameplay experience. If a player is joining a game from clicking a Join link in their friends list where a friend is currently playing, they will join the server instance their friend is in.
Player Validation - HYTOPIA's internal services will validate the join request by the player to your game server. If the internal validation succeeds, they will join the server, if not, they will be unable to join.
Player Joins - If the validation attempt succeeds, your game instance will automatically handle creating a new player instance in your game server and the
world.onPlayerJoin()callback will be invoked with that player object, allowing you to use your own game logic from there.
Overall, you don't need to worry about any aspects of the player join lifecycle, or player matchmaking and server scaling. The HYTOPIA services automatically manage and handle all aspects of this internally for you without you ever needing to think about it.
Player Properties
A player instance exposes a number of useful properties. Here's a quick overview of some of the most useful.
player.id- A globally unique identifier of the player. This id is they player's public HYTOPIA account id. It will be consistent for any game they join.player.username- A globally unique username of the player. This username is the player's public HYTOPIA username. It will be consistent for any game they join.player.camera- An instance of the PlayerCamera class, automatically assigned to each player upon them joining your game. You can control aspects of the player's in game camera through this. Learn more here: Camera.player.input- The current input state of the player for each given tick. You can learn more here: Input & Controlsplayer.ui- An instance of the PlayerUI class, automatically assigned to each player upon them joining your game. You can control the entirety of the player's in game UI through this. Learn more here: User Interfaceplayer.world- The current world instance in your game that the player is in.
You can find the complete Player API Reference here.
Player Methods
A player instance exposes a number of methods to control their experience in your game with. These range from camera and UI controls, to the ability to force-disconnect them from your game, join a different world instance in your game, and more.
Here's a few notable ones that are most frequently used.
player.disconnect()- Forces the player to disconnect from the game server. Useful for things like kicking players from your game.player.joinWorld(someWorldInstance)- Connects a player to a provided world instance. If they're already in a world, it will automatically handle removing them from the current world. This is useful for things like teleporting players to different world instances, such as uniquely isolated arenas or dungeons, etc.player.leaveWorld()- Removed the player from the world they're currently connected to but orphans them. They'll still be connected to your game server but won't visibly see any gameplay or interactions other than chat messages until you explicitly useplayer.joinWorld()on their player instance to put them into another world.
There's a number of other features available, you can find the most up to date documentation of the Player class in the Player API Reference here.
Diving Deeper
The Player class is constantly evolving. You can find the latest Player API Reference here.
If there are features that we don't currently support for Player that you'd like to see added to the HYTOPIA SDK, you can submit a feature request here.
Next Steps
Player Manager
Documentation of the PlayerManager, used to iterate and search all players.
Last updated