{"id":13340822,"url":"https://github.com/PaciStardust/SimpleOscBot","last_synced_at":"2025-03-11T19:30:45.332Z","repository":{"id":213734572,"uuid":"519583949","full_name":"PaciStardust/SimpleOscBot","owner":"PaciStardust","description":"SimpleOscBot is a free to use template for Discord Bots with OSC integration. Setting it up takes only a few minutes.","archived":false,"fork":false,"pushed_at":"2024-06-06T16:00:21.000Z","size":58,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-06T17:53:39.723Z","etag":null,"topics":["discord","discord-bot","open-sound-control","osc","vrchat"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PaciStardust.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-07-30T17:47:51.000Z","updated_at":"2024-06-06T16:00:25.000Z","dependencies_parsed_at":"2023-12-22T18:25:21.228Z","dependency_job_id":"1d56a87c-0a6d-44d9-bb9c-6b54700096ae","html_url":"https://github.com/PaciStardust/SimpleOscBot","commit_stats":null,"previous_names":["pacistardust/simpleoscbot"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaciStardust%2FSimpleOscBot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaciStardust%2FSimpleOscBot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaciStardust%2FSimpleOscBot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaciStardust%2FSimpleOscBot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PaciStardust","download_url":"https://codeload.github.com/PaciStardust/SimpleOscBot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221243422,"owners_count":16783635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord","discord-bot","open-sound-control","osc","vrchat"],"created_at":"2024-07-29T19:24:02.538Z","updated_at":"2024-10-23T22:31:03.345Z","avatar_url":"https://github.com/PaciStardust.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimpleOscBot\n\nSimpleOscBot is a free to use *(as long as you give credit)* template for Discord Bots with OSC integration.\nSetting it up takes only a few minutes.\n\n# Warning\nThis project is outdated, if you need me to update it, let me know and ill do it if demand is high enough\n\nJoin the discord here: https://discord.gg/pxwGHvfcxs\n\nThe bot comes with the following features:\n- Full [Discord.NET](https://discordnet.dev/) *(Slash commands, Interactions, etc)*\n- Sending any OSC data in an easy way *(Thanks to *[CoreOSC](https://github.com/PaciStardust/CoreOSC-UTF8))*\n- An OSC Listener-framework that allows for easy listening on any port and custom handling\n- Logging functions for easy logging\n\nThe template comes with following examples:\n- A group of preconfigured slash commands to see how OSC control works\n- An OscListener that splits incoming traffic to multiple ports\n- An OscListener that shows the contents of incomming traffic\n\nKnown Issues:\n- Seems to have trouble handling bools, this can be fixed by using 0 and 1 instead, if you know how to fix it, please lmk\n\n## SETUP\n1. Create your own discord bot at the Discord Developer Platform\n2. Invite the bot into a server\n3. Set up the project and install Discord.NET via NuGet\n4. Copy the bot token into the config file\n5. Copy the main Sever-ID into the config aswell\n6. You are done! Server should be able to be started.\n\n# Config\nThe config file contains various useful and needed things for your bot to run\n* **BotToken**: The token of your bot (Available on the Discord Dev Portal)\n* **GuildId**: The main server of your bot, this is where commands will be loaded first\n* **DefaultSendIp**: The default IP for your bot to send OSC data to\n* **DefaultSendPort**: The default Port your bot sends OSC data to\n* **EnabledLogs**: Disables and enables different log levels in the Console window, by default everything is on, if the bot does a lot I recommend disabling \"Log\"\n* **GlobalCommands**: Makes commands load in any server the bot is in, should only be done once the bot is set up and its actually required, takes approx 30 minutes\n* **Listeners**: Information about all the listeners you want to start up at launch of the bot\n\t* **Name**: The identifier of the Listener in the logs\n\t* **Port**: The port the listener is listening on\n\t* **Type**: The exact type name of the listener class, this needs to be exact as it will crash otherwise (You really have to use the *full name* for it to work. *Ex: SimpleOscBot.OSCControl.ListenerDebugExample*)\n\t* **Data**: An array of data of any type (can be mixed) for the listener to use when starting up (*Ex: Ports to send data to, addresses to listen to*), you have to implement the parsing of those in the listener classes \"AssignData\" function (An example can be found in the listener examples)\n\n\n# DOCUMENTATION\n\n## using SimpleOscBot\n\n### Program\n The programm class handles the start of the bot, it starts all other services and publishes the slash command\n\n### InteractionHandler\nThis class handles everything in regard to Discords interaction system\n\n### Config\nThis file reads the config file and provides access to variables that can quickly change via Config.Data\n\n## using SimpleOscBot.Services\n\n### Logger\nThis class handles all logging for both OSC and Discord\n\n#### Logger.Log()\nLogs data in multiple ways\n\n```csharp\n//Logging using only a Discord LogMessage\nLogger.Log(new LogMessage(LogSeverity.Verbose, \"LogSource\", \"LogMessage\"));\n\n//Logging using a specified severity\nLogger.Log(\"LogMessage\", \"LogSource\", LogSeverity.Warning);\n\n//Leaving out the severity makes it verbose\nLogger.Log(\"LogMessage\", \"LogSource\")\n```\n\n#### Logger.Error()\nLog errors in multiple ways\n\n```csharp\n//Using an error for logging\nLogger.Error(exception, \"ErrorSource\");\n\n//Without error\nLogger.Error(\"ErrorType\", \"ErrorMessage\", \"ErrorSource\", \"ErrorStackTrace\");\n\n//The trace can be left out\nLogger.Error(\"ErrorType\", \"ErrorMessage\", \"ErrorSource\");\n\n//Alternatively it can be handled like any log message\nLogger.Error(\"ErrorMessage\", \"ErrorSource\");\n```\n\n#### Logger \"Shortcuts\"\nThese function basically as proxies for calling Logger.Log with different severities\n\n```csharp\n//Logging Info (Dark Gray)\nLogger.Info(\"LogInfo\", \"InfoSource\");\n\n//Logging Warning (Yellow)\nLogger.Warning(\"LogWarning\", \"WarnSource\");\n\n//Logging Debug (Dark Blue)\nLogger.Debug(\"LogDebug\", \"DebugSource\");\n```\n\n### Embeds\nThis class is a utility class for quickly creating embeds for Discord Messages\n\n#### Embeds.CreateField()\nCreates a simple EmbedFieldBuilder to use when manually building an embed\n```csharp\n//Creates a basic field\nvar field = Embeds.CreateField(\"Title\", \"Content\");\n\n//Creates the same field but inline\nvar field = Embeds.CreateField(\"Title\", \"Content\", true);\n```\n\n#### Embeds\u003cspan\u003e.Info()\nCreates a basic info embed to use in a reply\n```csharp\n//Creating the embed, color will be light gray\nvar info = Embeds.Info(\"Title\", \"Content\");\n\n//Using a different color\nvar info = Embeds.Info(\"Title\", \"Content\", Color.Red);\n```\n\n#### Embeds.Error()\nCreates a special type of embed to tell the user something went wrong and automatically logs it\n\n```csharp\n//Creates an error embed\nvar err = Embeds.Error(\"ErrorType\", \"ErrorMessage\", \"ErrorTrace\");\n\n//Trace is again optional\nvar err = Embeds.Error(\"ErrorType\", \"ErrorMessage\");\n\n//Using an error instead\nvar err = Embeds.Error(exception);\n\n//Disable logging\nvar err = Embeds.Error(\"ErrorType\", \"ErrorMessage\", \"ErrorTrace\", false);\nvar err = Embeds.Error(exception, false);\n```\n\n#### Error \"Utility\"\nA few embeds to tell a user something went wrong that might come up more often\n\n```csharp\n//A user has given invalid input\nvar invalidInput = Embeds.InvalidInput();\n\n//A command has yielded no result\nvar noResult = Embeds.NoResult();\n\n//A command has been run outside a server when it shouldnt have\nvar invalidGuild = Embeds.InvalidGuild();\n\n//A database error has occured, unlike the others actually marked as error\nvar dbError = Embeds.DbFailure();\n```\n\n## using SimpleOscBot.OSCControl\n\n### OSC\nThe main class to handle OSC related things\n\n#### OSC.InitializeListeners()\nThis starts all the the listeners using reflection and the config file, it can only be called once\n\n#### OSC.SendCustom()\nSend OSC-Data to any IP with any Port, it returns a boolean value if sending was successful\n\n```csharp\n//Sending a single string to /test/address on localhost:9000\nvar sent = OSC.SendCustom(\"/test/address\", \"127.0.0.1\", 9000, \"test\");\n\n//Sending both an int and a float instead\nvar sent = OSC.SendCustom(\"/test/address\", \"127.0.0.1\", 9000, 1, 0.1f);\n\n//To avoid confusion you can also pack it into an array\nvar data = new object[] { 1, 0.1f };\nvar sent = OSC.SendCustom(\"/test/address\", \"127.0.0.1\", 9000, data);\n```\n\n#### OSC.Send()\nBehaves identically to SendCustom but uses the IP and Port listed as default in the config file\n\n```csharp\n//Sending a single string to /test/address on localhost:9000\nvar sent = OSC.Send(\"/test/address\", \"test\");\n\n//Sending both an int and a float instead\nvar sent = OSC.Send(\"/test/address\", 1, 0.1f);\n\n//To avoid confusion you can also pack it into an array\nvar data = new object[] { 1, 0.1f };\nvar sent = OSC.Send(\"/test/address\", data);\n```\n\n#### OSC.SplitAddress()\nSplits an address into an array of strings for easier parsing\n\n```csharp\nvar address = \"/test/address\";\n//Split into \"test\" and \"address\"\nvar split = OSC.SplitAddress(address);\n```\n\n### OscListenerBase\nAbstract class all listeners inherit from\n\n#### Port\nThe port the listener listens on, can only be set when starting it\n\n#### Name\nThe identifier of the listener, can only be set when starting it\n\n#### Start()\nStarts the listener with a name, port and data, can only be called once\n\n```csharp\n//Creating the instance of a listener (using an example here)\n//This should never really be done manually unless neccesary\nvar listener = new ListenerRelayExample();\n\n//Data (in this case ports) for the listener\nvar ports = new List\u003cobject\u003e() { 9000, 9020 };\n\n//Starting the listener\nlistener.Start(\"ListenerName\", \"ListenerPort\", ports);\n```\n\n#### virtual AssignData()\nOptional override to parse the data sent with Start\n\n```csharp\nprivate List\u003cstring\u003e _strings = new();\n\n//Overriding the function\nprotected override void AssignData(List\u003cobject\u003e data)\n{\n\t//Iterating through array\n\tforeach(var item in data)\n\t{\n\t\t//Adding all strings to list of strings\n\t\tif (item.GetType() == typeof(string))\n\t\t{\n\t\t\tvar newString = (string)item;\n\t\t\tLogger.Info($\"Added \\\"{newString}\\\" to list of strings in listener \\\"{Name}\\\"\", Name);\n\t\t\t_strings.Add(newString);\n\t\t}\n\t}\n}\n```\n\n#### abstract HandleData()\nFunction gets called whenever data is received by the listener\n\n```csharp\n//Setting the function\nprotected override Task HandleData(string address, params object[] args)\n{\n\t//Splitting address\n\tvar splitAddress = OSC.SplitAddress(address);\n\n\t//Return if address is somehow empty or the address is not testing\n\tif (splitAddress.Length == 0 || splitAddress[0] != \"testing\") return Task.CompletedTask;\n\n\t//Gathering a list of all types\n\tvar typeList = new List\u003cstring\u003e();\n\n\tforeach(var arg in args)\n\t{\n\t\ttypeList.Add(arg.GetType().FullName);\n\t}\n\n\t//Logging types\n\tLogger.Debug($\"Data sent to \\\"{address}\\\" on port {Port}: {string.Join(\", \", typeList)}\", Name);\n\treturn Task.CompletedTask;\n}\n```\n\n### ListenerDebugExample\nAn example for a listener that just logs the data sent to it\n\n### ListenerRelayExample\nAn example for a listener that takes data and sends it to multiple other points\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPaciStardust%2FSimpleOscBot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPaciStardust%2FSimpleOscBot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPaciStardust%2FSimpleOscBot/lists"}