ENTITY EVENTS DOCUMENTATION
Version: 1.10.0.7

Index#

General Notes#

This document contains details for driving various events via entity .json data. Note that entity events go in behavior packs, and use the same animations and animation controllers setup that are used in resource packs.

Entity events are a way to drive gameplay in the Bedrock engine. These events can typically include slash commands, entity events (e.g. become an adult), and MoLang expressions (e.g. set the MoLang variable "variable.foo" to 3 on a particular entity). Animations and Animation controllers provide a method for driving state machines and timelines for an entity. For example, a particular animation controller could be in a particular state, and running a particular animation, and we want events triggered when entering/exiting that state. Alternately, an "animation" could be running, and we wish to fire off events during that animation. The entity event timeline mechanic makes this possible.

Animation Notes#

Entity events occur in behavior packs, which execute only on the server. As the server side of the game has no visual aspects to it, obviously no bone-based animations can occur. However, a traditional animation is basically a timeline of events, with the events being bone positions for an animated visual rig that moves the entity's visual shape around. The mechanisms for the Bedrock animation system are state machines (Animation Controllers), and timelines (Animations). These concepts apply directly to the triggering of events, thus the animation system can execute on the server (minus the visual aspects), with the intent of driving entity events.

To use entity events, add animation controllers and animations to a behavior pack just as you would to a resource pack. Add animation and animation controllers to an "animations" section in the description field of an entity. These animations and animation controllers will run on the server just as if they were on the client in a resource pack.

{
  "format_version": "1.8.0",
  "minecraft:entity": {
    "description": {
      "identifier": "minecraft:cat",
      ...
      "animations": {
        "anim1": "animation.anim1",
        "anim2": "animation.anim2",
        "anim_controller1": "controller.animation.test1",
        "anim_controller2": "controller.animation.test2"
      },
      ...
    },
    ...
  },
  ...
}

Events#

Events consist of three categories, all represented by a string:
- Entity events
- Slash Commands
- MoLang Expressions

In detail:

Entity Events: Currently, we only support entity events to self, and these take the form "@s event". These are events declared in the events section of the entity definition file. For example, in the cat.json, "minecraft:ageable_grow_up" event causes the kitten to grow up. This would take the form of "@s minecraft:ageable_grow_up"

Slash commands: Any slash command can be invoked, such as "/particle minecraft:example_smoke_puff ~ ~ ~". The assumed entity for the slash command is the invoking entity, so this particular slash command will spawn a smoke puff effect at the entity's location.

MoLang Expressions: This executes a MoLang expression. The primary usage is to set MoLang variables that can be used later. For example, a state transition might be looking at a particluar MoLang variable, and this expression could change that variable. A particle effect on the entity might change color due to MoLang variables that the effect uses for color tints.

Animation Controller Events#

Animation controllers can trigger events on entry or exit of a state. Events to trigger on state entry go in the "on_entry" section, those on exit go in the "on_exit" section.

{
  "format_version": "1.8.0",
  "animation_controllers": {
    "controller.animation.test": {
      "states": {
        "default": {
          "on_entry": [
            "event1",
            "event2",
            "event3"
          ],
          "on_exit": [
            "event1",
            "event2"
          ]
        },
      }
    }
  }
}

Animation Events#

Animations can have a timeline dedicated to events. The "timeline" section contains the event timeline list. Below there are various examples where particular times can trigger a single event, or an array of events:

{
  "format_version": "1.8.0",
  "animations": {
    "animation.test_events": {
      "timeline": {
        "2.0": "@s minecraft:entity_born",
        "4.0": [ "@s minecraft:ageable_grow_up" ]
      },
      "animation_length": 5.0
    },
    "animation.test_molang": {
      "timeline": {
        "0.0": "variable.pop_smoke = 1; variable.pop_bubbles = 0;",
        "3.0": [
          "variable.pop_smoke = 0;",
          "variable.pop_bubbles = 1"
        ]
      }
    },
    "animation.test_commands": {
      "timeline": {
        "1.0": "/tell @a timeline command1",
        "2.0": [
          "/tell @a timeline command 2.1",
          "/tell @a timeline command 2.2"
        ],
        "3.0": [ "/tell @a command 3" ]
      }
    }
  }
}