This plugin can be uses to spawn and control virtual entities of MCME-Entities plugin by defining events which trigger actions when specified conditions are met.

Commands

Script command
Manages plugin behavior.

• /scripts import <type> <filename>
  Imports a file from the MCME Drive. Argument type can be "animations", "entities" or "scripts". Argument filename must be specified without file extension.
• /scripts export <type> <filename>
  Exports a file from the MCME Drive. Argument type can be "debug", "animations", "entities" or "scripts". Argument filename must be specified without file extension. Type "debug" exports debug log file to scripts folder using filename "debug.txt".
• /scripts list <module>
  Lists all registered objects of a module. Valid modules are "script" and "trigger" (=event).
• /scripts debug filter <player> | console | file <script> | all | none
  Sets debug output filter for a player (game chat), server console or debug log file to log debug output for a specific script only (or to log all scripts or to log no scripts).
• /script debug <module> [level]
  Sets debug output level. Valid levels are "verbose", "info", "warning", "severe" and "critical". Valid modules are displayed by the command. Module "all" affects all modules. Without optional argument "level" debug level is cycled. Module "all" without level argument sets all modules to debug level "verbose" and module "none" without level argument sets all debug levels to "critical".
• /scripts reload
  Reloads the plugin config and all scripts. Needs to run after importing a script.
• /scripts disable
  Disables all scripts and removes all entities created by them.
• /scripts enable
  Enables scripts.
• /scripts external <script> <event> <arguments>
  Triggers an external event named <event> that is defined in <script>. Meaning of <arguments> depend on the event.
• /scripts wand <script> <event> <argument>
  Binds command /scripts external <script> <event> <argument> to the main hand item. Execution by right-click.

Party command
Manages quest parties. By default each player has a solo party to do quests. Players can be in more than one party at the same time but they can have only one active party.

• /party join <party>
  The player who issues the command joins <party>.
• /party leave <party>
  The player who issues the command leaves <party>.
• /party create <party>
  Creates a new party named <party>. There might be parties with duplicate names.
• /party disband <party>
  Disbands <party>.
• /party activate <party> (not yet implemented)
  Sets <party> as active party of the player who issues the command.

Writing a Script
For writing scripts you should use some kind of json editor (e.g. JSON Editor Online) to avoid syntax errors.

Script
Scripts control a scene of several entities with complex behavior. A script is activated only when a given condition (or a set of conditions) is met. A frequent condition is that a player is in a specified area. If the condition is not met all entities of the script are remove and all event triggers are unregistered to avoid server lag. Every script is loaded from a separate .json file that is expected to contain a single json object.
Json elements:

• "name": String
  Name of the script
• "condition" or "conditions": Condition or array of Condition
  Condition(s) to activate this script. Without condition a script is active all the time (possible source of server lag).
• "met_all_conditions": Boolean (default: false)
  If all conditions must be met to activate the script.
• "event" or "events": Event or array of Event
  Event(s) to register when script is activated and unregister when script is deactivated.
• "entity" or "entities": Entity or array of Entity
  Entities that spawn when a player comes into a specified range and despawn when there is no player in range.
• "access_stage": Boolean (default: false)
  Used in quest stages only.

Quest
Quests are sets of Stages that interact only with a group of players aka. a party. Stages are scripts that are enabled and disabled by actions. Access stages are used to create a new quest of a party. If a party mets the condition of an access stages a new instance of the related quest is created.
For doing quests parties need to be active. A party is active only when all players in the party are online and have this party chosen as active party.
Json Elements:

• "public": Booelan (default: false)
• "unique": Boolean (default: false)
• "stages": Compound of scripts

Event
Events are the core feature of MCME-Scripts plugin. When an Event is called it checks a list of condtions and depending on the result triggers actions. As events can register and unregister other events complex behaviour is possible. Also each event can follow a decision tree to react on combinations of conditions.
Json elements common to all events:

• "name": String
  Used by unregister_event action to identify an event.
• "type": String
  Events are called in various circumstances depending on their type:
  • "real_timed"
    Called at a specific real world date and time (Central European Time Zone)
  • "real_periodic"
    Called periodically at specific real world time intervals.
  • "server_timed"
    Called at a specific server daytime.
  • "server_periodic"
    Called periodically at specific server tick intervals. On busy servers this event type might increase lag. Consider using "real_periodic" events instead.
  • "player_talk"
    Called when a player sends a chat message that it preceded by an exclamation mark "!".
  • "player_join"
    Called when a player joins a server.
  • "player_quit"
    Called when a player leaves a server.
  • "player_virtual_attack"
    Called when a player attacks a virtual entity.
  • "virtual_talk"
    Called when a virtual entity says something
  • "virtual_stop_talk"
    Called when a virtual entity stops saying something
  • "goal_finished"
    Called when a virtual entity finshes an assigned goal.
  • "animation_change"
    Called when an animated virtual entity changes animation.
  • "selection"
    Called when the selected entities of a selector changes.
• "call_once": Boolean (default: false)
  Set this to true to unregister the event after first call no matter if conditions are met and actions are triggered.
• "then": Subevent
  This subevent is called if condition of this event is met and actions are triggered.
• "else": Subevent
  This subevent is called if condition of this event is not met and no actions are triggered.
• "location": Location (default: special, see below)
  Location associated with this event. Some conditions and actions refer to this event location (see there). If no event location is specified location of the player or entity associated with the event is used.
• "player": Selector (default: "@s")
  Player associated with this event. Some conditions and actions refer to this event player (see there).
• "entity": Selector (default: "@s")
  Virtual Entity with this event. Some conditions and actions refer to this event entity (see there).
• "met_all_conditions": Boolean (default: false)
  If this is set to true all conditions of this event need to be met to trigger actions (logical and). Otherwise just one condition needs to be met to trigger actions (logical or).
• "condition" or "conditions": Condition or Array of Condition
  Conditions which are checked when this event is called.
• "action" or "actions": Action or Array of Action
  Actions which are triggered depending on condition checks.

Event specific Json elements:

• "real_timed" event:
  • "time": String
    Must be a valid Date/Time string of format "YYYY-MM-DDThh:mm:ss".
    Example: "2019-07-26T13:15:00".
• "server_timed" event:
  • "time": Integer
    Server daytime in ticks.
• "real_period"event:
  • "period": Integer
    Period in milliseconds.
• "server_period" event:
  • "period": Integer
    Period in server ticks.
• "animation_change"event:
  • "current_animation": String (default: ignore)
    If this is set the name of the current animation needs to match this string. Otherwise the event is not triggered.
  • "next_animation": String (default: ignore)
    If this is set the name of the next animation needs to match this string. Otherwise the event is not triggered.
  • "use_all_entities": boolesn (default: false)
    If this is set to true the event will fire for all entities otherwise only for entities of the same script as the event.
• "player_virtual_attack"event:
  • "use_all_entities": boolesn (default: false)
    If this is set to true the event will fire for all entities otherwise only for entities of the same script as the event.
• "virtual_talk"event:
  • "use_all_entities": boolesn (default: false)
    If this is set to true the event will fire for all entities otherwise only for entities of the same script as the event.
• "virtual_stop_talk" event:
  • "use_all_entities": boolesn (default: false)
    If this is set to true the event will fire for all entities otherwise only for entities of the same script as the event.
• "goal_finished" event:
  • "use_all_entities": boolesn (default: false)
    If this is set to true the event will fire for all entities otherwise only for entities of the same script as the event.
• "selection"event:
  • "select": Selector
    Selection that is observed by this event.
  • "period": int
    Period in server ticks at which changes are checked.
  • "process": String
    enter -> Event is called when an entity is added to the selection.
    leave -> Event is called when an entitiy is removed from the selection.

Subevent
Subevents are events that are called by other events. They work the same as events but are limited to Json elements "condition", "action", "met_all_conditions","then", "else". Subevents use same location and event entity as parent event.

Entity
Entity section of a script is just for convenience. All you can do in entity section is also possible (but tedious) by defining events. Entities defined in this section will spawn when the first player enters their spawn range and will despawn when the last player leaves their spawn range.
Json elements:

• "spawn_data": String, Spawn Data or Array of Spawn Data
  If a string is specified it is interpreted as file name of an entity saved by MCME-Entities plugin. Otherwise spawn data are read directly from the script. It's usually best to uses saved entities as MCME-Entities provides in-game commands to create those.
• "name": String
  Name of the spawned entity. Can be used for selector argument "name". Overrides name from "spawn_data". If more than one entity is spawned "name" will be used as group name followed by a number.
• "spawn_range": Integer (default: 64)
  If any player is within this range of the spawn location the entity will be active.
• "view_distance": Integer (default: special, see below)
  View distance of all spawned entities. If this value is not provided are set to 90% of "spawn_range".
• "event" or "events": Event or Array of Event
  Event or events that are registered when the entity is activated and unregistered when the entitiy is deactivated.

Condition
Conditions determine if an event triggers any actions. There are some condition types already implemented. If you need any other type please tell in Development section of this forum or Discord.
Json elements common to all conditions:

• "type": String
  Condition type, must be one of this list or condition is ignored:
  • "talk":
    Is met when one or all (depending on "match_all" element) selected virtual entities are currently talking.
  • "no_talk":
    Is met when one or all (depending on "match_all" element) selected virtual entities are currently not talking.
  • "goal_type":
    Is met when one or all (depending on "match_all" element) selected virtual entities have a specific type of goal assigned or not assigned (depending on "negate" element).
  • "location_proximity":
    Is met when a specified number of selected entities is in proximity of a given location.
  • "player_proximity":
    Is met when a specified number of selected entities is in proximity of a given player.
  • "entity_proximity":
    Is met when a specified number of selected entities is in proximity of a given entity.
  • "animation":
    Is met when one or all (depending on "match_all" element) selected animated virtual entities are in a specific animation state.
  • "server_daytime":
    Is met when server daytime at a world is in (or not in) a specific interval.
  • "player_online":
    Is met when a specified number of selected entities is online.
  • "message":
    Is met if an event related message is matching the search string. Wildcard * may be used ad start and end of search string.

Condition specific Json elements:

• "talk" and "no_talk"conditions:
  • "select": Selector (default: "@s")
    Selection of virtual entities whose talking status will be checked.
  • "match_all": Boolean (default: false)
    If all selected entities need to match the condition or just a single one.
• "goal_type"condition:
  • "negate": Boolean (default: false)
    If true selected entities must NOT match the given goal type to met the condition.
  • "goal_type": String
    Specifies which goal type selected entities should be checked for.
  • "select": Selector (default: "@s")
    Selection of virtual entities whose goal types will be checked.
  • "match_all": Boolean (default: false)
    If all selected entities need to match the condition or just a single one.
• "location_proximity", "entity_proximity" and "location_proximity"conditions:
  • "select": Selector (default: "@s")
    Selection of virtual entities whose quantity will be compared against the criterion.
  • "center": Location or String
    Defines the selection center. Depending on condition type this must be a Location, a name of a player or a name of a virtual entity.
  • "criterion": String
    Consists of an comparative operator followed by a number. Operators are
    • "=" equal
    • "!=" or "<>" not equal
    • "<" less than
    • ">" greater than
    • "<=" less or equal
    • ">=" greater or equal
• "animation"condition:
  • "select": Selector (default: "@s")
    Selection of animated virtual entities whose animation state will be checked.
  • "current_animation": String (default: ignore)
    Name of animation the entity needs to play currently to mach the condition. If not specified all animation names are accepted.
  • "manual_animation": Boolean (default: ignore)
    If the virtual entity is set to manual animation control.
  • "manual_animation_override": Boolean (default: ignore)
    If the virtual entity is currently playing an anmation either triggered by command or an event (e.g. attack, injury)
  • "instant_animation_switching": Boolean (default: ignore)
    If the virtual entity is set to switch animations instantly as opposite to finish an animation before switching.
• "server_daytime"condition:
  • "world": String
    Name of the world where to check daytime.
  • "start": Integer
    Begin of interval to check in server daytime ticks.
  • "end": Integer
    End of interval to check in server daytime ticks. Must be greater than "start".
  • "negate": Boolean (default: false)
    If the condition is met when daytime is outside the given interval.
• "player_online"condition:
  • "select": Selector (default: "@s")
    Selection of players to check if they are online. Quantity of these players will be compared against the criterion.
  • "criterion": String
    Consists of an comparative operator followed by a number. Operators are
    • "=" equal
    • "!=" or "<>" not equal
    • "<" less than
    • ">" greater than
    • "<=" less or equal
    • ">=" greater or equal
• "message" condition:
  • "message": String (default: "*")
    Search string to compare the event message with.
  • "negate": Boolean (default: false)
    Negates the outcome of the string comparison.

Action
Actions are triggered by events when their conditions are met. There are quite some types of Actions already. If you need anything else please tell me at development section of this forum or on Discord.
Json elements common to all actions:

• "type": String
  Action type, for more information see the list of action specific Json elements.
• "delay": Integer
  Delay in server ticks (1/20 second) before this actions takes effect.

Action specific Json elements:

• "action_bar":
  Displays a text in action bar of selected players.
  • "select": Selector (default: "@s")
    Selection of players who will see the action bar.
• "animation":
  Sets animation of selected virtual entities.
  • "select": Selector (default: "@s")
    Selection of animated virtual entities whose animation will be changed.
• "boss_bar_add":
  Creates and displays a boss bar to selected players.
  • "select": Selector (default: "@s")
    Selection of players who will see the boss bar.
• "boss_bar_edit":
  Edits a boss bar previously created by a boss_bar_add action.
• "boss_bar_remove":
  Removes a boss bar from selected players.
  • "select": Selector (default: "@s")
    Selection of players who will be removed from the boss bar.
• "despawn":
  Despawns selected virtual entity.
  • "select": Selector (default: "@s")
    Selection of virtual entities that will despawn.
• "entity state":
  Sets animation state of one or more virtual entity.
  • "select": Selector (default: "@s")
    Selection of virtual entities whose animation state will be changed.
• "execute_command":
  Makes selected players dispatch a command
  • "select": Selector (default: "@s")
    Selection of players who will all execute the given command.
• "explosion":
  Creates an explosion.
• "eye_effect":
  Cages selected players in a portal block.
  • "select": Selector (default: "@s")
    Selection of players who will all caged individually.
• "firework":
  Launches a firework rocket.
• "give_chest":
  Places a chest in front of each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities who will each get a chest.
• "give_item":
  Adds one or more items to each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities who will each get the items.
• "remove_item":
  Removes one or more items from each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities who will lose the items.
• "item_rain":
  Makes items rain down around each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities who will be in the item rain.
• "potion_effect_add":
  Adds a potion effect to each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities who will get the potion effect.
• "potion_effect_remove":
  Removes a potion effect from each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities who will loose the potion effect.
• "set_enemy":
  Sets the enemies of each selected virtual entity.
  • "select": Selector (default: "@s")
    Selection of virtual entities whose enemies will be set.
  • "enemies": Selector (default: "@s")
    Selection of entities that will become enemies of the selected entities.
• "set_goal":
  Assigns a goal to selected virtual entities.
  • "select": Selector (default: "@s")
    Selection of virtual entities that will get a new goal assigned.
  • "goal": String or Goal
    If a string is specified it is interpreted as file name of an entity saved by MCME-Entities plugin. The goal of the first entity in that file will be used. Otherwise goal data are read directly from the script.
  • "goal_target": Selection (default: "@s")
    Selection of entities that will be used as goal targets.
• "set_server_time":
  Sets server daytime.
• "start_sound":
  Plays a sound or music for all selected players (by OpenAudioMC plugin)
  • "select": Selector (default: "@s")
    Selection of players who will hear the sound.
• "stop_sound":
  Stops playing OpenAudioMC sounds for all selected players.
  • "select": Selector (default: "@s")
    Selection of players whose sound will be stopped.
• "spawn":
  Spawns one or more (virtual) entities.
  • "spawn_data": String or SpawnData
    If a string is specified it is interpreted as file name of an entity saved by MCME-Entities plugin. Otherwise spawn data are read directly from the script.
  • "lifespan": Integer (default: -1)
    Lifespan of the spawned entity. Entities with negative lifespan will not despawn.
  • "server_side": Boolean (default: false)
    With this set to true a vanilla entity that is controlled by the server is spawned instead of a virtual entity.
• "spawn_relative":
  Spawns one or more (virtual) entities relative to each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities. Relative to the location of each entity in this selection virtual entities specified in this action will spawn.
  • "spawn_data": String or SpawnData
    If a string is specified it is interpreted as file name of an entity saved by MCME-Entities plugin. Otherwise spawn data are read directly from the script. Each entity in the spawn data is spawned relative to each selected entity.
  • "location": Location
    Location relative to each selected entity at which first entity will spawn. For example (0,0,0) would spawn directly at the selected entity.
  • "goal": String or Goal
    If a string is specified it is interpreted as file name of an entity saved by MCME-Entities plugin. The goal of the first entity in that file will be used. Otherwise goal data are read directly from the script.
  • "goal_target": Selection (default: "@s")
    Selection of entities who will be used as goal targets.
  • "checkpoints": Array of Location
    Will be used by waypoint related goals. Locations will be interpreted relative to each selected entity.
  • "server_side": Boolean (default: false)
    With this set to true a vanilla entity that is controlled by the server is spawned instead of a virtual entity.
  • "lifespan": Integer (default: -1)
    Lifespan of the spawned entity. Entities with negative lifespan will not despawn.
  • "spread": Double (default: 0)
    Distance between spawned entities and also between entity rows.
  • "x_edge": Integer (default: sqrt of quantity)
    Width of each row of spawned entities. After spawning x_edge entities a new entity row will begin. With default value entities are spawned roughly in a square.
  • "quantity": Integer (default: 1)
    Each entity in spawn data is spawned "quantity" times for each selected entity.
  • "on_ground": Boolean (default: true)
    Whether entities should spawn on terrain (instead of in mid-air or in solid blocks). y-coordinate will be adapted to place entities on terrain.
• "random_spawn":
  Spawns one or more virtual entities at random locations relative to a given location or each selected entity.
  • "select": Selector (default: "@s")
    Selection of entities. Around the location of each entity in this selection virtual entities specified in this action will spawn randomly.
• "talk":
  Makes selected virtual entites say something.
  • "select": Selector (default: "@s")
    Selection of virtual entities who will talk.
  • "layout": Layout
    Layout for speech balloons.
  • "message": String
    Message text each selected entity will say.
  • "duration": Integer
    Duration of a speech bubble to last in server ticks.
• "stop_talk":
  Makes selected virtual entities stop talking.
  • "select": Selector (default: "@s")
    Selection of virtual entities who will stop talking.
• "teleport":
  Teleports selected virtual entities or players to a location
  • "select": Selector (default: "@s")
    Selection of players who will be teleported.
  • "location": Location
    Teleportation target Location.
  • "spread": Double (default: 0)
    Distance between players at teleportation target. (double check!)
• "title":
  Displays a title to each selected player.
  • "select": Selector (default: "@s")
    Selection of players who will see the title.
• "register_event"
  Register (activate) a new event.
  • "event" or "events": Event or Array of Events
    Events that will be registered (become active).
• "unregister_event":
  Unregister (deactivate) an event.
  • "name": String or Array of String
    Name(s) of events to unregister.
• "enable_stage":
  Used in quest stages only. Enables a named stage of that quest.
  • "name": String
    Name of the stage to enable.
• "disable_stage":
  Used in quest stages only. Disables a named stage of that quest.
  • "name": String
    Name of the stage to disable.
• "set_Tag":
  Used in quest stages only. Stores a bit of information, a tag.
  • "name": String
    Name of the tag to store.
  • "value": String (other types might be added later)
    Value of the tag.
• "delete_tag":
  Used in quest stages only. Deletes a stored tag.
  • "name": String
    Name of the stage to delete.

Selector
Selections are strings used to specifiy which entity or group of entities should be used in a condition or action. They work very similar to Minecraft target selectors. Each selector must have a selector type which may be followed by one or more selector arguments in squared brackets, separated by commas.
Selectors that are used in quest stages select players only from the quest party.

Selector Types:

• @p: select nearest player
• @a: select all players
• @r: select a random player
• @e: select all entities
• @v: select all virtual entities
• @s: select event related entity

Selector arguments:

• name: Limits selection on entities that match the argument value. Values may end on wildcard character '*'.
• limit: Maximum number of entities to select.
• goal_type: Limits selection on virtual entities that have a goal assigned matching the argument value.
• x,y,z: Selection center. Leading '~' makes a coordinate relative to event location.
• dx,dy,dz: Selection volume.
• distance: Distance range from selection center.
• type: Limits selection to entities of a specified MCME-Entity type or excludes an entity type.
• gamemode: Limits selection to players in a specified gamemode excludes players in a gamemode.
• x_rotation
• y_rotation
• talking

Location
String that contains information about a location. Format: "<world_name>,<x>,<y>,<z>"

Spawn Data
Contains information for spawning a Virtual Entity.
Json elements:

• "type": String
  Entity type, can be any vanilla minecraft entity type or:
  • "baked_animation"
  • "winged_flight"
• "name": String
• "data_file": String
  Animation data file in "animations" folder of MCME-Entities plugin.
• "display_name":
• "display_name_position":
• "spawn_location_entity":
• "spawn_location": Location
• "roll":
• "head_yaw":
• "head_pitch":
• "health":
• "movement_type": String (default: "upright")
  Type of movement. Can be "upright", "sneaking", "flying", "falling", "gliding" or "swimming".
• "attributes":
• "bounding_box":
• "goal_factory":
• "head_pitch_center":
• "speech_balloon_layout":
• "mouth":
• "manual_animation": Boolean
• "head_pose_delay":
• "view_distance":
• "max_rotation_step":
  Not working right now.
• "max_rotation_step_flight":
  Not working right now.
• "jump_height":
• "knock_back_base":
• "knock_back_per_damage":
• "enemies":

Layout
Layout for speech balloons.
Json elements:

• "balloon_visible": Boolean (default: true)
  If this is true text of talking virtual entities is displayed in a speech balloon.
• "line_prefix": String
  This string is added at the beginning of each line of a messge.
• "line_pitch": Double
  Vertical distance between lines in blocks.
• "width": String (default: "optimal")
  Controls width of speech ballons. Can be:
  • "wide": Wide speech balloon
  • "narrow": Narrow speech ballloon
  • "optimal": Width of speech balloon depends on message.
• "position": String (default: "right")
  Defines position of speech ballons relative to the talking entity. Can be:
  • "left": left side of entity
  • "right": right side of entity
  • "top": over entity

Goal
Goal of an virtual entity.
Json elements:

• "goal_type"; String
  The type of a goal defines the entity behaviour. Supported types are:
  • "hold_position":
  • "attack_entity":
  • "watch_entity":
  • "follow_entity":
  • "follow_checkpoints":
  • "random_checkpoints":
  • "goto_location":
• "movement_speed": String (default: "walk")
  Defines how fast an entity is moving. Possible values are "stand", "slow", "walk", sprint".
• "target_location":
• "checkpoint":
• "start_checkpoint":
• "target_entity":
• "update_interval":
• "loop":
• "head_goals":
  
  • "duration":
  • "type":
  • "yaw":
  • "pitch":