Skripty NPC — ArdaNPCs Wiki

První skript

Skripty ArdaNPCs 1.1.0 jsou serverové události s vlastním omezeným JavaScript API. Upravuje je důvěryhodný správce s oprávněním OP 2. Skript z CustomNPCs nelze prostě vložit beze změn: názvy událostí a dostupné objekty se liší.

Otevřete editor NPC a tlačítko Otevřít skripty….
Vyberte událost interact. Vložte jen tělo události, například api.message("Vítej!");. Nepřidávejte obal function interact(e) { ... }.
Použijte Kontrola pro syntaxi všech událostí. Test simuluje vybranou událost se správcem jako hráčem; nemění svět, proměnné, časovače, questy ani poštu.
Přepněte Skripty: zapnuto a stiskněte Uložit. Počkejte na potvrzení serveru. Zapnutí je společné pro všechny události NPC.
Zavřete editor a vyvolejte skutečnou interakci. Výsledek i chyby sledujte přes Výpis.

Test nenahrazuje hraní: používá pomocné hodnoty jako event.timer = "test", takže nemusí projít větví s vaším skutečným ID. Příklady níže zkoušejte nejprve v kopii světa. Pokud už událost obsahuje kód, spojte potřebné bloky; vložení nového příkladu přes původní text jej přepíše.

Události a kontext

Událost	Spuštění	Pole navíc
`init`	První načtení NPC v relaci serveru a znovu po uložení skriptů.	—
`tick`	U načteného NPC v nastaveném intervalu 1–3600 sekund.	—
`interact`	Interakce hráče s NPC.	—
`dialog`	Skutečně otevřený dialog.	`dialogId`
`quest`	Potvrzená změna questu hráče.	`questId`, `stage`: `accepted`, `completed`, `failed`
`damage`	Před poškozením NPC; hráč je přítomen, pokud je útočníkem.	`damage`
`death`	Smrt NPC; hráč je přítomen, pokud je útočníkem.	—
`timer`	Doručení pojmenovaného časovače.	`timer`
`predicate`	Vyhodnocení podmínky; musí vrátit boolean.	`key`

Společná pole jsou event.type, npcId, npcName, hasPlayer, playerId a playerName. Používejte je s prefixem event.. Bez hráče je ID prázdné; před hráčským API ověřte event.hasPlayer. Identitu všech druhů hostů popisují event.hostId, hostKind, hostName a ownerNpcId. API neposkytuje objekty Minecraftu ani Javy.

Přehled běžného API

V ID předmětů, efektů a zvuků používejte úplný namespace, například minecraft:bread. Klíče proměnných a názvy timerů mají 1–48 znaků z [A-Za-z0-9_.:-]. V predicate jsou povolená pouze čtení; změna dat, timeru, questu nebo světa vyvolá chybu.

Volání	Význam
`api.get(key)`, `api.set(key, value)`, `api.has(key)`, `api.remove(key)`	Trvalá data NPC/instance. Hodnoty jsou řetězce; chybějící klíč vrátí prázdný řetězec. Pro číslo použijte `Number(...)`.
`api.playerGet(key)`, `api.playerSet(key, value)`, `api.playerHas(key)`, `api.playerRemove(key)`	Oddělená data pro hráče události u tohoto NPC/instance. Vyžadují hráče.
`api.message(text)`, `api.say(text)`	Zpráva hráči události / všem hráčům do 32 bloků ve stejné dimenzi; nejvýše 256 znaků.
`api.heal(amount)`	Vyléčí hráče události o 0–40 bodů zdraví, nejvýše do jeho maxima.
`api.give(itemId, count)`	Předá hráči 1–64 kusů, nejvýše limit stacku předmětu. Zbytek z plného inventáře odhodí.
`api.hasItem(itemId, count)`	Vrátí boolean podle inventáře hráče; počet 1–4096.
`api.questProgress(questId, objectiveId, amount)`	Zařadí posun vlastního cíle MANUAL; celé číslo 1–10 000. Viz příklad níže.
`api.mail(title, body, key)`	Zařadí příběhový dopis hráči. Titul 1–80, text 1–2000 znaků; stabilní klíč 1–64 znaků `[A-Za-z0-9_.:-]`. Bez příloh a volby jiného příjemce.
`api.sound(soundId, volume, pitch)`	Zvuk na pozici NPC/hosta; hlasitost 0–1, výška 0,5–2. ID musí existovat v registru.
`api.effect(effectId, seconds, amplifier)`	Efekt hráči na 1–300 sekund; zesílení 0–4 (0 je úroveň I).
`api.spawn(entityId, count)`	1–2 mobové; pouze `minecraft:zombie`, `skeleton`, `spider`, `slime`, `cow`, `sheep`, `pig` se stejným prefixem `minecraft:`. Platí prostorové a společné limity.
`api.timer(name, seconds, repeating)`, `api.cancelTimer(name)`	Vytvoří/zruší časovač hosta na 1–3600 sekund. Stejný název nahradí předchozí; `true` opakuje, `false` spustí jednou.
`api.cancel()`	V události interakce spotřebuje běžnou interakci; v `damage` zabrání příslušnému poškození. Nevrací již provedené změny.
`api.log(text)`	Záznam do diagnostiky, nejvýše 300 znaků; uchovává posledních 10 řádků.
`api.time()`, `api.dimension()`, `api.raining()`	Čas dne Overworldu v ticích / ID dimenze hosta / déšť. `time()` ovlivňuje změna času a pravidlo denního cyklu; pro odpočet použijte timer.
`api.playerHealth()`, `api.playerLevel()`, `api.playerTag(tag)`	Zdraví / XP úroveň / boolean, zda hráč události má command tag.
`api.creative()`, `api.playerGamemode()`	Creative boolean / číselné ID herního režimu hráče.
`api.hostX()`, `api.hostY()`, `api.hostZ()`	Souřadnice NPC, předmětu nebo bloku, který skript spustil.
`api.playerX()`, `api.playerY()`, `api.playerZ()`	Souřadnice hráče; bez hráče vyvolají chybu.
`api.x()`, `api.y()`, `api.z()`	Souřadnice hráče, pokud je přítomen; jinak souřadnice hosta.

Příklad: léčitel s odpočtem

Do interact vložte:

if (!event.hasPlayer) return;
if (api.playerGet("heal_wait") === "1") {
    api.message("Na další léčení si chvíli počkej.");
    return;
}
api.playerSet("heal_wait", "1");
api.timer("heal:" + event.playerId, 30, false);
api.heal(8);
api.message("Tvé rány se hojí.");

Do timer téhož NPC vložte:

if (event.hasPlayer && event.timer === "heal:" + event.playerId) {
    api.playerRemove("heal_wait");
}

První klik vyléčí až 8 bodů zdraví (4 srdce). Další léčení povolí jednorázový timer po 30 herních sekundách. Název obsahuje UUID hráče, takže se hráči navzájem nepřepisují. Timer čeká, když NPC není načtené nebo hráč není online. Na jedno NPC připadá nejvýše 16 timerů včetně ostatních skriptů; tento jednoduchý příklad je pro malé skupiny.

Příklad: podmínka podle XP

Do predicate vložte:

return event.key === "experienced"
    && event.hasPlayer
    && api.playerLevel() >= 5;

V podmínkách dialogu nebo questu zvolte SCRIPT_PREDICATE a klíč experienced. Podmínka projde hráči od XP úrovně 5. Každá cesta musí vrátit true nebo false; nic zde neposílejte ani neukládejte. Pro jednoduché číselné proměnné lze použít SCRIPT_VARIABLE_MIN s klíčem player:nazev nebo npc:nazev.

Příklad: ruční cíl questu

Nejdříve na tomto NPC vytvořte quest a přidejte cíl typu MANUAL s požadovaným počtem 1. Opište skutečné ID questu a cíle z editoru; ID cíle se generuje automaticky. V ukázce nahraďte patrani skutečným ID questu a stopa_les skutečným ID cíle. Hráč musí quest přijmout. Upravený kód vložte do interact:

if (api.questProgress("patrani", "stopa_les", 1)) {
    api.message("Zaznamenání stopy bylo zařazeno.");
} else {
    api.message("Tuto stopu teď zaznamenat nepotřebuješ.");
}

true znamená přijetí do fronty, nikoli potvrzený zápis. Po skutečném kliku ověřte deník questu. Neaktivní nebo hotový cíl a dosud zamčený krok SEQUENTIAL vrátí false; neexistující quest nebo nesprávný typ cíle je chyba konfigurace. Nenahrazujte skutečný questový stav vlastní proměnnou „hotovo“.

Příklad: příběhový dopis

Do interact NPC vložte:

if (api.mail("Pozvání", "Vrať se ke strážci pro další úkol.", "chapter1_invitation")) {
    api.message("Dopis je ve frontě. Zkontroluj schránku.");
}

Stabilní klíč brání opakovanému dopisu pro stejné NPC a hráče. false může znamenat již použitý klíč, plnou schránku nebo limit; není to potvrzení doručení. Příjemcem je hráč události. Skriptované předměty a bloky potřebují pro poštu i questový postup existujícího vlastníka NPC.

Ukládání a provozní limity

Jedna událost: 12 288 znaků; všechny události: 32 768 znaků. Jeden běh: 60 000 instrukcí. NPC, předměty a bloky sdílejí serverové rozpočty, včetně 64 událostí za tick.
Prostor NPC/instance nebo instance + hráč: 64 klíčů, 1024 znaků hodnoty, celkem 16 384 znaků. V celém světě nejvýše 4096 těchto prostorů.
16 timerů na hosta a 1024 celkem. Timery používají herní čas, přežívají restart a nedohánějí vynechaná opakování.
Nejvýše 8 vnějších efektů a 2 vyvolaní mobové na událost. Další minutové kvóty omezují spam.

Kód se ukládá s konfigurací NPC, stav a timery do <world>/data/ardanpcs/scripts-state.json. Klon převezme kód, ale má nové UUID a vlastní prázdný stav. Proměnné a timery se potvrzují před účinky ve světě; pád serveru mezi těmito kroky může znamenat neprovedený účinek. Nejde o záruku společné transakce všech systémů.

Chybná událost zablokuje skripty daného hosta. Opravte chybu podle diagnostiky a znovu uložte. Neprověřený cizí kód nepouštějte: prostředí je omezené, ale běží ve stejném procesu jako server. Java, soubory, síť, příkazy, eval, konstruktory new a část běžného JavaScriptu nejsou dostupné. Pokračujte na skriptované předměty a bloky nebo řešení problémů.