MCME-Entities is a Minecraft Spigot server plugin that allows you to create various kinds of virtual entities. These entities don’t exist in the minecraft server but are simulated by sending network packets using ProtocolLib. This concept avoids server lag from large amounts of entities and allows more direct control of the entity behaviour.

Entity Types
Almost every type of vanilla minecraft entity can be simulated. Additionally the plugin directly reads animation files exported by Animated Java to create animated custom entities.

Entity Behaviour
There are various Goals that can be assigned to a virtual entity:

• Follow another entity (Virtual entity or player)
• Watch another entity
• Melee Attack another entity (ranged is planned)
• (planned) Attack closest entity of a given group
• (planned) Defend a position (attack approaching entities)
• Follow a chain of waypoints (once or repeated)
• Randomly move between waypoints

Talking
Entities can talk in speech balloons. Speech balloons can be placed left, right or on top of an entity and are rotated around the entity individually for each viewer.

Viewer
You can select which players will see a virtual entity by command and also permission based.

Pathfinding
The pathfining of virtual entities is completely custom made for this plugin. It’s able to find paths on quite long distances and is navigating around obstacles. But it’s not guaranteed to work in complex terrain. It’s using a rather simple algorithm that favours speed over general functionality. The approach is geared to our needs at MCME server where we use virtual entities to display movie-like scenes.

Animations
Animations for custom entities can be chosen by command or played automatically by animation name. Plugin will check for three states of the entity:

• type of movement (upright,flying,falling,gliding,swimming or sneaking),
• speed of movement (stand,slow,walk or sprint)
• action (idle,attack,interact,hurt or death).

Animation names can contain all three states like:

• upright.walk.attack
  will play when the entity moves upright on ground (not sneaking) with walking speed and attacks.

Animation names may omit one or two states like:

• flying.walk
  will play when the entity flies with walking speed for all actions that have no more specific animation assigned.
• upright.attack
  will play when the entity attacks while being upright on ground no matter which movement speed (except there is a more specific animation defined).

Animation names may contain leading parts of your own choice. The plugin used animations names only after the key “animations” or the animation filename (whatever comes last).

Entity Interaction
Player attacks at a virtual entity are detected by the MCME-Entities plugin. If an entity is configured to be vulnerable players can deal damage.
Right-click interaction with a virtual entity triggers events in the Entities-API plugin.
Virtual entities can attack and hurt players.

Selection
Players can select a virtual entity by right-clicking at it with stick in hand. With shift+right-click an entity is added to the players selection.

Commands
/vserver reload | restart
Plugin management command. Depending on argument reloads the plugin config or restarts the entities server. Restarting the entities server removes all virtual entities.

/vspawn <entity_type> <entity_goal> [data_file [name]]
Spawns a virtual entity and sets the command sender’s selection to it.

• <entity_type> can be most bukkit entity types (e.g. “skeleton”) or custom types “baked_animation” and "winged_flight"
• <entity_goal>can be one of this list:
  • hold_position
  • attack_entity
  • watch_entity
  • Follow_entity
  • Follow_checkpoints
  • Random_checkpoints
  • Goto_location
• [data_file] is used only for custom types, file must be present in animation folder
• [name] entity name to address it (not used for display name). May be present only after [data_file] argument.

/varmy <size> <entity_type> <entity_goal> [data_file [name]]
Spawns an army of virtual entities.

• <size> number of entities in a row and also number of rows. Actual number of entities is size*size.
• <entity_type> see command /vspawn
• <entity_goal> see command /vspawn
• [data_file] see command /vspawn
• [name] see command /vspawn. Actual entitiy names are name1, name2, name3, ...

/vremove [name]
Removes virtual entities. Without a specified [name] all entities selected by the player who issues the command are removed.

• [name] of the entity to remove. 'all' may be used to remove all virtual entities.

/vselect
Manages selections of the player who issues the command.
Subcommands

• [selector] target entity selector. Currently @p is implemented which uses the player himself as target entity. Also it's possible to use an entity name as selector, e.g.: /vselect entity target Eriol_Eandur

/vset
Set properties of all entities selected by the player.
Subcommands:

/vsave <filename>
Saves all selected entities to file.

/vload <filename>
Loads virtual entities from file.

/vanimate play | frame <animation_ID> [frame_ID]
Plays an animation or displays an animation frame.

• <animation_ID> identifier of the animation (see Animations). May be set to auto to give control of animations to the plugin.
• [frame_ID] index of the frame to display. Used only for subcommand 'frame'.

/vsay <position> <duration> <message>
Displays a speech ballon.

• <position> Can be 'l'eft, 'r'ight or 't'op.
• <duration> in server ticks
• <message> Text of the speech ballon. For line feeds use backslash '\'. For color codes use '&' instead of '§'.

/vfactory [<property> <value>]
Changes properties of the entity factory associated to the player who issues the command. This factory is used for /vspawn and /varmy commands. Without argument it displays current factory settings.

• <property> of the factory to change. Use tab complete to see all properties.
• <value> to set the property to.

Entities-API
The Entities-API allows custom plugins to create and remove virtual entities and interact with them. The Entities-API allows you to implement special behaviour of entities by creating custom goals. Also there is an Event API with many events related to virtual entities.
Other plugins can register listeners in the Entities-API to react to these events.

The following classes are intended to be used by external plugins. Calling methods of other classes might lead to unexpected results and is not supported.

class EntityAPI
Main entry point. Use to spawn, access and remove virtual entities, register and unregister event listeners.

interface Entity
Interface to safely access and change entity properties.

class VirtualEntityFactory
Class to provide information about entities during the spawn process.

class VirtualEntityGoalFactory
Class to provide information about entity goals.

Events
Listening to events works pretty much the same way as listening to Bukkit events. Event listener must implement flag interface McmeEventListener and event handler methods in the listener class must have annotation @McmeEventHandler.

Custom Goals
New entity behaviour can be created by implementing interface Goal. Method doTick() is called by the entity server every tick and method update() is called every getUpdateInterval() server ticks. Custom goals need to be applied to an entity by method Entity.setGoal(Goal goal).