Skill Book Api by November_Fir

Skill Book Api

A skill-book framework for Minecraft 1.21.1 on NeoForge — turn any ability into a physical book you slot into a 9-skill hotbar, upgrade with skill points, and fire with the number keys.

Skill Book Api does two jobs at once. For players, it adds a book-based ability system: skills live inside enchanted-looking books, books go into a dedicated skill bar, and in Combat Mode your 1–9 keys cast those skills instead of swapping items. For developers, it is a small, readable API to define skills in a few lines of Java and have the items, creative tab, networking, GUI and data sync generated for you.

Please note: this is a 1.0.0-demo release. It ships with two example skills (an apple-fuelled explosion and a charge-up lightning strike) purely to demonstrate the system. The real content is meant to come from add-on mods built on this API.

Showcase video

• 1.21.1 NeoForge Skill Book mod walkthrough (Chinese commentary): https://www.bilibili.com/video/BV1eFHv61Ezu/

What a player experiences

1. Skills are books
Every skill is a real item: a Skill Book. Hovering over one shows its name and every attribute it carries, for example Level: 3/20 or Power: 7/30. Right-click a book in your main hand to open its upgrade screen.

2. A dedicated 9-slot Skill Bar
Press K (default) to open the Skill Bar and drop up to nine skill books into it. The bar is stored per player and travels with you, so your loadout stays intact.

3. Combat Mode turns your number keys into casts
Press G (default) to toggle Combat Mode. While it is on, your hotbar selection is locked and the 1–9 keys fire the matching skill-bar slot instead of switching items. A compact overlay appears on the right side of the screen listing every bound key and its skill; a skill whose conditions are not met is greyed out and marked with xx instead of ->, so you can see at a glance what is ready.

4. Press, hold, release — three trigger phases
Each skill can react to three moments: down (instant cast), press (repeated while held, receiving the hold duration), and up (release, receiving how long you held). That is what makes charge-up and channel-style abilities possible — hold the key to build up, release to fire. Client-side callbacks run visual effects; server-side callbacks run the actual logic.

5. Skill points and upgrades
Attributes are levelled with Skill Points (SP) from the book's upgrade screen. Each attribute has its own max level and its own cost curve, so a skill can get progressively more expensive as it grows. Running out of SP or hitting the cap gives you a clear in-chat message. (In this demo build, SP is granted by the included "Skill Point x 100 Giver" item.)

The two bundled example skills

• Example Skill 1 — a resource-gated nuke. It checks your inventory for an apple before it fires (checker), consumes one, and detonates an explosion whose power scales with the book's Level and Power attributes. It shows how a skill can require items and how attributes feed directly into strength.
• Example Skill 2 — a charge-up storm. Holding the key draws an expanding ring of soul-fire particles around you (client-side, purely visual, radius grows with hold time); releasing it calls down lightning on every living entity inside that radius for Power × 10 damage. It shows off the press / up phases and client-server split.

For developers: the API

Defining a skill is a single builder chain. You decide the id, the display name, the attributes (with per-attribute cost formulas), the conditions, and what happens on each trigger phase — on the server, on the client, or both.

Skill example = new SkillBuilder()
    .id(ResourceLocation.fromNamespaceAndPath("mymod", "fireball"))
    .displayName(Component.translatable("skill.mymod.fireball"))
    .attributes(
        new SkillAttributeBuilder().id("level")
            .displayName(Component.translatable("attr.level"))
            .defaultValue(1).maxValue(20)
            .costGeter((player, value) -> 8 + value).build(),
        new SkillAttributeBuilder().id("power")
            .displayName(Component.translatable("attr.power"))
            .defaultValue(1).maxValue(30)
            .costGeter((player, value) -> 20 + value).build()
    )
    .downSer((player, book) -> {
        // server-side: real logic, e.g. damage, entities, items
    })
    .pressCli((player, book, dt) -> {
        // client-side: particles, sounds, HUD feedback
    })
    .upSer((player, book, dt) -> {
        // server-side: release effect, dt = how long the key was held
    })
    .checker((player, book) -> player.getInventory().contains(s -> s.is(Items.APPLE)))
    .build();

SkillRegistry.register(example);
SkillBookAutoRegistry.initEasy("mymod", bus);

That last line is the point of the mod: SkillBookAutoRegistry.initEasy scans the skills registered under your mod id and automatically creates the skill book items and a creative-mode tab for them. No item JSON, no registry boilerplate, no manual creative-tab wiring. Attribute values, skill-bar contents, skill points and combat-mode state are all handled by the mod's attachment types and network payloads, so you only write the behaviour.

Other conveniences: SkillApi.queueServerWork(delay, action) for scheduling delayed server-side tasks on the tick loop, and helpers such as SkillBookItem.getAttributeValue(stack, "power") to read a book's current attribute value straight from an ItemStack.

Requirements and compatibility

• Minecraft 1.21.1
• NeoForge 21.1.234 or newer
• No third-party mod dependencies — it runs standalone
• Required on both client and server (it registers network payloads, menus and player data attachments)

Controls (defaults, rebindable)

Current state and limitations

• Version 1.0.0-demo: a functional demonstration of the framework, not a content pack. Only the two example skills are included.
• Skill books are obtained from the auto-generated creative tab (Example Skill Book Tab); there are no survival crafting recipes yet.
• Skill points currently come only from the bundled "Skill Point x 100 Giver" item; a survival progression source is not implemented yet.
• Skill cooldowns are not enforced yet (the hook exists in the code but is disabled in this build).

Credits

• Author: Aulbilaister | November_Fir
• Built on the NeoForge ModDevGradle template

License

All Rights Reserved. Do not re-upload or redistribute modified versions of this mod.

简体中文说明

一个面向 Minecraft 1.21.1 NeoForge 的《技能书》框架：把技能变成一本真实存在的书，放进 9 格技能栏，用技能点升级，打开战斗模式后直接用数字键放技能。

这个模组同时做两件事： 对玩家，它是一套完整的技能系统； 对开发者，它是一套轻量的技能 API，几行代码定义一个技能，物品、创造模式栏目、网络同步、 GUI 与数据存储全部自动生成。

请注意：当前为 1.0.0-demo 演示版本，自带的两个示例技能仅用于演示系统能力，真正的技能内容需由基于本 API 的附属模组提供。

玩家体验

• 技能即书本：每个技能都是一本《技能书》物品，悬停显示技能名与全部属性（如等级 3/20、力量 7/30）；主手右键打开升级界面。
• 9 格技能栏：默认 K 键打开，把技能书放进去，数据按玩家保存。
• 战斗模式：默认 G 键切换。开启后物品栏选择被锁定，1–9 键不再切换物品，而是释放对应槽位的技能；屏幕右侧实时显示每个按键对应的技能名，条件不满足的会变灰并显示 xx。
• 三段触发：按下（down）、持续按住（press，每 3 tick 同步一次并传入持续时长）、松手（up，带蓄力时长）——所以蓄力技能可以很自然地做出来；客户端回调负责特效，服务端回调负责实际判定。
• 技能点与升级：在技能书界面消耗技能点升级属性，每个属性有独立上限与独立的消耗曲线；点数不足或已满级都有明确提示。演示版中技能点由自带的《技能点 x100》物品提供。

自带的两个示例技能

• 示例技能 1：需要背包内有苹果才能放（checker 条件），消耗一个苹果引焦，威力随《等级》与《力量》属性增长。
• 示例技能 2：按住蓄力时身边会出现一圈不断扩大的灵魂火炅（客户端特效），松手后对半径内所有生物降下闪电，伤害为《力量 × 10》。

开发者 API

用 SkillBuilder 链式定义技能：id、显示名、属性（含单独的升级消耗公式与上限）、触发条件、三个阶段的服务端/客户端回调； 再调用 SkillRegistry.register() 注册，最后一行 SkillBookAutoRegistry.initEasy("mymod", bus) 就会自动生成技能书物品与创造模式栏目。 属性数值、技能栏内容、技能点与战斗状态的存储与同步全部由模组内置的数据附件与网络包处理，你只需写行为逻辑。

安装要求

• Minecraft 1.21.1 + NeoForge 21.1.234 及以上
• 无第三方依赖，可单独使用
• 客户端与服务端均需安装

操作（默认，可自定义）

• G：切换战斗模式
• K：打开技能栏
• 1–9（战斗模式下）：释放对应槽位技能，持续按住可蓄力
• 右键技能书：打开升级界面

当前状态与局限

• 1.0.0-demo 版𐛘示版本，仅包含两个示例技能
• 技能书仅能从自动生成的创造模式栏目获取，暂无生存合成配方
• 技能点暂只能由自带物品获得，尚未实现生存获取途径
• 技能冷却未启用（代码中已留好接口，本版未实装）

鸣谢与许可

• 作者：Aulbilaister | November_Fir，基于 NeoForge ModDevGradle 模板构建
• All Rights Reserved，请力二次上传或重新分发修改版本