Transitions are how Echo:NPC moves from state to state. Echo:NPC provides a few default transitions which users can use:


    "name": "main",
    //Use set lang to set transitions
    "transitions": {
        "1": ["interact"],
        "2, 3": ["timer 3"] //We can pass data into transitions
    "text": [
        "You just clicked on me!",
        "Timer one!",
        "Timer two!"

Transition arguments

Some transitions take arguments. For example, the timer transition takes in an optional “time” variable, which sets how long the timer is. If not supplied, most arguments will use a default value.

After supplying all optional arguments, all events take an “event override”. Event overrides are used to pick what state to move to, instead of using the default state. If no event is used, Echo will simply go to the next state (first following sub-states, and then following the next argument)


This is the “right click” transition. If no transitions are supplied, this transition is used.

Interact takes no arguments, other than an optional event override.

Examples: interact interact echo:main


This is a simple timer: It will run after the time runs down.

Timer takes one option “time” argument.

Examples: timer timer 6 timer 3.3 timer 4 echo:main


Tests for a right click with a specific item.

interact_has_item takes a required item argument

Examples: interact_with_item minecraft:stone interact_with_item namespace:custom_item interact_with_item minecraft:iron_ingot echo:main


Tests for when a player is within a set distance.

It takes one optional “distance” argument.

Examples: proximity proximity 5 proximity 20.1 proximity 10 echo:main

note There is also a transitions called protected_proximity, which exactly the same as proximity, except it requires the entity to be tagged with echo:active. This can make developing/testing NPCs easier, since you can easily switch on/off proximity interactions.


Tests for when NO players are within a set distance.

It takes one optional “distance” argument.

Examples: proximity proximity 5 proximity 20.1 proximity 10 echo:main

note: Like above, protected_reverse_proximity exists.


Tests for if the entity has a specific tag.

It takes one required “tag” argument, which is the tag it is testing for.

Examples: has_tag despawn has_tag my_tag has_tag something echo:main


Tests if the entity is near a specific mob. Acts a bit like proximity.

It takes a few family, and a sensor-range (default 2).

Examples. near_mob pig near_mob sirlich:example_npc near_mob cow 10 near_mob cow 2 echo:main


Tests if the entity took damage from the player. This is useful for doing left/right interactions.

It takes in deals-damage as an optional parameter (true by default)

Examples: hit_by_player hit_by_player false hit_by_player true echo:main


Pathfinding is the ability to walk to a specific entity family, including the player.

It takes quite a few arguments:

  • Family to path to, defaults to player.
  • Movement speed, defaults to 0.3
  • How close the entity will walk to the target before stopping, defaults to 0
  • Sensor range, how close the entity needs to be before the interaction counts as finished.

Examples: pathfinding pathfinding pig pathfinding pig 1 pathfinding pig 0.3 10 pathfinding pig 0.3 0 20 pathfinding pig 0.3 0 20 echo:main

Adding your own transitions

Want to add your own transitions? Check out the templates document for instructions.