Model Entities

Model entities are an entity that is visually representing by a .gltf or .glb model. Model entities are the most common type of entity you'll use. For example, players, enemies in your game, fixed and moving elements like lamp-posts or birds, and more, will typically be created using an Entity.

Common Uses & Examples

Let's dive into some common patterns when using model entities.

Bullet Entity

Some games may want a bullet that moves through the physical world and registers a hit when it intersects with another entity. You could alternatively just use a Raycasts for this, but in this example we'll use an entity.

const bullet = new Entity({
  name: 'Bullet',
  modelUri: 'models/bullet.gltf',
  modelScale: 0.3,
  rigidBodyOptions: {
    type: RigidBodyType.KINEMATIC_VELOCITY, // Kinematic means entity's rigid body will not be affected by physics. KINEMATIC_VELOCITY means the entity is moved by setting velocity.
    linearVelocity: { // Setting the linear velocity on a Kinematic type means it will move at a constant speed, unaffect by gravity or other forces
      x: direction.x * BULLET_SPEED,
      y: direction.y * BULLET_SPEED,
      z: direction.z * BULLET_SPEED,
    },
  },
});

bullet.on(EntityEvent.ENTITY_COLLISION, ({ otherEntity, started }) => {
  if (!started) { return } // we only care about the initial hit, not when it stops
  
  // Perform your bullet logic here, the otherEntity is the entity the bullet hit.
  // You can do things like despawn the entity that was hit, use your own damage
  // logic, and more. 
});

Extra Large Entity

With model entities, you can control their physical scaling in the world. This allows you to scale up or down the model of the entity relative to its initial size. We'll use model scale to create a massive spider.

const spider = new Entity({
  modelUri: 'models/npcs/spider.gltf',
  modelScale: 10, // 10x the default scale
  modelLoopedAnimations: [ 'idle' ],
});

// Spawn the spider in the world.
spider.spawn(world, { x: 0, y: 3, z: -15 });

Now, we'll see a massive spider!

Automatic Model Optimizations

Typically, most model editing software will export your .gltfand .glbmodels with many internal meshes and named nodes. The more unique meshes & named nodes that make up your model, the more strain it puts on a device's GPU when your game is played. If you have a variety of loaded entity models at the same time, or your models have many complex meshes, this can cause a significant degradation of frame rate and overall game performance for players.

Because of this, the HYTOPIA SDK when you run your game server, and when your game is uploaded to the HYTOPIA platform, will automatically run a variety of optimization passes on each of your models and output them into a hidden .optimizedfolder in your game's assetsfolder.

Each model is ran internally through our gltf-transform based optimizer, performing operations like merging redundant meshes, named nodes, and other optimizations in various combinations, resulting in multiple .gltfmodels for the same input model, outputted into the automated .optimizeddirectory.

The HYTOPIA client based on how you use your models will try to load the most optimal version of that model at runtime. This results in the best model for performance & your usage being used automatically, dramatically improving device frame rate and performance.

Overall, you don't need to manage or do anything with this system. It is automated and 100% internally managed.

If for some reason you are experiencing unusual behavior that you think is coming from optimized models, you can disable model optimization globally by invoking the following method of the ModelRegistry class at the beginning of your index.ts game script.

// If you're disabling the optimizer, this boolean must be set before `startServer()`.
ModelRegistry.instance.optimize = false;

startServer(world => {
  // game code...
});