ShellReact
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.
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.
Is there anyone besides me using this? This is great, once you figure out the possibilities.
Anyway, does anyone know if it's possible not to have any strings sent to the shell script converted to lower case letters? Having
in the config and typing
gets the result
foobar
Hi. How do I trigger commands with redstone? Neither command blocks nor [command] Craftbook works with Shellreact commands.
Amazing plugin, works really well! However, it seems passing %parameters% to "Message_out" dumps an error. I think it's a bug related to frogman786 and wtfwasithinking's comments below.
I've noticed passing a URL as a parameter [to a bash script/in general] seems to remove the / and \ characters. I'm not too sure if this can be avoided?
I'm getting the same issue that wtfwasithinking is getting and I've also tried it with default params _runtime Can't seem to figure out how to get it working. Anybody able to help?
Looking for a little help. I've got the below command set up. When I issue the console command basic2player, the command runs and leaves in the variable name. If I issue the command with a parameter (ie: basic2player wtfwasithining) it doesn't fire at all. Is there something I'm missing or is it a glitch?
1: Cmd_name : basic2player Default_params : none Message_out : User %parameters% updated to Player, notifying Admin Shell_cmd : /usr/bin/twidge update "@unl33t %parameters% became a Player" Console_cmd : none Player_cmd : none Sreact_cmd : none Audio_alert : none Override : false Include_console : true Op_allow : false Perm_node : none Player_allow : none Active : true
The YAML shown is for ShellReact 2.5, in the Bukkit approval queue. This represents a lot of work, hence the half increment on the major portion of the version number. I feel the programming environment is reasonably complete and stable at this point, so your 'config.yml' files should remain valid going forward.
The next cut will complete the remote configuration environment, and follow up with any problems that may surface with this, big release. By the way, ShellReact features may increase as it evolves, but it's overall weight as a plugin is getting lighter. This is a result of footprint optimization, and doggedly faithful determination to turn on, or use only the resources defined. Each section is scanned for active settings and only turned on if one is found.
Cheers!
ShellReact 2.0 with Linux support is in the Bukkit approval queue. Uses the Bash shell.
@Slimjim1520
This is the sort of application that usually gets developed on Linux first with Windows following because of the no nonsense approach and just work (damn it!) philosophy.
My Bukkit stuff is set up on a Windows based server, so I have to start here. I plan to include Linux eventually and will need folks to test it on Linux for me, so please keep checking in.
With the exception of the audio alert and shell commands, ShellReact should work fine on Linux, theoretically. I am using a Java api to access the Windows audio api, for all I know Java handles this internally because of its portable design.
OMG I NEED THIS FOR LINUX!!!!!!!!!!!!
Ever hit that X in the upper right hand corner of your Bukkit server by accident? I run my Bukkit servers in an RDP session on the console of the server itself to keep them out of harms way, but even then it occasionally happens. Bukkit wrappers generally cause more problems than they solve in my experience. But I found a simple and elegant solution. A utility that disables that window close option. It is called ConsoleNoClose.
Just put it in the Bukkit directory and include the line:
ConsoleNoClose /1
at the top of the batch file. The cmd session will have to close under batch control. Taskmanager is the other way, but no more accidents.
http://www.uwe-sieber.de/files/consolenoclose.zip
@NodexServers
I know... I was waiting for that. I like Linux too. The shell part could be accomodated, but I don't know about the theme audio. When the modeling of this plugin settles dowm, I will accomodate Linux even if I have to resort to 'beep' for the audio.
Linux support?
config.yml posted above is for ShellReact 1.6, in the Bukkit approval queue.
Thank you so much! Solved my problem. :)
@Brandrew
I know. I wrote it because I couldn't find it either. I was surprised it didn't already exist.
Fantastic!
I spent hours looking for this, I was just about to start writing it myself!
Version 1.0 in Bukkit approval queue.
Command triggers added, credit aileron565
Optional soft depend on Vault.
I found that little gem when trying to come up with something a little better than 'beep'. Here is the guts of that Windows api call (via Java). I run it Asynchronously to make sure it doesn't disturb the game.
import java.awt.*;
final Runnable runnable = (Runnable) Toolkit.getDefaultToolkit().getDesktopProperty("win.sound.default"); if (runnable != null) { runnable.run(); }
@MineCrafterCity
It does work.
I don't think it will work :P You can't use music in minecraft! Only when the user has the same client? If this would work and you could get sound than I could open more files check if he/she has a hacked client. that's why I'm not entirly sure if this will work :P
btw, sorry if I got it totally wrong.