PaletteAPI
一个用于 Forge 1.20.1 的数据驱动结构处理器。它会在你的结构生成时,将你选定的方块替换为权重调色板中的随机方块。你只需在数据包 JSON 中配置一切,从此再也不用碰 Java 代码来更改调色板!
功能介绍
假设你用铁块建造了一处废墟。将 PaletteAPI 的处理器应用到上面,所有的铁块都会变成圆石、苔藓圆石或裂开的石砖,具体取决于你赋予它们的权重。选取结果会锁定到世界坐标,因此区块加载出来时外观始终一致。重新加载时不会出现闪烁现象。
安装说明
这是一个服务端模组。所有处理都在世界生成期间完成,因此客户端完全不需要安装它。
在专用服务器上,将 paletteapi-1.0.0.jar 放入服务器的 mods 文件夹即可大功告成。加入服务器的玩家无需安装任何内容,他们可以使用纯净原版风格的客户端,依然能正常工作。在单人游戏中,只需像平常一样将其放入你自己的 mods 文件夹即可,因为游戏在后台运行自己的服务器,所以一切都能正常运行。
如果你正在开发自己的模组,并希望以代码方式构建调色板,请将 PaletteAPI 添加为依赖项,你将可以在下方找到 Java API。
数据包 API
这是使用它的主要方式。在此处创建一个处理器列表文件:
data/<你的命名空间>/worldgen/processor_list/my_palette.json
这个文件夹路径非常重要。必须是 worldgen/processor_list,否则游戏会忽略你的文件且不会告知任何原因。
{
"processors": [
{
"processor_type": "paletteapi:palette_randomizer",
"target": "minecraft:iron_block",
"palette": [
{ "data": { "Name": "minecraft:cobblestone" }, "weight": 70 },
{ "data": { "Name": "minecraft:mossy_cobblestone" }, "weight": 20 },
{ "data": { "Name": "minecraft:cracked_stone_bricks" }, "weight": 10 }
]
}
]
}
processor_type
始终为 paletteapi:palette_randomizer。这是告诉游戏使用 PaletteAPI 的关键标识。
target
要查找并替换的方块,例如 minecraft:iron_block。它会匹配方块本身,因此即使是你占位方块的浸水或旋转版本也会被捕获。空气以及非目标方块将被保留原样。
palette
目标方块可以转换成的方块列表。每个条目都需要包含两个要素:
data:完整的方块状态对象。对于普通方块,只需 { "Name": "minecraft:cobblestone" }。对于带有状态的方块,你需要添加属性,例如 { "Name": "minecraft:oak_stairs", "Properties": { "facing": "north" } }。
weight:该方块出现的概率权重。在上面的示例中,圆石出现概率约为 70%,苔藓圆石为 20%,裂开的石砖为 10%。权重之和不必等于 100,它们之间只是相对比例关系。
注意: data 是一个完整的方块状态对象,而不仅仅是一个名称字符串。如果省略 data 包装器或 weight,文件将无法解析。如果在日志中看到“Failed to parse”(解析失败),请首先检查这一点。
将结构指向处理器
一旦创建了处理器列表,便可以通过其 ID 从模板池中进行引用。请注意,此处的 processors 仅仅是字符串 ID,而不是整个对象。
{
"name": "yourmod:example_pool",
"fallback": "minecraft:empty",
"elements": [
{
"weight": 1,
"element": {
"element_type": "minecraft:single_pool_element",
"location": "yourmod:my_piece",
"processors": "yourmod:my_palette",
"projection": "rigid"
}
}
]
}
Java API
数据包用户不需要了解这些内容。仅当你希望在自己的模组中以代码方式直接构建处理器时,才需要参考此处。
PaletteProcessorTypes.PALETTE_RANDOMIZER
已注册的处理器类型。这是其他模组进行挂钩的对象。
new PaletteRandomizerProcessor(Block target, SimpleWeightedRandomList<BlockState> palette)
自行构建处理器。这与 JSON 生成的效果相同,只不过是从 Java 代码中创建。
var palette = SimpleWeightedRandomList.<BlockState>builder()
.add(Blocks.COBBLESTONE.defaultBlockState(), 70)
.add(Blocks.MOSSY_COBBLESTONE.defaultBlockState(), 20)
.add(Blocks.CRACKED_STONE_BRICKS.defaultBlockState(), 10)
.build();
var processor = new PaletteRandomizerProcessor(Blocks.IRON_BLOCK, palette);
在其他模组中使用
如果你的模组希望以代码方式构建调色板,你需要在两个地方引入 PaletteAPI。一个是让代码能够编译通过,另一个是让 Forge 要求玩家安装它。
首先将其添加到你的编译路径中。最简单的方法是使用 Maven 仓库。将以下内容添加到你的 build.gradle 中:
repositories {
maven { url "https://raw.githubusercontent.com/TheCatsApplelol/PaletteAPI/main/repo" }
}
dependencies {
implementation fg.deobf("com.paletteapi:paletteapi:1.0.0")
}
想手动获取 jar 包?将其放入项目中的 libs 文件夹,并指向该文件:
dependencies {
implementation fg.deobf(files("libs/paletteapi-1.0.0.jar"))
}
切勿跳过 fg.deobf 包装器。该 jar 包发布的是生产环境下的混淆名称,而该包装器会将其映射回未混淆状态,以便与你的开发代码对齐。如果使用普通的 files(...),虽然可以编译,但在运行时立刻就会崩溃。
现在让 Forge 强制要求它。在你的 META-INF/mods.toml 中添加一个依赖块,并将 yourmodid 替换为你的模组 ID:
[[dependencies.yourmodid]]
modId="paletteapi"
mandatory=true
versionRange="[1.0.0,)"
ordering="AFTER"
side="BOTH"
mandatory=true 可确保除非存在 PaletteAPI,否则你的模组不会加载,并提示玩家去获取它。ordering="AFTER" 使 PaletteAPI 优先加载,这样在你的代码触及它之前,其处理器类型就已就绪。
最后,当实际游玩时,两个 jar 文件都需要放入 mods 文件夹。在开发环境中,libs jar 用于覆盖你的测试运行。
在游戏中测试
内置了一个命令,让你无需先搭建完整结构就能看到效果。
/paletteapi test
在你脚下生成一个 12x12 的铁块地板,通过示例调色板进行处理,并将统计数量打印到聊天栏中。你落地的位置应该大致符合 70 / 20 / 10 的比例分布。在相同位置再次运行该命令,你将得到完全相同的图案,这是位置锁定正在发挥作用。
/paletteapi test <size>
同样的功能,但你可以自定义地板的大小。/paletteapi test 24 会生成更大的样本,使概率更易于观察。
注意: 该命令需要 op(权限等级 2)。示例调色板已内置于 jar 文件中,因此无需额外安装任何内容。
为什么要使用这个?
如果你制作结构,并且厌倦了每次生成的结果都一模一样,那么这个工具就是为你准备的。如果你不制作结构,那么你可能不需要它。
PaletteAPI
A data-driven structure processor for Forge 1.20.1. It swaps a block you pick for a random one out of a weighted palette while your structures generate. You set the whole thing up in datapack JSON so you never have to touch Java to change a palette!
What it does
Say you build a ruin out of iron blocks. Drop PaletteAPI's processor on it and every iron block turns into cobble, or mossy cobble, or cracked bricks, whatever weights you hand it. The pick is locked to the world position too, so a chunk always comes back looking the same. No flickering when you reload.
Installation
It's a server side mod. All it does happens during world generation, so the client never needs it.
On a dedicated server, drop paletteapi-1.0.0.jar in the server's mods folder and you're done. People joining don't have to install anything, they can be on plain vanilla-ish clients and it still works. In singleplayer just put it in your own mods folder like normal, the game runs its own server behind the scenes so it all just works.
If you're making your own mod and you want to build palettes in code, add PaletteAPI as a dependency and you get the Java API further down.
Datapack API
This is the main way to use it. Make a processor list file here:
data/<your_namespace>/worldgen/processor_list/my_palette.json
That folder matters. It has to be worldgen/processor_list or the game just ignores your file and never tells you why.
{
"processors": [
{
"processor_type": "paletteapi:palette_randomizer",
"target": "minecraft:iron_block",
"palette": [
{ "data": { "Name": "minecraft:cobblestone" }, "weight": 70 },
{ "data": { "Name": "minecraft:mossy_cobblestone" }, "weight": 20 },
{ "data": { "Name": "minecraft:cracked_stone_bricks" }, "weight": 10 }
]
}
]
}
processor_type
Always paletteapi:palette_randomizer. This is what tells the game to use PaletteAPI.
target
The block to look for and replace, like minecraft:iron_block. It matches on the block itself, so a waterlogged or rotated version of your placeholder still gets caught. Air and anything that isn't your target gets left alone.
palette
The list of blocks your target can turn into. Every entry needs two things.
data: a full blockstate. For a plain block that's just { "Name": "minecraft:cobblestone" }. For something with states you add Properties, like { "Name": "minecraft:oak_stairs", "Properties": { "facing": "north" } }.
weight: how likely that block is. In the example up there cobble shows up around 70% of the time, mossy 20%, cracked 10%. The weights don't have to add up to 100, they're just relative to each other.
Heads up: data is a full blockstate object, not just a name string. Leave off the data wrapper or the weight and the file won't parse. If you get a "Failed to parse" in the log, that's the first thing to check.
Pointing a structure at it
Once your processor list exists, reference it from a template pool by its id. Note that processors is just the string id here, not the whole object.
{
"name": "yourmod:example_pool",
"fallback": "minecraft:empty",
"elements": [
{
"weight": 1,
"element": {
"element_type": "minecraft:single_pool_element",
"location": "yourmod:my_piece",
"processors": "yourmod:my_palette",
"projection": "rigid"
}
}
]
}
Java API
You don't need any of this for datapacks. It's only here if you want to build a processor straight in code from your own mod.
PaletteProcessorTypes.PALETTE_RANDOMIZER
The registered processor type. This is the thing other mods hook into.
new PaletteRandomizerProcessor(Block target, SimpleWeightedRandomList<BlockState> palette)
Builds a processor yourself. It's the same thing the JSON makes, just from Java.
var palette = SimpleWeightedRandomList.<BlockState>builder()
.add(Blocks.COBBLESTONE.defaultBlockState(), 70)
.add(Blocks.MOSSY_COBBLESTONE.defaultBlockState(), 20)
.add(Blocks.CRACKED_STONE_BRICKS.defaultBlockState(), 10)
.build();
var processor = new PaletteRandomizerProcessor(Blocks.IRON_BLOCK, palette);
Using it in another mod
If your mod wants to build palettes from code, you need PaletteAPI in two spots. One so your code compiles against it, and one so Forge makes players install it.
Get it onto your compile path first. The easiest way is the maven repo. Add it and the coordinate to your build.gradle:
repositories {
maven { url "https://raw.githubusercontent.com/TheCatsApplelol/PaletteAPI/main/repo" }
}
dependencies {
implementation fg.deobf("com.paletteapi:paletteapi:1.0.0")
}
Rather grab the jar by hand? Drop it into a libs folder in your project and point at the file instead:
dependencies {
implementation fg.deobf(files("libs/paletteapi-1.0.0.jar"))
}
Do not skip the fg.deobf wrapper. The jar ships in production names and that wrapper maps it back so it lines up with your dev code. A plain files(...) will compile and then die the second you run it.
Now make Forge require it. In your own META-INF/mods.toml, add a block and put your mod id where yourmodid is:
[[dependencies.yourmodid]]
modId="paletteapi"
mandatory=true
versionRange="[1.0.0,)"
ordering="AFTER"
side="BOTH"
mandatory=true keeps your mod from loading unless PaletteAPI is there, and it tells the player to go get it. ordering="AFTER" makes PaletteAPI load first so its processor type is ready before your code touches it.
Last thing, both jars go in the mods folder when someone actually plays. In dev the libs jar covers your test runs.
Testing it in game
There's a built in command so you can see it work without setting up a whole structure first.
/paletteapi test
Drops a 12 by 12 floor of iron blocks under you, runs it through the example palette, and prints the counts to chat. You should land somewhere near that 70 / 20 / 10 split. Run it on the same spot again and you get the exact same pattern back, that's the position locking doing its job.
/paletteapi test <size>
Same deal but you pick how big the floor is. /paletteapi test 24 gives you a bigger sample so the odds are easier to read.
Heads up: the command needs op (permission level 2). The example palette ships inside the jar already so there's nothing extra to install for it.
Why should i use this?
If you make structures and you're tired of them coming out identical every single time, this is for you. If you don't make structures, then no, you probably don't need it.
评论 0
登录后参与评分
还没有评论,来抢沙发吧