Schémas de Framework

Un fichier de Framework

Chaque fichier de schemas/ déclare un Framework. Les pages de référence font évoluer le Keeper du démarrage rapide. Il a maintenant un choix de Calling, une valeur dérivée Guard, un préréglage prêt à l'emploi, une section et un Lamp enfant.

manifest/project.json
schemas/keeper.json
schemas/lamp.json
rules/keeper.ts
rules/lamp.ts
rules/hurt.ts
rules/heal.ts
rules/guard.ts
layouts/keeper.json
layouts/lamp.json
scenarios/new-keeper.json
scenarios/heal.json
scenarios/new-lamp.json

Champs principaux

Dans un JEU, le Framework d'entrée du manifeste doit être un personnage jouable.

The entry framework must be a character constructor.

Entrées

Une entrée personnalise un paramètre du constructeur, et sa clé doit correspondre au nom du paramètre. La plupart des entrées n'ont besoin que d'un label. Les autres clés limitent ce qu'un joueur peut saisir.

  "inputs": {
    "name": { "label": "Name" },
    "max_hp": {
      "label": "Maximum HP",
      "description": "How much damage a Keeper can take.",
      "defaultValue": 10,
      "min": 1,
      "max": 40
    },
    "calling": {
      "label": "Calling",
      "options": ["Guard", "Scout"],
      "defaultValue": "Guard"
    },
    "lamp": { "label": "Lamp", "defaultValue": "lamp", "hidden": true }
  },

{
  "id": "keeper",
  "name": "Keeper",
  "elementType": "character",
  "constructor": "rules/keeper.ts",
  "inputs": {
    "name": { "label": "Name" },
    "max_hp": {
      "label": "Maximum HP",
      "description": "How much damage a Keeper can take.",
      "defaultValue": 10,
      "min": 1,
      "max": 40
    },
    "calling": {
      "label": "Calling",
      "options": ["Guard", "Scout"],
      "defaultValue": "Guard"
    },
    "lamp": { "label": "Lamp", "defaultValue": "lamp", "hidden": true }
  },
  "childFrameworks": { "lamp": "lamp" },
  "sections": [
    {
      "id": "basics",
      "title": "Basics",
      "inputs": ["name", "max_hp", "calling", "lamp"]
    }
  ],
  "actions": [
    { "id": "hurt", "name": "Take damage", "source": "rules/hurt.ts" },
    { "id": "heal", "name": "Heal", "source": "rules/heal.ts" }
  ],
  "ledgerFunctions": [
    {
      "id": "guard",
      "name": "Guard",
      "field": "guard",
      "source": "rules/guard.ts"
    }
  ],
  "frames": [
    { "id": "sheet", "source": "layouts/keeper.json", "default": true }
  ],
  "content": [
    {
      "id": "mira-scout",
      "name": "Mira the Scout",
      "parameters": {
        "name": "Mira",
        "max_hp": 8,
        "calling": "Scout",
        "lamp": "lamp"
      }
    }
  ]
}

Une valeur par défaut qui n'est pas l'une des options est refusée.

{
  "calling": {
    "label": "Calling",
    "options": ["Guard", "Scout"],
    "defaultValue": "Mage"
  }
}

Default for calling must be one of its options ("Guard", "Scout").

Les scénarios et les préréglages doivent aussi respecter les bornes.

Parameter max_hp 99 is not between 1 and 40.

Une entrée cachée sans valeur par défaut échoue avec :

Input name is hidden, so it must declare a defaultValue.

Actions et fonctions de registre

Chaque action a un id, un nom et un fichier source. Chaque fonction de registre a les mêmes, plus un champ. Le champ est la valeur stockée que la fonction dérive, et ce doit être un champ scalaire que le constructeur retourne. Une fonction de registre lit des valeurs et retourne la valeur dérivée. Elle n'écrit jamais.

  "ledgerFunctions": [
    {
      "id": "guard",
      "name": "Guard",
      "field": "guard",
      "source": "rules/guard.ts"
    }
  ],

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);
}

Ledger function must target an existing scalar field.

Les ids doivent être uniques dans un Framework. Les actions et les fonctions de registre partagent un seul ensemble d'ids.

Duplicate semantic identity or source path.

Deux fonctions de registre peuvent partager un fichier source. Une action et une fonction de registre ne le peuvent pas :

action source does not match its owner contract

Entrées d'action

Les entrées d'une action sont les paramètres de sa fonction. La signature les déclare, et le schéma peut ajouter une entrée pour chacune. Chaque entrée est un nombre, un texte ou une valeur vrai/faux.

Le joueur se voit demander chaque entrée dans une boîte de dialogue quand il utilise le bouton. La boîte de dialogue nomme une entrée par le nom de son paramètre, sauf si l'entrée lui donne un libellé. Une entrée peut aussi donner une description et une valeur par défaut. Une entrée numérique peut avoir un minimum et un maximum. Une entrée de texte peut avoir une liste d'options ou des options issues d'une table. La boîte de dialogue affiche le tout, et le serveur refuse une valeur hors des bornes ou des options. Un bouton ne peut pas fournir de valeur. Nommez chaque paramètre pour qu'un joueur puisse le lire : roll, pas r.

    {
      "id": "check_lore",
      "name": "Lore check",
      "source": "rules/check-lore.ts",
      "inputs": { "roll": { "label": "Roll", "min": 1, "max": 100 } }
    }

Un minimum et un maximum n'empêchent pas un nombre à décimales. Si la règle a besoin d'un entier, elle le vérifie elle-même, et une étape de scénario le prouve. Une étape de scénario hors des bornes est refusée.

export function check_lore(self: ElementRef, roll: number): void {
  if (math.floor(roll) === roll) {
    const lore: number = element.var(self, "lore") as number;
    ledger.set(self, "last_target", lore);
    ledger.set(self, "last_roll", roll);
  }
}

Une entrée de texte peut plutôt proposer une liste de choix tirée d'une table du livre de règles. La page Tables du livre de règles montre comment.

Une entrée de texte peut aussi choisir par son nom l'un des champs stockés du Framework, avec une liste fields. La page Écrire des règles montre une action qui l'utilise.

Une entrée numérique peut demander au serveur de la lancer. Ajoutez une clé roll avec une expression de dés, comme "roll": "1d100" ou "roll": "2d6+1". La boîte de dialogue affiche alors un bouton Lancer à la place d'un champ à saisir. Le serveur lance les dés et la boîte de dialogue affiche le total, que le joueur ne peut pas modifier. Seul un paramètre numérique peut être lancé. Le compilateur refuse un roll accompagné d'un defaultValue, et refuse une expression de dés que le serveur n'accepte pas.

Une entrée lancée n'est dépensée qu'une fois : l'action prend le jet quand elle s'exécute, et un nouveau jet annule les précédents non dépensés de cette entrée. Un jet est lié à sa campagne et expire au bout de 15 minutes. La page Dispositions et fiches montre ce que voit la table.

Ligne de journal d'une action

Une action peut publier une ligne de résultat dans le journal de la table. Ajoutez un modèle de journal à l'entrée de l'action dans le schéma, par exemple "log": "{name} takes {amount} damage, defense {defense}". Le serveur remplit chaque champ {name} en texte brut une fois l'action enregistrée. Un navigateur n'envoie jamais la ligne.

Un champ réservé peut nommer une entrée de l'action, ou un champ numérique, texte ou vrai/faux du même Framework. Le compilateur refuse une entrée masquée, un champ de santé (hp, current_hp, hit_points, temp_hp, current_health, max_health, hitPoints, ainsi que les champs de santé et d'état du bloc de combat), un nom qui n'existe pas, un modèle de plus de 200 caractères, plus de 16 champs réservés, une accolade isolée et un caractère de contrôle. Quand une entrée et un champ portent le même nom, l'entrée l'emporte. Les valeurs sont celles d'après l'action : un champ que l'action a écrit affiche donc sa nouvelle valeur. Un champ calculé n'est pas recalculé et affiche la valeur qu'il avait avant l'action.

Un joueur qui agit sur son propre personnage voit la ligne auprès du même public que ses jets de dés : tout le monde, lui seul, ou lui et les MJ. Dans tous les autres cas, y compris un MJ qui agit sur un personnage quelconque, la ligne n'atteint que les membres de la campagne qui peuvent lire ce personnage. Si le public est tout le monde mais qu'un membre ne peut pas lire le personnage, la ligne part en message privé aux membres qui le peuvent. La table affiche la ligne sous l'étiquette Jeu, pour que personne ne la prenne pour le message d'un joueur.

Préréglages de contenu

Un préréglage est un ensemble nommé de valeurs d'entrée, comme un personnage prêt à jouer. Fabled vérifie chaque préréglage comme un scénario : chaque valeur doit donc correspondre à son entrée. Un jeu peut contenir jusqu'à 512 préréglages par Framework.

  "content": [
    {
      "id": "mira-scout",
      "name": "Mira the Scout",
      "parameters": {
        "name": "Mira",
        "max_hp": 8,
        "calling": "Scout",
        "lamp": "lamp"
      }
    }
  ]

Sections

Les sections regroupent les entrées en étapes de l'assistant de création. Quand un Framework déclare des sections, chaque entrée doit figurer dans l'une d'elles, entrées cachées comprises.

  "sections": [
    {
      "id": "basics",
      "title": "Basics",
      "inputs": ["name", "max_hp", "calling", "lamp"]
    }
  ],

Input lamp is not assigned to any section.

Frameworks enfants

Un Framework enfant est une partie d'un Élément plus grand, comme le Lamp que porte un Keeper. L'enfant a son propre schéma, son constructeur, son Cadre et son scénario.

  "childFrameworks": { "lamp": "lamp" },

{
  "id": "lamp",
  "name": "Lamp",
  "elementType": "item",
  "constructor": "rules/lamp.ts",
  "inputs": {
    "name": { "label": "Name" },
    "oil": { "label": "Oil", "defaultValue": 5 }
  },
  "frames": [{ "id": "card", "source": "layouts/lamp.json", "default": true }]
}

Le parent associe un nom d'emplacement à un id de Framework dans childFrameworks. Une entrée cachée contient la référence. Le constructeur retourne les entrées de l'enfant à côté de ses propres valeurs.

export function construct(
  name: string,
  max_hp: number,
  calling: string,
  lamp: FrameworkRef,
): {
  values: { name: string; max_hp: number; hp: number; calling: string; guard: number };
  children: { lamp: { framework: FrameworkRef; params: { name: string; oil: number } } };
} {
  return {
    values: { name: name, max_hp: max_hp, hp: max_hp, calling: calling, guard: 0 },
    children: { lamp: { framework: lamp, params: { name: "Lantern", oil: 5 } } },
  };
}

Chaque Framework, enfants compris, doit retourner un nom.

must define the required 'name' value, normally as a string constructor field.

Un emplacement qui pointe vers un Framework hors du jeu échoue avec :

Invalid child Framework constraint: lamp.

Champs avancés

Suite