LogoLogo
  • Get Started
  • Getting Started
    • Initial Setup
    • Create Your First Game
    • API Reference
    • Build Your First World Map
    • Multiplayer Testing
    • Use Templates & Examples
    • Styling & Assets
      • Modeling Guidelines
      • Texturing Guidelines
      • Default Assets
  • Build Faster With AI Tools
  • SDK Guides
    • Assets
    • Audio & SFX
      • Audio Manager
    • Blocks & Chunks
      • Block Types
      • Block Type Registry
      • Chunks
      • Chunk Lattice
    • Camera
    • Chat & Commands
    • Debugging
    • Entities
      • Animations
      • Block Entities
      • Colliders & Hitbox
      • Child Entities
      • Entity Controllers
        • Base Entity Controller
        • Pathfinding Entity Controller
        • DefaultPlayer Entity Controller
        • Simple Entity Controller
      • Entity Manager
      • Model Entities
      • Movement & Pathfinding
      • Player Controlled Entities
    • Events
    • Input & Controls
    • Lighting
      • Ambient Light
      • Light Manager
      • Point Lights
      • Spot Lights
      • Sun Light (Directional)
    • Mobile
    • Persisted Data
    • Players
      • Player Manager
      • Persisted Player Data
    • Plugins
    • Physics
      • Colliders
      • Collision Groups
      • Debugging
      • Gravity
      • Raycasts
      • Rigid Bodies
    • User Interface
      • Overlay UI
      • Scene UIs
      • Scene UI Manager
    • Worlds
      • Map Data Format
  • Helpful Resources
    • HYTOPIA Architecture & Platform Overview
    • Useful Third-Party Tools
Powered by GitBook
On this page
  • Flexibility
  • Block Entities vs Model Entities
  • Creating & Spawning An Entity
  • Next Steps
Export as PDF
  1. SDK Guides

Entities

PreviousDebuggingNextAnimations

Last updated 4 months ago

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.

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

  • 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.

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

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.

Learn more about Rigid Bodies
Learn more about Colliders
Model Entities
Block Entities
A block entity constantly spinning, and 3 model entities smoothly tracking our player position.