Entities

Entities are the core piece of any game. An entity is any object in the physical world of the game can move, interacts with physics, and more. Examples of an Entity can be anything from the character controlled by a player, a shop NPC, a vehicle, a movable block or platform, and so much more.

In short, anything that is not a permanently immovable block that makes up a world's terrain is likely best suited to be created as an entity.

A block entity constantly spinning, and 3 model entities smoothly tracking our player position.

Flexibility

Entities are highly flexible. The HYTOPIA SDK exposes the ability to fully control all aspects of an entity, including the rigid body and collider(s) representation of an entity within the game engine. The SDK will automatically assume and infer sane defaults for entities, but allows you to override any of them.

You can learn more about the Rigid Body and Colliders used to represent the physical nature of an entity here.

Block Entities vs Model Entities

Entities are represented by either a GLTF (.gltf) format model from your assets folder - we call these Model Entities. Or, by a size and block texture, we call these Block Entities.

  • Model Entities - Model entities are great for characters, enemies, NPCs, animals, unique terrain models that interact with the world, and much more

  • Block Entities - Block entities are great for moving platforms, blocks that can be push/pulled for various puzzle or terrain traversing, and more.

Creating & Spawning An Entity

Here's an example of how to create and then spawn an Entity. An entity will not exist in the game until its .spawn() method is called. An entity can be despawned at any time with .despawn(). Once an entity is despawned, it can be respawned again with .spawn() .

startServer(world => {
  // Enable debug rendering so we can see the collider shape
  // of our entities. Please note that enabling this in a large
  // world or with many entities spawned will severely impact
  // game client performance. This is because the lines to draw
  // the physics collider representations are sent to the client
  // every tick, and with a large world and/or many colliders, this
  // can be many megabytes of data, sending 60 times per second,
  // choking the websocket even on a local connection.
  world.simulation.enableDebugRendering(true);

  // Create a block entity that spawns
  // or despawns every second
  const blockEntity = new Entity({
    blockTextureUri: 'blocks/bricks.png', // A texture URI without a file extension will use a folder and look for the textures for each face in the folder (-x.png, +x.png, -y.png, +y.png, -z.png, +z.png)
    blockHalfExtents: { x: 0.5, y: 0.5, z: 0.5 },
    // The collider & rigid body will automatically be
    // inferred and created by the blockHalfExtents.
    // You may override this by using rigidBodyOptions.
    // blockHalfExtents will always represent the visual
    // size of the block entity, no matter its colliders.
  });
  
  setInterval(() => {
    if (blockEntity.isSpawned) {
      blockEntity.despawn();
    } else {
      blockEntity.spawn({ x: 4, y: 2, z: 6 });
    }
  }, 1000);
  
  // Create a skeleton entity (model entity), an approximate hitbox collider for
  // physics will be automatically generated based on the model itself and the scale.
  const skeletonEntity = new Entity({
    modelUri: 'models/npcs/skeleton.gltf',
    modelLoopedAnimations: [ 'idle' ],
    // Scale is the proportional model size relative 
    // to its size in its .gltf file
    modelScale: 0.8,
    rigidBodyOptions: {
      enabledRotations: { x: false, y: true, z: false }, // Only allow rotations around Y axis (Yaw)
    },
  });
});

Next Steps

Entities are incredibly powerful and support a variety of features. We strongly recommend you check out the following guides to gain a better understanding of the different things you can do with entities.

Animations

Learn more about controlling GLTF animations for Model Entities.

Block Entities

Learn more about block entities through common use cases and examples.

Entity Controllers

Learn more about entity controllers to create unique movement and behaviors.

Entity Manager

Learn how to use a world's Entity Manager to iterate entities in a world.

Model Entities

Learn more about model entities and GLTF model considerations.

Movement & Pathfinding

Learn how to use the SimpleCharacterController for pathfinding, or create your own controller.

Player Controlled Entities

Learn about the PlayerEntity and using player inputs to control player entity behavior.

PreviousDebuggingNextAnimations

Last updated