Przejdź do treści

Task API

Za każdym razem, gdy komenda się uruchamia, tworzy zadanie dla każdego celu. Zadanie trafia potem do run i odpowiada za to, jak długo komenda żyje, za networking, sprzątanie i dużo więcej.

Metody

task:keep Server

task:keep(persistence: Persistence?)

Utrzymuje zadanie przy życiu po tym, jak run zwróci wynik, w przeciwnym razie jest od razu niszczone. Do wyboru masz "UntilTargetRespawns", "UntilTargetLeaves", "UntilCallerRespawns", "UntilCallerLeaves" i "Indefinitely". Jeśli wywołasz to więcej niż raz, warunki się łączą, więc zadanie kończy się przy tym, który nastąpi pierwszy. Zobacz Persistence.


task:getArg Server

task:getArg(nameOrPosition: string | number, ignoreDefault: boolean?): any

Odczytuje zwalidowaną wartość argumentu o podanej nazwie lub pozycji. Ta wartość może pochodzić z default argumentu, ze zwalidowanej wartości podanej przez wywołującego, ze zwalidowanej wartości, na którą zmienił ją monit, albo z wartości ustawionej przez task:setArg().

Przekaż true jako drugi argument, żeby dostać nil, gdy wywołujący nigdy nie podał argumentu, a jego wartość pochodzi tylko z default. Przydaje się to przy opcjonalnych argumentach, gdy chcesz wrócić do własnego zachowania, tak jak ;message wylicza czas wyświetlania z długości tekstu, jeśli nikt go nie wpisał.


task:setArg Server

task:setArg(nameOrPosition: string | number, value: any)

Zmienia wartość argumentu o podanej nazwie lub pozycji.


task:buff Server

task:buff(player: Player, group: string, priority: number?, callback: (hasEnded: boolean, original: any) -> any)

Zmienia właściwość, nakłada zmiany ponownie, gdy zmienią się buffy w tej samej grupie, a po zakończeniu zadania przywraca właściwości jej pierwotną wartość. Zobacz Buffs.


task:updateBuffs Server

task:updateBuffs(player: Player?, group: string?)

Uruchamia ponownie buffy dla danego gracza i grupy. W większości przypadków dzieje się to automatycznie, więc przyda ci się tylko wtedy, gdy chcesz na siłę odświeżyć wszystko w tej grupie.


task:redo Server

task:redo(player: Player?, callback: () -> ())

Od razu uruchamia twój callback, a potem jeszcze raz za każdym razem, gdy gracz się odrodzi, dopóki zadanie żyje. Przydaje się do efektów, które inaczej znikałyby po respawnie.


task:bindPrompt Server

task:bindPrompt(config)

Daje wywołującemu monit z akcjami powiązany z komendą, taki jak suwak przy ;speed albo kolor oczu przy ;laserEyes:

run = function(task: CommandAPI.Task)
    task:keep("UntilCallerLeaves")
    task:bindPrompt({
        title = "Dangerous Script",
        text = "This script uses HttpService, are you sure you want to load it?",
        audience = task.caller,
        duration = 20,
        deactivate = false,
        endOnClose = true,
        buttons = {
            {
                label = "Load",
                onActivate = function()
                    --loadScript()
                    task:destroy()
                end,
            },
            {
                label = "Cancel",
                style = "Neutral",
                onActivate = function()
                    task:destroy()
                end,
            },
        },
    })
end,

Config

Key Type What it does
title string Nagłówek monitu, domyślnie nazwa komendy
text string Tekst główny
subtext string Mniejsza linijka pod tekstem
audience Player Kto widzi monit, domyślnie task.target
duration number Liczba sekund, po których monit sam znika. Domyślnie 0, czyli bez limitu czasu
args table Argumenty komendy, które mają być pokazane jako kontrolki, zobacz Controls
onChange function function(argName, value), uruchamia się po tym, jak kontrolka zmieni argument
toggle table Dodatkowy przełącznik włącz/wyłącz, który nie jest powiązany z argumentem, {label = "Trails", value = true, onChange = function(isOn) end}
buttons table Jednorazowe przyciski akcji, zobacz Buttons
deactivate boolean Domyślnie true, co daje monitowi przełącznik wstrzymujący i wznawiający komendę oraz przycisk Stop, który ją kończy. Ustaw false dla monitu, który ma tylko przyciski
rerun boolean Dodaje przycisk ponownego uruchomienia, który sprząta i odpala komendę od nowa. Pokazuje się tylko wtedy, gdy deactivate ma wartość false
endOnClose boolean Domyślnie zamknięcie monitu kończy zadanie. Ustawienie false utrzymuje je, dopóki klient go nie zamknie

Controls

Żeby argument dało się kontrolować z monitu z akcjami, dodaj jego nazwę do args w bindPrompt. Number zamienia się w suwak, Color w selektor koloru, Bool w przełącznik itd. Za każdym razem, gdy klient coś zmieni, argument się aktualizuje i odpala się twój onChange, więc wystarczy znowu wywołać task:getArg, żeby odczytać nową wartość. Nie musisz też niczego walidować, każda wartość jest sprawdzana dokładnie tak, jakby została wpisana na czacie:

run = function(task: CommandAPI.Task)
    local function applySpinSpeed()
        local speed = task:getArg("Number")
        -- spin the character at this speed
    end
    applySpinSpeed()
    task:bindPrompt({
        args = {"Number"},
        onChange = applySpinSpeed,
    })
end,

Buttons

Przyciski są równie proste. Daj każdemu label i funkcję onActivate, a ta funkcja uruchomi się na serwerze za każdym razem, gdy klient go naciśnie. Możesz tu też spokojnie yieldować (monit zakupu, wywołanie datastore itp.), bo przycisk po prostu pokazuje spinner, dopóki nie skończysz:

Key Type What it does
label string Tekst na przycisku
onActivate function Co się dzieje po jego naciśnięciu
style string Domyślnie "Primary", albo "Neutral" dla wyszarzonego wyglądu, idealny dla Cancel
confirm boolean Dodaje krok Confirm?, więc przycisk odpala się dopiero po dwukrotnym naciśnięciu, przydatne przy czymś mocnym, jak potwierdzenie banu

Przycisk może zakończyć własne zadanie przez task:destroy(), tak robią jednorazowe monity komend, jak ;teleport.


task.client:run Server

task.client:run(player: Player?, ...)
task.client:runAll(...)
task.client:runOthers(originPlayer: Player, ...)
task.client:runNearby(originPlayer: Player?, radius: number, ...)

Uruchamia pasującą komendę kliencką na urządzeniach graczy, przekazując dalej wszystko, co dodasz. run celuje w jednego gracza, runAll we wszystkich, runOthers we wszystkich oprócz originPlayer, a runNearby w tych w promieniu radius studów. Zobacz Networking.


task.client:expose Server

task.client:expose(player: Player, instances: Instance | {Instance})
task.client:exposeAll(instances: Instance | {Instance})

Upewnia się, że instancje faktycznie dotarły do gracza, zanim twój kod kliencki zacznie ich szukać. Streaming potrafi coś wstrzymać, więc wszystko, co tworzysz na serwerze i używasz na kliencie, powinno najpierw przejść tędy.


task.server:replicate Client

task.server:replicate(...)

Wysyła wartości z komendy klienckiej z powrotem na serwer, gdzie trafiają do tego samego zadania. Ustaw task.client.replicator na serwerze, żeby wybrać, do kogo mają iść dalej, a potem dotrą do funkcji replication tej komendy. Zobacz Networking.


task:tween Shared

task:tween(instance: Instance, tweenInfo: TweenInfo, properties: {[string]: any}): Tween

Odtwarza tween, który jest sprzątany razem z zadaniem, więc nigdy nie przeżyje komendy.


task:createSound Shared

task:createSound(soundType: SoundType?): Sound

Tworzy Sound, którego właścicielem jest zadanie i które je sprząta. Głośność (Volume) i wysokość dźwięku (Pitch) mogą być potem konfigurowane przez wszystkich graczy w ich YouSettings. SoundType domyślnie ma wartość "Command", jeśli go nie ustawisz.


task:onEnded Shared

task:onEnded(callback: () -> ())

Uruchamia twój callback za każdym razem, gdy zadanie się kończy. To to samo, co task.janitor:add(callback).


task:onEndedForGood Shared

task:onEndedForGood(callback: () -> ())

Uruchamia twój callback tylko wtedy, gdy zadanie się zakończyło ORAZ zaraz potem nie powstało identyczne zadanie. Przydaje się to przy komendach takich jak ;serverLock Admin, która wyświetla powiadomienie przy uruchomieniu ("This server has been locked for Admins") i przy zakończeniu ("This server has been unlocked"). Gdybyśmy jednak potem uruchomili ;serverLock Mod, nie chcemy, żeby poprzednia komenda pokazała swoje powiadomienie o zakończeniu, tylko żeby wyświetliło się nowe powiadomienie o uruchomieniu.


task:destroy Shared

task:destroy()

Kończy zadanie siłą i sprząta wszystko, co do niego należy. To właśnie wywołuje ;un w tle.


Scheduling Shared

task.spawn(callback: () -> ())
task.defer(callback: () -> ())
task.delay(seconds: number, callback: (() -> ())?)
task.wait(seconds: number?)
task.iterate(count: number, callback: (index: number) -> ())
task.loop(callback: (stop: () -> (), index: number) -> ())

To wersje wbudowanego w Roblox task do planowania, które znają zadanie. Są niezbędne, żeby komenda mogła być utrzymywana przy życiu, dopóki jest aktywna, i żeby dało się je automatycznie anulować, gdy zadanie jest sprzątane (np. gdy ktoś wywoła undo przed końcem zadania). Używaj ich tak, jak zwykłych metod task z Roblox, a resztą HD Admin zajmie się w środku.

Właściwości

task.target Server

task.target: Player

Gracz, na którym działa komenda. Jeśli twoim pierwszym argumentem jest Player, zawsze jest jeden, bo HD Admin dzieli uruchomienie na osobne zadanie dla każdego dopasowanego gracza, więc możesz go używać bez sprawdzania. Komendy, które przyjmują zbiorczy argument Players, nie są tak dzielone, więc tu pole jest puste. task.targetUserId zawiera jego UserId i jest dostępne nawet wtedy, gdy jest offline.


task.qualifiers Server

task.qualifiers: {[string]: {string}}

Kogo wywołujący wskazał w swoim oryginalnym ciągu komendy. ;clone others daje {others = {}}, a samo ;clone daje pustą tabelę. To zawsze tabela, więc można ją bezpiecznie czytać bezpośrednio.


task.caller Server

task.caller: Player?

Ten, kto uruchomił komendę, albo nil, gdy zrobił to serwer (albo gdy serwer dostaje komendę globalną, a wywołującego nie ma na twoim serwerze). task.callerUserId jest zawsze dostępne, więc użyj go, jeśli potrzebujesz UserId wywołującego.


task.janitor Shared

task.janitor:add(item): typeof(item)

Obiekt Janitor, któremu możesz przekazywać instancje, połączenia i funkcje, żeby były automatycznie sprzątane. Na przykład:

local fire = task.janitor:add(Instance.new("Fire"))
fire.Parent = targetsHumanoidRootPart


task.config Server

task.config: {[string]: any}

Własna tabela config komendy, razem ze wszystkim, co pakiet zmienił przez modify w Config > Commands. Dzięki niej komenda czyta ustawienie, które właściciel gry ma móc zmieniać, jak listy dozwolonych i zabronionych przy ;insert.


task.extra Shared

task.extra: {[string]: any}

Tabela na dodatkowe informacje, które możesz do niej dopisać i które przeżywają dezaktywację, aż zadanie zostanie całkowicie zakończone.


task.isActive Shared

task.isActive: boolean

true, dopóki zadanie działa, false, gdy zaczyna się kończyć. Używaj tego w pętlach, żeby efekt mógł od razu przestać działać, jeśli na przykład zadanie zostało zakończone siłą.


task.commandKey Shared

task.commandKey: string

Nazwa komendy, którą to zadanie uruchamia, pisana małymi literami.


task.isReplay Server

task.isReplay: boolean

true, gdy zapisana stała komenda jest odtwarzana przy starcie serwera, a nie uruchamiana teraz przez kogoś. Przydaje się do ograniczania monitów w stałych komendach, których nie chcemy pokazywać wywołującemu automatycznie jeszcze raz (np. monit ;music przy wejściu na każdy nowy serwer).