VoxLib

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) 许可。