StructurePlacerAPI

Structure Placer API

Этот простой API даёт простой способ заспавнить структуру в мире один раз, вместо того чтобы добавлять её в генерацию мира. Может пригодиться для предмета, создающего портал, или какой-нибудь другой структуры. Или для создания LuckyBlocks, кто знает!

Установка

Подключи эту библиотеку в свой build.gradle как зависимость

repositories {
    maven {
        name = "Modrinth"
        url = "https://api.modrinth.com/maven"
        content {
            includeGroup "maven.modrinth"
        }
    }
}

dependencies {
    modImplementation "maven.modrinth:structureplacerapi:<version>"
}

Если хочешь, можешь include API в свой jar-файл, добавив только строку include:

repositories {
    maven {
        name = "Modrinth"
        url = "https://api.modrinth.com/maven"
        content {
            includeGroup "maven.modrinth"
        }
    }
}

dependencies {
    modImplementation "maven.modrinth:structureplacerapi:<version>"
    include "maven.modrinth:structureplacerapi:<version>"
}

Весит меньше 25 кб!

Как этим пользоваться

Как создать структуру?

Нужно создать NBT-структуру с помощью StructureBlocks из Minecraft, как показано в этом видео: https://www.youtube.com/watch?v=umhuRXinD3o

Куда положить полученный файл?

Файл structure.nbt нужно положить в папку data твоего мода, вот так: data/yourmodid/structures

Создание нового объекта placer

Чтобы разместить структуру, сначала нужно создать объект placer — это делается просто созданием нового объекта StructurePlacerAPI. У него довольно много параметров, с которыми можно поиграться:

StructurePlacerAPI(ServerWorld world, Identifier templateName, BlockPos blockPos, BlockMirror mirror, BlockRotation rotation, boolean ignoreEntities, float integrity, BlockPos offset)

Параметры

• Первый параметр world — это мир, в котором мы будем размещать структуру. Его можно получить из сущности или откуда угодно ещё.
• Второй параметр templateName — это Identifier, состоящий из MOD_ID твоего мода и имени структуры
• Третий параметр blockPos — это позиция блока, где заспавнится твоя структура. Например, её можно получить из координат сущности
• Четвёртый, mirror — первый из необязательных параметров. С его помощью можно отразить структуру, используя класс BlockMirror. Не нужно создавать новый объект, просто пиши BlockMirror.#stuff
• Пятый, rotation — как и предыдущий, позволяет повернуть структуру с помощью класса BlockRotation. Не нужно создавать новый объект, просто пиши BlockMirror.#stuff
• Параметр ignoreEntities, если установить в true, не будет спавнить сущности, включённые в файл структуры. Если false — наоборот, заспавнит их
• Параметр integrity довольно интересный: это значение float от 0f до 1f, которое определяет, насколько структура будет разрушенной. Если установить значение ниже 1f, часть блоков будет удалена при генерации
• И наконец, параметр offset — ещё один BlockPos, который может пригодиться, чтобы переставить структуру под ноги сущности или куда-то ещё.

Размещение структуры

Ты только что создал StructurePlacerAPI placer = new StructurePlacerAPI(всё то, что выше), и чтобы заспавнить её, нужно сделать так:

placer.loadStructure();

Да-да, всё не так уж сложно. Только запускать нужно именно это, а не метод .place напрямую, поскольку load ещё и проверит существование этой структуры перед спавном.

Восстановление старого ландшафта через некоторое время

Начиная с версии 1.1.0 можно также использовать:

placer.loadAndRestoreStructure(int restore_ticks);

чтобы указать количество тиков (1 секунда = 20 тиков), после которого старый ландшафт будет восстановлен. ВНИМАНИЕ: это может привести к проблемам с производительностью, особенно если структура действительно большая! (Нужно сохранить каждый блок внутри структуры!)

Также можно добавить анимацию появления блоков обратно с помощью:

placer.loadAndRestoreStructureAnimated(int restore_ticks, int blocks_per_tick, boolean random);

• blocks_per_ticks — это количество блоков, которые будут заменяться каждый тик. Так, если ваша структура состоит из 200 блоков, а blocks_per_ticks установлено на 1, то на размещение 20 блоков уйдёт 1 секунда, а на завершение восстановления ландшафта — 20 секунд.
• random отвечает за порядок, в котором блоки будут заменяться. Если установить true, каждый раз восстанавливаемый блок будет случайным, иначе замена пойдёт от одного угла структуры к другому. По-моему, random = true круче.

Выбор блоков, которые следует заменять (начиная с 2.0.0)

Теперь вы можете указать, может ли размещаемая структура заменять bedrock и барьеры или блоки с определённым тегом, либо она может заменять ТОЛЬКО блоки с определённым тегом. После создания объекта StructurePlacerAPI placer вы можете использовать эти методы:

/** Sets weather or not this structure should replace the bedrock */
placer.setReplaceBedrock(boolean replaceBedrock)
    
/** Weather or not this structure should replace the barrier block */
placer.setReplaceBarrier(boolean replaceBarrier)

/** Sets weather or not this structure should only replace blocks with the provided tag, for example only replace air blocks */
placer.setOnlyReplaceTaggedBlocks(boolean onlyReplaceTaggedBlocks, TagKey<Block> tag)

/** Allows to specify blocks which won't be replaced if they have the provided tag*/
placer.setPreventReplacementOfTaggedBlocks(boolean preventReplacementOfTaggedBlocks, TagKey<Block> tag)

Выполнение действия, когда определённый блок размещается структурой или заменяется ею (2.0.0+)

Теперь у вас есть возможность выполнить функцию, когда блок внутри структуры размещается в мире или когда блок заменяется при размещении структуры.

Например, если вы хотите, чтобы при размещении структуры с кустами ягод появлялась случайная лиса, можно использовать:

placer.actionOnBlocksPlacedByStructure(ActionOnBlockFind action, TagKey<Block> targets);

//Example:
placer.actionOnBlocksPlacedByStructure((info, world) -> {world.spawnEntity(EntityType.FoxEntity, ...)}, BlockTags.BUSHES);

Действие — это лямбда-функция, которая предоставляет вам StructureBlockInfo и ServerWorldAccess (или ServerLevelAccess, или как там оно называется с mojmaps). Вам нужно указать тег для типа блока, который вы хотите заменить. Если это только один тип блока, создайте тег для этого блока.

Другое, что вы можете сделать, — выполнить что-то, когда блок, уже находящийся в мире, заменяется структурой. Например, спавнить частицы снега, когда заменяется блок льда:

placer.actionOnBlocksReplacedByStructure(ActionOnBlockFind action, TagKey<Block> targets);

//Example:
placer.actionOnBlocksReplacedByStructure((info, world) -> {world.spawnParticles(ParticleType.SNOW, ...)}, BlockTags.ICE);

Пример

Примером этого может послужить тот, что вы найдёте внутри мода LightWithin (кстати, вам стоит его проверить):

StructurePlacer placer = new StructurePlacer((ServerWorld) caster.getWorld(), new Identifier(MOD_ID, "frost_light"), caster.getBlockPos(), BlockMirror.NONE, BlockRotation.CLOCKWISE_90, true, 1.0f, new BlockPos(-4, -3, -3));
placer.loadStructure();

Чтобы получить постоянную структуру

StructurePlacer placer = new StructurePlacer((ServerWorld) caster.getWorld(), new Identifier(MOD_ID, "frost_light"), caster.getBlockPos(), BlockMirror.NONE, BlockRotation.CLOCKWISE_90, true, 1.0f, new BlockPos(-4, -3, -3));
placer.loadAndRestoreStructureAnimated(200, 2, true);

Чтобы старый ландшафт восстановился, заменяя два блока за тик, в случайном порядке.

Внимание!

ВАЖНО! УБЕДИТЕСЬ, ЧТО ВЫ НАХОДИТЕСЬ В ПОТОКЕ СЕРВЕРА!

if(!world.isClient){
//run stuff
}

Поддержать меня

Если хотите угостить меня кофе, вот ссылка.

Лицензия

Этот API доступен под лицензией CC0. Не стесняйтесь изучать его и включать в