VoxLib
VoxLib 是一个轻量级的 用于处理 Minecraft VoxelShape 系统的 Fabric 和 NeoForge 库。
它最初是我在 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 上,可通过模组屏幕访问。
调试系统的渲染部分完全是客户端的,不会在专用服务器上加载。
性能
VoxLib 主要是一个 便利库,而非某种神奇地比 Minecraft 体素形状实现更快的替代品。
大多数操作最终仍会使用 Minecraft 自身的 VoxelShape API。如果一个形状从未改变,通常最好一次性创建它并将其存储为常量,而不是每次 Minecraft 询问方块的形状时都重新构建它。
在 VoxLib 成为独立项目后,我还添加了 Caffeine 来处理重复变换和并集的有界缓存。那里的目标是希望能减少在相同操作反复发生时的工作量,但我刻意没有声称给某样东西加上缓存就自动能使其变快。
VoxLib 还对其常用形状工厂进行了记忆化处理(memoization),并包含了可选的简化工具,但这些仅适用于确实有意义的情况。
简单来说:使用方便的 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 的模式。
它们可能仍会收到针对实际错误或严重问题的修复,但新功能和较大改进将集中在当前版本的 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) 许可证授权。
VoxLib
VoxLib is a lightweight Fabric and NeoForge library for working with Minecraft's VoxelShape system.
It originally started as a collection of utilities inside my Wooden Accents Mod. I kept finding myself writing the same kinds of shape code over and over again, and since I was already using Kotlin, I started turning that code into more intuitive and readable helpers instead of constantly dealing with the raw VoxelShape API.
Eventually, that utility code got big enough that keeping it buried inside Wooden Accents stopped making much sense. I split it into its own project so I could reuse it across other mods without copying everything around every time.
VoxLib provides utilities for creating, combining, rotating, flipping, simplifying, caching, and debugging voxel shapes while still using Minecraft's normal VoxelShape system underneath.
For Players
If you're here because another mod says VoxLib is required, you probably don't need to know much about the API side of things.
Just install the correct VoxLib version for your Minecraft version and mod loader, put it in your mods folder, and you're good.
What does it actually do?
VoxLib mainly gives mod developers a cleaner way to work with voxel shapes.
Some of the stuff included:
- Easier creation of cuboid shapes using Minecraft's normal 0–16 block coordinates
- Shape combination using operators like
+ - Left/right rotation and flipping utilities
- Conditional shape assembly
- Reusable common shapes for things like slabs, pillars, tables, chairs, stairs, and fences
- Bounded caching for repeated rotations and shape unions
- Optional shape simplification tools for less-detailed outlines
- Debug tools for visualizing outline and collision shapes in-game
- Shape information and comparison utilities for debugging
For example, instead of manually combining everything:
val tableShape = base + post + top
Or, if you've already made the north-facing version of a block:
val east = north.rotateRight()
val south = north.flip()
val west = north.rotateLeft()
That's pretty much the idea behind VoxLib: make the annoying parts of working with voxel shapes easier without trying to completely replace how Minecraft handles them.
Common Shapes
VoxLib also includes factories for a few shapes that tend to get recreated constantly:
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()
These are mostly there as convenient starting points. You obviously don't have to build everything around them.
Debug Tools
One of the more useful parts of VoxLib during development is its shape debugging system.
Debug mode can visualize the block currently under your crosshair and independently display its:
- Outline shape
- Collision shape
- Or both at the same time
The overlay color and transparency can also be configured.
On Fabric, the settings screen can be accessed through Mod Menu if it is installed. On NeoForge, it is available through the Mods screen.
The rendering side of the debug system is entirely client-side and does not load on dedicated servers.
Performance
VoxLib is primarily a convenience library, not some magical faster replacement for Minecraft's voxel shape implementation.
Most operations still eventually use Minecraft's own VoxelShape APIs. If a shape never changes, you're normally better off creating it once and storing it as a constant rather than rebuilding it every time Minecraft asks for the block's shape.
After VoxLib became its own project, I also added Caffeine to handle bounded caching for repeated transformations and unions. The goal there is to hopefully cut down on repeated work in cases where the same operations are happening over and over again, but I'm intentionally not pretending that slapping a cache on something automatically makes it faster.
VoxLib also memoizes its common-shape factories and includes optional simplification utilities, but those are meant for cases where they actually make sense.
Basically: use the convenient APIs, but don't throw basic performance practices out the window just because there's a cache involved.
Compatibility
VoxLib currently supports:
- Minecraft 1.21.1
- Fabric
- NeoForge
- Java 21+
- Both client and dedicated servers
Fabric requires Fabric API and Fabric Language Kotlin.
The NeoForge build bundles the Kotlin standard library and Caffeine, so an additional Kotlin dependency is not required there.
Older Minecraft Versions
The 1.19.x and 1.20.x branches are now in bug-fix-only mode.
They may still receive fixes for actual bugs or serious issues, but new features and larger improvements will be focused on the current version of VoxLib instead.
I don't really want to maintain multiple actively-developed versions of the same library forever, so older Minecraft versions will stay available without holding back development of the current one.
Using VoxLib in Your Mod
Fabric
Fabric developers can use VoxLib directly through Modrinth's Maven repository:
repositories {
exclusiveContent {
forRepository {
maven {
name = "Modrinth"
url = "https://api.modrinth.com/maven"
}
}
filter {
includeGroup "maven.modrinth"
}
}
}
dependencies {
modImplementation "maven.modrinth:voxlib:VERSION"
}
Replace VERSION with the VoxLib version you want to use.
NeoForge
NeoForge uses a separate artifact, so don't use the Fabric coordinate above.
For NeoForge setup, dependency information, and the rest of the installation details, check the VoxLib installation guide.
The wiki also contains more detailed setup information, API examples, and documentation.
AI Usage
VoxLib was originally created and developed by me without AI assistance, and the core ideas and direction of the project are still my own.
More recent development has included AI-assisted coding, particularly while overhauling, refactoring, testing, documenting, and porting parts of the existing project. I still review and make the decisions around what actually goes into VoxLib; AI is mainly another development tool I use to speed up work that I would otherwise be doing manually.
Source & Issues
VoxLib is open source, so if you want to dig through the code, report something broken, or see how any of it works:
Support
VoxLib is free, and it always will be. Nobody owes me anything for it.
If you somehow still want to support my projects, you can buy me a coffee. No pressure at all.
License
VoxLib is licensed under the Minecraft Mod Public License 1.0.1 (MMPL-1.0.1).
下载 VoxLib
下载 VoxLib
下载 VoxLib
下载 VoxLib
下载 VoxLib
下载 VoxLib
下载 VoxLib
下载 VoxLib
下载 VoxLib
下载 VoxLib
更新内容
- 将 Fabric 和 NeoForge 版本移植至 Minecraft 1.21.1。
- 升级 Fabric Loader 至 0.19.5、Fabric API 至 0.116.17、Fabric Language Kotlin 至 1.14.1、Kotlin 至 2.4.20、NeoForge 至 21.1.250,以及 Mod Menu 至 11.0.4。
- 复用原版包围盒辅助工具,并从调试渲染中移除临时方框。
- 弃用具有误导性的
and联合别名,改用+。其行为及 JVM 方法保持不变。 - 修复了完整方块联合运算时丢弃区块边界外几何体的问题。
- 将 NeoForge 入口点从 Java 转换为 Kotlin。
- 更新了 1.21.1 的加载器元数据、资源包格式以及 NeoForge 配置屏幕注册。
- 升级 Loom 至 1.18.2。Gradle 守护进程需要 Java 25,但编译后的模组仍目标兼容 Java 21。
兼容性
- Minecraft 1.21.1
- Fabric 和 NeoForge
- Java 21
完整更新日志:
关于这个资源的讨论、问题反馈与使用心得
还没有讨论,来发第一帖吧
你是这个资源的作者?登录后可认领此资源。
相似资源
模组
一个用于收集生物掉落物的多区块模组。
模组
显示你正在注视的方块的信息。(适用于 Minecraft 1.16+ 的 Hwyla/Waila 分支)
模组
查看物品与配方
模组
使用 JavaScript 编辑配方、添加自定义物品、编写世界事件!
模组
适用于 MC 1.18+ 的 Effekseer 加载器
模组
添加区块认领和玩家组队功能,并与 Xaero's Minimap 和 World Map 集成
评论 0
登录后参与评分
还没有评论,来抢沙发吧