Kindred Souls

Kindred Souls 1.1.0

API Update Notes (For Addon Developers)

Hello addon developers! Version 1.1.0 marks a major expansion of the Kindred Souls API — introducing the Ability Types System and improving overall addon integration and flexibility.

This update focuses on API structure, ability customization, and event-driven logic, giving you more control over how Guardian and Ward roles behave.

---

1. Unified API Access — IKindredSoulsAPI

All API interactions are now unified under a single singleton interface.
You should no longer call managers directly — instead, access everything through IKindredSoulsAPI.

Old (deprecated):

SoulbindManager.getSomeData(...);

New (current):

IKindredSoulsAPI.getInstance().getSomeData(...);

This singleton provides access to all core systems — including the new Ability Registry:

// Retrieve the ability registry
AbilityRegistry registry = IKindredSoulsAPI.getInstance().getAbilityRegistry();

---

2. Creating and Registering Custom Abilities

The new Ability Types API lets you define your own Guardian and Ward “classes” with custom behavior and lore.

Step 1: Implement IAbilityType

For convenience, you can extend the provided AbilityType class, which handles most boilerplate setup for you.

public class MyShadowGuardianAbility extends AbilityType {

    public static final ResourceLocation ID = new ResourceLocation("my_addon", "shadow_guardian");
    public static final ResourceLocation ICON = new ResourceLocation("my_addon", "textures/gui/shadow_guardian_icon.png");

    public MyShadowGuardianAbility() {
        super(
            ID,
            AbilityRole.GUARDIAN, // The role this ability is tied to
            Component.translatable("ability.my_addon.shadow_guardian.name"),
            Component.translatable("ability.my_addon.shadow_guardian.desc"),
            Component.translatable("ability.my_addon.shadow_guardian.lore"), // Lore for selection UI
            ICON
        );
    }
}

💡 Note:
The getLore() component is now synced automatically from the server.
The AbilityLoreRegistry still exists, but its role is solely for defining additional lore entries that are referenced in the selection UI — not for syncing or registration.

Step 2: Register Your Ability

Abilities must be registered via the Ability Registry during the common setup phase (FMLCommonSetupEvent):

IKindredSoulsAPI.getInstance().getAbilityRegistry().register(new MyShadowGuardianAbility());

If multiple abilities exist for the same role, the player will automatically be prompted to choose between them.

Optional: Define Extra Lore (Client-Side)

If you want to define extra lore entries that appear in the selection UI or tooltips, register them through the AbilityLoreRegistry on the client:

@Mod.EventBusSubscriber(bus = Mod.EventBusSubscriber.Bus.MOD, value = Dist.CLIENT)
public class MyAddonClientSetup {
    @SubscribeEvent
    public static void onClientSetup(FMLClientSetupEvent event) {
        AbilityLoreRegistry.register(
            MyShadowGuardianAbility.ID,
            Component.translatable("ability.my_addon.shadow_guardian.lore")
        );
    }
}

---

3. New Forge Events for Ability Logic

Several new Forge events have been added to let you define custom logic for your abilities.

Event	Description	Cancelable
SoulbindHurtEvent	Fired when a bound player is hurt, before damage sharing occurs. Modify or cancel to override logic.	✅
SoulbindHealEvent	Fired when a bound player heals, before healing is shared. Cancel to implement your own logic.	✅
SoulbindPlayerTickEvent	Fired once per second for each bound player. Ideal for passive buffs or visual effects.	❌
SoulbindActiveAbilityEvent	Fired when a player triggers an active ability (you should post this from your keybind handler).	✅

Example: Passive effect logic

@SubscribeEvent
public static void onPlayerTick(SoulbindPlayerTickEvent event) {
    ResourceLocation typeId = IKindredSoulsAPI.getInstance().getPlayerAbilityType(event.getPlayer());

    if (MyShadowGuardianAbility.ID.equals(typeId)) {
        if (event.getPlayer().isCrouching()) {
            event.getPlayer().addEffect(new MobEffectInstance(MobEffects.INVISIBILITY, 30, 0, true, false));
        }
    }
}

---

4. Additional Technical Updates

• GUI Networking Overhaul:
  All GUI-opening packets (S2C_Open...Packet) are now handled by a centralized ClientPacketHandler, fixing server-side crashes and removing the need for DistExecutor checks.

• Global Save Data:
  SoulbindSaveData now stores globally in the Overworld rather than per-dimension.
  Internal access remains through SoulbindManager.getSaveData().

• Lore Registry Clarification:
  The AbilityLoreRegistry remains part of the API but is now purely for defining lore content that appears in UIs or tooltips.
  It does not handle registration or synchronization — that’s fully managed by the server.

---

5. Summary

Kindred Souls 1.1.0 transforms the mod’s backend into a flexible API for addon developers.
You can now:

✅ Create and register your own Guardian and Ward ability types.
✅ Use centralized API access via IKindredSoulsAPI.
✅ Hook into new Forge events for active and passive abilities.
✅ Define UI lore through the AbilityLoreRegistry.

🔧 Migration Tip:
Replace all direct manager references with IKindredSoulsAPI.getInstance().
Only use the AbilityLoreRegistry to define lore, not for syncing or gameplay logic.