Руководство

В руководстве две части. Первая для владельцев серверов: хранилище, настройки и команды. Вторая для авторов плагинов: как проверять и менять права через API.

Строки прав

Право это строка из сегментов, разделённых точками. Плагины сами выбирают свои строки, обычно начиная их с имени плагина.

• * может быть только последним сегментом. Пустые сегменты (a..b, a.) не допускаются.
• admin.* покрывает admin.kick, а обычная строка admin не покрывает.
• Запретом отнимают одно право у того, у кого есть wildcard: admin.* вместе с -admin.ban.

Как решается проверка

Когда право проверяется для игрока, побеждает первое место, которое знает ответ:

1. временные права игрока;
2. постоянные права игрока;
3. группы игрока, от самого высокого приоритета к самому низкому. Сначала спрашивается сама группа, затем её родитель, затем родитель родителя.

Поэтому собственные права игрока перекрывают группы, а группа с более высоким приоритетом перекрывает группу с более низким.

Иммунитет

У каждого игрока есть уровень иммунитета. Администратор может действовать на игрока, только когда иммунитет администратора равен или выше. Иммунитет -1 означает «взять приоритет моей старшей группы».

Владельцам серверов

Установка

Все три плагина входят в билд Plugify Source 2 и сразу работают с базой SQLite. Как поставить их отдельно, описано на странице Установка.

Хранилище

Плагин хранилища держит настройки в permissions_storage.settings.yaml. Значения по умолчанию лежат рядом с плагином. Чтобы изменить их, создайте configs/permissions/permissions_storage.settings.yaml с теми ключами, которые меняете:

storage_method: mysql
server_id: 1
data:
  host: "127.0.0.1"
  port: 3306
  username: "plugify"
  password: "secret"
  database: "permissions"

• SQLite не требует настройки. База лежит в data/permissions/permissions.db и создаётся при первом запуске с группой Default, которую получает каждый игрок. SQLite всегда работает как сервер 0.
• Таблицы MySQL и PostgreSQL плагин не создаёт. Создайте их до первого запуска скриптом tables_mysql.sql или tables_postgres.sql из репозитория permissions-storage.

Настройки коннектора

Коннектор так же читает permissions_connector_s2.settings.yaml, правки кладутся в configs/permissions/:

Фразы лежат в permissions_connector_s2.translations.yaml. Чтобы изменить их, положите свою копию в data/permissions/. Применить изменения без перезапуска можно командами perms_reload_cfg и perms_reload_translations.

Команды

Команды работают в консоли сервера и в чате. Из консоли сервера разрешено всё. Игроку нужно право из таблицы, и он не может действовать на игроков с более высоким иммунитетом.

<player> это #userid, $steamid64, &account_id или имя. <duration> это число в единицах time_mode, а 0 означает навсегда. В perms_creategroup передайте "", если родителя нет, а несколько прав запишите в кавычках через пробел.

Первая настройка

Выполните в консоли сервера, чтобы создать группу администраторов и выдать её себе:

perms_creategroup Admin 100 "" "admin.* permissions.*"
perms_user_add_group $76561198000000000 Admin 0

Игрок должен быть на сервере: пользователи загружаются при входе и выгружаются при выходе.

Авторам плагинов

Добавьте зависимость

{
  "$schema": "https://raw.githubusercontent.com/untrustedmodders/plugify/refs/heads/main/schemas/plugin.schema.json",
  "name": "my_plugin",
  "version": "1.0.0",
  "description": "An example plugin",
  "author": "Your Name",
  "website": "https://example.com",
  "license": "MIT",
  "language": "golang",
  "entry": "bin/my_plugin",
  "dependencies": [
    { "name": "permissions", "constraints": ">=1.3.0" }
  ]
}

Примеры ниже написаны на Go и используют готовые биндинги, go get github.com/fr0nch/go-plugify-permissions. В других языках те же функции импортируются из плагина permissions, см. страницу Import Functions вашего языка.

Проверка права

package main

import (
    permissions "github.com/fr0nch/go-plugify-permissions"
)

// May this player use the kick feature of my plugin?
func canKick(steamID64 uint64) bool {
    return permissions.HasPermission(steamID64, "my_plugin.kick") == permissions.Status_Allow
}

// May the admin act on the target at all?
func canTarget(adminID, targetID uint64) bool {
    return permissions.CanAffectUser(adminID, targetID) == permissions.Status_Allow
}

HasPermission возвращает Status: Allow, Disallow, PermNotFound или TargetUserNotFound, когда игрок не загружен. Сравнивайте с Allow, тогда отсутствующее право означает «нет».

Изменение прав и подписка на изменения

// Give the VIP group for 30 days. pluginID is the id of your plugin.
expires := time.Now().Add(30 * 24 * time.Hour).Unix()
status := permissions.AddGroup(pluginID, steamID64, "VIP", expires, false)
if status > permissions.Status_ErrorsStart {
    // GroupNotFound, TargetUserNotFound, DBNotReady and so on
}

// React to changes
permissions.OnUserGroupChange_Register(func(pluginID int64, action permissions.Action,
    targetID uint64, group string, oldTimestamp int64, newTimestamp int64) {
    // action is Action_Add, Action_Remove or Action_Replace
})

• Время задаётся как Unix-время момента, когда право или группа истекает. 0 означает навсегда.
• Функции, которые что-то меняют, принимают pluginID, он передаётся в колбэки, и dontBroadcast, с которым изменение применяется без уведомления подписчиков.
• Любой статус больше ErrorsStart является ошибкой.
• AddPermission отказывается менять право, которое уже есть с противоположным состоянием (PermConflict). SetPermission его заменяет.

Основные функции

События

У каждого события есть пара функций, On<Event>_Register и On<Event>_Unregister.

Своё хранилище или коннектор

Ядро само ничего не загружает. LoadGroups и LoadUser вызывают колбэки OnGroupsLoad и OnUserRequest, а плагин, который их зарегистрировал, наполняет ядро через CreateGroup, CreateUser, AddGroup, AddPermission и SetCookie.

Чтобы сохранять изменения, зарегистрируйте колбэки хранилища: OnUserPermissionChangeStorage, OnUserGroupChangeStorage, OnUserCookieChangeStorage, OnUserImmunityChangeStorage, OnGroupCreateStorage, OnGroupDeleteStorage, OnGroupPermissionChangeStorage, OnGroupOptionChangeStorage и OnSetParentStorage. Они вызываются до применения изменения и возвращают bool. Если вернуть false, изменение отменяется, а вызвавший получает статус DBNotReady.

Полный список функций, колбэков и кодов статуса есть на API Hub.