This add-on is required for all other Cherry add-ons
Add-on | |
---|---|
Cherry Core | |
This add-on. Cherry Core is required for all other Cherry add-ons | |
Cherry Telegram | |
Utilizes Telegram's bot technology to transfer messages back and forth to the game. Telegram is free and creating a bot is free as well as easy. No coding skills are needed. Follow the instructions carefully to ensure that you don't have any issues | |
Cherry Discord | |
Send in game messages directly to your discord server. Utilize commands to communicate directly with your friends and free company members and any other message based usage you can think of. Directly command and receive message from supported add-ons mods. |
Cherry Connect allows your add-on to send and receive messages from any Cherry communication add-on the user has installed. When Your add-on requests access, Cherry Connect automatically registers with all communication add-ons that the user currently employs. The user has full control over which, if any, communication add-ons your add-on is allowed to connect to. Cherry Connect abstracts the individual details away and allows you to focus on sending and receiving messages without the details of the specific communication client that the user has deployed.
The Cherry Connect API is fairly simple and is accessed by the global variable
CherryConnect
Communication with the code is done in two ways: Callback functions and immediate result structs. The immediate function results will notify the user that the initial step taken was either successful or was an error. This handles cases where there are no clients registered or some other local issue happens. Further results and errors will be communicated in the callback function once the bot hears back from the communication Clients.
The function that is passed to CherryConnect.Register will be the function that which most user messages and commands will be routed. The exception would be Cherry Connect.MessageOptions where the user-selected option will be routed directly to the specially supplied function.
The When the user sends a message or command that is routed to cmd_func The signature will be function(result). The result will either be an error or a message result:
On errors:
{ mode = result_modes.error, err_code = error.error_code, message = message, }
See below for possible error codes and messages
On success:
{ mode = "message", message = { cmd = "ORIGINAL_COMMAND", text = "USER_MESSAGE" }, }
Result Modes
result_modes = { new_id = "new_id", success = "success", error = "error", message = "message", }
Error Codes
errors = { setting_commands = { error_code = 1001, message = "Error Setting Commands." }, missing_fields = { error_code = 1002, message = "Please provide an author, command function, mod name, and description." }, mod_name_spaces = { error_code = 1003, message = "Mod name cannot contain spaces." }, cmdFunc_not_function = { error_code = 1004, message = "[cmdFunc] must be a function." }, duplicate_mod = { error_code = 1005, message = "Mod already registered. Please use a different author / name combination." }, mod_not_found = { error_code = 1006, message = "Mod not found." }, id_not_supplied = { error_code = 1007, message = "ID not supplied." }, mod_not_allow_posting = { error_code = 1008, message = "Mod does not allow posting." }, message_not_supplied = { error_code = 1009, message = "Please supply a message." }, no_registered_clients = { error_code = 1010, message = "The user has not registered any communication clients." }, }
Cherry Connect functions are explained below:
Usage: Registers a mod through the Cherry Connect platform to enable an add-on to send/receive messages and commands with a user's installed communication clients.
CherryConnect.Register(author, cmd_func, mod_name, desc)
returns
On errors:
{ mode = result_modes.error, err_code = error.error_code, message = message, }
See below for possible error codes and messages
On success:
{ mode = "new_id", message = "MOD_ID", }
Notes
The mod name cannot conflict with any other mod or command. Mods do not share a 1 to 1 relationship with an add-on, so a single add-on can register multiple mods. MOD_ID Will be used in all the other API calls to identify which mod is making the call. The MOD_ID must be saved for as long as Cherry Core is not unloaded or until the mod is unregistered. Once the mod is unregistered, you must re-register the mod to access a new MOD_ID
Usage:
CherryConnect.Unregister(mod_id)
Unregisters the mod from Cherry Connect
Notes Most of the time, you will not need to unregister a mod. The mod will need to be re-registered anytime the add-ons are all reloaded and a new mod_id will be generated. If you're going to lose the mod_id and you need to re-register your mod without reloading Cherry Core, Then you will need to unregister the mod.
Usage:
CherryConnect.Message(mod_id, message)
Sends a message to all clients that the user has allowed the message to be sent to.
returns
On errors:
{ mode = result_modes.error, err_code = error.error_code, message = message, }
See below for possible error codes and messages
On success:
{ mode = "success", message = "Message sent.", }
Notes Sends a message to the user. This function does not allow a return function because there's no way for the user to directly reply to the message. If you need to give the user options to select then use the CherryConnect.MessageOptions function.
Usage:
CherryConnect.MessageOptions(mod_id, options, message, callback_func)
Sends a message that includes options that the user can select.
returns
On errors:
{ mode = result_modes.error, err_code = error.error_code, message = message, }
See below for possible error codes and messages
On success:
{ mode = "success", message = "Message sent.", }
Notes The option that is returned will exactly match one of the options that was sent. the callback_id should be immediately used when an option is selected. Some clients use this data to give the user ui feedback.
Usage:
CherryConnect.MessageResponse(mod_id, callback_id, message)
Let the user's client know That the option has been received successfully
* mod_id - required
Returns
On errors:
{ mode = result_modes.error, err_code = error.error_code, message = message, }
See below for possible error codes and messages
On success:
{ mode = "success", message = "Message sent.", }
Notes This should be used immediately after an option is selected from CherryConnect.MessageResponse to provide a good experience for the end user to understand that the option that they selected was acknowledged.
If you have any questions or need help, please visit the Cherry discord server: Cherry Discord