Перейти к содержанию

Свои команды

Tip

Дополнительные команды можно найти здесь.

Команды

Команда это просто таблица с описанием того, что она такое и как должна работать. Устроены они так по нескольким причинам:

Память Когда команда запускается, она может быть представлена как задача, которую персонал легко видит и отменяет. Задачи сами за собой убирают, поэтому память не утекает, а писать отдельную функцию undo тебе даже не нужно.
Охват Задачи больше не зависят от конкретного игрока, который запустил команду (то есть вызывающего), поэтому любая команда работает с любым модификатором, и команды, которые ты пишешь, сразу можно запускать на всех серверах.
Безопасность Аргументы проверяются до вызова run, поэтому аргумент Player приходит как настоящий Player, а Number всегда приходит в допустимом диапазоне и так далее. Твой код никогда не работает с сырым текстом, а вызывающие не могут запустить команду, которая недоступна их ролям.
Интерфейс Страница Run, подсказки командной строки и автодополнение создаются автоматически из твоих args, поэтому каждая команда, которую ты пишешь, сразу доступна игрокам, которые не могут писать в чат.
Типизация Команды полностью типизированы, поэтому если пометить их как CommandAPI.Commands, ты получишь автодополнение и предупреждения о типах прямо при написании.

Создай свои

В ConfigCommands просто дополни существующий модуль Custom или добавь свой модуль с любым количеством таблиц команд:

изображение

--!strict
-- LOCAL
local TAGS = {"CoolCommands"}
local StarterPlayer = game:GetService("StarterPlayer")
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
local getHumanoid = CommandAPI.getHumanoid
local getHRP = CommandAPI.getHRP

-- COMMANDS
local commands: CommandAPI.Commands = {

    --------------------
    {
        name = "Jump",
        args = {"Player"},
        tags = TAGS,
        run = function(task: CommandAPI.Task)
            local target = task.target
            local humanoid = getHumanoid(target)
            if not humanoid then return end
            humanoid.Jump = true
        end,
    },

    --------------------
    {
        name = "Fire",
        args = {"Player"},
        tags = TAGS,
        run = function(task: CommandAPI.Task)
            local target = task.target
            local hrp = getHRP(target)
            if not hrp then return end
            task:keep("UntilTargetRespawns")
            local fire = task.janitor:add(Instance.new("Fire"))
            fire.Parent = hrp
        end,
    },

    --------------------

}

return commands

Клиентские команды

По умолчанию код команд доступен и выполняется только на сервере, а иногда его нужно запускать на клиенте. Для этого под модулем команд можно добавить ModuleScript с именем Client и таблицами команд, у которых значения name совпадают с командами на сервере:

image

--!strict
-- LOCAL
local TAGS = {script.Name}
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)

-- COMMANDS
local commands: CommandAPI.Commands = {

    --------------------
    {
        name = "Flash",
        args = {"Player"},
        tags = TAGS,
        run = function(task: CommandAPI.Task)
            local target = task.target
            task.client:run(target)
        end,
    },

    --------------------

}

return commands

image

--!strict
-- LOCAL
local CommandAPI = require(script:FindFirstAncestor("HD Admin").Core.CommandAPI)
local Players = game:GetService("Players")
local TweenService = game:GetService("TweenService")

-- COMMANDS
local clientCommands: CommandAPI.ClientCommands = {

    --------------------
    {
        name = "Flash",
        run = function(task: CommandAPI.Task)
            local localPlayer = Players.LocalPlayer
            local playerGui = localPlayer:FindFirstChildOfClass("PlayerGui")
            if not playerGui then
                return
            end
            local screenGui = Instance.new("ScreenGui")
            screenGui.Name = "HDCustomFlash"
            screenGui.IgnoreGuiInset = true
            screenGui.DisplayOrder = 999
            local frame = Instance.new("Frame")
            frame.BackgroundColor3 = Color3.new(1, 1, 1)
            frame.Size = UDim2.fromScale(1, 1)
            frame.Parent = screenGui
            screenGui.Parent = playerGui
            local tween = TweenService:Create(frame, TweenInfo.new(1), {BackgroundTransparency = 1})
            tween.Completed:Once(function()
                screenGui:Destroy()
            end)
            tween:Play()
        end,
    },

    --------------------

}

return clientCommands

Содержит мигающие изображения. Нажми, чтобы посмотреть

Info

Ничего реплицировать самому не нужно. Фреймворк сам находит дочерний модуль с именем Client и автоматически отправляет его игрокам.


Поля команды

Все поля, кроме name, необязательные:

Названия
name Shared Название команды, которое показывается в интерфейсе и которое игроки вводят после своего префикса. Оно же служит именем для отмены, поэтому ;speed заканчивается командой ;unspeed
aliases Server Другие названия, которые запускают эту команду``
undoAliases Server Названия, которые отменяют команду, а не запускают её (например, у NoClip это {"Clip"})
description Server Предложение, которое показывается под командой на её странице запуска
credit Server Кого указать автором команды (например, {"GigsD4X"})
Запуск
args Server Аргументы, которые принимает твоя команда (например, "Player", "Text", "Number" и так далее). Полный список есть в MainModuleValueModulesParserArgs
run Shared Код твоей команды. На сервере ей передаются задача и проверенные аргументы, а на клиенте задача и то, что сервер передал в task.client:run
replication Client Функция, в которую приходят данные, возвращённые с сервера. Твой клиент вызывает task.server:replicate, task.client.replicator на сервере выбирает, кто их получит, и после этого функция запускается на клиенте этих игроков
config Server Значения по умолчанию, которые разработчики игры могут менять через modify при загрузке встроенных команд
cooldown Server Сколько секунд ждать после завершения команды, прежде чем её можно запустить снова
stackable Server Обычно на одном игроке или сервере может быть активна только одна такая команда, но при значении true их может быть несколько сразу
groups Server Команды из одной группы отменяют друг друга на одном игроке (например, Fly и NoClip обе в группе "Flight", поэтому запуск одной завершает другую) и делят общий cooldown. Две группы имеют особое значение: "Prompt" отмечает команды в стиле сообщений, которые тратят лимит текста в одну штуку в минуту, даже если ничего не введено, и фильтруются настройкой Block prompts, а "Map" отмечает команды, которые меняют карту, поэтому первая запущенная из них тихо сохраняет копию для ;clearmap
Охват
tags Server Теги, которые наследует эта команда, а роли по ним решают, какие команды наследовать
disableModifiers Server Запрещает использовать модификаторы с этой командой
disableGlobalModifiers Server Запрещает использовать глобальные модификаторы (например, global, perm, join и так далее) с этой командой
Интерфейс
order Server Позиция на странице команд. Меньшие числа идут первыми
hide Server Скрывает команду со страницы Commands
autoPreview Server Когда команда запускается через чат или кнопку быстрого просмотра, вместо запуска открывается страница Run (например, Ban использует это, чтобы сначала подтвердить детали)

Свои аргументы

Встроенные аргументы (в MainModuleValueModulesParserArgs) покрывают почти всё, что тебе понадобится, но если захочешь создать свой, это можно сделать в Config > Args:

изображение

return function(Args)
    return {

        ["Radius"] = Args.createAliasOf("Number", {
            display = "Radius",
            min = 0,
            max = 500,
            step = 1,
            default = 50,
        }),

    }
end

Warning

Следи, чтобы выбранное имя не совпадало ни с одним встроенным аргументом HD Admin, иначе при запуске будет предупреждение, и один из аргументов перекроет другой.

Если нужно изменить аргументы только одной команды, можно вместо имени аргумента указать таблицу аргумента:

args = {
    "Player",
    {arg = "Number", display = "Speed", default = 50, min = 0, max = 1000, step = 1, logarithmic = true},
},
args = {
    "Player",
    "Number",
},

Tip

Это удобно, когда нужно поменять ограничения аргумента, не заменяя его поведение целиком: image

Текст, который видят другие игроки

Правила Roblox по возрастной безопасности ограничивают текст, который игрок показывает другим, одним сообщением в минуту. HD Admin фильтрует каждый текстовый аргумент и тратит лимит в одну минуту для его типа, общий для всех команд этого типа:

Аргумент Для чего использовать
"Text" Всё, что показывается как сообщение, подсказка, уведомление, оповещение или опрос
"SurfaceText" Имена, заголовки и подписи над игроком или в мире
"ChatText" Теги и имена в чате
"Reason" Причины кика и бана

Чтобы выбрать тип самому, добавь textSurface в таблицу аргумента, например {arg = "Text", textSurface = "SurfaceText"}. Используй "None" для текста, который лишь иногда показывается другим, и вызывай checkTextLimit в тот момент, когда он показывается.


Args

Чтобы получить аргумент команды, используй task:getArg() и укажи его имя или индекс:

args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
    local target = task:getArg("Player")
    local number = task:getArg("Number")
    -- ...
end
args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
    local target = task:getArg(1)
    local number = task:getArg(2)
    -- ...
end

Note

Получать аргумент по индексу нужно, когда у команды два или больше одинаковых аргумента: {"Player", "Number", "Number"}

Когда "Player" используется как первый аргумент, команда запускается отдельно на каждом выбранном игроке. В этом случае на "Player" можно ссылаться через task.target:

args = {"Player", "Number"},
run = function(task: CommandAPI.Task)
    local target = task.target
    local number = task:getArg("Number")
    -- ...
end

Постоянство

Задача уничтожается сразу, как только run завершается. Для команд вроде ;jump, которые заканчиваются мгновенно, это нормально, но для таких, как music, где эффект должен остаться, не подходит. Поэтому любую команду, которую нужно оставить живой, нужно пропускать через task:keep:

task:keep("UntilTargetRespawns")
Постоянство Задача завершается, когда
"UntilTargetRespawns" цель возрождается или выходит
"UntilTargetLeaves" цель выходит
"UntilCallerRespawns" тот, кто запустил команду, возрождается или выходит
"UntilCallerLeaves" тот, кто запустил команду, выходит
"Indefinitely" кто-то завершает её через ;un или игрок выходит

Tip

Несколько вариантов «keep» можно комбинировать. Например, если вызвать task:keep("UntilTargetLeaves") и task:keep("UntilCallerLeaves"), команда завершится, когда с сервера выйдет либо тот, кто её запустил, либо цель.


Бафы

Менять свойства, например WalkSpeed у гуманоидов, обычно просто: ты задаёшь свойству нужное значение, и всё. Сложнее становится, когда участвуют несколько команд.

Представь, что твоё здоровье 100, и ты запускаешь ;health me 500, а потом ;god me. Сначала ;health ставит здоровье 500, затем ;god меняет его на 99999. Пока всё нормально, но что, если потом нужно убрать задачу god и оставить health? Во многих админ-системах отмена god просто вернёт здоровье к 100, не учитывая всё ещё действующую задачу health. Это плохо, и тут пригодятся бафы:

task:buff(target, "WalkSpeed", function(hasEnded: boolean, original: any)
    local humanoid = getHumanoid(target)
    local before = if humanoid then humanoid.WalkSpeed else StarterPlayer.CharacterWalkSpeed
    if humanoid then
        humanoid.WalkSpeed = if hasEnded then original else task:getArg("Number")
    end
    return before
end)

Баф это просто твой код плюс группа, к которой он относится (в этом примере "WalkSpeed"). Каждый раз, когда задача из этой группы запускается или завершается, все её бафы запускаются заново по порядку, так что свойство в итоге получает то значение, которое нужно последней команде.

Ещё можно вернуть исходное значение, то есть значение, которое запоминает самый ранний баф в группе. Когда убирается последний баф, свойство можно вернуть к этому исходному значению, так что здоровье вернётся к 100, а не к тому, что оставила предыдущая команда.


Сеть

Чтобы с сервера обратиться к нашим клиентским командам, используем task.client:

local part = Instance.new("Part")
task.client:expose(target, part)
task.client:run(target, part , "Hello this is a part from the server")
run = function(task: CommandAPI.Task, part, message)
    print("part, message =", part, message)
end

Important

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

Часто клиенту тоже нужно передать информацию серверу или даже другим клиентам. Например, при ;laserEyes мы хотим, чтобы другие клиенты видели наши лазерные лучи и то, куда мы их направляем. Для этого используем task.server:

-- The client's device knows something that others don't
task.server:replicate(targetCFrame, lookCFrame)
-- Your chance to pick who sees it, and to throw out anything dodgy
task.client.replicator = function(replicateTo, targetCFrame, lookCFrame)
    if typeof(targetCFrame) ~= "CFrame" or typeof(lookCFrame) ~= "CFrame" then
        return
    end
    for _, player in getTargets("OthersNearby", target, 100) do
        replicateTo(player, target, targetCFrame, lookCFrame)
    end
end
-- Runs on every client the server chose in the same client module
replication = function(target: Player, targetCFrame: CFrame, lookCFrame: CFrame)
    -- Show it happening on their screen
end,

Important

Обязательно проверяй, что значения внутри replicator именно такие, как ты ожидаешь, потому что клиент всегда может прислать вредоносные или другие значения.

Info

Ничего не доходит до другого игрока, пока твой replicator это не отправит, поэтому клиент не может тихо разослать всё, что захочет. Количество запросов на репликацию тоже ограничено внутри, и возможные злоупотрения со стороны клиентов учтены.


Запросы

Запускать команды это одно, но подстраивать их прямо во время работы ещё приятнее. Для этого есть task:bindPrompt, который даёт вызывающему карточку, которую можно настраивать:

local function applyLaserColour()
    local colour = task:getArg("Color")
    -- set the beam colours, eye colours, etc
end

applyLaserColour()
task:bindPrompt({
    args = {"Color"},
    onChange = applyLaserColour,
})

Ещё можно добавить buttons для разовых действий:

task:bindPrompt({
    title = "Teleport",
    text = `Click to teleport to '{placeName}'`,
    deactivate = false,
    endOnClose = true, -- dismissing the card ends its task
    buttons = {
        {
            label = "Teleport",
            onActivate = onActivate,
        },
    },
})

Все ключи, которые принимает карточка, включая кнопки confirm, дополнительные переключатели и кнопку Re-run, перечислены в task:bindPrompt. Про обычные уведомления и сообщения смотри prompt.

Подробнее о задачах и их методах можно прочитать в Task API.