[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12,"_13":14},"actionData","errors","root",{"_211":212,"_213":-7,"_214":215,"_25":216},"c/Community",{"_66":192,"_193":194,"_25":195},"p/packageListing",{"_66":67,"_68":69,"_70":-7,"_71":72,"_57":-7,"_73":20,"_74":22,"_75":24,"_25":76},"wikiLayout",{"_15":56,"_19":20,"_21":22,"_23":24,"_40":-7,"_57":-7,"_25":58},"p/tabs/Wiki/WikiFirstPage",{"_15":16,"_17":18,"_19":20,"_21":22,"_23":24,"_25":26},"wiki",{"_37":48,"_35":49,"_40":50,"_42":51,"_44":52,"_53":54},"firstPage",{"_37":38,"_35":39,"_40":41,"_42":43,"_44":45,"_46":47},"communityId","mage-arena","namespaceId","D1GQ","packageId","BlackMagicAPI","seo",{"_27":28},"descriptors",[29,30],{"_35":36},{"_31":32,"_33":34},"name","description","content","Wiki page for D1GQ-BlackMagicAPI","title","BlackMagicAPI Guide - D1GQ-BlackMagicAPI | Thunderstore","id","3840","BlackMagicAPI Guide","slug","3840-blackmagicapi-guide","datetime_created","2025-08-02T21:45:04.288441Z","datetime_updated","2025-08-26T21:21:29.877476Z","markdown_content","# **BlackMagicAPI Guide** \n*A comprehensive framework for Mage Arena modding*\n\n## **Table of Contents**\n1. [Basic Setup](#basic-setup)\n2. [Spell Creation](#spell-creation) \n3. [Item System](#item-system) \n4. [Crafting Recipes](#crafting-recipes) \n5. [Soup System](#soup-system)\n6. [API Reference](#api-reference) \n7. [Troubleshooting](#troubleshooting)\n\n---\n\n## **Basic Setup** \n### **Core Requirements**\n- BepInEx 5.4.21+\n- .NET Framework 4.8\n- `BlackMagicAPI.dll` reference\n\n### **Plugin Template**\n```csharp\n[BepInPlugin(\"your.mod.id\", \"Your Mod Name\", \"1.0.0\")]\npublic class MyMod : BaseUnityPlugin\n{\n private void Awake()\n {\n // Registration examples\n BlackMagicManager.RegisterSpell(this, typeof(YourSpellData), typeof(YourSpellLogic));\n BlackMagicManager.RegisterItem(this, typeof(YourItemData), typeof(YourItemBehavior));\n BlackMagicManager.RegisterCraftingRecipe(this, typeof(IngredientA), typeof(IngredientB), typeof(Result));\n BlackMagicManager.RegisterDeathIcon(this, \"custom.death\", \"death_icon.png\");\n BlackMagicManager.RegisterSoup(this, typeof(LogItem), typeof(YourSoupData), typeof(YourSoupEffect));\n }\n}\n```\n\n---\n\n## **Soup System** \n### **Soup Registration**\n```csharp\n///

\n/// Registers a new soup with the soup management system.\n///

\n/// The plugin registering the soup.\n/// The type of the item used to create the soup (must implement IItemInteraction).\n/// The type of the soup data (must inherit from SoupData).\n/// The type of the soup effect (must inherit from SoupEffect, optional if SoupData can load a prefab).\n/// Thrown if soup data cannot be created or cast to SoupData.\nBlackMagicManager.RegisterSoup(\n BaseUnityPlugin plugin, \n Type IItemInteraction, \n Type SoupDataType, \n Type? SoupEffectType = null\n)\n```\n\n### **Soup Data Class**\n```csharp\ninternal class HealthSoupData : SoupData\n{\n public override string Name => \"Health Soup\";\n public override string ConsumeDescription => \"Restores health over time\";\n public override Color SoupColor => Color.red;\n \n // Optional: Load custom effect prefab\n public override Task GetEffectPrefab()\n {\n // Load your custom prefab here\n return Task.FromResult(null);\n }\n \n // Optional: Customize visual transform\n public override void SetObjectVisualTransform(GameObject render)\n {\n render.transform.localPosition = new Vector3(-0.0003f, 0.004f, 0.004f);\n render.transform.rotation = Quaternion.Euler(-3f, 0f, 0f);\n render.transform.localScale = render.transform.localScale * 0.03f;\n }\n}\n```\n\n### **Soup Effect Class**\n```csharp\ninternal class HealthSoupEffect : SoupEffect\n{\n public override void ApplyEffect(PlayerMovement player)\n {\n // Implement your soup effect logic here\n // Example: Heal player over time\n StartCoroutine(HealOverTime(player));\n }\n \n private IEnumerator HealOverTime(PlayerMovement player)\n {\n float duration = 10f;\n float healPerSecond = 2f;\n float elapsed = 0f;\n \n while (elapsed < duration)\n {\n if (player != null)\n {\n // Apply healing logic\n // player.health += healPerSecond * Time.deltaTime;\n }\n elapsed += Time.deltaTime;\n yield return null;\n }\n \n DisposeEffect();\n }\n \n // Optional: Custom prefab initialization\n public override void OnPrefabCreatedAutomatically(GameObject prefab)\n {\n // Add custom components or modify the prefab\n }\n}\n```\n\n### **Sprite Requirements**\n- Place soup UI sprites in `Sprites/{SoupName}_Ui.png` within your plugin directory\n- Sprite filename should have spaces removed (e.g., \"HealthSoup_Ui.png\")\n- Fallback to default empty UI sprite if custom sprite not found\n\n### **Complete Soup Example**\n```csharp\n// Registration\nBlackMagicManager.RegisterSoup(\n this,\n typeof(SoupBowlItem), \n typeof(HealthSoupData),\n typeof(HealthSoupEffect)\n);\n\n// Soup Data\ninternal class HealthSoupData : SoupData\n{\n public override string Name => \"Health Restoration Soup\";\n public override string ConsumeDescription => \"Gradually restores 20 health over 10 seconds\";\n public override Color SoupColor => new Color(1f, 0.2f, 0.2f, 1f);\n}\n\n// Soup Effect\ninternal class HealthSoupEffect : SoupEffect\n{\n public override void ApplyEffect(PlayerMovement player)\n {\n StartCoroutine(HealOverTime(player));\n }\n \n private IEnumerator HealOverTime(PlayerMovement player)\n {\n float totalHealing = 20f;\n float duration = 10f;\n float elapsed = 0f;\n \n while (elapsed < duration && player != null)\n {\n // Apply healing logic here\n elapsed += Time.deltaTime;\n yield return null;\n }\n \n DisposeEffect();\n }\n}\n```\n\n---\n\n## **Spell Creation** \n### **Spell Data Class**\n```csharp\ninternal class FireballData : SpellData\n{\n public override SpellType SpellType => SpellType.Page;\n public override string Name => \"Fireball\";\n public override float Cooldown => 3f;\n public override Color GlowColor => Color.red;\n \n // Additional voice command aliases\n public override string[] SubNames => [\"flameball\", \"inferno\"];\n}\n```\n\n### **Spell Logic Class**\n```csharp\ninternal class FireballLogic : SpellLogic\n{\n public override bool CastSpell(PlayerMovement caster, PageController page, Vector3 spawnPos, Vector3 viewDirectionVector, int castingLevel);\n {\n return true; // return true to go on cooldown\n }\n\n // Optional page item interaction\n public override void OnPageItemUse(PlayerMovement itemOwner, PageController page)\n {\n }\n}\n```\n\n### **Spell Prefab Access**\n```csharp\n// Get all active instances\nvar activeFireballs = Spell.GetLogicInstances();\n\n// Get specific prefab component\nvar fireballPrefab = Spell.GetLogicPrefab();\n\n// Check prefab existence\nif(Spell.GetPagePrefab() != null) \n{\n // Prefab is loaded\n}\n```\n\n### **Registration**\n```csharp\nBlackMagicManager.RegisterSpell(\n this, \n typeof(FireballData), \n typeof(FireballLogic)\n);\n```\n\n---\n\n## **Item System** \n### **Complete Item Example**\n```csharp\ninternal class HealthPotionData : ItemData\n{\n public override string Name => \"Health Potion\";\n}\n\ninternal class HealthPotionBehavior : ItemBehavior\n{\n protected override void OnItemUse(PlayerMovement itemOwner)\n {\n }\n}\n```\n\n---\n\n## **Crafting Recipes** \n### **Advanced Recipe Configuration**\n```csharp\n// Basic recipe\nBlackMagicManager.RegisterCraftingRecipe(\n this,\n typeof(FireEssence),\n typeof(IceShard), \n typeof(SteamSpirit)\n);\n```\n\n### **Recipe Requirements**\n| Component | Requirements |\n|-----------|-------------|\n| Ingredients | Must implement `IItemInteraction` |\n| Result | Must be a prefab of `IItemInteraction` |\n\n---\n\n## **API Reference** \n### **SpellLogic Class**\n```csharp\n///

\n/// Base class for all spell behaviors with lifecycle management\n///

\npublic abstract class SpellLogic : MonoBehaviour, ISpell\n{\n ///

\n /// Core spell casting implementation\n ///

\n public abstract void CastSpell(GameObject playerObj, PageController page, \n Vector3 spawnPos, Vector3 viewDirectionVector, int castingLevel);\n\n ///

\n /// Network data serialization for Castor\n ///

\n public virtual void WriteData(DataWriter writer, PageController page,\n GameObject player, Vector3 spawnPos, Vector3 direction, int level) {}\n\n ///

\n /// Client-side data synchronization\n ///

\n public virtual void SyncData(object[] values) {}\n}\n```\n\n### **Spell Utility Class**\n```csharp\n///

\n/// Generic spell accessor providing runtime management utilities\n///

\npublic class Spell where SD : SpellData\n{\n ///

\n /// Retrieves the PageController prefab for this spell type\n ///

\n public static PageController? GetPagePrefab() { ... }\n\n ///

\n /// Gets all active instances of this spell type\n ///

\n public static SpellLogic?[] GetLogicInstances() { ... }\n\n ///

\n /// Gets typed instances filtered by specific SpellLogic subtype\n ///

\n public static SL?[] GetLogicInstances() where SL : SpellLogic { ... }\n}\n```\n\n### **SoupData Class**\n```csharp\n///

\n/// Abstract base class representing soup data and configuration\n///

\npublic abstract class SoupData\n{\n public abstract string Name { get; }\n public abstract string ConsumeDescription { get; }\n public abstract Color SoupColor { get; }\n public int ItemId { get; internal set; }\n public int SoupId { get; internal set; }\n public BaseUnityPlugin? Plugin { get; internal set; }\n \n public virtual Task GetEffectPrefab() => Task.FromResult(null);\n public virtual void SetObjectVisualTransform(GameObject render) { }\n}\n```\n\n### **SoupEffect Class**\n```csharp\n///

\n/// Abstract base class for soup effect behavior logic\n///

\npublic abstract class SoupEffect : MonoBehaviour\n{\n internal int Id { get; set; }\n public abstract void ApplyEffect(PlayerMovement player);\n public virtual void OnPrefabCreatedAutomatically(GameObject prefab) { }\n public void DisposeEffect() { Destroy(gameObject); }\n}\n```\n\n---\n\n## **Troubleshooting** \n### **Common Soup Issues**\n- **Missing Sprites**: Ensure sprite files are in `Sprites/` folder with correct naming\n- **Registration Errors**: Ensure all types implement required interfaces","2101","D1GQ/BlackMagicAPI Wiki","2101-d1gqblackmagicapi-wiki","2025-08-02T21:45:04.281117Z","2025-08-26T21:21:29.879511Z","pages",[55],{"_37":38,"_35":39,"_40":41,"_42":43,"_44":45},{"_37":48,"_35":49,"_40":50,"_42":51,"_44":52,"_53":64},"permissions",{"_27":59},[60,61],{"_35":63},{"_31":32,"_33":62},"Wiki for D1GQ-BlackMagicAPI","D1GQ-BlackMagicAPI Wiki | Thunderstore",[65],{"_37":38,"_35":39,"_40":41,"_42":43,"_44":45},"community",{"_31":129,"_105":20,"_176":-5,"_32":177,"_178":-5,"_179":180,"_42":181,"_182":183,"_184":185,"_112":-5,"_186":187,"_188":189,"_190":191},"listing",{"_108":109,"_73":20,"_32":97,"_110":111,"_112":95,"_113":114,"_115":114,"_116":114,"_31":24,"_117":22,"_118":119,"_120":121,"_122":123,"_124":125,"_126":127,"_128":129,"_130":131,"_132":133,"_134":135,"_136":137,"_138":114,"_71":139,"_140":141,"_142":143,"_144":145},"listingStatus","team",{"_105":106,"_31":22,"_107":-5},"community_identifier","namespace_id","package_id",{"_27":77},[78,79,80,81,82,83,84,85,86,87],{"_35":104},{"_31":32,"_33":97},{"_88":102,"_33":103},{"_88":100,"_33":101},{"_88":98,"_33":99},{"_88":96,"_33":97},{"_88":94,"_33":95},{"_88":93,"_33":92},{"_88":91,"_33":92},{"_88":89,"_33":90},"property","og:site_name","Thunderstore","og:image:height","256","og:image:width","og:image","https://gcdn.thunderstore.io/live/repository/icons/D1GQ-BlackMagicAPI-3.0.2.png","og:description","An api that simplifies the task of adding custom spells, items, crafting recipes, and soups","og:title","BlackMagicAPI by D1GQ","og:url","https://thunderstore.io/c/mage-arena/p/D1GQ/BlackMagicAPI/wiki","og:type","website","BlackMagicAPI by D1GQ | Mage Arena | Thunderstore","identifier",21546,"donation_link","categories",[168,169],"download_count",43070,"icon_url","is_deprecated",false,"is_nsfw","is_pinned","namespace","rating_count",6,"size",647936,"latest_version_number","3.0.2","install_url","ror2mm://v1/install/thunderstore.io/D1GQ/BlackMagicAPI/3.0.2/","download_url","https://thunderstore.io/package/download/D1GQ/BlackMagicAPI/3.0.2/","community_name","Mage Arena","dependant_count",31,"dependencies",[148,149,150],"dependency_count",3,"full_version_name","D1GQ-BlackMagicAPI-3.0.2","has_changelog",{"_31":22,"_146":147},"website_url","https://github.com/D1GQ/BlackMagicAPI","package_created","2025-08-02T21:43:43.467137Z","version_created","2025-10-11T06:13:11.025819Z","members",[],{"_73":20,"_32":163,"_112":164,"_153":154,"_31":165,"_117":166,"_157":167},{"_73":20,"_32":159,"_112":160,"_153":154,"_31":161,"_117":22,"_157":162},{"_73":20,"_32":151,"_112":152,"_153":154,"_31":155,"_117":156,"_157":158},"A plugin for Mage Arena that synchronizes mods between host and clients. Press F9 to enable auto-kicking of non matching mod lists.","https://gcdn.thunderstore.io/live/repository/icons/hiccup-ModSync-1.1.0.png","is_active",true,"ModSync","hiccup","version_number","1.1.0","An api that simplifies the task of adding custom Network Objects.","https://gcdn.thunderstore.io/live/repository/icons/D1GQ-FishUtilities-1.3.0.png","FishUtilities","1.3.0","BepInEx pack for Mono Unity games. Preconfigured and ready to use.","https://gcdn.thunderstore.io/live/repository/icons/BepInEx-BepInExPack-5.4.2100.png","BepInExPack","BepInEx","5.4.2100",{"_31":173,"_40":174,"_37":175},{"_31":170,"_40":171,"_37":172},"Libraries","libraries","1465","Tools","tools","1464","short_description","Thunderstore is a mod database and API for downloading mods","wiki_url","discord_url","https://discord.gg/YXY5XZHG8R","2025-07-29T07:00:09.246573Z","hero_image_url","https://gcdn.thunderstore.io/assets/mage-arena/mage-arena-bg-1920x620.webp","cover_image_url","https://gcdn.thunderstore.io/assets/mage-arena/mage-arena-cover-360x480.webp","community_icon_url","https://gcdn.thunderstore.io/assets/mage-arena/mage-arena-icon-192x192.webp","total_download_count",545421,"total_package_count",102,{"_31":129,"_105":20,"_176":-5,"_32":177,"_178":-5,"_179":180,"_42":181,"_182":183,"_184":185,"_112":-5,"_186":187,"_188":189,"_190":191},"alerts",[],{"_27":196},[197,198,199,200,201,202,203,204,205,206],{"_35":209},{"_31":32,"_33":210},{"_88":102,"_33":103},{"_88":100,"_33":101},{"_88":98,"_33":209},{"_88":96,"_33":208},{"_88":94,"_33":187},{"_88":93,"_33":207},{"_88":91,"_33":207},{"_88":89,"_33":90},"88","Thunderstore is a mod database and API for downloading Mage Arena mods","The Mage Arena Mod Database","Mods for Mage Arena","publicEnvVariables",{"_235":233,"_236":233,"_237":233,"_238":239,"_240":241,"_242":233,"_243":244,"_245":246,"_247":248},"currentUser","config",{"_232":233,"_234":-7},{"_27":217},[218,219,220,221,222,223],{"_35":90},{"_31":32,"_33":231},{"_31":230,"_33":229},{"_31":228,"_33":229},{"_226":227},{"_31":224,"_33":225},"viewport","width=device-width, initial-scale=1","charSet","utf-8","theme-color","#29295b","msapplication-TileColor","An ecosystem for sharing mods for games!","apiHost","https://thunderstore.io","sessionId","VITE_SITE_URL","VITE_BETA_SITE_URL","VITE_API_URL","VITE_COOKIE_DOMAIN",".thunderstore.io","VITE_AUTH_BASE_URL","https://auth.thunderstore.io","VITE_AUTH_RETURN_URL","VITE_CLIENT_SENTRY_DSN","https://0dde07a3b02487bf768e90666ab8a83f@o578525.ingest.us.sentry.io/4509966833352704","VITE_RYBBIT_SITE_ID","00e7a81e15fc","VITE_RYBBIT_ANALYTICS_HOST","https://rybbit.thunderstore.io/api"]

Details

Categories

BlackMagicAPI Guide