ghast-tools/README.MD

GHAST TOOLS

Набор вспомогательных инструментов для Bukkit API.
Основан на версии Bukkit API 1.12.

Использование

Перед началом использования, необходимо в вашем Bukkit-плагине прописать подобный код:

void onLoad() {
    GhastTools.setPlugin(this);
}

Это необходимо сделать, т.к. весь инструментарий основан на статических (static) методах.

Все методы данного набора инструментов объеденены в классы, выполняющие роль группировщиков.

GhastTools

Методы общего назначения или без определённой группировки.

loadConfig

Загрузка файла настроек плагина - config.yml.

YamlConfiguration config = GhastTools.loadConfig();

По-умолчанию "гаст" пытается файл найти в папке плагина - getDataFolder(). Если файла там нет, то выгружает встроенный (имеющийся в .jar файле плагина) в эту папку и загружает его.

YamlConfiguration config = GhastTools.loadConfig(false);

Если передать параметр false, то при отсутствии файла config.yml в папке плагина, будет загруден исключительно встроенный файл настроек.

AssetsManager

Методы по работе с файлами плагина ("ассетами").

У каждой группы методов один и тот же набор входных параметров:

• resourceName - наименование и путь к файлу в папке плагина
• defaultResourceName - наименование и путь к файлу в плагине.
  Опционально. По-умолчанию равнен resourceName
• saveDefault - необходимость скопировать содержимое файла из defaultResourceName в файл resourceName.
  Опционально. По-умолчанию равен true

Правила поиска файлов так же одинаков для каждой группы:

• В начале файл ищется в папке плагина
• Если файл отсутствует в папке плагина, то...
  • если defaultResourceName не равен null...
    • если saveDefault равен true, то файл из плагина будет выгружен в папку плагина и от туда загружен в память.
    • если saveDefault равен false, то данные будут взяты из файлв в плагине.
  • если defaultResourceName равен null, то будет брошено исключение AssetsException с описанием ошибки вида "Файл X не найден".

getAsInputStream

InputStream inputStream = AssetsManager.getAsInputStream("translate.ru.yml", "translate.yml", false);

getAsReader

Reader reader = AssetsManager.getAsReader("translate.ru.yml", "translate.yml", false);

getAsString

String string = AssetsManager.getAsString("readme.txt", "readme.txt", StandardCharsets.UTF_8, false);

У этой группы есть дополнительный опциональный параметр - charset - в котором указывается кодиривка получаемой строки.
По-умолчанию равен StandardCharsets.UTF_8

BuildHelper

Набор методов облегчающих размецение объектов на карте.

placeSkull

Location location = ...;
Skull skull = BuildHelper.placeSkull(location, BlockFace.NORTH)

placeSignWall

Location location = ...;
Sign signWall = BuildHelper.placeSignWall(location, BlockFace.NORTH)

CommandManager

Регистрация команд.

Имеется два варианта использования: упрощённый

CommandManager.register("start", (sender, args) -> sender.sendMessage("hello!"));

и подробный:

CommandManager.create("start")
        .useOnlyPlayer()
        .executer((sender, args) -> sender.sendMessage("hello!"))
        .register();

register

Упрощенная регистрация команды. Указывается лишь название команды и исполнитель.

CommandManager.register("start", (sender, args) -> sender.sendMessage("hello!"));

create

Конструктор для подробного варианта регистрации команды.

CommandManager.Builder builder = CommandManager.create("start");

executer

Указание исполнителя для команды

CommandManager.Builder builder = CommandManager.create("start")
        .executer((sender, args) -> sender.sendMessage("hello!"));

onError

Обработчик исключений

CommandManager.Builder builder = CommandManager.create("start")
        .onError((sender, commandName, args, exception) -> {
            sender.sendMessage(ChatColor.RED + "Произошла ошибка при выполнении команды '" + commandName + "'.");
            exception.printStackTrace();
        });

useOnlyPlayer

Указание, что данную команду могут использовать только Игроки. Опционально можно указать сообщение, которое будет выводиться в консоль.
Отменяет действие указателя useOnlyConsole

CommandManager.Builder builder = CommandManager.create("start")
		.useOnlyPlayer("Команду могут использовать только игроки");

useOnlyConsole

Указание, что данную команду можно использовать только в консоле. Опционально можно указать сообщение, которое будет выводиться Игроку.
Отменяет действие указателя useOnlyPlayer

CommandManager.Builder builder = CommandManager.create("start")
		.useOnlyConsole(ChatColor.RED + "Команду можно использовать только в консоли");

register

Регистрация описанной в Конструкторе команды.

CommandManager.create("start")
        .useOnlyPlayer()
        .executer((sender, args) -> sender.sendMessage("hello!"))
        .register();

EffectsHelper

Набор методов для работы с эффектами.

playSound

Воспроизвести звук.

Location location = ...;
EffectsHelper.playSound(location, Sound.AMBIENT_CAVE, 1.0f);

particle

Создание частиц.

Location location = ...;
EffectsHelper.particle(location, Particle.REDSTONE, 1.0d, 1.0d, 1.0d, 1.0d, 5);

EventContext

Регистрация группы обработчиков событий, объединённых общим условием выполнения.

EventContext.create()
        .filter(() -> Bukkit.getOnlinePlayers().size() > 10)
        .onEvent(PlayerJoinEvent.class, event -> { event.getPlayer().kickPlayer("Max players"); });

create

Создание контекста событий.

EventContext eventContext = EventContext.create();

filter

Условие, при котором будут срабатывать обработчики событий в данном контексте.

EventContext.create()
        .filter(() -> Bukkit.getOnlinePlayers().size() > 10)

onEvent

Указание события и его обработчика.
Обработчик события регистрируется сразу же.

EventContext.create()
        .filter(() -> Bukkit.getOnlinePlayers().size() > 10)
        .onEvent(PlayerJoinEvent.class, event -> event.getPlayer().kickPlayer("Max players"));

cancelEvent

Отменить событие.
Обработчик события регистрируется сразу же.

EventContext.create()
        .cancelEvent(BlockPlaceEvent.class);

эквивалентен коду:

EventContext.create()
        .onEvent(BlockPlaceEvent.class, event -> event.setCancelled(true))

JdbcTemplate

Инструмент для упрощения работы с SQL базами данных, работающими через JDBC.

Для начала потребуется создать объект DataSource

// На примере MySQL
MysqlDataSource dataSource = new MysqlDataSource();
dataSource.setServerName("localhost");
dataSource.setPort(3306);
dataSource.setCharacterEncoding(StandardCharsets.UTF_8.name());
dataSource.setDatabaseName("MyDataBase");
dataSource.setUser("root");
dataSource.setPassword("secret");

После чего создать JdbcTemplate

JdbcTemplate jdbcTemplate = new JdbcTemplate(dataSource);

execute

Выполнение SQL запроса без последующей обработки результатов выполнения.

jdbcTemplate.execute("CREATE TABLE my_table (id int, name varchar(16));");

query

Выполнение SQL запроса и обработка его результатов.
Может возвращать любой тип объектов.

String name = jdbcTemplate.query("SELECT name FROM my_table LIMIT 0,1", resultSet -> {
        if (resultSet.next()) {
            return resultSet.getString("name");
        } else {
            return null;
        }
});

List<String> names = jdbcTemplate.query("SELECT name FROM my_table", resultSet -> {
        if (resultSet.next()) {
            List<String> list = new ArrayList<>();
            do {
                list.add(resultSet.getString("name"));
            } while (resultSet.next());
            return list;
        } else {
            return Collections.emptyList();
        }
});

queryOne

Выполнение SQL запроса с расчетом, что результат будет единичным либо не будет вовсе.
Возвращает Optional.

Optional<String> optName = jdbcTemplate.queryOne("SELECT name FROM my_table WHERE name LIKE 'dmitriymx'", rs -> rs.getString("name"));

queryList

Выполнение SQL запроса и обработка результата как списка данных.
Возвращает List.

List<String> names = jdbcTemplate.queryList("SELECT name FROM my_table", (resultSet, rowNum) -> resultSet.getString("name"));

queryForMap

Выполнение SQL запроса с расчетом, что результат будет единичным либо не будет вовсе.
Возвращает Map<String, Object>, где ключ — это наименование колонок таблицы, а значения — это значения в ячейках таблицы.

Map<String, Object> map = jdbcTemplate.queryForMap("SELECT * FROM my_table LIMIT 0,1;");

queryForMapList

Выполнение SQL запроса и обработка результата как списка данных.
Возвращает List<Map<String, Object>>, где ключ — это наименование колонок таблицы, а значения — это значения в ячейках таблицы.

List<Map<String, Object>> mapList = jdbcTemplate.queryForMapList("SELECT * FROM my_table");

update

Выполнение SQL запроса где будет происходить обновление данных в таблице. Под "обновлением" подразумеваются любые изменения в таблице: UPDATE, DELETE, INSERT.
Возвращает число строк, которые были по факту обновлены в таблице.

int rows = jdbcTemplate.update("DELETE FROM my_table WHERE name LIKE 'dmitriymx';");

ScheduleManager

Набор методов для создания параллельных задач, выполняющихся один раз или по рассписанию.

createTask

Создание конструктора задачи.

ScheduleManager.Builder builder = ScheduleManager.createTask();

useBukkitScheduler

Если задача будет взаимодействоватьс Bukkit API или необходима привязка задачи к тикам, то необходимо использовать данный указатель.

В ином случае, указатель не нужен.

ScheduleManager.Builder builder = ScheduleManager.createTask()
        .useBukkitScheduler();

after

Указание, что задачу нужно выполнить не сразу, а с некоторой задержкой перед запуском.

ScheduleManager.Builder builder = ScheduleManager.createTask()
        .after(5, TimeUnit.MINUTES);

every

Указание, что задачу нужно повторять через указанное время.

ScheduleManager.Builder builder = ScheduleManager.createTask()
        .every(5, TimeUnit.MINUTES);

create

Создание описанной задачи.

ScheduleTask scheduleTask = ScheduleManager.createTask()
        .every(1, TimeUnit.SECONDS)
        .create(() -> Bukkit.getServer().getLogger().info("TimeMS: " + System.currentTimeMillis()));

Задача будет только создана. Для её выполнения нужно вызвать scheduleTask.start().

execute

Создание и выполнение описанной задачи.

ScheduleTask scheduleTask = ScheduleManager.createTask()
        .every(1, TimeUnit.SECONDS)
        .execute(() -> Bukkit.getServer().getLogger().info("TimeMS: " + System.currentTimeMillis()));

ScheduleTask

Вспомогательный объект, созданный через ScheduleManager. Позволяет управлять созданной задачей.

start

Запускает задачу, если она еще не запущена.

ScheduleTask scheduleTask = ...;
scheduleTask.start();

isCanceled

Возвращает состояние задачи. Если true, значит задача была или отменена/остоновлена или была завершена.

ScheduleTask scheduleTask = ...;
boolean status = scheduleTask.isCanceled();

cancel

Отменяет/Остонавливает выполнение задачи.

ScheduleTask scheduleTask = ...;
scheduleTask.cancel();

I18n

TODO

loadMessages

TODO

get

TODO

paramBuilder

TODO

XLog

TODO

---

Подключение

Gradle

repositories {
    maven { url 'https://dmx-mc-project.gitlab.io/maven-repository/' }
}

implementation group: 'ghast', name: 'ghast-tools', version: '1.9'

Maven

<repositories>
    <repository>
        <id>dmx-mc-project</id>
        <url>https://dmx-mc-project.gitlab.io/maven-repository/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>ghast</groupId>
        <artifactId>ghast-tools</artifactId>
        <version>1.9</version>
    </dependency>
</dependencies>