Events

Table of Contents

• Table of Contents
• Events
  • Events Command
  • Fields
  • Event Types
    • Message Events
      • ReadMessage
      • ReadTimedMessage
      • ReadMessageChoice
      • ReadMessageChoiceTriggerEvent
  • Special Event Types
    • User Attribute Check Events
      • SkillCheck
      • HeightCheck
      • WeightCheck
      • AbilityCheck
      • ReputationCheck
    • User Interaction Events
      • FromWallet
      • ToWallet
      • FromItem
      • ToItem
      • RewardExperience
    • Control Flow Events
      • TriggerEvent
      • TimedTriggerEvent
      • SendMessage
      • TimedSendMessage
      • ReadMessageTriggerSuccessFail
      • TriggerSuccess
      • TriggerFailure
      • SendMessageTriggerEvent
      • TriggerFailureSendError
      • MessageChoiceDefault
      • MessageChoiceDefaultEvent
      • RollDiceSum

Events

The events system is designed to be a flexible method for defining functions within discord that can be used as standalone "read and response" type functions, functions for checking the various attributes and skills of a player, functions for checking world information such as the time of day or weather, or chained together using the scripts system to create more complex interactions with NPC's or Items (though not necessarily limited to those two).

The events command is used for managing events (adding, removing, modifying, etc.), and must first be enabled in a room before it can be used with the following command (see the command permissions page for more information):

~command enable events

Events Command

Command	Description	Example Usage
add
remove
list
info
enable
disable
listenabled
script
info
update
loadfromdisk	accepts force as an argument to force load from disk overwriting existing records
savetodisk
save		save

Go to top of page

Fields

All Events share the following field types:

Name

string

A unique name for the event. Attempting to save records with duplicate names will return an error.

Description

string

A description of 60 characters or less about the event.

Type

string

The type name of the event.

TypeFlags

string array

As described in the following section, each type of event has varying fields that are applicable to them.

PrivateResponse

bool

Whether or not to send a return message as a private message rather than a public one.

Data

string array

As described in the following section, each type of event has varying data fields that are applicable to them.

Go to top of page

Event Types

Message Events

ReadMessage

A ReadMessage event will send an automatic instant response to the user when the defined keyword is found in a message.

TypeFlags

TypeFlag Field #	Description
0	Keyword to trigger on

Data

Data Field #	Description
0	Formatted message to send

Example Event Definition:

In the following example, the trigger keyword is "hello", to which a response of "Hello @username!" will be sent. It is configured to start at boot, and to cycle indefinitely:

{
  "name": "ExampleReadMessage",
  "description": "Trigger a response to the word hello",
  "type": "ReadMessage",
  "typeflags": [
    "hello"
  ],
  "privateresponse": false,
  "data": [
    "Hello _user_!"
  ]
}

Go to top of page

ReadTimedMessage

A ReadTimedMessage event will respond to a user after the configured timeout when the defined keyword is defined in a message.

TypeFlags

TypeFlag Field #	Description
0	Keyword to trigger on
1	Seconds to pause for (max 300)

Data

Data Field #	Description
0	Formatted message to send

Example Event Definition:

In the following example, the event will be triggered by the keyword "hello", after which there will be a sleep period of 30 seconds. Finally, a response of "Hello @username!" will be sent. It is configured to start at boot, and to cycle indefinitely:

{
  "name": "ExampleTimedMessage",
  "description": "Trigger a timed response to the word hello",
  "type": "ReadTimedMessage",
  "TypeFlags": [
    "hello",
    "30"
  ],
  "privateresponse": false,
  "data": [
    "Hello _user_!"
  ]
}

Go to top of page

ReadMessageChoice

The ReadMessageChoice event will respond to a user with a message that corresponds to what the defined keyword is keyed to in the data array.

Note: This will only trigger on the **first keyword match in a message.

TypeFlags

TypeFlag Field #	Description
0	Keyword to trigger on
1	Second keyword to trigger on
2	Third keyword to trigger on
...	Up to ten choices may be defined

Data

Note: The number of keywords must match the number of responses defined. Or the event will not be registered and will return an error.

Data Field #	Description
0	Formatted message to send when keyword 0 is found
1	Formatted message to send when keyword 1 is found
2	Formatted message to send when keyword 2 is found
...	Up to ten responses may be defined

Example Event Definition:

In the following example, the keywords "hello" and "goodbye" will be responded to with "Hello @username!" and "Goodbye @username!" respectively:

{
  "name": "ExampleReadMessageChoice",
  "description": "Trigger responses for hello and bye",
  "type": "ReadMessageChoice",
  "TypeFlags": [
    "hello",
    "bye"
  ],
  "privateresponse": false,
  "data": [
    "Hello _user_!",
    "Goodbye _user_!"
  ]
}

Go to top of page

ReadMessageChoiceTriggerEvent

The ReadMessageChoiceTriggerEvent event will trigger a keyed event when the corresponding keyword is found in a message.

Note: This will only trigger on the first keyword match in a message.

TypeFlags

TypeFlag Field #	Description
0	Keyword to trigger on
1	Second keyword to trigger on
2	Third keyword to trigger on
...	Up to ten choices may be defined

Data

It is not necessary to define an eventID, but the data array length must match the length of the TypeFlags array. If you do not have an event yet defined to trigger, a value of "nil" can be used and updated later. If a value other than nil is defined, a check will be performed to ensure that the ID is valid.

Data Field #	Description
0	ID of event to trigger (or nil)
1	ID of event to trigger (or nil)
2	ID of event to trigger (or nil)
...	Up to ten events may be defined

Example Event Definition:

In the following example, the keywords "sword" and "dagger" will trigger eventID "d590cbc5" and "nil" respectively:

{
  "name": "ExampleMessageChoiceTriggerEvent",
  "description": "Trigger an event in response to the words sword and dagger",
  "type": "ReadMessageChoiceTriggerEvent",
  "TypeFlags": [
    "sword",
    "dagger"
  ],
  "privateresponse": false,
  "data": [
    "d590cbc5",
    "nil"
  ]
}

Go to top of page

Special Event Types

These events are intended to be used for scripting and not as general purpose events. As such, they can be defined but they cannot be enabled on a per-channel basis.

User Attribute Check Events

SkillCheck

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "SkillCheck",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

HeightCheck

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "HeightCheck",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

WeightCheck

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "WeightCheck",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

AbilityCheck

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "AbilityCheck",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

ReputationCheck

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "ReputationCheck",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

User Interaction Events

FromWallet

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "FromWallet",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

ToWallet

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "ToWallet",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

FromItem

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "FromItem",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

ToItem

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "type": "ToItem",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

RewardExperience

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "Name":"ExampleRewardExperience",
  "Description":"An example event",
  "type": "RewardExperience",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

Control Flow Events

TriggerEvent

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "Name":"ExampleTriggerEvent",
  "Description":"An example event",
  "type": "TriggerEvent",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

TimedTriggerEvent

TypeFlags

TypeFlag Field #	Description
0	...

Data

Data Field #	Description
0	...

Example Event Definition:

In the following example...

{
  "Name":"ExampleTimedTriggerEvent",
  "Description":"An example event",
  "type": "TimedTriggerEvent",
  "TypeFlags": [
    "nil"
  ],
  "data": [
    "nil"
  ]
}

Go to top of page

SendMessage

TypeFlags

TypeFlag Field #	Description
0	n/a

Data

Data Field #	Description
0	Message to send

Example Event Definition:

In the following example...

{
  "Name":"ExampleSendMessage",
  "Description":"An example event",
  "type": "SendMessage",
  "data": [
    "Hello _user_!"
  ]
}

Go to top of page

TimedSendMessage

TypeFlags

TypeFlag Field #	Description
0	Time in seconds to sleep for (max 300)

Data

Data Field #	Description
0	Message to send

Example Event Definition:

In the following example, the event will wait for 5 seconds before sending Hello @user! to the user.

{
  "Name":"ExampleTimedSendMessage",
  "Description":"An example event",
  "type": "TimedSendMessage",
  "TypeFlags": [
    "5"
  ],
  "data": [
    "Hello _user_!"
  ]
}

Go to top of page

ReadMessageTriggerSuccessFail

TypeFlags

TypeFlag Field #	Description
0	Message to parse for

Data

Data Field #	Description
0	n/a

Example Event Definition:

In the following example, the event will search for the word hello in the first message it receives from the user. If the message does not have a match, it will return a failure otherwise it will return true.

{
  "Name":"ExampleReadMessageTriggerSuccessFail",
  "Description":"An example event",
  "type": "ReadMessageTriggerSuccessFail",
  "TypeFlags": [
    "hello"
  ]
}

Go to top of page

TriggerSuccess

TypeFlags

TypeFlag Field #	Description
0	n/a

Data

Data Field #	Description
0	n/a

Example Event Definition:

In the following example, the event will return an instant succes on the script it is being run from. It has no text output for the user.

{
  "Name":"ExampleTriggerSuccess",
  "Description":"An example event",
  "type": "TriggerSuccess"
}

Go to top of page

TriggerFailure

TypeFlags

TypeFlag Field #	Description
0	n/a

Data

Data Field #	Description
0	n/a

Example Event Definition:

In the following example, the event will return an instant failure on the script it is being run from. It has no text output for the user.

{
  "Name":"ExampleTriggerFailure",
  "Description":"An example event",
  "type": "TriggerFailure"
}

Go to top of page

SendMessageTriggerEvent

TypeFlags

TypeFlag Field #	Description
0	Message to send to user

Data

Data Field #	Description
0	eventID to trigger

Example Event Definition:

In the following example, the event will send Hello @user! and trigger the eventID 5dd4d56f immediately.

{
  "Name":"ExampleSendMessageTriggerEvent",
  "Description":"An example event",
  "type": "SendMessageTriggerEvent",
  "TypeFlags": [
    "Hello _user_!"
  ],
  "data": [
    "5dd4d56f"
  ]
}

Go to top of page

TriggerFailureSendError

TypeFlags

TypeFlag Field #	Description
0	n/a

Data

Data Field #	Description
0	Message to send in failure status

Example Event Definition:

In the following example, the event will trigger a failure status along with the message "Another day!" in the output.

{
  "Name":"ExTriggerFailureSendError",
  "Description":"An example event",
  "type": "TriggerFailureSendError",
  "data": [
    "Another day!"
  ]
}

Go to top of page

MessageChoiceDefault

The MessageChoiceDefault event will trigger a keyed message response when the corresponding keyword is found in a message. If no match is found, the default message will be sent.

Note: This will only trigger on the first keyword match in a message.

TypeFlags

TypeFlag Field #	Description
0	Keyword to trigger on
1	Second keyword to trigger on
2	Third keyword to trigger on
...	Up to ten choices may be defined

Data

The data array length must match the length of the TypeFlags array.

Data Field #	Description
0	Message to send
1	Message to send
2	Message to send
...	Up to ten messages may be defined

DefaultData

The default message to send if no match is found.

Example Event Definition:

In the following example, the event will send Hello @user! and trigger the eventID 5dd4d56f immediately.

{
  "Name":"ExampleMessageChoiceDefault",
  "Description":"An example event",
  "type": "MessageChoiceDefault",
  "TypeFlags": [
    "password123"
  ],
  "data": [
    "congrats"
  ],
  "defaultdata":"Nuh uh uh you didn't say the magic word!"
}

Go to top of page

MessageChoiceDefaultEvent

The MessageChoiceDefaultEvent event will trigger a keyed event when the corresponding keyword is found in a message. If no match is found, the default message will be sent.

Note: This will only trigger on the first keyword match in a message.

TypeFlags

TypeFlag Field #	Description
0	Keyword to trigger on
1	Second keyword to trigger on
2	Third keyword to trigger on
...	Up to ten choices may be defined

Data

It is not necessary to define an eventID, but the data array length must match the length of the TypeFlags array. If you do not have an event yet defined to trigger, a value of "nil" can be used and updated later. If a value other than nil is defined, a check will be performed to ensure that the ID is valid.

Data Field #	Description
0	ID of event to trigger (or nil)
1	ID of event to trigger (or nil)
2	ID of event to trigger (or nil)
...	Up to ten events may be defined

DefaultData

The defautl event to trigger if no match is found.

Example Event Definition:

In the following example, the event will send Hello @user! and trigger the eventID 5dd4d56f immediately.

{
  "Name":"ExMessageChoiceDefaultEvent",
  "Description":"An example event",
  "type": "MessageChoiceDefaultEvent",
  "TypeFlags": [
    "Hello _user_!"
  ],
  "data": [
    "5dd4d56f"
  ],
  "defaultdata":"lkj4ual"
}

Go to top of page

RollDiceSum

The RollDiceSum event will roll n-dice with x-faces and return the sum of the rolls to the eventmessages record for the event stream. You may need to retrieve this value from an event later.

TypeFlags

TypeFlag Field #	Description
0	Number of die faces (minium 2)
1	Number of dice to roll (minimum 1)

Data

You must have either a valid event ID or nil entered into the first element of the data array. After the die roll is completed the event here will be triggered.

Data Field #	Description
0	ID of next event to trigger (or nil)

Example Event Definition:

In the following example, one six-sided die will be rolled and the sum added to the eventmessages record for the event chain for later processing. After the die is rolled, the event 5dd4d56f will be triggered.

{
  "Name":"ExampleRollDiceSum",
  "Description":"An example event",
  "type": "RollDiceSum",
  "TypeFlags": [
    "6",
    "1"
  ],
  "data": [
    "5dd4d56f"
  ]
}

Go to top of page