Spear Core

Lyingice's Spear Library · 长矛公共库

本作者长矛模组共用的底层库：把矛的移动判定、命中检测、蓄力阶段与生物 AI 抽出来，供各版本的长矛模组复用。 整合包作者可以不写一行 Java —— 用 KubeJS 脚本就能注册一把真正的矛。

中文在前，English below.

KubeJS：用脚本加自己的矛（重点）

不写 Java、不改模组本体，五行脚本就是一把真矛：

StartupEvents.registry('item', event => {
    event.create('mypack:bronze_spear', 'spearcore:spear')
        .displayName('青铜矛')
        .durability(400)
        .attackDamageBonus(3)
        .texture('mypack:item/bronze_spear')
})

• 第二参数 'spearcore:spear' 是物品类型，写了它才会用本库的矛类创建。
• 所有参数都能在脚本里调：耐久、攻击力、冲锋伤害系数、攻速、附魔能力、四段蓄力时长、攻击距离、判定箱、冲锋推力、击退、击落骑手、怪物距离倍率、音效……不写就沿用铁矛的数值。
• 造出来的是真矛：戳刺、冲锋、第一/第三人称动作、附魔、怪物 AI 一视同仁，不用再配任何东西。
• 脚本没生效时本库照常运行，不会报错、也不会加载任何相关代码。
• KubeJS 版本：1.21.1 用 2101.x，1.20.1 用 2001.x。
• 完整参数表、贴图规范与常见坑见仓库里的 kjs-guide.md（中英双语）。

其余提供什么

• 长矛基类：继承即可拥有戳刺、蓄力冲锋，以及多段阶段窗口（起手 / 击落骑手 / 击退 / 伤害）。
• 速度判定接口：自定义生物实现 UseSpearSpecialEntity 就能接入同一套"移动越快伤害越高"的规则，所需速度、攻击距离、伤害倍率都可调。
• 命中与击退工具：沿视线方向的实体命中检测，以及命中后攻击者自身的动量处理。
• 生物用矛 AI：靠近、蓄力、冲锋、拉开距离的通用 Goal。
• 突进：戳刺时向前推进的通用实现。

谁需要它

• 玩家：不用单独装 —— 依赖它的长矛模组会自动带上。
• 整合包作者：想加自己的矛，看上面的 KubeJS 一节就够，不需要写代码。
• 模组作者：想基于它做自己的矛，或让自己的生物会用矛，可以单独装来开发。

版本

Minecraft	加载器
1.20.1	Forge 47.3.0+
1.21.1	NeoForge 21.1+

客户端与服务端都要装。

链接

• 源码 / 问题反馈：https://github.com/lyingice/Spear-Core
• KubeJS 教程：仓库内 kjs-guide.md

许可

MIT License

---

Lyingice's Spear Library · English

The shared core behind this author's spear mods: movement-based damage, hit detection, charge phases and mob AI — with first-class KubeJS support so modpack authors can add their own spears without writing Java.

KubeJS: add your own spear from a script

No Java, no touching the mod itself — five lines give you a real spear:

StartupEvents.registry('item', event => {
    event.create('mypack:bronze_spear', 'spearcore:spear')
        .displayName('Bronze Spear')
        .durability(400)
        .attackDamageBonus(3)
        .texture('mypack:item/bronze_spear')
})

• 'spearcore:spear' is the item type; it is what makes KubeJS build the item with this library's spear class.
• Every stat is scriptable: durability, damage, charge damage multiplier, attack speed, enchantability, the four charge-phase windows, reach, hitbox, forward push, knockback, dismounting, mob reach factor, sounds… anything you leave out falls back to the iron spear's values.
• What you get is a real spear: stabbing, charging, first- and third-person animations, enchantments and mob AI all behave identically — nothing else to configure.
• If the script fails, the library keeps working: no errors, and none of that code is loaded.
• KubeJS version: 2101.x on 1.21.1, 2001.x on 1.20.1.
• Full parameter tables, texture conventions and pitfalls: kjs-guide.md in the repository (Chinese and English).

What else it provides

• A spear base class — extend it and you get stabbing, charging, and the multi-phase windows (windup / dismount / knockback / damage).
• A movement hook — implement UseSpearSpecialEntity on your own mob and it joins the same "the faster you move, the harder you hit" rules; required speed, reach and damage multiplier are tunable.
• Hit detection and knockback helpers — ray-based entity sweeping, plus the attacker's own momentum handling after a hit.
• Spear AI for mobs — a reusable goal that approaches, charges, strikes and backs off.
• Lunge — a generic forward push on stab.

Who needs it

• Players: nothing to install by hand — spear mods that require it pull it in automatically.
• Modpack authors: to add your own spear, the KubeJS section above is all you need — no code required.
• Mod authors: install it directly to build your own spears, or to let your mobs use one.

Versions

Minecraft	Loader
1.20.1	Forge 47.3.0+
1.21.1	NeoForge 21.1+

Install on both client and server.

Links

• Source / issue tracker: https://github.com/lyingice/Spear-Core
• KubeJS tutorial: kjs-guide.md in the repository

License

MIT License