Comment fonctionne DZML
DZML est une manière d'écrire un menu DayZ comme une page HTML. Le jeu ne lit pas le HTML : il lit des
fichiers .layout, un format texte qui liste des widgets avec leur position, leur taille et leurs propriétés.
DZML contient les mêmes informations écrites en HTML, ce qui est plus facile à lire, à écrire à la main, à comparer
avec un diff, et à demander à un assistant. Le Workbench compile la page en le .layout que le jeu
charge, et peut reconvertir n'importe quel .layout existant en DZML.
Vous n'êtes pas obligé de l'utiliser. L'Éditeur de layouts ouvre et modifie aussi les fichiers
.layout bruts. DZML est la manière recommandée de démarrer une nouvelle UI.
L'idée en un exemple
<body data-dzml="vanilla">
<div data-dz="frame" data-name="Root" class="dz-xy-0-0 dz-wh-full">
<div data-dz="panel" data-name="Window" class="dz-wh-500px-260px dz-align-cc dz-c-1C1C1CF0">
<span data-dz="text" data-name="Title" class="dz-xy-0-16px dz-wh-460px-36px dz-align-tc dz-font-28 dz-exact-text">Warning</span>
<button data-dz="button" data-name="CloseButton" data-on-click="Close" data-style="Colorable"
class="dz-xy-0-20px dz-wh-160px-40px dz-align-bc dz-c-B03030FF">Close</button>
</div>
</div>
</body>
- Un élément avec
data-dzest un widget :frame,panel,text,button,image,scroll,grid,wrap,editbox,checkbox,slider,progresset les autres que possède le jeu. Un élément sansdata-dzest ignoré avec tout ce qu'il contient. data-nameest le nom du widget : celui que votre script cherche avecFindAnyWidget. Nommez chaque widget que votre script touche.- Les classes
dz-*sont les propriétés de layout.dz-xy-X-Yest la position,dz-wh-W-Hla taille,dz-align-ccl'ancrage (centre / centre),dz-c-RRGGBBAAla couleur,dz-font-28la police. - Une valeur avec
pxest en pixels ; un nombre seul est un pourcentage du parent (dz-wh-50-100donne la moitié de la largeur, toute la hauteur).dz-wh-fullremplit le parent. - Les éléments imbriqués sont des widgets enfants.
- Le CSS,
style=,idet le nom de la balise ne changent rien dans le jeu. Ils ne servent qu'à l'aperçu dans un navigateur.
De la page au jeu
- Vous écrivez
MyMod/gui/layouts/my_menu.html. - Le Workbench la vérifie (widgets inconnus, noms en double, tailles manquantes, polices et images qui n'existent pas) et montre les problèmes avec leur ligne.
- Il la compile en
my_menu.layoutà côté de la page. Les deux fichiers vont dans le mod ; le jeu charge le.layout. - Il rend le layout comme le jeu le dessine, à plusieurs résolutions d'écran, avec les polices, styles et images du jeu. Le texte qui déborde, les widgets hors écran ou superposés sont signalés.
- Pour une page vanilla, il peut écrire le script du menu : une classe avec un champ par widget nommé,
la distribution des événements, et une méthode vide pour chaque
data-on-click="Method".
Dans l'Éditeur de layouts, cela correspond au canevas, à la liste des problèmes, à Enregistrer, à Aperçu et à l'onglet Script. Le canevas et le HTML restent synchronisés : déplacez un widget sur le canevas et seule sa balise ouvrante change dans la page ; votre mise en forme et vos commentaires sont conservés.
Faire la visite de DZML (dans l'app) · Démarrer une nouvelle page DZML (dans l'app)
Deux sortes de pages
Pages vanilla (par défaut)
<body data-dzml="vanilla"> est une page pour un mod ordinaire, sans dépendance.
data-on-click="Method"(aussichange,select,focus,focuslost) sur un widget nommé : le script généré appelleMethod()quand l'événement se produit.data-on-click="Close"ferme le menu.data-rowsur un élément nommé à l'intérieur d'un widget nommé en fait un modèle de ligne : il devient son propre petit.layout, et le script obtientAdd<Row>()etClear<Row>s()pour remplir une liste. Gardez une ligne d'exemple dans la page pour que l'aperçu la montre.- Vous remplissez les widgets depuis votre script (
SetText,LoadImageFile...), comme dans n'importe quel menu DayZ.
Pages DayZular
DayZular est un mod de framework d'UI pour DayZ : au lieu de remplir les widgets à la main, la page les lie
à des données. DZML a d'abord été conçu pour lui, ce qui explique que les attributs de liaison ressemblent à ceux d'un framework
web. Dans une page sans data-dzml="vanilla" :
data-bind="{{ expression }}"lie un texte, une image, une barre de progression ou un champ de saisie à une valeur ;data-foreachrépète un modèle pour chaque élément d'une liste ;data-on-clicket les autres événements appellent une méthode du view model de la page ;data-componentetdata-nav-targetcomposent des pages et naviguent entre elles ;data-dz="dropdown"est une liste déroulante toute prête.
Ces éléments se compilent en classes de script qui n'existent que dans le mod DayZular, donc une page DayZular a besoin de
ce mod sur le serveur et chez les clients. Dans une page vanilla, ils sont signalés comme des erreurs
(dayzular-only). Si vous ne savez pas lequel il vous faut, il vous faut une page vanilla.
Convertir un layout existant
Ouvrez n'importe quel .layout (le vôtre ou celui du jeu) et choisissez Vers DZML : le Workbench écrit le
.html équivalent à côté. Tout layout vanilla survit à l'aller-retour sans changement, donc c'est aussi
le moyen le plus rapide d'apprendre : ouvrez un menu du jeu et lisez-le en HTML.
Ouvrir le menu principal du jeu (dans l'app)
Positions et tailles, ce qui surprend
- La position se mesure à partir de l'ancrage. Avec
dz-align-br(en bas à droite),dz-xy-24px-24pxsignifie 24 pixels depuis les bords droit et bas. Pour centrer, utilisezdz-xy-0-0 dz-align-cc. - Un widget sans
dz-wh-*n'a pas de taille : il fait 0 sur 0 et il est invisible. La vérification avertit. - Les tailles en pixels ne suivent pas la résolution de l'écran, sauf si le widget a
data-prop-scaled="1"(la taille est alors celle pour 1080 pixels de haut). Les pourcentages suivent toujours. - Les enfants d'un
gridou d'unwrapignorent leur propre position : c'est le conteneur qui les place. - La hauteur du texte suit la hauteur du widget sauf si
dz-exact-textest défini ; un texte sur plusieurs lignes veutdz-wrap dz-exact-text.
Styles et images
data-style="Name"utilise un style de widget : un de ceux du jeu, ou un des vôtres issu d'un fichier.stylescréé dans le Studio de styles.dz-c-*teinte le style. Un panneau avec une couleur et sans style obtient une couleur unie ; un bouton coloré veutdata-style="Colorable".data-image="set:NAME image:ICON"affiche une icône d'un imageset ; un chemin affiche une texture.- Vos propres
.styleset imagesets doivent être déclarés dans leconfig.cppdu mod (CfgMods,widgetStylesetimageSets), sinon le jeu ne les charge pas.
Pièges
- Envelopper des widgets dans un simple
<div>sansdata-dz: tout le sous-arbre est omis. - Deux widgets avec le même
data-name: le script n'en trouverait qu'un. C'est une erreur. <p>,<img>,<input>et<select>ne peuvent pas contenir de widgets enfants (règles d'analyse du HTML) : utilisez<div>pour les conteneurs.- Ne livrer que le
.html: le jeu a besoin du.layoutcompilé dans le PBO. - Modifier à la main le
.layoutaprès la compilation : la compilation suivante l'écrase. Modifiez la page.
Pour les agents
dzml_check {path}: diagnostics avec ligne et colonne.layout_render {path}: compile la page et renvoie un PNG par résolution avec les constats, chacun avec lehtml_linede son élément.dzml_compile {path, output?, dry_run?},dzml_decompile {path, output?, dry_run?, overwrite?}.dzml_scaffold {path, key?}: le.layout, les layouts de lignes, le script du menu et éventuellement une liaison de touche qui ouvre le menu.layout_inspect,layout_widget_classes,layout_validatetravaillent sur du texte.layoutbrut.- Le skill
ui-layoutde l'assistant contient la référence complète (chaque classe, chaque attribut, chaque diagnostic). - Fichiers :
<page>.html(source),<page>.layoutet<page>_<row>.layout(compilés),Scripts/5_Mission/<Mod>/<Class>.c(généré une fois, puis à vous).
Voir aussi
Éditeur de layouts · Studio de styles · Éditeur de scripts · Premiers pas