Player Controlled Entities

Player controlled entities, represented by the PlayerEntity class, are entities that are controlled by a player's inputs. Player controlled entities can be either a Model Entitiesor a Block Entities. Yes, that means if you really want, you could even have players control a movable block in your game!

DefaultPlayerEntity Class

If you only need the default player character that can move around, and supports all standard behaviors for HYTOPIA, you'll use an instance of the DefaultPlayerEntity class.

The PlayerEntity class is primarily meant for situations where you need to have full control over player behaviors for inputs, their representative model, etc. PlayerEntity is a lower level implementation that gives more control compared to DefaultPlayerEntity.

PlayerEntity Class & Entity Controllers

The behavior of the PlayerEntity class based on player inputs is dependent on the logic in it's entity controller (playerEntity.controller).

In our Entity Controllers section, we covered the lifecycle of an entity controller. Entity controllers have a special lifecycle method called tickWithPlayerInput(). A PlayerEntity invokes this method of it's controller every tick, passing the current inputs of the player to it.

Through this, the PlayerEntity class, which represents a player controlled entity, is controlled through the logic of it's entity controller based on the input of the player each tick.

To learn more about player inputs and controls, check out Input & Controls

Creating A PlayerEntity

Here's an example from our boilerplate, showcasing how we create a new player entity controlled by a player when they join our game.

world.on(PlayerEvent.JOINED_WORLD, ({ player }) => {
  const playerEntity = new PlayerEntity({
    // PlayerEntity accepts an additional property 
    // in its options, player, which is the player
    // who's inputs will control the actions of this
    // entity. The default PlayerEntityController()
    // is assigned to this entity, since we did not
    // override it by specifying the `controller: new MyCustomController()`
    // property option.
    player,
    name: 'Player',
    modelUri: 'models/players/player.gltf',
    modelLoopedAnimations: [ 'idle' ],
    modelScale: 0.5,
  });
  
  playerEntity.spawn(world, { x: 0, y: 10, z: 0 });
});

You can learn more about the PlayerEntity class options here.