
VoxLib
必须为方块的每个朝向创建新体素形状的日子已经一去不复返了!借助这个库,只需使用一个简单的函数即可完成。
VoxLib
VoxLib 是一个轻量级的 Fabric 和 NeoForge 库,用于处理 Minecraft 的 VoxelShape 系统。
它最初是我在 Wooden Accents Mod 中的一组工具代码。我发现自己总是反复编写相同类型的形状代码,而且当时已经在用 Kotlin,于是我开始把这些代码变成更直观、更易读的辅助方法,而不是一直直接跟原始的 VoxelShape API 打交道。
最终,这些工具代码变得足够大,继续埋在 Wooden Accents 里已经不太合理了。我把它拆分成独立项目,这样我就可以在其他模组中复用它,而不必每次都把一切复制来复制去。
VoxLib 提供了用于创建、组合、旋转、翻转、简化、缓存和调试体素形状的工具,同时底层仍然使用 Minecraft 正常的 VoxelShape 系统。
面向玩家
如果你来这里是因为另一个模组说需要 VoxLib,那你大概不需要了解 API 那一侧的事情。
只需为你的 Minecraft 版本和模组加载器安装正确版本的 VoxLib,把它放进 mods 文件夹,就可以了。
它实际做什么?
VoxLib 主要为模组开发者提供一种更简洁的方式来处理体素形状。
包含的一些内容:
- 使用 Minecraft 正常的 0–16 方块坐标更方便地创建长方体形状
- 使用
+等运算符进行形状组合 - 左/右旋转和翻转工具
- 条件式形状组装
- 可复用的常见形状,如台阶、柱子、桌子、椅子、楼梯和栅栏
- 针对重复旋转和形状并集的有界缓存
- 可选的形状简化工具,用于生成细节较少的轮廓
- 用于在游戏内可视化轮廓和碰撞形状的调试工具
- 用于调试的形状信息和比较工具
例如,不用手动组合所有东西:
val tableShape = base + post + top
或者,如果你已经制作了方块的朝北版本:
val east = north.rotateRight()
val south = north.flip()
val west = north.rotateLeft()
这基本上就是 VoxLib 背后的理念:让处理体素形状中烦人的部分变得更容易,而不试图完全取代 Minecraft 处理它们的方式。
常见形状
VoxLib 还包含一些经常被反复创建的形状的工厂方法:
val slab = CommonShapes.createSlab(8)
val pillar = CommonShapes.createPillar(6)
val table = CommonShapes.createTable()
val chair = CommonShapes.createChair()
val stairs = CommonShapes.createStairs(Direction.NORTH)
val fencePost = CommonShapes.createFencePost()
这些主要作为方便的起点。你显然不必围绕它们构建一切。
调试工具
VoxLib 在开发期间比较有用的部分之一是它的形状调试系统。
调试模式可以可视化你准星当前所指的方块,并独立显示其:
- 轮廓形状
- 碰撞形状
- 或同时显示两者
叠加层的颜色和透明度也可以配置。
在 Fabric 上,如果安装了 Mod Menu,可以通过它访问设置界面。在 NeoForge 上,可以通过 Mods 界面访问。
调试系统的渲染部分完全在客户端,不会在专用服务器上加载。
性能
VoxLib 主要是一个便利库,而不是 Minecraft 体素形状实现的某种神奇更快的替代品。
大多数操作最终仍然使用 Minecraft 自己的 VoxelShape API。如果一个形状从不改变,通常更好的做法是创建一次并将其存储为常量,而不是每次 Minecraft 请求方块形状时都重新构建它。
在 VoxLib 成为独立项目后,我还加入了 Caffeine 来处理重复变换和并集的有界缓存。目标是希望减少相同操作反复发生时的重复工作,但我有意不假装给某个东西加上缓存就能自动让它变快。
VoxLib 还会对其常见形状工厂方法进行记忆化,并包含可选的简化工具,但这些只适用于确实有意义的场景。
基本上:使用方便的 API,但不要仅仅因为涉及缓存就把基本的性能实践抛到窗外。
兼容性
VoxLib 目前支持:
- Minecraft 1.21.1
- Fabric
- NeoForge
- Java 21+
- 客户端和专用服务器
Fabric 需要 Fabric API 和 Fabric Language Kotlin。
NeoForge 构建会捆绑 Kotlin 标准库和 Caffeine,因此那里不需要额外的 Kotlin 依赖。
较旧的 Minecraft 版本
1.19.x 和 1.20.x 分支现在处于仅修复 bug 模式。
它们仍可能收到针对实际 bug 或严重问题的修复,但新功能和较大的改进将集中在当前版本的 VoxLib 上。
我并不想永远维护同一个库的多个活跃开发版本,因此较旧的 Minecraft 版本将继续可用,但不会阻碍当前版本的开发。
在你的模组中使用 VoxLib
Fabric
Fabric 开发者可以通过 Modrinth 的 Maven 仓库直接使用 VoxLib:
repositories {
exclusiveContent {
forRepository {
maven {
name = "Modrinth"
url = "https://api.modrinth.com/maven"
}
}
filter {
includeGroup "maven.modrinth"
}
}
}
dependencies {
modImplementation "maven.modrinth:voxlib:VERSION"
}
将 VERSION 替换为你想要使用的 VoxLib 版本。
NeoForge
NeoForge 使用单独的构件,因此不要使用上面的 Fabric 坐标。
有关 NeoForge 设置、依赖信息以及其他安装细节,请查看 VoxLib 安装指南。
Wiki 还包含更详细的设置信息、API 示例和文档。
AI 使用
VoxLib 最初由我在没有 AI 协助的情况下创建和开发,项目的核心理念和方向仍然是我自己的。
较近期的开发包含了 AI 辅助编码,特别是在对现有项目的部分内容进行大改、重构、测试、编写文档和移植时。我仍然会审查并决定 VoxLib 实际包含什么;AI 主要是我用来加速原本需要手动完成的工作的另一个开发工具。
源码与问题反馈
VoxLib 是开源的,所以如果你想翻阅代码、报告问题,或了解其中任何部分是如何工作的:
支持
VoxLib 是免费的,而且永远都会是。没有人因此欠我什么。
如果你仍然想支持我的项目,可以请我喝杯咖啡。完全没有压力。
许可证
VoxLib 采用 Minecraft Mod Public License 1.0.1 (MMPL-1.0.1) 许可。
正在加载版本记录…
正在加载评论…
评论在新手盒子客户端中发表,这里同步展示。