Skip to content
SharpMUSH

Events

EVENTS

Section titled “EVENTS”

SharpMUSH Events are hardcoded events that may or may not be caused by players. An object designated as the event handler (via the “event_handler” config option) has attributes triggered on it, with arguments, on specified events.

Unlike PennMUSH, SharpMUSH pre-populates the event handler: a new database is seeded with an Event Handler object (#9), and the “event_handler” config option already points at it. You do not create one or set the config — you simply add attributes named after the events you care about:

> &<event name> #9=<action list>

If you would rather use a different object, point the config at it with @config/set event_handler=<dbref> and set the “event_handler” option in your mush.cnf so it survives dumps and is receiving events even during startup. On a fresh instance this is optional.

How handler code runs:

  • Event attributes run with the handler object’s own permissions (it executes as itself, like the HTTP handler and any normal attribute). The seeded Event Handler #9 is a WIZARD object, so out of the box it can @set, @power, @lock, and see-all as an admin handler needs. If you point event_handler at your own object, flag it wizard (@set <obj>=wizard) to grant it those powers.
  • The enactor (%#) is the executor that caused the event. For a system event with no executor (an automatic dump, a signal, an idle-boot), %# is #1 (God), not #-1. If the causer has been destroyed since, %# is #1 as well. Because %# is a real dbref either way, use an event’s own arguments (not %#) to distinguish system- from player-caused triggers.

See Also:

EVENT EXAMPLES

Section titled “EVENT EXAMPLES”

Suppose you want random dbsave messages:

> &DUMP`COMPLETE #9=@config/set dump_complete=SAVE: [v(randword(lattr(me/dumpmsg`*)))]
> &DUMPMSG`NOTHING #9=The Database has been saved, nothing to see here.
> &DUMPMSG`GRETZKY #9=The Database saves, but Gretzky scores!
> &DUMPMSG`GEICO #9=The Database saved 15% by switching to Geico!
> @dump
SAVE: The Database has been saved, nothing to see here.
> @dump
SAVE: The Database saved 15% by switching to Geico!

Or admin want to be notified when a player connect attempt fails:

> &SOCKET`LOGINFAIL #9=@wizwall/emit On descriptor '%0' from IP '%1' a failed connect attempt to '%4': '%3'
(Later, a player attempts to log in as #1)
Broadcast: [Event Handler]: On descriptor 3, from IP '127.0.0.1', a failed connect attempt to '#1': 'invalid password'

See Also:

EVENT EXAMPLES2

Section titled “EVENT EXAMPLES2”

Suppose you want @pcreated players to be powered builder, set shared and zonelocked to roys, but players created at the connect screen to not be. Set the handler on the seeded Event Handler (#9). Distinguish the two cases with the event’s how argument (%2 — one of pcreate, create, register), not %#: for a connect-screen create %# is #1 (God), so @assert %# would not skip it.

> &PLAYER`CREATE #9=@assert strmatch(%2,pcreate) ; @pemit %#=Auto-Setting [name(%0)] Builder and shared ; @power %0=builder ; @lock/zone %0=FLAG^ROYALTY ; @set %0=shared
> @pcreate Grid-BC
Auto-Setting Grid-BC Builder and Shared

Note there is no @set #9=wizard step — the seeded #9 is already a wizard object, so it runs with its own elevated permissions and can @power/@lock the new player as-is. (A custom, non-wizard handler object would need @set <obj>=wizard first.)

The Event Handler object, since it’s handling so many events, may become cluttered with attributes. We recommend using @trigger and @include to separate events to multiple objects.

EVENT LIST

Section titled “EVENT LIST”

Event names are of the format `. The ‘type’ is used simply to group similar events together for help.

Event syntax in the help is of the form:
` (What is passed as %0, %1, … %9)

The following event types and events have been added to SharpMUSH. To see the help for them, type event .

Event Types:

  • dump: dump`5min, dump`1min, dump`complete, dump`error
  • db: db`dbck, db`purge, db`warnings
  • log: log`err, log`cmd, log`conn, log`trace, log`check, log`huh
  • object: object`create, object`destroy, object`move, object`rename, object`flag
  • sql: sql`connect, sql`connectfail, sql`disconnect
  • signal: signal`usr1, signal`usr2
  • player: player`create, player`connect, player`disconnect, player`inactivity
  • socket: socket`connect, socket`disconnect, socket`loginfail, socket`createfail
  • http: http`blocked http`fail http`command

EVENT DB

Section titled “EVENT DB”
  • db`dbck: Run after the regular database consistency check.
  • db`purge: Run after the regular purging of destroyed objects.
  • db`wcheck: Run after the regular @warnings check.

Note: These events are only triggered after the automatic scheduled checks, and not if someone manually runs @dbck, @purge or @wcheck.

EVENT DUMP

Section titled “EVENT DUMP”
  • dump`5min (Original message, isforking)
  • Database save will occur in 5 minutes.
  • dump`1min (Original message, isforking)
  • Database save will occur in 1 minute.
  • dump`complete (Original message, wasforking)
  • Database save has completed.
  • dump`error (Error message, wasforking, exit_status)
  • Database save failed! You might want this to alert any admin on.
  • exit_status has different meanings in forking and non-forking dumps.
  • In forking: exit_status is a string, either “SIGNAL ” or “EXIT ”. SIGNAL refers to the mush process receiving error message via signal while EXIT refers to mush process exiting abnormally.
  • In nonforking: exit_status is “PERROR ” - string being the error message returned by strerror(errno). If you are seeing errors on dbsave, we recommend setting forking_dump to 0, as nonforking dumps have more verbose error messages.

The standard messages shown on dumps are still displayed when these events are set. To disable the standard message, set them to empty strings via @config or in mush.cnf.

EVENT LOG

Section titled “EVENT LOG”

Events in the log tree get triggered whenever the game logs any information to a log file (Either because of @log, or something else happening.) They all get passed a single argument, the message being logged.

  • log`err: Errors and the general catch-all.
  • log`cmd: Logged commands.
  • log`wiz: Logged wizard activity.
  • log`conn: Connection notifications.
  • log`trace: Memory tracking notifications.
  • log`check: Save-releated log messages.
  • log`huh: Commands that generate huh messages.

EVENT OBJECT

Section titled “EVENT OBJECT”

  • object`create (new objid, cloned-from)

  • Triggered on the creation of any object except player. If it was created using @clone, then will be a objid. Otherwise will be null.

  • object`destroy (objid, origname, type, owner, parent, zone)

  • Triggered after the object is totally destroyed. Passed arguments are former objid, name, type, owner, etc. Enactor is always #-1, so use former owner.

  • object`move (objid, newloc, origloc, issilent, cause)

  • Triggered after the object is moved, @tel'd, or otherwise sent to a new location. If is 1, then the object was moved using @tel/silent.

  • object`rename (objid, new name, old name)

  • Triggered when any object is renamed.

  • object`flag (objid of object with flag, flag name, type, setbool, setstr)

  • Triggered when a flag or power which has the “event” restriction is set or cleared. is one of FLAG or POWER. is 1 if the flag/power is being set, and 0 if it’s being cleared. is either “SET” or “CLEARED”.

Example

Section titled “Example”
&OBJECT`FLAG #9=@cemit Admin=capstr(lcstr(%2)) %1 [lcstr(%4)] on [name(%0)] by %n.

EVENT SQL

Section titled “EVENT SQL”

  • sql`connect (platform)

  • Triggered on successful connect to the SQL database. is ‘mysql’, ‘postgresql’ or ‘sqlite3’.

  • sql`connectfail (platform, error message)

  • Triggered on unsuccessful connect to the SQL database.

  • sql`disconnect (platform, error message)

  • Triggered if SQL disconnects for any reason. Usually not a worry since Penn will auto-reconnect if it can.

EVENT SIGNAL

Section titled “EVENT SIGNAL”

No arguments are passed to these events.

  • signal`usr1: Triggered when the SharpMUSH process receives a “kill -USR1”
  • signal`usr2: Triggered when the SharpMUSH process receives a “kill -USR2”

If these attributes exist, then penn will NOT perform what it usually does when it receives a signal. In effect, these override Penn’s default actions.

To mimic old behaviour:

&SIGNAL`USR1 #9=@nspemit/list lwho()=GAME: Reboot w/o disconnect from game account, please wait. ; @shutdown/reboot
&SIGNAL`USR2 #9=@dump

EVENT PLAYER

Section titled “EVENT PLAYER”

  • player`create (objid, name, how, descriptor, email)

  • Triggered when a player is created. If the player was @pcreated, then %# will be the person who did the @pcreate. If player was created by using ‘create’ at the connect screen, then %# will be #-1 and will be non-null. is one of: “pcreate”, “create” or “register”. If created using ‘register’, will be set appropriately.

  • player`connect (objid, number of connections, descriptor)

  • Similar to @aconnect, but for events, and so you can use descriptor.

  • player`disconnect (objid, number of remaining connections, hidden?, cause of disconnection, ip, descriptor, conn() secs, idle() secs, recv bytes/sent bytes/command count)

  • Similar to @adisconnect, but for event system, and with more information available.

  • player`inactivity

  • Triggered when idle players are disconnected. Only run if at least one player gets idlebooted (Or auto-hidden), not at every inactivity check.

EVENT SOCKET

Section titled “EVENT SOCKET”

  • socket`connect (descriptor, ip)

  • Triggered when a socket first connects to the port. Using both this and player`connect could be spammy. This happens when a connecting socket sees the connect screen.

  • socket`disconnect (former descriptor, former ip, cause of disconnection, recv bytes/sent bytes/command count)

  • Triggered when a socket disconnects. Using this and player`disconnect could be spammy.

  • socket`loginfail (descriptor, IP, count, reason, playerobjid, name)

  • Triggered when a login attempt fails. is the number of fails in the past 10 minutes. If used in conjuction with the config option connect_fail_limit, then any failures after the limit is reached will NOT trigger socket`loginfail. If the connect is a failed attempt to log into a valid player, will be set to that objid. Otherwise it will be set to #-1. is the name the connection attempted to connect with, and is only set when is #-1.

  • socket`createfail (descriptor, ip, count, reason, name*, *error)

  • Triggered when a player create attempt fails. is the # of fails caused by this ip. If the failure is from an attempt to register a player via email, the error code of the mailer program is provided as .

Note: A sitelock rule with deny_silent will not trigger socket`createfail or socket`createfail.

EVENT HTTP

Section titled “EVENT HTTP”

  • http`blocked (former descriptor, ip, method, path, reason)

  • Triggered when an HTTP request is sitelocked !connect, by IP or path, ‘reason’ will describe if it’s IP or path.

  • http`fail (former descriptor, ip, reason)

  • Triggered when an HTTP connection fails for poor formatting, malformed requests, or similar parsing errors. This can occur before method, path, etc are obtained, so is limited in information.

  • http`command (IP, method, path, resp_code, resp_content_type, resp_content_len)

  • Triggered after an HTTP command is executed.

Note: A sitelock rule with deny_silent will not trigger http`blocked