How DZML works
DZML is a way to write a DayZ menu as an HTML page. The game does not read HTML: it reads
.layout files, a text format that lists widgets with their position, size and properties.
DZML is the same information written as HTML, which is easier to read, to write by hand, to
diff, and to ask an assistant for. The Workbench compiles the page to the .layout the game
loads, and can turn any existing .layout back into DZML.
You do not have to use it. The Layout Editor opens and edits plain .layout
files too. DZML is the recommended way to start a new UI.
The idea in one example
<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>
- An element with
data-dzis one widget:frame,panel,text,button,image,scroll,grid,wrap,editbox,checkbox,slider,progressand the others the game has. An element withoutdata-dzis skipped with everything inside it. data-nameis the widget's name: the one your script looks up withFindAnyWidget. Name every widget your script touches.dz-*classes are the layout properties.dz-xy-X-Yis the position,dz-wh-W-Hthe size,dz-align-ccthe anchor (centre / centre),dz-c-RRGGBBAAthe colour,dz-font-28the font.- A value with
pxis in pixels; a bare number is a percentage of the parent (dz-wh-50-100is half the width, full height).dz-wh-fullfills the parent. - Nested elements are child widgets.
- CSS,
style=,idand the tag name change nothing in the game. They only serve the preview in a browser.
From the page to the game
- You write
MyMod/gui/layouts/my_menu.html. - The Workbench checks it (unknown widgets, duplicate names, missing sizes, fonts and images that do not exist) and shows the problems with their line.
- It compiles it to
my_menu.layoutnext to the page. Both files go in the mod; the game loads the.layout. - It renders the layout the way the game draws it, at several screen resolutions, with the game's own fonts, styles and images. Text that overflows, widgets off screen or on top of each other are reported.
- For a vanilla page, it can write the menu script: a class with one field per named widget,
the event dispatch, and an empty method for each
data-on-click="Method".
In the Layout Editor these are the canvas, the problems list, Save, Preview and the Script tab. The canvas and the HTML stay in step: move a widget on the canvas and only its opening tag changes in the page; your formatting and comments are kept.
Take the DZML tour (in the app) · Start a new DZML page (in the app)
Two kinds of pages
Vanilla pages (the default)
<body data-dzml="vanilla"> is a page for a normal mod, with no dependency.
data-on-click="Method"(alsochange,select,focus,focuslost) on a named widget: the generated script callsMethod()when it happens.data-on-click="Close"closes the menu.data-rowon a named element inside a named widget makes it a row template: it becomes its own small.layout, and the script getsAdd<Row>()andClear<Row>s()to fill a list. Keep one sample row in the page so the preview shows it.- You fill the widgets from your script (
SetText,LoadImageFile...), as in any DayZ menu.
DayZular pages
DayZular is a UI framework mod for DayZ: instead of filling widgets by hand, the page binds
them to data. DZML was first made for it, which is why the binding attributes look like a web
framework's. In a page without data-dzml="vanilla":
data-bind="{{ expression }}"binds a text, an image, a progress bar or an edit box to a value;data-foreachrepeats a template for each item of a list;data-on-clickand the other events call a method of the page's view model;data-componentanddata-nav-targetcompose pages and navigate between them;data-dz="dropdown"is a ready-made dropdown.
These compile to script classes that only exist in the DayZular mod, so a DayZular page needs
that mod on the server and the clients. In a vanilla page they are reported as errors
(dayzular-only). If you do not know which one you need, you need a vanilla page.
Converting an existing layout
Open any .layout (yours or the game's) and choose To DZML: the Workbench writes the
equivalent .html next to it. Every vanilla layout survives the round trip unchanged, so this
is also the quickest way to learn: open a menu of the game and read it as HTML.
Open the game's main menu (in the app)
Positions and sizes, the part that surprises
- The position is measured from the anchor. With
dz-align-br(bottom right),dz-xy-24px-24pxmeans 24 pixels from the right and bottom edges. To centre, usedz-xy-0-0 dz-align-cc. - A widget without
dz-wh-*has no size: it is 0 by 0 and invisible. The check warns. - Pixel sizes do not follow the screen resolution unless the widget has
data-prop-scaled="1"(the size is then the one at 1080 pixels high). Percentages always follow. - Children of a
gridorwrapignore their own position: the container places them. - Text height follows the widget's height unless
dz-exact-textis set; multi-line text wantsdz-wrap dz-exact-text.
Styles and images
data-style="Name"uses a widget style: one of the game's, or one of yours from a.stylesfile made in the Style Studio.dz-c-*tints the style. A panel with a colour and no style gets a flat colour; a coloured button wantsdata-style="Colorable".data-image="set:NAME image:ICON"shows an icon of an imageset; a path shows a texture.- Your own
.stylesand imagesets must be declared in the mod'sconfig.cpp(CfgMods,widgetStylesandimageSets), or the game does not load them.
Pitfalls
- Wrapping widgets in a plain
<div>withoutdata-dz: the whole subtree is left out. - Two widgets with the same
data-name: the script would find only one. It is an error. <p>,<img>,<input>and<select>cannot hold child widgets (HTML parsing rules): use<div>for containers.- Shipping only the
.html: the game needs the compiled.layoutin the PBO. - Editing the
.layoutby hand after compiling: the next compile overwrites it. Edit the page.
For agents
dzml_check {path}: diagnostics with line and column.layout_render {path}: compiles the page and returns one PNG per resolution with findings, each with thehtml_lineof its element.dzml_compile {path, output?, dry_run?},dzml_decompile {path, output?, dry_run?, overwrite?}.dzml_scaffold {path, key?}: the.layout, the row layouts, the menu script and optionally a key binding that opens the menu.layout_inspect,layout_widget_classes,layout_validatework on plain.layouttext.- The assistant's
ui-layoutskill holds the complete reference (every class, every attribute, every diagnostic). - Files:
<page>.html(source),<page>.layoutand<page>_<row>.layout(compiled),Scripts/5_Mission/<Mod>/<Class>.c(generated once, then yours).
See also
Layout Editor · Style Studio · Script Editor · Getting started