Differences

This shows you the differences between two versions of the page.

--- cherrycore [2024/03/25 21:50] – created onslaught
+++ cherrycore [2024/05/07 17:54] (current) – onslaught
@@ Line 1: / Line 1: @@
-{{::cherry:core_addon_logo.png?400|}}
+{{::cherry:core_addon_logo.png?150|}}
-<html>
+======Cherry Core======
-<span style="color:Black;font-size:300%;"> cherryCore </span>
-====
-The add-on is required for all other Cherry add-ons
-</html>
+This add-on is required for all other Cherry add-ons
+==== Cherry Add-ons List====
+^ ^ Add-on^
+| {{:cherry:core_addon_logo.png?100|}}| **[[cherrycore|Cherry Core]]** |
+|:::                                  |This add-on. Cherry Core is required for all other Cherry add-ons     |
+| {{:cherry:telegram_addon_logo.png?100|}}| **[[cherrytelegram|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:cherry:discord_wiki_logo.png?100|}}| **[[cherrydiscord|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 API Reference====
+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
+<code> CherryConnect </code>
+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.
+=== Main Communication function ===
+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:
+<code>
+{
+   mode = result_modes.error,
+   err_code = error.error_code,
+   message = message,
+}
+</code>
+// See below for possible error codes and messages//
+On success:
+<code>
+{
+   mode = "message",
+   message =
+   {
+     cmd = "ORIGINAL_COMMAND",
+     text = "USER_MESSAGE"
+   },
+}
+</code>
+=== Results & Errors ===
+**Result Modes**
+<code>
+result_modes = {
+   new_id = "new_id",
+   success = "success",
+   error = "error",
+   message = "message",
+}
+</code>
+**Error Codes**
+<code>
+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."
+	},
+}
+</code>
+Cherry Connect functions are explained below:
+=== CherryConnect.Register ===
+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.
+<code> CherryConnect.Register(author, cmd_func, mod_name, desc)</code>
+  * **author** - //required//
+    * The name of the author of the mod.
+  * **cmd_func** - //required//
+    * The function that will be called anytime the user communicates with one of the clients. The function signature must be function(result)
+  * **mod_name** - //required//
+    * This is the name of the mod and will also become the command that the user will use to communicate with the mod.
+  * **desc** - //required//
+    * This helps the user understand what the purpose of the mod is and is visible in the mod section of each communication client.
+**returns**
+On errors:
+<code>
+{
+   mode = result_modes.error,
+   err_code = error.error_code,
+   message = message,
+}
+</code>
+// See below for possible error codes and messages//
+On success:
+<code>
+{
+   mode = "new_id",
+   message = "MOD_ID",
+}
+</code>
+//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**
+{{:cherry:mod_view.png?600|}}
+=== CherryConnect.Unregister ===
+Usage:
+<code> CherryConnect.Unregister(mod_id)</code>
+Unregisters the mod from Cherry Connect
+  * **mod_id** - //required//
+    * The id of the mod that is being unregistered
+//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.
+=== CherryConnect.Message ===
+Usage:
+<code> CherryConnect.Message(mod_id, message)</code>
+Sends a message to all clients that the user has allowed the message to be sent to.
+  * **mod_id** - //required//
+    * The id of the mod that has been registered
+  * **message** - //required//
+    * The message to the user
+**returns**
+On errors:
+<code>
+{
+   mode = result_modes.error,
+   err_code = error.error_code,
+   message = message,
+}
+</code>
+// See below for possible error codes and messages//
+On success:
+<code>
+{
+   mode = "success",
+   message = "Message sent.",
+}
+</code>
+//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.
+=== CherryConnect.MessageOptions ===
+Usage:
+<code> CherryConnect.MessageOptions(mod_id, options, message, callback_func)</code>
+Sends a message that includes options that the user can select.
+  * **mod_id** - //required//
+    * The ID of the mod that has been registered.
+  * **options** - //required//
+    * A list of options that the user has to select from. The options are in the format of: {"Option1","Option2","Option3",...}
+  * **message** - //required//
+    * The message to the user.
+  * **callback_func** - //required//
+    * The function that gets called when the user selects an option. The function is in the format of: function(option, callback_id)
+**returns**
+On errors:
+<code>
+{
+   mode = result_modes.error,
+   err_code = error.error_code,
+   message = message,
+}
+</code>
+// See below for possible error codes and messages//
+On success:
+<code>
+{
+   mode = "success",
+   message = "Message sent.",
+}
+</code>
+//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.
+=== CherryConnect.MessageResponse ===
+Usage:
+<code> CherryConnect.MessageResponse(mod_id, callback_id, message)</code>
+Let the user's client know That the option has been received successfully
+ * **mod_id** - //required//
+    * The id of the mod that has been registered.
+  * **callback_id** - //required//
+    * The callback ID that was given from a successful option selection of the CherryConnect.MessageOptions function
+  * **message** - //optional//
+    * A simple message to the user acknowledging that the option was selected.
+**Returns**
+On errors:
+<code>
+{
+   mode = result_modes.error,
+   err_code = error.error_code,
+   message = message,
+}
+</code>
+// See below for possible error codes and messages//
+On success:
+<code>
+{
+   mode = "success",
+   message = "Message sent.",
+}
+</code>
+//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.
+==== Troubleshooting ====
+If you have any questions or need help, please visit the Cherry discord server:
+[[https://discord.gg/NTnZZAsjHj|Cherry Discord]]

User Tools

Site Tools

Differences

Page Tools