Utilisation
tilttek/dice-skinsLes skins
Un Skin a une clé, un libellé, le SkinLook de ses dés et, pour certains types de dés, un aspect propre par nombre
de faces. Un aspect est la couleur des faces, la couleur des chiffres et des points — l'encre —, un Material et,
s'il y en a une, une TextureReference.
La bibliothèque fournit huit skins de base, BaseSkins::all() : ivory — le skin par défaut —, obsidian, crimson,
forest, ocean, amethyst, gold et high-contrast. Un site ajoute les siens à partir de JSON, comme les écrit
Skin::toArray() :
[
{"key": "ember", "label": "Ember", "face": "#9b1b30", "ink": "#ffffff", "material": "pearl",
"texture": "pearl/soft", "types": {"20": {"face": "#1b1b1f", "ink": "#f5f5f5"}}}
]
$catalog = FixedSkinCatalog::withBase($json); // the base skins, then the site's
$catalog = new FixedSkinCatalog(SkinDefinitions::fromJson($json)); // the site's only
L'aspect d'un type reprend de l'aspect du skin ce qu'il ne dit pas. Une couleur s'écrit #rgb ou #rrggbb ; une
matière est l'une de solid, translucent, pearl, glitter, marble, metal, wood, stone et gem ; une
texture est une clé que le moteur de rendu résout en une image qui lui est propre, jamais une adresse.
SkinDefinitions refuse, avec InvalidSkin, un champ qu'il ne connaît pas, une valeur du mauvais type, deux skins de
même clé, un aspect dont les chiffres ressortent à moins de 4,5:1, plus de 256 skins ou de 32 types par skin, et un
texte de plus de 256 Kio ou de plus de 8 niveaux de profondeur.
Les choix
$skins->choose($member, 'ember'); // for all the member's dice
$skins->choose($member, 'gold', 20); // for their d20
$skins->choices($member); // the one for all their dice first, then by number of sides
$skins->clear($member, 20); // back to the skin for all their dice
$skins->eraseMember($member); // every choice forgotten
choose() refuse avec SkinRefused un skin que le catalogue n'offre pas, et avec InvalidSkin un nombre de faces
hors de 2 à 1000. Un skin que le site cesse d'offrir est écarté : les dés du membre retombent sur le choix suivant.
Les dés possédés
Un membre qui possède des dés dans tilttek/collections en choisit un pour son nombre de faces sur son étagère, avec
DiceShelf::choose(). DiceSkins::owned() liste les dés qu'il possède, par le port Contract\OwnedDice, pour la page
où il choisit. Un dé échangé n'est plus affiché : l'étagère ne le donne plus.
L'apparence d'un dé
appearance($member, $sides) donne le premier de ces choix :
- le dé d'un ensemble que le membre possède et a choisi pour ce nombre de faces — sa couleur, avec l'encre noire ou blanche qui ressort le plus, et la matière que nomme sa collection ; un dé dont la collection ne donne pas de couleur prend l'aspect du niveau suivant, avec son propre nom ;
- le skin que le membre a choisi pour ce nombre de faces ;
- le skin que le membre a choisi pour tous ses dés ;
- le skin par défaut du site, que le catalogue doit offrir.
Le DieAppearance indique d'où il vient, $source, et donne au moteur de rendu :
| Méthode | Donne |
|---|---|
cssProperties() | --tilttek-dice-color pour les faces et --tilttek-dice-ink pour les chiffres |
style() | les mêmes, comme valeur d'un attribut style |
dataAttributes() | data-dice-appearance, data-dice-sides, data-dice-material, ainsi que data-dice-texture et data-dice-contrast="high" quand ils s'appliquent |
toArray() | tout en valeurs simples, ratio de contraste compris, pour un moteur de rendu qui lit du JSON |
Dans Twig, les attributs passent par html_attr, qui les échappe, le nom du skin compris :
<span class="die" style="{{ appearance.style }}" {{ html_attr(appearance.dataAttributes) }}>{{ face }}</span>
Un contrôleur Stimulus qui dessine les dés lit les mêmes valeurs ; la bibliothèque ne fournit aucun script.