Structure Gel APIReleased: May 30th, 2020
LicenseAll Rights Reserved with major exceptions
|release | 253.93 KB - Apr 7th, 2021|
|release | N/A - Jun 26th, 2020|
|release | N/A - Jun 26th, 2020|
Structure Gel is an API mod designed to make creating structures easier on the developers, specifically ones using the jigsaw system. All code is open source and documented. Some of its features include:
Structure Gel Block
This block is a creative tool to fill the insides of structures easily. The gel is replaced with air when your structure generates while all air is ignored when being placed. This ensures that your structures won’t have natural terrain where it shouldn’t be. The gel block behaves similarly to structure voids in that you can walk through it, while actually being visible.
When placing gel while sneaking, you can trigger the spreading mechanic. Each gel spreads differently, and you can read how they work by hovering over the item.
Red gel uses the default spreading mechanic, spreading along the cardinal directions, only replacing air.
Blue gel functions similarly to red, except it won’t spread into locations where the sky can be seen.
Green gel spreads the same as red gel, with the addition of also spreading diagonally. This allows it to get through corners created by vines or other complex builds. Be careful not to let it leak outside of your build.
Cyan gel acts as a combination of green and blue gel, by both spreading diagonally and avoiding the sky.
Orange gel behaves the same as red gel, but the distance it spreads is determined by how many you’re holding when you place it, making it handy for builds in open areas.
Yellow gel will only spread along the plane that you’re facing when you place it, making it great for sealing off walls, windows, or other holes that the gel would otherwise go through.
Gel can be removed by using gunpowder on it. Doing this will trigger a chain reaction, removing all connected gels of the same type.
Here’s an example of how it could be used in a build. If this structure were loaded into the game, the gel inside would be replaced with air, while the air outside would not be placed.
The code for this block is designed in a way such that you can easily extend it and hook into its behavior with methods in blocks.IStructureGel, should you need behavior not already implemented.
Some fields are not normally accessible. Using the access_helpers.EntityAccessHelper or the access_helpers.TileEntityAccessHelper will allow you some flexibility with loot tables and monster spawners.
Using the access_helpers.JigsawAccessHelper allows you to add/remove structures to/from an existing jigsaw pool. With this feature, you can do things like adding custom houses to villages. You can also use this to allow your structure to generate a natural looking base of terrain underneath it, the same as villages.
With access_helpers.StructureAccessHelper, you can prevent lakes from generating inside of your structure. All structures created using GelStructure or its child classes will automatically be protected from lakes. Vanilla surface structures such as woodland mansions are also protected, although this may be disabled in the config.
Several registry shortcuts have been added to handle the backend of structure registration. Using the util.RegistryHelper class should allow for your structure registry to not need changes between version updates, unless drastic changes are made by Mojang. Any changes needed to be made on your end will be documented.
The RegistryHelper also has shortcuts to put your structure into biomes with the addFeature and addStructure methods. Doing this should allow for your code to not need changes between versions, unless something major changes, as the API will handle all of the backend work.
The ConfigTemplates class contains two different config templates to allow your structure to have configurable spacing, probability, and even what biomes it should/shouldn’t generate in. Register these templates in your config file the same as you would any other config option.
The JigsawRegistryHelper and JigsawPoolBuilder drastically shorten the work required to register a structure. In the example below, converting the vanilla code for a plains village town center to this system has a 50% character reduction.
The structures.jigsaw.JigsawRegistryHelper is used to register a structure pool to the jigsaw registry. When registering a pool, use the name of the pool, the pool it should try to generate if it fails to place, the pool it will try to place
(a List<Pair<JigsawPiece, Integer>>), and the placement behavior. At minimum, you need to give it a name and pool to generate, as the rest uses preset defaults. In the example above (line 77), the defaultPool if it fails is automatically set to
"minecraft:empty" and the placement behavior is set to rigid.
When created (line 53), you can tell it the id of your mod as well as a prefix to use. These values are here to reduce required typing and prevent typing errors. Since
"village/plains/" will be common for all pools in this registry, I can set that as the prefix. In the example above, the pool created on line 77 will be named
"minecraft:village/plains/town_centers" by combining the mod id, prefix, and string passed in. If you input a ResourceLocation instead of a String, the mod id and prefix will not be used.
setModID() methods will create a new instance of the registry helper with the prefix or mod id that you set. This can be seen with the zombie variations of the town centers (line 81).
builder() method will give you a JigsawPoolBuilder that uses the mod id and prefix of the registry helper (line 78). This is explained more in the next section.
structures.jigsaw.JigsawPoolBuilder is used to add various shortcuts to creating structure pools, represented as a
List<Pair<JigsawPiece, Integer>>. Using this builder class, you can create multiple different JigsawPieces with shared settings between them, as opposed to rewriting those settings for every piece.
On line 78 in the example above, a builder is created from the JigsawRegistryHelper, “registry”. The builder on this line will have two pieces, both with a weight of 50, and use the
cobbleToMossy20 processor that converts 20% of cobblestone to its mossy variant.
The options for the builder are as follows:
- Sets the weight of the pieces passed in with names(). For code efficiency, do this before setting names. -
names(Map<String, Integer>), namesR(Map<ResourceLocation, Integer>), names(Collection), namesR(Collection), names(String...), namesR(ResourceLocation...):
- The Map options will use the Integer field as the weight of the piece. All others will assume the weight to be 1 or the value set with weight(). Using Strings will allow the modid and prefix from the JigsawRegistryHelper that created it to be taken into account, while ResourceLocations ignore them. In the example above, the name set on line 79 will become
- These are the StructureProcessors that each piece set in
names() will use to determine placement settings. This functions as an append, adding to the existing processors in a builder. There are various processors in the api for simple block swaps that you can see between lines 57 and 75. -
- When your structure is placed in water, should waterloggable blocks become waterlogged? True by default.
- Sets the placement behavior of the pieces in this pool. Generally you’re better off doing this in the JigsawRegistryHelper. Rigid by default. The
JigsawPoolBuilder.collect() method shown on line 77 allows for multiple JigsawPoolBuilders to be compiled into one pool, maintaining the individual weights and settings for every piece.
clone() on an existing JigsawPoolBuilder will create a new instance of the builder. This can be used to further save on typing for different pools that all use the same settings by creating a pool that only contains the processors needed for other pools, and then setting the names on the copies. Think of it like a parent/child system.
The final method used in a JigsawPoolBuilder will be
.build(). This simply takes the settings you gave it and compiles a
List<Pair<JigsawPiece, Integer>> that the jigsaw registry can use.
structures.jigsaw.GelJigsawPiece is an extension of the vanilla SingleJigsawPiece that allows implementation with structure gel blocks, contains accessors for setting how it should behave in water, and allows for data structure blocks to be used within jigsaw structures (requires GelStructurePiece).
structures.GelStructurePiece is an extension of the vanilla AbstractVillagePiece that contains accessors to get information about your structure, shortcuts for some processes like creating entities, and the ability to use data structure blocks within your jigsaw structures (requires GelJigsawPiece).
For an open source working example of this api, check out Dungeons Plus
This is a core mod that modifies the LakesFeature class. If you get a crash with this mod that only occurs when mixed with another mod, this may be the cause. Please test before reporting.