Regeln schreiben

Drei Arten von Regeldateien

Eine Konstruktor-Datei exportiert eine Funktion. Eine Aktions- oder Ledger-Datei darf mehrere exportieren, wenn jeder Exportname eine für diese Datei deklarierte ID ist: eine Aktions-ID oder eine Ledger-Funktions-ID. Gespeicherte Feldnamen verwenden Kleinbuchstaben, Ziffern und Unterstriche.

Eine Ledger-Funktion kann auch Text zurückgeben. Gib currentValue und das Ergebnis als string an, und gib dem Ledger-Eintrag des Szenarios einen Text als currentValue.

export function last_band(currentValue: string, self: ElementRef): string {
  const roll: number = element.var(self, "last_roll") as number;
  const target: number = element.var(self, "last_target") as number;
  if (roll === 0) {
    return "No roll yet";
  }
  if (roll <= math.floor(target / 5)) {
    return "Flawless";
  }
  if (roll <= math.floor(target / 2)) {
    return "Strong";
  }
  if (roll <= target) {
    return "Pass";
  }
  return "Miss";
}

export function hurt(self: ElementRef, amount: number): void {
  ledger.add(self, "hp", 0 - amount);
}

Eine Regeldatei kann auch Hilfsfunktionen enthalten. Schreibe sie ohne export und rufe sie in derselben Datei beim Namen auf. Die Datei exportiert weiterhin genau eine Funktion oder nur die Aktionen oder Ledger-Funktionen, die sie deklariert.

function base_guard(calling: string): number {
  return calling === "Guard" ? 3 : 1;
}

export function guard(currentValue: number, self: ElementRef): number {
  const calling: string = element.var(self, "calling") as string;
  return base_guard(calling);
}

Eine Regeldatei kann keinen Code importieren. Eine Aktionsdatei exportiert eine Funktion, es sei denn, mehrere Aktionen teilen sie. Ein zusätzlicher Export allein scheitert mit:

export function hurt(self: ElementRef, amount: number): void {
  ledger.add(self, "hp", 0 - amount);
}
export function hurt_twice(self: ElementRef, amount: number): void {
  ledger.add(self, "hp", 0 - amount - amount);
}

functions but only the action hurt uses it

Um eine Hilfsfunktion zwischen Aktionen zu teilen, lasse diese Aktionen eine Datei teilen. Benenne jeden Export nach der Aktion, die er ausführt, deklariere jeden Export als Aktions-ID und lasse die Hilfsfunktion ohne export. Die Aktionen dürfen zu verschiedenen Frameworks gehören, und eine Aktion kann keine andere aufrufen. Jede Funktion trägt eine Kopie ihrer ganzen Datei im kompilierten Spiel, also halte geteilte Dateien kurz.

Eine Hilfsfunktion darf nur berechnen und einen Wert zurückgeben. Sie darf ledger.set oder ledger.add nicht aufrufen. Eine Hilfsfunktion, die schreibt, wird abgelehnt, auch in einer Datei, die Aktionen teilen:

function wound(self: ElementRef): void {
  ledger.add(self, "hp", -1);
}

effectful action helpers are not supported until call-target provenance is enforced

Lasse die Hilfsfunktion den Wert zurückgeben und jede Aktion selbst schreiben. Diese beiden Aktionen teilen eine reine Hilfsfunktion:

function clamp(value: number, low: number, high: number): number {
  return math.max(low, math.min(high, value));
}

export function hurt(self: ElementRef, amount: number): void {
  const hp: number = element.var(self, "hp") as number;
  const max_hp: number = element.var(self, "max_hp") as number;
  ledger.set(self, "hp", clamp(hp - amount, 0, max_hp));
}

export function heal(self: ElementRef, amount: number): void {
  const hp: number = element.var(self, "hp") as number;
  const max_hp: number = element.var(self, "max_hp") as number;
  ledger.set(self, "hp", clamp(hp + amount, 0, max_hp));
}

Ein Konstruktor, der untergeordnete Plätze füllt, gibt { values, children } statt eines einfachen Records zurück. Der Schnellstart zeigt den einfachen Record, und die Seite Framework-Schemas zeigt die Form mit untergeordneten Elementen.

Die TypeScript-Teilmenge

Regeln laufen überall gleich ab, und sie enden immer. Deshalb ist die Sprache klein.

Beende jede Anweisung mit einem Semikolon. Jeder dieser Fehler wird beim Prüfen des Projekts erkannt.

export function heal(self: ElementRef, amount: number): void {
  while (amount > 0) {
    ledger.add(self, "hp", 1);
    amount = amount - 1;
  }
}

while loops are not allowed

export function heal(self: ElementRef, amount: number): void {
  ledger.set(self, "hp", Math.min(10, amount));
}

'Math' is a host global and not part of the TypeScript subset

import { clamp } from "./clamp";

import is not allowed

Eine Funktion mit Rückgabetyp muss auf jedem Pfad einen Wert zurückgeben.

export function hurt(self: ElementRef, amount: number): number {
  ledger.add(self, "hp", 0 - amount);
}

a non-void function must return a value on every reachable path

Weitere Fehler, die die Prüfung findet

Jede Zeile zitiert einen Teil einer Meldung und sagt, was du stattdessen schreibst.

Host-Aufrufe

Regeln erreichen Fabled über Host-Aufrufe. Du schreibst sie so, wie sie sind, zum Beispiel ledger.add(...). Du importierst sie nie.

In diesen Signaturen ist HostValue jeder Wert, den ein Host-Aufruf zurückgeben kann. Caste ihn also mit as, bevor du ihn nutzt. AbiValue ist eine Zahl, ein Text, ein Boolean oder null, oder eine Liste oder ein Record davon. Ein optionaler Parameter sticky ist für Fabled selbst, also lass ihn weg.

element.var(ref: ElementRef, name: HostValue, sticky?: AbiValue): HostValue;
ledger.set(ref: ElementRef, key: string, value: AbiValue): void;
ledger.add(ref: ElementRef, key: string, value: number): void;
math.floor(x: number): number;
math.ceil(x: number): number;
math.round(x: number): number;
math.max(...values: number[]): number;
math.min(...values: number[]): number;
math.abs(x: number): number;
math.pow(base: number, exponent: number): number;
math.sqrt(x: number): number;
list.add(ref: ElementRef, key: string, item: ContentRef, offer: ContentOffer): void;
list.remove(ref: ElementRef, key: string, item: ContentRef): void;
list.count(ref: ElementRef, key: string): number;
offer.where(where: ContentWhere, opts?: { maxItems?: number; flag?: { by: string; map: Record<string, string> } }): ContentOffer;

Ein Listen-Aufruf nennt eine Liste des Frameworks mit einem literalen Schlüssel, und der Eintrag ist ein ContentRef, eine Eingabe, die den vom Spieler gewählten Eintrag hält. Ein Angebot nimmt nur literale Bedingungen, zum Beispiel offer.where({ weight: { lte: 3 } }). Jedes Feld nimmt eq, ne, gte, lte, in oder has. Ein Angebot kann das Element nicht lesen. Wenn es von einem Wert des Charakters abhängen soll, prüfe ihn mit if vor list.add.

export function pack_trinket(self: ElementRef, trinket: ContentRef): void {
  if (list.count(self, "pack") < 2) {
    list.add(self, "pack", trinket, offer.where({ weight: { lte: 3 } }));
  }
}

export function unpack_trinket(self: ElementRef, trinket: ContentRef): void {
  list.remove(self, "pack", trinket);
}

Feldnamen werden ausgeschrieben

In einer Aktion muss der Name eines Feldes ein im Code ausgeschriebener Text sein, zum Beispiel "hp". Er kann nicht aus einem Wert kommen. Eine Regel wie diese schlägt fehl:

export function hurt(self: ElementRef, skill: string): void {
  const value: number = element.var(self, skill) as number;
  ledger.set(self, "hp", value);
}

Action accesses require literal keys on self.

Ohne Feldliste kann eine Aktion also nicht jeden Skill nach Namen prüfen. Schreibe für jeden Skill eine eigene Aktion, und lass jede ihr eigenes Feld lesen. Das Rezept Gegen einen Skill würfeln zeigt eine kurze Aktion zum Kopieren. Die Ausnahme ist eine Eingabe, die ihre Felder auflistet. Gib der Aktionseingabe eine Liste "fields", etwa ["lore", "library_use"], dann darf die Aktion diese Eingabe als Namen übergeben, wie in ledger.add(self, skill, amount). Die Prüfung behandelt die Aktion so, als berühre sie jedes aufgelistete Feld, und der Server akzeptiert nur einen Schreibzugriff auf das Feld, das der Spieler gewählt hat.

Diese Aktion erhöht die Fertigkeit, die der Spieler wählt:

    {
      "id": "improve",
      "name": "Improve a skill",
      "source": "rules/improve.ts",
      "inputs": {
        "skill": { "label": "Skill", "fields": ["lore", "library_use"] }
      }
    }

export function improve(self: ElementRef, skill: string): void {
  ledger.add(self, skill, 1);
}

Jeder Name in fields muss ein gespeichertes Feld des Frameworks sein, das eine Aktion schreiben darf. Ein von einer Ledger-Funktion abgeleitetes Feld oder ein Modifikator wird abgelehnt. Hat ein Feld eine gleichnamige Schema-Eingabe mit label, zeigt der Dialog diese Beschriftung; andernfalls zeigt er die Feld-ID, etwa library_use. Beispielsweise kann inputs.library_use.label die Auswahl Bibliotheksnutzung nennen. Der ausgewählte Wert, Szenario-Parameter und Log-Platzhalter wie {skill} verwenden weiterhin die Feld-ID. Jede native Textauswahlliste, deren Werte alle schreibbare skalare Felder benennen, verwendet dieselben Beschriftungen.

fields "skill_total" is not a writable state field

Nur deklarierte Felder

Eine Aktion darf nur Felder schreiben, die der Konstruktor zurückgibt. Die Prüfung nennt das Feld, das sie nicht findet.

Action "keeper.heal" calls ledger.set(self, "mana", ...), and "mana" is not declared on this schema. Declared scalar fields: hp, max_hp, name.

Weiter