React to Events

Shell React monitors general server and player events and runs specific shell programs or scripts in response. Audio alerts are highly configurable and may be different for each event. Originally created to trigger the opening of bandwidth on a private server when players join. The server status of vacant is reliably detected which would fire the appropriate outside script redirecting the bandwidth elsewhere. The concept has many applications, limited only by one's imagination.

Custom Commands

Quickly define secure commands that have access to player, console and even the host operating system. Custom commands have many definable override capabilities. Existing commands may be re-mapped to do something else, on the fly. Define new commands capable of invoking other commands, complete with custom messages audio output and parameter control.

Bukkit Integration

ShellReact integrates a Bukkit server into its host operating system. Standard operating system facilities may be used to control a Bukkit server, and a Bukkit server may use those same, standard facilities to direct the host it runs on.

Hot Processing

Implement your changes on a live server, by design. The configuration file 'config.yml' is the user interface, and always the master reference. ShellReact never modifies this file, it only updates from it, on command. For example, add a new command in 'config.yml', enter /sr at the console, or as a player and poof! it is there. Features are turned on and off, hot. Server builders or admins may have libraries of special purpose 'config.yml's that can be copied into the ShellReact directory and instantly invoked.

YAML Validation

Starting at version 2.5, ShellReact pre-scans it's YAML configuration file and will only update from it if is valid. If it is not valid, the syntax error is reported, along with the row/column location. Complimenting this new robustness, is a new capability to automatically reload when any changes to its configuration file are detected. The pre-scan makes this safe to use. It is optional, and defaults to off.

Bidirectional

Also new with version 2.5 is bidirectional interaction with the host operating system. This is accomplished using the underlying file system, common to both. Use the Host OS scheduler or cron to trigger defined procedures on a running Bukkit server. Signal a server restart, stop, save-all, etc… from anywhere you have access to the ShellReact directory. My personal favorites are stop and restart buttons that appear on my desktop when the server is running, and disappear when it is stopped.

Structured Approach

Commands triggers and responses defined in ShellReact are very structured and self documenting. This makes it easy to build on existing work without getting lost. Evolve as you go, build on Terra firma.

Updates are Optional

Shell React supports the Microsoft and Linux operating systems right now and makes good use of the integrated, theme audio when available. It is a true Bukkit plugin gaining access to Minecraft through the Bukkit api only. This exempts Shell React from any versioning requirements. There will be only one version :-) It is written entirely in Java and is intended to be a robust plugin that simply works and gets forgotten about. The balance of this description will be the 'config.yml' file since it is intended to be self documenting.

Note: I have this flagged for 146 and 147, but it should be good for earlier versions of Bukkit. I just haven't tested them.

EXAMPLES

CONFIG.YML

# Shell React, a Bukkit plugin

# ShellReact will use Vault for permissions if it is installed,
# otherwise it defaults to Bukkit permissions.

# This is a light weight plugin that endeavors to use only the
# resources it needs to implement what is defined in this file.
# There is also no limit on numbered definitions, discretion is
# left to the user.

# ShellReact is a system level configuration utility designed to
# facilitate automatic responses to specified events.  An event may
# be originated by the Bukkit server, the host OS or a user/player.
# Two way communication with the host OS makes it possible for
# server builders to control the Bukkit server using the underlying
# file system, common to both. Customizable audio alerts on the
# server may be defined. General access to defined player commands
# may be secured by op status, permission status, or even to a
# specific player. Ops are given access to the configuration
# environment by default, but ops don't always have file system
# access. This provides a system level basis of security, by design.

# Use /shellreact or /sr to reload config.yml at any time, both
# player and console. Or use the auto reload feature in 'Settings'
# and ShellReact will automatically reload whenever changes are
# made to 'config.yml'.  ShellReact never modifies config.yml, this
# file is always the master.  ShellReact only uses 'config.yml' on
# startup or when reloading.  All configuration details are retained
# in memory arrays.  On reload, all memory arrays are rebuilt and
# 'config.yml' is released.  Everything setup here is designed to
# be added and modified hot, without disturbing the server.
# Permission node 'shellreact.admin' is required to use the
# /shellreact command if the Allow_op_shellreact flag under settings
# below is set to 'false'.

# DON'T USE TABS, PERIOD.  Follow standard YAML rules and formatting.

# 'config.yml' is validated when loaded or reloaded.  A syntax error
# will be concisely displayed along with the row/column.  This
# validation is done before using the yaml file allowing ShellReact
# to routinely abort the process, leaving the existing config intact.

# Every programmable detail in this file has an 'Active' flag
# designed to make it convenient to turn triggers on or off as
# needed, dynamically.  Details of triggers not always left live
# may therefore remain intact while inactive.

# Every individual setting has a reasonable default value and may be
# ommitted if not used, or the default value is OK.  String settings
# generally default to 'none', booleans generally default to 'false'.
# An invalid setting will revert to it's default value.

# Player and Server cool's determine how long to wait before making
# a final decision on server vacant status.  This makes allowances
# for players struggling with tcp problems and prevents unnecessary
# player quit processing.

# 'Platform' can be: 'Auto', 'Windows', 'Linux' or 'Custom'
# 'Custom' requires the shell and shell parameters in the command
# defined by 'Shell_cmd' in addition to the command itself.  ie:
# Shell_cmd: CMD, /C, batch.cmd parm1 parm2 etc
# Use commas to separate the shell, shell parameters, and command.

Settings:
  Platform             : Auto
  Allow_op_shellreact  : true
  Auto_reload          : false
  Quiet                : false
  Debug                : false
  Player_quit_cool     : 10
  Server_vacant_cool   : 20

# ShellReact will automatically reload 'Config.yml' when it has
# been changed if 'Auto_reload' is set to 'true'

# Set 'Quiet' to 'true' to turn off all ShellReact messages except
# custom 'Message_out' strings and error messages.

# 'Debug' will display the output from your shell command on the
# console when set to true.

# For the Windows platform it is best to stay with the standard
# backslashes instead of forward slashes for shell commands, but
# either should be ok.

# FQN:
# Shell_cmd: C:\parent_dir\child_dir\batch_file.cmd parm1 %player%

# UNC:
# Shell_cmd: \\Computer\parent_dir\child_dir\program.exe %player%

# Audio alerts may be set using the platform friendly 'beep' alert.
# 'beep' alone will emit a single console beep.  'beep.5' will emit
# 5 console beeps.  'beep.3.300' will emit 3 console beeps, 300
# milliseconds apart.  The format is:  beep.[count].[delay]

# Standard, Windows theme alerts are also available.  See bottom.
# In Windows, any audio may be connected to any theme identifier
# using Control-Panel/Sounds.

# 'Console_cmd', 'Player_cmd' and 'Sreact_cmd' accept multiple
# commands separated by commas.  'Shell_cmd' does not need this.
# The command processor will accept multiple commands, or, you may
# simply pass all your variables to a script or batch file and do
# whatever you want, completely separate and isolated from Bukkit
# and Minecraft. Isolated, but informed :-)  ie:
# Shell_cmd: SCRIPT.CMD %parameters% %player% %player_ip%
#                           %player_count% %location%
#                           %world% %X% %Y% %Z%

# VARIABLES         (Case sensitive)
# %parameters%      Parameters entered with at runtime
# %player%          The player that either joined or quit
# %player_ip%       The player's tc/ip address '0.0.0.0'
# %player_count%    The number of players online
# %location%        Player location in the form of: 'world x y z'
# %world%           Player world location
# %X%               Player X coordinate location
# %Y%               Player Y coordinate location
# %Z%               Player Z coordinate location

# DIRECTIVES        (Case sensitive)
# '_ '              Underscore followed by a space, called a line
#                     anchor.  Mark the beginning of a string
#                     definition, per line. Eliminates the need for
#                     balanced quotes. Facilitates multi line
#                     string definitions. Stripped at runtime
#                     including the space. Preserves white spaces
#                     between it and the beginning of the string
#                     definition on that line.
# _nl               Represents a new line in message output
# _runtime          Used in the 'Default_params' setting in the
#                     Commands' section below.  Used to flag a
#                     command as one that uses parameters, but no
#                     default parameter is defined.

# 'Message_out' is a custom message to the player when associated
# with a player command, otherwise to the console.  Use standard
# '&x' formatting.  Variables are expanded. Contains no ShellReact
# prefixing.  Use '_nl' in your string to indicate newlines.  You
# *must* start your string with '_ ' if your string starts with a
# formatting character.  It will be stripped at runtime. ie:
# Message_out:  _ &cExample string starting with the line anchor.
# The line anchor will also preserve white spaces.

# Use Active 'false' to leave entire event inactive.
# Use 'none' to leave a detail unused.

# ***************************************************************
# SERVER TRIGGERS
# ***************************************************************

Player_join:
  Active       : false
  Message_out  : none
  Shell_cmd    : none
  Console_cmd  : none
  Sreact_cmd   : none
  Audio_alert  : none

Player_quit:
  Active       : false
  Message_out  : none
  Shell_cmd    : none
  Console_cmd  : none
  Sreact_cmd   : none
  Audio_alert  : none

# EXAMPLE Player join and quit. Uncomment and replace above to use.
# player log, by player in a directory named 'PlayerLogs' in your
# Bukkit directory. Customize it any way you want, or use it for
# something else.

# Linux users need to change the shell commands to suit their needs.

#Player_join:
#  Active       : true
#  Message_out  : none
#  Shell_cmd    : _ MD .\PlayerLogs &
#                 _ ECHO %date% %time% JOINED from %player_ip% at
#                 _ %location% with %player_count% players online.
#                 _ >> .\PlayerLogs\%player%.log
#  Console_cmd  : none
#  Audio_alert  : beep

#Player_quit:
#  Active       : true
#  Message_out  : none
#  Shell_cmd    : _ ECHO %date% %time% QUIT   from %player_ip% at
#                 _ %location% with %player_count% players online.
#                 _ >> .\PlayerLogs\%player%.log
#  Console_cmd  : none
#  Audio_alert  : beep.2.500

Server_vacant:
  Active       : false
  Message_out  : none
  Shell_cmd    : none
  Console_cmd  : none
  Sreact_cmd   : none
  Audio_alert  : none

#Server_vacant:
#  Active       : true
#  Message_out  : All changes flushed to disk.
#  Shell_cmd    : none
#  Console_cmd  : save-all
#  Audio_alert  : win.sound.exit

Server_start:
  Active       : false
  Message_out  : none
  Shell_cmd    : none
  Console_cmd  : none
  Sreact_cmd   : none
  Audio_alert  : none

Server_stop:
  Active       : false
  Message_out  : none
  Shell_cmd    : none
  Console_cmd  : none
  Sreact_cmd   : none
  Audio_alert  : none

# ***************************************************************
# All sections below this message are lists of numberd sequences,
# starting with 0 (zero), and incremented, sequentially.  The
# correct sequencing is mandatory.  There is no built in limit
# as to how many.  Sequence number 0 contains all the settings
# availble for each section, with the default values.  Sequence 0
# may be used, but it might be best to leave it as a reference,
# left inactive.  There is no need to include all the definition
# names for each sequence.  Only the definitions not using the
# default values are required.
# ***************************************************************

# File Trigger.  These are boolean triggers defined by a file name.
# Use this facility to signal ShellReact from the host OS.
# When a file with a name defined by 'File_name' is found in the
# ShellReact directory, it is triggered.  The file is automatically
# deleted to prevent unintentional recursion.

# ***************************************************************
# HOST OS Flags (Start at 0, increment sequentially)
# ***************************************************************

File_triggers:
  0:
    File_name        : DEFAULT
    Message_out      : none
    Shell_cmd        : none
    Console_cmd      : none
    Sreact_cmd       : none
    Audio_alert      : none
    Active           : false
#  1:
#    File_name        : Do_Restart
#    Message_out      : Server restarted using a file trigger.
#    Sreact_cmd       : RESTART
#    Active           : true
#  2:
#    File_name        : Do_Stop
#    Message_out      : Server stopped using a file trigger.
#    Sreact_cmd       : STOP
#    Active           : true

# Examples 1 and 2 will signal the server to stop or restart.
# They reference commands in the 'Commands' section below.
# A Windows example:  Create a new shortcut on your desktop and
# enter 'cmd /c echo %time% > path_to_ShellReact_dir\Do_Restart'
# for the location, and name it 'RESTART'.  Give it a nice icon
# and you have a Bukkit restart button on your desktop.  The
# server may be anywhere on your network.

# Console monitor triggers.  These are triggers defined by case
# insensitive strings. The trigger is invoked when Trigger_string
# is found in a line of console output.

# Trigger_string      The string to look for in console output
# Trigger_cool        Minimum delay in milliseconds between
#                     successive invocations

# ***************************************************************
# CONSOLE MONITOR TRIGGERS (Start at 0, increment sequentially)
# ***************************************************************

Console_mon:
  0:
    Trigger_string   : DEFAULT
    Message_out      : none
    Shell_cmd        : none
    Console_cmd      : none
    Sreact_cmd       : none
    Trigger_cool     : 10000
    Audio_alert      : none
    Active           : false
#  1:
#    Trigger_string   : Did the system time change
#    Message_out      : Automatic server lag response example.
#    Console_cmd      : lag
#    Trigger_cool     : 30000
#    Active           : true

# Custom named commands.  These are commands input by a player and
# may, optionally, include console input.  These are also named
# subroutines that may be called from any section using the
# 'Sreact_cmd' setting.

# Use this facility with the /shellreact or /sr command to
# dynamically add secure console and player command sequences that
# may, optionally, alert the console and trigger shell commands.
# This is designed to be configured hot, with no need to disturb the
# server, or play in process.

# While the action sequences may potentially be lengthy, care is
# taken to invoke them in a manner that will not disturb Minecraft
# play.  For example;  a typical command will immediately invoke
# 'Player_cmd' sequences.  'Console_cmd' and 'Sreact_cmd' sequences
# follow, slightly delayed.  'Shell_cmd' and 'Audio_alert' are
# invoked on their own threads.

# With Override set to false, commands defined here will not affect
# the commands named with 'Name' that have the same name belonging
# to other plugins or the server.  Responses here will simply
# supplement any other command with the same name.  Setting Override
# to true will, in effect, create a master command, superseding and
# replacing any other command from other plugins with the same name.

# Cmd_name         Command entered by player, or console (trigger)
#                    May be called from any section.
# Default_params   Parameters to use if none entered with command
#                    Use directive '_runtime' to indicate that
#                    parameters are required, but no default set
# Player_cmd       Live player command to run
# Override         Cancel and replace original command entered
# Include_console  'true' to include console input

# PERMISSIONS
# Applies only when invoked by a live player. One of the below must
# be true for a command to be available to a particular player.
# If no player permissions are set and 'Include_console' is true,
# the command will be available only to the console.  If the same
# is true and 'Include_console' is false, the command may only be
# invoked as a subroutine, defined by 'Sreact_cmd'
#   Op_allow       'true' to respond to ops
#   Perm_node      Permission node, 'none' ignores node
#   Player_allow   Specific player permission, 'none' ignores player

# ***************************************************************
# CUSTOM INPUT COMMANDS (Start at 0, increment sequentially)
# ***************************************************************

Commands:
  0:
    Cmd_name         : DEFAULT
    Default_params   : none
    Message_out      : none
    Shell_cmd        : none
    Console_cmd      : none
    Player_cmd       : none
    Sreact_cmd       : none
    Audio_alert      : none
    Override         : false
    Include_console  : false
    Op_allow         : false
    Perm_node        : none
    Player_allow     : none
    Active           : false
#  1:
#    Cmd_name         : RESTART
#    Message_out      : Restarting the server...
#    Shell_cmd        : echo %time% > .\restart
#    Console_cmd      : save-all, stop
#    Audio_alert      : beep.5.1000
#    Override         : true
#    Include_console  : true
#    Op_allow         : true
#    Perm_node        : group.admin
#    Active           : true
#  2:
#    Cmd_name         : STOP
#    Message_out      : Stopping the server...
#    Shell_cmd        : del .\restart
#    Console_cmd      : save-all, stop
#    Audio_alert      : beep.5.1000
#    Override         : true
#    Include_console  : true
#    Active           : true
#  3:
#    Cmd_name         : RULES
#    Default_params   : be
#    Message_out      : Example root cmd, default parameter 'be'
#    Sreact_cmd       : rules %parameters%
#    Override         : true
#    Include_console  : true
#    Op_allow         : true
#    Perm_node        : group.players
#    Active           : true
#  4:
#    Cmd_name         : RULES no
#    Message_out      : _ &a Server Rules (No) _nl
#                       _   &e No Kicking      _nl
#                       _   &e No Biting       _nl
#                       _   &e No Cussing      _nl
#                       _   &e No Hair Pulling _nl
#    Override         : true
#    Include_console  : true
#    Op_allow         : true
#    Perm_node        : group.players
#    Active           : true
#  5:
#    Name             : RULES be
#    Message_out      : _ &a Server Rules (Be) _nl
#                       _   &e Be Nice         _nl
#                       _   &e Be Polite       _nl
#                       _   &e Be Helpful      _nl
#                       _   &e Be Constructive _nl
#    Override         : true
#    Include_console  : true
#    Op_allow         : true
#    Perm_node        : group.players
#    Active           : true

# EXAMPLE server RESTART command: To use, uncomment commands 1 and 2
# above.  In the batch file used to start the Bukkit server add the
# label :Restart above the java start line, and add the file EXIST
# check after.  ie:

# SET BINDIR=%~dp0
# CD /D "%BINDIR%"
# :Restart
# java -server -Xmx4G -Xms4G -jar craftbukkit.jar nogui
# IF EXIST restart GOTO Restart

# Linux users; change the shell commands to create/delete the file
# named 'restart' as shown, and modify your server start script to
# include the label and file exist check.

# Example commands 3, 4 and 5 are formatting examples for
# 'Message_out'. The '_ ' line anchor, the '_nl' new line
# formatters are illustrated.  They also demonstrate two separate
# command definitions using the same root command 'RULES'.

# AUDIO ALERT ID's

# Generic Audio alert (platform friendly)
# beep.[count].[delay]
#   count = the number of successive beeps, 1 to 5
#   delay = the delay between beeps in milliseconds, 150 to 1000

# Windows theme alerts
# win.sound.default
# win.sound.close
# win.sound.maximize
# win.sound.minimize
# win.sound.menuCommand
# win.sound.menuPopup
# win.sound.open
# win.sound.restoreDown
# win.sound.restoreUp
# win.sound.asterisk
# win.sound.exclamation
# win.sound.exit
# win.sound.hand
# win.sound.question
# win.sound.start

# Feel free to remove comments to suit your taste.  A default
# config.yml with documentation is easily regenerated by renaming
# your config.yml and running /shellreact (or /sr)  Also, there
# are no rules regarding section order, or definition order in
# each section.  Again, suit your own taste.  The numbered
# sequences must be correct, however.  Also, Individual setting
# names are only required when set to something other than the
# default value.  Keep your action definitions easier to read by
# omitting settings not used.