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 });