From 7838105fabe3d28f30a144a4a8371cd7d7dafaed Mon Sep 17 00:00:00 2001 From: HydrolienF Date: Tue, 7 Jan 2025 17:44:07 +0100 Subject: [PATCH] Update the readme. --- CHANGELOG.md | 4 + README.md | 177 +++++++++++++----------------- Underilla-Spigot/build.gradle.kts | 2 +- 3 files changed, 80 insertions(+), 103 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 34017ff..e564319 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,8 +1,12 @@ +# 2.0.0 + ## Features / Bug fix - **Custom biomes are fully supported**. Structures will be generate correctly in custom biomes ! - **Caves biomes can be merge inside the final world** without needing an extra cavesWorld. And they are merged only under the world surface. - **Carvers **can be run before world merging or after world merging. It is now possible to have carvers caves but still have a **clean surface without holes**. This option can be configure for each biome. - **Chunks outside** of the surface world are now generated **empty**. +- **Cleaning step after the world generation**: Blocks can be replace from the custom world or on the final world. Entity can be remove in the final world. +- **Full process include.** Underilla will configure the server & download it's dependency, then start chunky when the server start, then clean the world. Each of the 3 generation steps can be restarted. ## Other major or breaking changes - Complete reorganization of the configuration. diff --git a/README.md b/README.md index 588f89c..95d1bb9 100644 --- a/README.md +++ b/README.md @@ -10,143 +10,116 @@ [**Discord**](https://discord.gg/RPNbtRSFqG) | [**Hangar**](https://hangar.papermc.io/Hydrolien/Underilla) | [**GitHub**](https://github.com/HydrolienF/Underilla) | [**Original author Github** (Outdated)](https://github.com/Jeshuakrc/Underilla) # Underilla -Underilla is a Paper based plugin for Minecraft Servers to 'merge' existing custom Minecraft word surfaces and vanilla undergrounds. It works by allowing the vanilla generation engine create chunks as normal, then intercepting the generator and forcing the surface of the original world, which works as a reference. In oder worlds, Underilla generates a brand-new world with vanilla undergrounds, but cloning the surface of an already existing world. +Underilla is a minecraft plugin to 'merge' existing custom Minecraft word surfaces and vanilla undergrounds. It works by allowing the vanilla generation engine create chunks as normal, then intercepting the generator and forcing the surface of the original world, which works as a reference. In other worlds, Underilla generates a brand-new world with vanilla undergrounds, but cloning the surface of an already existing world. It's original purpose is adding vanilla caves to custom [WorldPainter](https://www.worldpainter.net/) worlds, but it would perfectly work for any pre-generated world. ![Underilla](https://github.com/HydrolienF/Underilla/assets/71718798/5d4c0812-443e-42db-90cf-a138f11ec6c9) ## Main features -- 3 merging strategies: - - **None:** No actual vanilla underground noise is generated. `generate_noodle_caves` setting can still be on, to generate noodle caves. - - **Absolute:** A Y coordinate value divides the original world surface and vanilla underground. - - **Surface:** Mix the original world surface and vanilla underground at a variable y that depends of original & vanilla world surface. It have the best racio generated world quality & performance. +- Merge the original world surface and vanilla underground. - Heightmap fixed. Underilla re-calculates heightmaps when merging chunks, getting rid of floating and buried structures. Vanilla villagers and other structures are placed at the right height. -- Biome overwrite. Biomes from the reference world will be transferred and overwrite biomes from de vanilla seed being used. Cave biomes underground will be preserved. +- Biome overwrite. Biomes from the reference world will be transferred and overwrite biomes from de vanilla seed being used. Cave biomes underground will be preserved. Custom biomes are supported. +- Population. Trees, flowers, ores etc are placed back. Features can be customized with datapacks. +And many more options in the config to transform your custom world. ## Getting started ### Perquisites - Java 21. -- A pre-generated world to use as a reference (Such as a WorldPainter world). +- A pre-generated world to use as a reference (Such as a [WorldPainter](https://www.worldpainter.net/) world). - A [Paper](https://papermc.io/software/paper) (or forks) Minecraft Server. Supported Minecraft version are in the release name. ### Single player or non-Paper Underilla is currently only implemented as a Paper plugin. It support datapacks and most plugins. It does not support mods and might be incompatible with some generation plugins that modify minecraft source code. Once the map have been generated with a Paper server, you're free to use it in signle player or on modded server. -### Installation - -1. Set up your Paper (or fork) server. -2. Download Underilla's `.jar`. -3. Place Underilla's `.jar` file into the `./plugins` directory of your server. Create the folder if it doesn't exist already. -4. Into the `./plugins` folder, create a new folder called `Underilla` and place a `config.yml` file in it. You may get the file from [this repo](Underilla-Spigot/src/main/resources/config.yml). -5. Open the `bukkit.yml` file in your server's root and add the following lines on top: - ``` - worlds: - world: - generator: Underilla - ``` - This will tell Paper to use Underilla's chunk generator. -6. In your server's root, create a new folder called `world_surface`. -7. From the folder of your reference world, copy the `region` folder, and paste it into the `world_surface` folder you just created. -8. If existing, delete the `world` folder fom your server's root. -9. (Optional) Open the `server.properties` file in your server's root, and tweak the `level-seed` property. This has a direct impact on the generated underground. -10. Run the server. - You'll notice Underilla generating merged chunks during world creation. - -**Important:** Make sure your server's main world is still set to `world`. Aside from this plugin, the server itself doesn't need to "know" about the reference world. - ### Pregenerate -Underilla is significantly slower than the vanilla generator, as it doesn't relly on noise generation but on reading the reference world's region `nbt` files and analyzing its patterns to 'clone' its surface to a vanilla world. So, if your world is intended for heavy duty in a big server. It's recommended to pre-generate the whole reference world area with a chunk generator plugin, such as [Chunky](https://hangar.papermc.io/pop4959/Chunky). I'm planning adding a build-in pre-generation system in the future. -To increase generation speed you should edit `worker-threads` in your `config/paper-global.yml` to match your number of CPU cores, else paper won't use all CPU cores aviables. Using your number of core instead of default value usually double speed generation. - -### Performances -Huge map generation can takes hours or even days, here is some stats about performance to help you choose your configuration settings. -All tests have been done on paper 1.20.4 on a 1000*1000 map generation of the same world painter generated world with default settings except strategy. We can't garanty that your computer will be as fast as mine, but it should be enoth to imagine how much time your world will need. -- Minecraft Vanilla generator (No Underilla) 1:36 -- None strategy 3:25 (2.13 times longer than Vanilla generation) -- Absolute stategy 4:34 (2.85 times longer than Vanilla generation) -- Surface srategy 4:32 (2.83 times longer than Vanilla generation) -- Relative strategy (have been removed since) 11:07 (6.94 times longer than Vanilla generation) - -For a 50000 * 30000 world, it would take 40 hours to generate with Minecraft vanilla generator, 113 hours in surface strategie and 279 hours in relative. - -### How to get the best caves as possibles -This steps are longer than the instalation steps, but will allow you to avoid all the current limitation of the plugins witch are : -- Chests data aren't transfered from cave world. -- Caves biomes are generated after the other biome. -- Default Minecraft population will generate unwanted features. -If you are strugeling with world generation, you can ask for help on the Discord: https://discord.gg/RPNbtRSFqG - -1. Download the last paper version [here](https://papermc.io/downloads/paper). -2. Create a new repository for your server and move the paper .jar file inside. -3. Start paper with `java -jar paper-*replace by paper last version*.jar -nogui` -4. Server stops because of eula, open eula.txt, set `eula=true` and restart the server. -5. You know have a vanilla ready to work server. But we still want to do some config change to make it faster for world generation. Stop the server. -6. Increase the number of thread that will be used for parallel chunk generation by setting `worker-threads: x` in `config/paper-global.yml`. x = physical CPU cores - 1. Paper default value use half your physical CPU cores, witch is great in most case, but for generation it's faster to use almost all your CPU cores. -7. Set a seed for your world by editing `servers.properties` `level-seed=x`. x = a random number. If you know it, use the same seed than your woldpainter world. This steps will make the world caves generate always the same way. It will be usefull to merge caves biomes into a new world witch have exacly the same cave shapes. -8. Download [Chunky](https://hangar.papermc.io/pop4959/Chunky) and place it in your `plugins/` directory. -9. Start your server. -10. Get your custom map min and max X & Z coordinate. -11. Select the area with Chunky from the server console `chunky corners minX minZ maxX maxZ`. (Replace min & max by the actual values.) -12. Start the world generation with `chunky start`. -13. Wait until world generation is over. World generation might takes hours or even days if your world is huge. You can do the 2 nexts steps while waiting for the world generation to be over. -15. If you haven't export your Underilla world yet, export it with no water or lava underground, no ores, no caves and no underground special stone (diorite, gravel). We will let Minecraft generation take care of the underground. This might take hours, you can do the next steps while waiting. -16. Create an empty datapack. Then add the [vanilla biome files](https://github.com/misode/mcmeta/tree/data) into your datapack and edit them to remove the unwanted features. You probably want to remove all trees if you have some in your custom world. If you don't, you will have vanilla tree & custom world tree on the final world. It is recommand to set the depth to 320 everywhere to be sur that there will be caves where you have custom world moutains. See [UnderillaBaseDataPack]. -17. All previous steps need to be done here. Rename your `world` directory to `world_caves`. We will use this vanilla world to have caves biome in our final world. -18. Rename your exported custom world to `world_surface/` -19. Download [Underilla latest release](https://github.com/HydrolienF/Underilla/releases) & place it in your `plugins/` directory. -20. Open the `bukkit.yml` file in your server's root and add the following lines on top: - ``` - worlds: - world: - generator: Underilla - ``` - This will tell Paper to use Underilla's chunk generator. -21. Copy the [Underilla config](Underilla-Spigot/src/main/resources/config.yml) into `plugins/Underilla/config.yml`. -22. Edit Underilla config by setting `transferBiomesFromCavesWorld: true`. -23. Underilla config: Remove some transferedCavesWorldBiomes if you don't want all of them. -24. Underilla config: Add ignoredBlockForSurfaceCalculation if needed. -25. Underilla config: Add blacklisted structures if needed. -26. It's know time to merge your custom world surface and a vanilla world underground. Start Chunky again with the 2 same commands. Underilla world generation might takes hours or even days if your world is huge. *The magic happends now, Underilla generate default caves then add your custom world surface. Then mixt your custom world biomes & the caves biomes from `world_caves` onto the final world. Then add structures witch will be placed according to the new surface shape & the new biome mixt. Then add the features (tree, flower, ores, grass, gravel etc) according to your datapack. Then spawn mobs according to the new biome mixt.* -27. Once the underilla generation is done, you should do a save of `world`, then check if you like it. -28. You can now safely remove Underilla from the plugin and remove `world_caves` & `world_surface` -29. You can also remove Underilla from the `bukkit.yml` generator. You should replace it with [VoidWorldGenerator](https://github.com/HydrolienF/VoidWorldGenerator) to avoid any vanilla biome generation out of the Underilla world. - - -## Known issues - -- Due to Paper's generation API, outside the reference world's area, heightmaps are broken, which has an impact on structures. You may work around this by pre-generating the whole reference world area, and then disabling Underilla. Commands as `/locate` might timeout the server. +Underilla is significantly slower than the vanilla generator, as it doesn't rely only on noise generation but also on reading the reference world's region `nbt` files and analyzing its patterns to 'clone' its surface to a vanilla world. +So Underilla will pregenerate the world when you run it. You can disable auto generation in the config by disabling the generations steps. + +### How to generate vanilla caves in a custom world with Underilla +This is a **step by step guide**, if you already did some steps you can move to the next ones. +If you are strugeling with world generation, you can ask for **help on the Discord**: https://discord.gg/RPNbtRSFqG + +1. Setup a paper server + 1. Download the latest paper version [here](https://papermc.io/downloads/paper). + 2. Create a new directory for your server and move the paper .jar file inside. + 3. Create a `start.sh` on Linux or MacOS or a `start.bat` in Windows with `java -jar paper-1.21.4-76.jar -nogui` inside. (Replace `1.21.4-76` by your paper version.) + 4. On Linux & MacOS only, give exec perms to `start.sh` by running `chmod 700 start.sh`. + 5. Start the server with `./start.sh` on Linux and MacOS or `./start.bat` on Windows. + 6. The server stops because of eula, open `eula.txt`, set `eula=true` and restart the server. + 7. If you want to have the same cave result for each of your generatioj try, you can edit `level-seed=` in `servers.properties` to a random number. + 8. You can edit the mob spawning settings or any other server config here if you want. + 9. You know have a vanilla ready to work server. Time to setup Underilla. +2. Setup Underilla + 1. Download the latest Underilla version from the [releases](https://github.com/HydrolienF/Underilla/releases). + 2. Move the downloaded jar file to `plugins/` in your server directory. +3. Setup your custom world + 1. copy your custom world to `world_surface` in your server directory. (Only the `region/` sub directory of your world matters.) +4. Configure Underilla + 1. Copy the config from [this file](https://github.com/HydrolienF/Underilla/blob/main/Underilla-Spigot/src/main/resources/config.yml) and save it as config.yml in `plugins/Underilla/`. The default config can also be initialized by running underilla, but copying it from the repo ensure that Underilla config is configured before Underilla starts. + 2. Edit `generationArea` inside `plugins/Underilla/config.yml` to match your surface world size. If you just want to test Underilla for a 1st generation, you can keep default values. + 3. You can read the other fields of the config and edit some of them. This steps can be done later after a 1st generation try, to customize your world generation. +5. Configure datapack + 1. If your custom world already have a datapack, you can move it to `world/datapacks/` to keep your custom biomes etc. + 2. If you don't have a datapack yet, you should create one from [vanilla biome files](https://github.com/misode/mcmeta/tree/data) where you have remove the features you don't want. For example if your custom surface world already have trees +6. Start **caves generation** + 1. Run the server again, this time the eula have been accepted, so the server will start. The 1st time you start the server Underilla will download it's dependencies to your `plugins/`, configure paper for faster world generation & set Underilla as world Generator in `bukkit.yml`. This steps can be disabled in the config. + 2. If you have set a start script, the server should restart automaticaly, if not you will have to restart it manually. + 3. The generation is now started, yopu just have to wait until it's done now. If you stop the server, the generation will restart the next time you start the server. + You can explore the map while it's being generated to check how it's doing. Be aware that being on the server while the map is generated migth edit the world, even in spectator mod and might result in a sligtly different world generation because of water or falling sand being updated before the cleaning tasks. Best will be to stay out of the server for you last generation try. + The generation process will be done in 3 steps: + 1. **Merging** your **surface world** to a new world with **vanilla caves**. This step merge blocks & biomes and generate new features, new structures & new mobs. It is by far the longest steps and it will takes hours for the biggest worlds. + 2. Cleaning the blocks of the final world. + 3. Cleaning the entities of the final world. +7. What's next + 1. Check that the world meet what you expected and redo the generation since step 4 if needed. (You should keep a save of `world`somewhere just in case) + 2. You can now delete the `world_surface/` (You should keep a save somewhere just in case) + 3. You can now remove Underilla from `plugins/` & edit `bukkit.yml` to make `VoidWorldGenerator` your world generator. This will ensure that no chunk is generated by the vanilla generator outside of the final world area. If you wich to have a vanilla world merging with the generated world, you can remove the generator from `bukkit.yml`. Vanilla generator will try to merge it's custom world with the existing one. You can also add a datapack to have only ocean biome generated over the generated world. + 4. I hope Underilla will improve the cave experience of your players. If you find any bugs please report them in the [Github issues](https://github.com/HydrolienF/Underilla/issues). + + +## Known issues & workarounds + +- Commands as `/locate` might timeout the server. This happens when Minecraft think that the structure should exist in the world, but you have disable that structure in Underilla config or if the generation area is to small and that structure haven't spawn. - Olds map before 1.19 won't be load by Underilla. To use an old map, generate the full map without Underilla in the right version, then use the generated map. This will let minecraft update the map files and Underilla will be able to read them as expected. +- Chests content arent copied from custom world. This does not affect the structures chests generated by Underilla on the final world. +- Default Minecraft population will generate all vanilla features. Use a datapack in `world/datapacks/` to prevent that. ## WorldPainter considerations If you're going to plug your custom WorldPainter world into Underilla, consider before exporting: - Disable caves, caverns, and chasms altogether, allow Underilla to take over that step. This is due to biome placement, every underground non-solid block in the surfaceWorld drags its biome over along with it, this interferes with proper underground vanilla biomes. - Always disable the `Allow Minecraft to populate the entire terrain` option. Rather use the `vanillaPopulation` option in Underilla's `config.yml` file. -- Don't user the resource layer. Underilla will have the vanilla generator take care of that for you. +- Don't use the resource layer. Underilla will have the vanilla generator take care of that for you. - The Populate layer has no effect. Weather all or none of the terrain will be populated based on the above point. ## Custom biome -Cave generation on custom biomes is now working. Features (ores, flowers etc) will be placed according to the custom surface world biome but structures won't. +Cave generation on custom biomes is working. Features (ores, flowers etc) & structures will be placed according to the custom surface world biome. ## Feature fiter If you want to remove some of the game features, for example the `monster_room` you can create a datapack where you have customize witch feature can spawn in each biome. Underilla will generate feature according to your cusomized biome. -It can also be used to add feature to some biome. For example a quartz_ore feature if your nether is disabled you you still want your builder to have quartz. +It can also be used to add feature to some biome. For example a quartz_ore feature if your nether is disabled you you still want your builders to have quartz. + +## Performances +Huge map generation can takes hours or even days, here is some stats about performance to help you choose your configuration settings. +All tests have been done on paper 1.20.4 on a 1000*1000 map generation of the same world painter generated world with default settings except strategy. We can't garanty that your computer will be as fast as mine, but it should be enoth to imagine how much time your world will need. +- Minecraft Vanilla generator (No Underilla) 1:36 +- None strategy 3:25 (2.13 times longer than Vanilla generation) +- Absolute stategy 4:34 (2.85 times longer than Vanilla generation) +- Surface srategy 4:32 (2.83 times longer than Vanilla generation) +- Relative strategy (have been removed since) 11:07 (6.94 times longer than Vanilla generation) + +For a 50000 * 30000 world, it would take 40 hours to generate with Minecraft vanilla generator, 113 hours in surface strategie and 279 hours in relative. + +## Build & test the plugin +Clone the [repo](https://github.com/HydrolienF/Underilla) `git clone git@github.com:HydrolienF/Underilla.git` -## Build Create a working jar with `./gradlew assemble`. + Run a local paper server with the example map & datapack on Linux. ```sh rm Underilla-Spigot/run/world_surface/ -fr; cp testMap/world/ Underilla-Spigot/run/world_surface/; rm -fr Underilla-Spigot/run/world/; mkdir -p Underilla-Spigot/run/world/datapacks; cp UnderillaBaseDataPack/ Underilla-Spigot/run/world/datapacks; ./gradlew runServer ``` -```sh -rm Underilla-Spigot/run/world_surface/ -fr; cp testMap/worldY/ Underilla-Spigot/run/world_surface/; rm -fr Underilla-Spigot/run/world/; mkdir -p Underilla-Spigot/run/world/datapacks; cp UnderillaHighYDataPack/ Underilla-Spigot/run/world/datapacks; ./gradlew runServer -``` - -```sh -rm -fr Underilla-Spigot/run/world/; mkdir -p Underilla-Spigot/run/world/datapacks; cp ../MvndiSeasons/datapacks/* Underilla-Spigot/run/world/datapacks/; ./gradlew runServer -``` -## TODO -- Build-in pre-generation system. +Feature requests or pull requests are welcome. Concider create an issue 1st to talk about your new feature before sending a pull request. diff --git a/Underilla-Spigot/build.gradle.kts b/Underilla-Spigot/build.gradle.kts index 6d5217e..ca2c619 100644 --- a/Underilla-Spigot/build.gradle.kts +++ b/Underilla-Spigot/build.gradle.kts @@ -11,7 +11,7 @@ plugins { } group = "com.jkantrell.mc.underilla" -version = "1.9.0" +version = "2.0.0" description="Generate vanilla cave in custom world." val mainMinecraftVersion = "1.21.4" val supportedMinecraftVersions = "1.21.3 - 1.21.4"