Talents API

A powerful and highly customizable API mod for adding RPG-style Talents to your Minecraft mod.

Talents API allows mod developers to create:

• Infinite talent trees
• Offensive and defensive abilities
• Passive or active effects
• Custom talent screens
• Unlock systems
• Progression mechanics
• Networking-based synchronization

The API is designed to be simple, lightweight, and fully expandable for your own systems.

---

Features

• Create unlimited talents
• Root and child talent support
• Offensive, defensive, and custom talent types
• Talent dependency system
• Easy talent effect implementation
• Client/server networking support
• Fully customizable GUI system
• Item-based talent unlocking support
• Lightweight and easy to integrate

---

Installation

Add the GitHub Packages repository to your build.gradle:

repositories {
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/CobraGamingSj/TalentsAPI")
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
            password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

Then add the dependency:

dependencies {
    modImplementation "org.cobra.api:talents-api:x.x+y.y.y"
}

Replace the version with the version you are using. Example: 1.0+1.21.11

---

Creating Talents

Example talent registration:

public class Talents {

    // Example talent effect

    public static final AttackTalentEffect ATTACK_EFFECT = new AttackTalentEffect();

    // Root talent

    public static final Talent<AttackTalentEffect> ATTACK =
            Talent.root("name", ATTACK_EFFECT, 0);

    // Child talents

    public static final Talent<AttackTalentEffect> EXAMPLE_1 =
            Talent.ofAttack("name", ATTACK, EXAMPLE_EFFECT_1, 1);

    public static final Talent<AttackTalentEffect> EXAMPLE_2 =
            Talent.ofDefense("name", ATTACK, EXAMPLE_EFFECT_2, 2);
}

The last integer parameter is the buttonIndex.

This can be useful for:

• Networking
• Unlock systems
• GUI interactions
• Synchronizing talent buttons

---

Creating Talent Effects

Talent effects are fully customizable.

Example:

public class AttackTalentEffect implements TalentEffect {

    @Override
    public void apply(PlayerEntity user,
                      @Nullable LivingEntity target,
                      int level) {

        user.addStatusEffect(
                new StatusEffectInstance(
                        StatusEffects.STRENGTH,
                        -1,
                        1,
                        false,
                        false,
                        false
                )
        );
    }
}

Talent effects can:

• Apply status effects
• Modify attributes
• Damage entities
• Heal players
• Trigger particles
• Spawn lightning
• Add passive abilities
• Execute custom logic

Some effects may require Mixins depending on the behavior you want to implement.

---

Example Talent Screen

The API does not provide a built-in GUI.

You are free to:

• Create your own talent screen
• Design custom widgets/buttons
• Use your own textures/layouts
• Build unique progression trees

Example screen implementation:

public class TalentScreen extends Screen {

    private final Map<Talent<?>, ButtonWidget> talentButtons = new HashMap<>();
    private Talent<?> selectedTalent;

    @Override
    protected void init() {

        int i = (this.width - 176) / 2;
        int j = (this.height - 166) / 2;

        TalentButton attackTalentButton =
                new TalentButton(
                        i + 10,
                        j + 30,
                        Talents.ATTACK,
                        button -> selectedTalent = Talents.ATTACK,
                        player
                );

        this.addDrawableChild(attackTalentButton);

        talentButtons.put(Talents.ATTACK, attackTalentButton);
    }
}

TalentButton is a custom widget used by the Talents mod itself.

API users are expected to create their own widgets, layouts, and talent selection logic.

In this example, clicking the button simply selects the talent:

selectedTalent = Talents.ATTACK;

---

Unlocking Talents

Talents can be unlocked using:

• Custom items
• GUI buttons
• Networking packets
• Commands
• Currency systems
• Experience systems
• Any custom mechanic you create

Example networking usage:

ClientPlayNetworking.send(
        new TalentDataPayload(selectedTalent.buttonIndex())
);

---

Fully Expandable

Talents API is intentionally designed to be flexible.

You can build:

• RPG systems
• Skill trees
• Combat classes
• Weapon abilities
• Armor passives
• Custom player progression systems

---

Notes

• The API only provides the talent framework.
• GUI design is left entirely to the developer.
• Networking logic can be customized.
• Talents can have infinite depth and branching paths.

---

Example Uses

• Sword mastery
• Critical hit systems
• Lifesteal
• Lightning attacks
• Defense passives
• Bow abilities
• Custom combat mechanics
• Magic progression

---

Requirements

• Fabric Loader 0.15.0+
• Fabric API
• Minecraft 1.21.5+

---

Networking Example

Talents API can easily be integrated with Fabric Networking for synchronizing talent unlocks between the client and server.

Example payload implementation:

public record TalentDataPayload(int buttonIndex) implements CustomPayload {

    public static final Id<TalentDataPayload> ID =
            new Id<>(Identifier.of(TalentsMod.MOD_ID, "talents"));

    public static final PacketCodec<RegistryByteBuf, TalentDataPayload> CODEC =
            PacketCodecs.VAR_INT
                    .xmap(TalentDataPayload::new,
                          TalentDataPayload::buttonIndex)
                    .cast();

    public void handlePacket(ServerPlayNetworking.Context context) {

        switch (buttonIndex) {

            case 0 ->
                    TalentManager.unlockTalent(
                            context.player(),
                            Talents.ATTACK
                    );

            case 1 ->
                    TalentManager.unlockTalent(
                            context.player(),
                            Talents.EXAMPLE_1
                    );

            case 2 ->
                    TalentManager.unlockTalent(
                            context.player(),
                            Talents.EXAMPLE_2
                    );
        }
    }

    @Override
    public Id<? extends CustomPayload> getId() {
        return ID;
    }
}

---

Sending the Packet

Example client-side packet sending:

ClientPlayNetworking.send(
        new TalentDataPayload(selectedTalent.buttonIndex())
);

This allows:

• Unlocking talents from buttons
• Custom item interactions
• GUI synchronization
• Server-side validation
• Multiplayer support

---

Unlocking Talents Through Networking

The example above uses:

TalentManager.unlockTalent(player, talent);

to unlock talents directly from networking packets.

You can fully customize:

• Unlock conditions
• Required items
• Experience requirements
• Skill points
• Currency systems
• Quest rewards
• Commands
• Custom progression systems

Item-based requirements may require Mixins depending on how you implement the unlock logic.

---

Player Data Integration

Talents API stores unlocked talents inside a PlayerTalentData instance.

To ensure talent data persists when players leave and rejoin the world, you must save and load the data using Mixins.

The API provides:

// For 1.21.5
playerTalentData.talents$writeNbt(NbtCompound nbt);
playerTalentData.talents$readNbt(NbtCompound nbt);

// For 1.21.6 or higher
playerTalentData.talents$writeNbt(WriteView view);
playerTalentData.talents$readNbt(ReadView view);

These methods should be called from a Mixin targeting either:

PlayerEntity

or

ServerPlayerEntity

Example:

// For 1.21.5
@Inject(method = "writeCustomDataToNbt", at = @At("TAIL"))
private void writeTalents(NbtCompound nbt, CallbackInfo ci) {
    playerTalentData.talents$writeNbt(nbt);
}

@Inject(method = "readCustomDataFromNbt", at = @At("TAIL"))
private void readTalents(NbtCompound nbt, CallbackInfo ci) {
    playerTalentData.talents$readNbt(nbt);
}

// For 1.21.6 or higher
@Inject(method = "writeCustomData", at = @At("TAIL"))
private void writeTalents(WriteView view, CallbackInfo ci) {
    playerTalentData.talents$writeNbt(view);
}

@Inject(method = "readCustomData", at = @At("TAIL"))
private void readTalents(ReadView view, CallbackInfo ci) {
    playerTalentData.talents$readNbt(view);
}

If you do not save and load the player talent data, unlocked talents will not persist between world saves or player reconnects.