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
Export as PDF
  1. SDK Guides
  2. Entities

Block Entities

Block entities are exactly what they sound like. A block, that behaves like an entity. This allows you to create blocks of any size that interact with the physical world. They can move, rotate, have impulses and velocities applied to them, and so much more.

Common Uses & Examples

Let's dive into some of the most common use cases of block entities.

Moving Platform

Probably the most common use, let's create a block entity that is a platform in the sky that moves at a constant speed in the +z/-z axis direction.

const blockPlatform = new Entity({
  blockTextureUri: 'blocks/grass', // 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: 1, y: 0.5, z: 1 },
  rigidBodyOptions: {
    type: RigidBodyType.KINEMATIC_VELOCITY, // Kinematic means platform won't be effected by external physics, including gravity
    linearVelocity: { x: 0, y: 0, z: 3 }, // A starting velocity that won't change because it's kinematic
  },
});

// Clamp the z range the platform moves back and forth between
blockPlatform.on(EntityEvent.TICK, () => {
  const position = blockPlatform.getTranslation();

  if (position.z < -9) {
    blockPlatform.setLinearVelocity({ x: 0, y: 0, z: 3 });
  }

  if (position.z > 8) {
    blockPlatform.setLinearVelocity({ x: 0, y: 0, z: -3 });
  }
});

blockPlatform.spawn(world, { x: 3, y: 3, z: -7 });

Pushable Block

A block that we can push is great for puzzles and other things.

// Block entity is dynamic by default, meaning it will 
// interact with external forces/physics, including gravity
const movableBlock = new Entity({
  blockTextureUri: 'blocks/sand.png',
  blockHalfExtents: { x: 0.5, y: 0.5, z: 0.5 }, 
});

// For the sake of demonstration, we can even
// have a callback when we push the block!
movableBlock.on(EntityEvent.ENTITY_COLLISION, ({ otherEntity, started }) => {
  if (started) {
    world.chatManager.sendBroadcastMessage('The sand block was pushed!');
  }
});

movableBlock.spawn(world, { x: -4, y: 10, z: -6 });

Pushable Block With Locked Rotations & Translations

const movableBlock = new Entity({
  blockTextureUri: 'blocks/sand.png',
  blockHalfExtents: { x: 0.5, y: 0.5, z: 0.5 }, 
  rigidBodyOptions: {
    type: RigidBodyType.DYNAMIC, // default
    // Disable all rotations
    enabledRotations: { x: false, y: false, z: false },
    // Disable X axis, only allowing
    // movement (translation) on the Y and Z axes
    enabledTranslations: { x: false, y: true, z: true }, 
  }
});

movableBlock.spawn(world, { x: -4, y: 10, z: -6 });

Teleporting Block

Perhaps we want to create a block that teleports to different coordinate every few seconds for a platforming game, here's how we can do that.

const teleportCoordinates = [
  { x: 1, y: 3, z: 2 },
  { x: 5, y: 7, z: -5 },
  { x: 3, y: 5, z: 0 },
];
const blockPlatform = new Entity({
  blockTextureUri: 'blocks/grass', // 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: 1, y: 0.5, z: 1 },
  rigidBodyOptions: {
    type: RigidBodyType.KINEMATIC_POSITION, // Kinematic means platform won't be effected by external physics, including gravity
  },
});

blockPlatform.spawn(world, teleportCoordinates[0]);

// Pick a random coordinate to teleport to every 5 seconds
setInterval(() => {
  const teleportIndex = Math.floor(Math.random() * teleportCoordinates.length);
  blockPlatform.setTranslation(teleportCoordinates[teleportIndex]);
}, 5000);

Heavy Pushable Block

Pushable blocks are fun, but what if we want a block that multiple entities would need to push to be able to easily move? We can do that by creating a block with a heavier mass.

const movableBlock = new Entity({
  blockTextureUri: 'blocks/sand.png',
  blockHalfExtents: { x: 0.5, y: 0.5, z: 0.5 }, 
  rigidBodyOptions: {
    type: RigidBodyType.DYNAMIC,
    // Higher number = harder to push, play with 
    // changing this for different results
    additionalMass: 10,
  }
});

movableBlock.spawn(world, { x: -4, y: 10, z: -6 });
PreviousAnimationsNextColliders & Hitbox

Last updated 3 months ago