Layout Editor
The Layout Editor builds the screens of a mod: menus, HUD elements, dialogs. A screen of DayZ is a .layout file, a tree of widgets (frames, panels, texts, buttons, images) that a script creates and fills. Here you edit that tree on a canvas drawn with the game's own fonts, images and styles, or you write the screen in DZML, an HTML form that compiles to the .layout. You need nothing to start: the page opens on an empty layout. With the DayZ folder set in Settings, the game's own layouts open read-only as examples, and their images and styles are shown.
The screen
- Left pane, Files tab: the
.layoutand DZML files of the folders you opened and of your workspaces. A filter, a button to add a folder, a rescan. Click a file to open it in a tab; the grid icon of a folder shows thumbnails of every layout in it. - Left pane, Widgets tab (shown first), from top to bottom:
- Palette: the widget classes of the game. Click one to add it inside the selected widget, or drag it onto the canvas or the hierarchy.
- Prefabs: groups of widgets you saved for reuse. Select widgets and click the save icon to make one; click or drag a prefab to insert it.
- Hierarchy: the widget tree of the document. Click selects (Ctrl or Shift adds to the selection), double-click centres the canvas on the widget, drag moves a widget into another parent. The arrows of its header move the selection up, down, out of or into a neighbour. The eye hides a widget and the key locks it, in the editor only.
- Document tabs: one per open document; a dot marks unsaved edits. The + opens the list of new documents: DZML document, blank layout, menu template, HUD template.
- Toolbar: Open file, Browse game layouts, Save, Reload from disk, Save as, then To DZML (for a
.layout) or Compile and Bundle (for a DZML document), Undo, Redo, Play and Preview. A "Game file" badge marks a layout opened from the game. - View tabs (right of the toolbar): Design (the canvas), Source (the
.layouttext; named HTML for a DZML document) and Browser (DZML only: the saved page in the web view). - Canvas toolbar (Design view): screen resolution, zoom, Fit, 1:1, what is drawn behind the UI, Guides (snapping), Outlines, Hidden (also show widgets whose
visibleis off), Texts (translate#keysfrom stringtable.csv), the snap step, the console safe zone, and ? for the keyboard shortcuts. With several widgets selected, align and distribute buttons appear. - Canvas: the screen as the game draws it at the chosen resolution, with rulers. Click selects the top widget (Alt+click cycles through the ones under the cursor), drag moves, the edges resize, a drag on the empty area selects several. Click a ruler to add a guide, right-click to remove it.
- Right pane, Properties: the properties of the selected widget, grouped (Widget, Layout, Appearance, Text, Image, Navigation, Spacer, Control, Other). Position and size have a px / % switch per axis; the small x resets a property to its default.
- Right pane, Script: the Enforce Script class generated for this layout, as a menu (
UIScriptedMenu) or a widget handler (ScriptedWidgetEventHandler). Copy it, or write it into the mod of the layout. Below: the bindings of the selected subtree, and a search for where the widget names are used in your scripts. - Right pane, Problems: what would go wrong in the game, with a count on the tab. Click a problem to select its widget.
- Play (F5): the screen alone, with live buttons, checkboxes, edit boxes and scrolling, a resolution selector and a log of the events a script would receive. Esc leaves it.
First steps
- Open the Layout Editor. An empty layout named
untitled.layoutis ready, with one root frame. - In the palette, click Panel: a panel is added inside the root. Drag it on the canvas and resize it by its edges.
- With the panel selected, click Text in the palette: the text is added inside the panel. In Properties, set its
text. - Give both widgets a name in Properties (F2): scripts find widgets by name.
- Look at the Problems tab and fix what it lists.
- Press F5 to see the screen without the editor's marks, Esc to come back.
- Click Save (Ctrl+S) and write the file inside your mod, for example
MyMod/gui/layouts/my_panel.layout.
Take the tour (in the app)
Common tasks
Start a menu in DZML
- Click + in the tab bar and choose DZML document (HTML). A panel with a title and a Close button opens on its HTML.
- Edit the HTML; switch to Design to see and adjust the result.
- Save: the first time, you choose the name of the
.html, inside your mod. - Click Compile and accept the proposed
.layoutnext to the.html. A page with row templates also gets one<page>_<row>.layoutper template. - In the Script tab, keep the kind "Menu" and click Write to mod: the class is written under
scripts/5_Mission/<Mod>/GUI/(the path is editable; an existing file is replaced only after you confirm).
Study a layout of the game
- Click Browse game layouts (the magnifier) and type a part of the name, for example
inventory. - Click a result: it opens read-only in a tab, with the "Game file" badge.
- Tick Hidden to see the widgets that scripts show at run time; use Source to read the text.
- To keep a modified copy, click Save: it asks where to write it. The game file is never changed.
Check a screen at several resolutions
- In the canvas toolbar, choose another resolution (1280 × 720, 2560 × 1440, 3840 × 2160, an ultrawide and a portrait size are listed).
- Watch what moves: sizes in % follow the screen, sizes in pixels do not.
- Choose a safe zone (95, 90 or 85 %) to see where console screens may cut the picture.
- Play has the same resolution selector.
Convert an existing layout to DZML
- Open the
.layout. - Click To DZML and choose where to write the
.html(next to the layout by default). - The new document opens. Keep the
.layoutout of your edits from now on: it is produced by Compile.
Reuse a group of widgets
- Select the widgets (Ctrl+click, or drag a rectangle on the empty area).
- In the Widgets tab, click the save icon of Prefabs and name it.
- In any document, click the prefab to insert it into the selection, or drag it onto the canvas or the hierarchy.
Generate the script of a layout
- Save the layout inside a mod (a folder with a
$PBOPREFIX$or aconfig.cpp): the editor then knows the path the game will use. - Open the Script tab and choose the kind: a menu opened with
ShowScriptedMenu, or a handler for a sub-panel. - Copy the class, or click Write to mod, then Open in Scripts.
Examples
- The main menu of the game (in the app): a full screen. Look at the hierarchy and at the styles of its buttons and panels.
- The in-game HUD (in the app): the largest vanilla layout. Tick Hidden: many widgets only appear when a script shows them.
- The inventory screen (in the app): a frame with a few areas that scripts fill with other layouts.
- A simple dialog: logging out (in the app): a window, texts and buttons stacked by a grid spacer.
- A new menu in DZML (in the app): the DZML starter page, not saved anywhere.
Concepts
Two ways of working: the .layout or DZML
- The .layout directly. You edit the file the game loads. Design and Source show the same document: an edit in one is in the other. Choose it to adjust an existing layout or to stay close to what Bohemia's own tools produce.
- DZML. You edit an
.htmlfile in which each element markeddata-dzis a widget anddz-*classes are its properties. The HTML is the source: the canvas shows what it compiles to, and a visual edit is written back as the smallest change of the HTML. Before shipping, Compile writes the.layout. Choose it for a new UI: the text is easier to read, to review and to let the assistant write. See How DZML works.
A .layout becomes DZML with To DZML; a DZML page becomes a .layout with Compile. Take the DZML tour (in the app)
Notions of the game
- .layout: a text file describing a tree of widgets: each has a class (
TextWidgetClass), a name and properties (position,size,color,text...). A script loads it withCreateWidgets("MyMod/gui/layouts/x.layout"). - Position and size: per axis, a value is in pixels (
hexactpos,vexactpos,hexactsize,vexactsizeset to 1) or a fraction of the parent (0).halignandvalignchoose the edge or the centre the position is measured from. - Spacers:
GridSpacerWidgetandWrapSpacerWidgetplace their children themselves; a child's own position is ignored. Reorder children in the hierarchy instead of dragging them. - Names: scripts get a widget with
FindAnyWidget("Name"). Two widgets with the same name: the first one is returned. The Problems tab reports duplicates. - Styles and imagesets: a
styleis a named look defined in a.stylesfile; an image is writtenset:NAME image:IMG, a piece of an.imagesetatlas. Both must be loaded by the game: the vanilla ones are, those of a mod must be listed in itsconfig.cpp. See Style Studio. - Texts: a text starting with
#is a key ofstringtable.csv, translated by the game. The Texts checkbox shows the translation. - Menu or handler: a
UIScriptedMenuis a whole screen that takes the input and shows the cursor; aScriptedWidgetEventHandlerreceives the events of a panel inside another screen. Menus go in5_Mission. - Safe zone: the part of the screen consoles guarantee to show. Widgets with
keepsafezoneare moved inside it.
Reference: the Bohemia Interactive community wiki (DayZ Workbench, GUI editor) and docs/FORMATS.md of this project.
Pitfalls
- A style or an image shows here but not in the game: its
.stylesor.imagesetis not listed in the mod'sconfig.cpp. The Problems tab says which file. - A missing texture: the Problems tab lists images and textures found neither in the game nor in your workspaces. Textures are referenced by their in-game path (prefix of the addon + relative path).
- Dragging does nothing inside a spacer: the status bar says the parent controls the position. Reorder in the hierarchy.
- A widget of size 0, or entirely clipped by its parent is invisible: both are reported as problems.
- Editing the generated children of a DZML dropdown: they come from a macro; the inspector says so and the edit must be made in the HTML.
- Editing the compiled .layout of a DZML page: the next Compile replaces it. Edit the
.html. - The file changed on disk (the assistant, another editor, git): a tab without edits takes the new version, the old one stays one undo away; a tab with edits shows a banner to choose.
- Hide and lock of the hierarchy are editor states: they are not saved and change nothing in the game.
- The Browser tab runs the page sandboxed: its scripts run, but they cannot read files of the Workbench or of your disk, nor its settings. Files outside the page's folder, the workspaces and the game are not served to it.
For agents
Tools of dzt that do the same work without the window:
layout_inspect: parse a.layout(disk path or game virtual path): diagnostics and the widget tree with computed rectangles at 1920x1080.layout_widget_classes: the widget classes and every property with type, default and options. Read it before writing a layout by hand.layout_validate: syntax check of.layouttext, with the canonical formatting.layout_render: render a.layoutor a DZML.htmlto PNG as the game would show it, with findings.dzml_check: validate a DZML document (names, unknown widgets and classes, bindings, style references) with line and column.dzml_compile: DZML to.layout.dzml_decompile:.layoutto DZML.dzml_bundle: a page and its sub-pages in one.bundle.html.dzml_scaffold: for a DZML page in a mod, write the.layout, the row layouts and the menu script.ui_style_check: check that every style used by the layouts of a mod is loaded by the game.vfs_searchandvfs_read: find and read the game's own layouts (gui/layouts/...).
Files:
- Read:
.layout,.html/.dzml(an.htmlcounts as DZML when it containsdata-dzml), the game's layouts from its PBOs, and the.imageset,.styles, fonts andstringtable.csvof the game and the workspaces.dzml.config.yaml, searched upward from a DZML file, gives font aliases. - Written: the document on Save / Save as (
.layouttext, or the.htmlof a DZML page); the.layoutand row layouts on Compile; a.bundle.htmlon Bundle; an.htmlon To DZML; prefabs as.layoutfiles in theprefabsfolder of the Workbench's settings folder; the generated.con Write to mod. Game files are never written.
What the page tells the assistant: the open file (or untitled.layout), the selected widget as name (class), the view (design, source or browser preview), the canvas resolution, whether there are unsaved edits, and the messages of the Problems tab. It proposes one action to the assistant, "Check this layout".
Anchors for tours and pointing are listed in the page's guide file (layout-palette, layout-hierarchy, layout-canvas, layout-inspector, layout-save, layout-play...).
See also
- How DZML works
- Style Studio: styles, imagesets and icons for your widgets.
- Script Editor: the class that opens the layout.
- Textures (PAA): the images a layout references.
- PBO Packer: pack the mod with its layouts.