DreamGUI
Tools

DreamMCP endpoint

The HTTP endpoint a DreamMCP server reaches DreamGUI through — check, compile, layout, preview, diagnostics, lookup and info for .dui screens, in the user's editor or in a host the server starts — with what layout lists, the layout rules and their thresholds, and what preview measures.

An AI agent connected through DreamMCP gets a dream_gui tool. Through it the agent checks and compiles .dui files, sees where every node of a screen lands at a viewport size and the problems a person would see at a glance (layout), draws the screen into a picture (preview), reads diagnostics and looks up the names the compiler accepts. The calls are answered by the user's editor when it is open, and by a host process the server starts when it is not.

The endpoint adds no compiler of its own: every action forwards to what the plugin already does — the parser and tree builder, the widget Blueprint compiler, the diagnostics mailbox, the symbol export the VS Code extension reads, and the designer's way of instancing a screen. What it adds is one answer shape for all of them, and the two things a model that writes .dui cannot otherwise see: the laid-out screen, in words, and the picture.

Kindeditor service, in the DreamGUIEditor module (Source/DreamGUIEditor/Private/MCP/)
ProtocolDreamMCP protocol 1
Manifest<Plugin>/Resources/DreamMCP.json: the actions, their arguments as JSON Schema, the route, the host commandlet
References.skill/reference/dui.md, example.md, presets.md, blocks.md, screens.md, pitfalls.md, controls.md, diagnostics.md, named by the manifest and packaged with the plugin. Each stands alone: its links lead to this manual, and an agent that cannot open them misses nothing it needs
Routehttp://127.0.0.1:<port>/dream/gui, tool name dream_gui
Port47800, or -DreamMCPPort=<n>; a port that cannot be bound is skipped for the next, up to 16. Other Dream plugins in the same process share it, each under its own route
Bind address127.0.0.1 only, proven at startup
Authenticationthe X-Dream-Token header on every request; the token is DREAM_MCP_TOKEN from the environment, else -DreamMCPToken=<t>, else random. A request with an Origin header is refused (403)
Discovery<Project>/Saved/DreamMCP/gui.json, written once the endpoint answers a hello (its own, or the first one a server sends, before that one is answered), deleted when it stops if it still names this process
Hoststhe editor with -DreamMCPHost -RenderOffscreen (draws); -run=DreamGUIHost -nullrhi -DreamMCPHost (does not draw, still lays out)
Switched off by-NoDreamMCP; in the user's editor also Project Settings ▸ Plugins ▸ Dream GUI ▸ Editor ▸ Enable DreamMCP Endpoint (on by default, read at startup)

Which process serves it

ProcessEndpointmodeDraws
The user's editoryes, once the engine has initializededitoryes
A render host: the editor with -DreamMCPHost -RenderOffscreen, no -run=yeshostyes
A headless host: -run=DreamGUIHost -nullrhi -DreamMCPHost, or another Dream plugin's host commandletyeshostno
Any other commandlet (-run=DreamUICompileWidgets, a cook), an automation run, a gameno——

A host is nobody's editor: it writes no editor settings, does not auto-save, renders no realtime viewport, caps its frame rate at 15 while no Dream endpoint in the process has a job (the console variable DreamMCP.BusyEndpoints, which every Dream plugin's endpoint counts itself in and out of, is 0), accepts POST /dream/gui/shutdown, exits when the process that started it goes away (-DreamMCPParentPid=<pid>, 0 for none) and exits with code 3 when it cannot start answering within -DreamMCPStartupTimeout seconds (600 by default). In the user's editor /shutdown is refused (409, not-a-host).

Where things are written: a compile in the user's editor leaves the widget Blueprints in memory for the user to save, as saving a .dui does; a compile in a host saves them. Pictures go to <Project>/Saved/DreamMCP/artifacts/<job>.png.

Actions

ActionLongWritesArgumentsAnswers
checkyesnofile, or all: trueparses the file and builds its tree the way the compiler does, into a tree that is thrown away. Reports lexer, parser, meaning, value and builder errors (DUI1xxx–5xxx); what only a compile sees (props, events, view models, expression bindings: DUI6xxx) needs compile. A component the file places that has not been compiled yet is no error of the source: its DUI5018 is an info, the summary names it, and next says to run layout or compile, which compile it first
compileyesyesfile, forcebuilds the widget Blueprint the file's class line names, creating it when it does not exist, and first every component the file places with use "X.dui" as X. Nothing that has not changed since this process last compiled it is compiled again unless force
diagnosticsnonofilewhat the engine holds from the last check or compile of each file, errors first, without compiling
lookupnononame, kind, limitan exact node type, component, enum or view model class gives its entry (properties with type, default and a one-line description from the C++ source, events), one a line in the answer's text; Type.Property narrows to properties starting so (with kind: "property" too); otherwise every name containing the text. Widget lists what every node takes, slot what @slot takes, and Widget.RenderRotation, slot.HorizontalAlignment narrow them. The anchors and the render transform say their axes (Y up, X depth)
layoutyesyesfile, width, height, sizes, root, depth, forcecompiles the screen as compile does, lays it out at the viewport size without drawing it, and lists every node and the problems (below)
previewyesyesfile, width, height, background, timeline, time, frames, duration, forcecompiles, draws the screen into a PNG, and measures it (below). Needs a process that draws
infonono—plugin version and commit, engine version and kind, OS, locale, mode, whether this process draws, the source folders

Paths in arguments and answers are relative to the project root (DUI/Menu.dui); a path relative to a DUI/ folder (Menu.dui) is found too. help and reference are added by the server.

What layout lists

The screen is put on a stage of the endpoint's own — a preview world, a root the size of the viewport, the compiled class instanced under it the way the designer instances it — and laid out until every glyph is in and two passes agree. Nothing of the user's level is touched. Layout reads no pixels, so the headless host lays screens out as well as the editor does.

The answer's summary is one sentence — the file, the viewport, how many nodes, how many problems and the most serious. Its text, which the server shows as written after the summary, is the screen, one node a line, children indented under their parent:

Laid out DUI/Menu.dui at 1920x1080: 7 nodes, 1 problem (1 warning(s), 0 info); the most serious: ...
The screen, one node a line (x, y from the top left of the viewport, in pixels):
Widget Root  x=0 y=0 w=1920 h=1080  [Overlay]
  Widget Card  x=701 y=466 w=519 h=148  [Overlay]
    Image Backdrop  x=701 y=466 w=519 h=148
    Widget Column  x=701 y=466 w=519 h=148  [VerticalBox]
      Text Heading  x=725 y=494 w=471 h=33  text="Hello, DreamGUI" size=28

Each line is the node's type as the file writes it, its id, its rect in viewport pixels (top-left origin, Y down, rounded), its text with its font size, CUT or OVERFLOWS(needs WxH) when the text does not fit, and in brackets what else matters: hidden / inactive / transparent, pressable, its own layout box, how its anchors hold it when no box places it (centred, fills its parent, held at the top left...), partly clipped, turned in 3D, own canvas X, and part of its control for what a control builds for itself (a button's face). depth (6 by default) limits the levels listed, and the list stops at 250 lines; the answer's next says how many nodes were left out and how to see them; root lists one node and what is under it.

data.tree is the same tree as JSON: per node type, name, path, rect, visibleRect when clipped, visible, order (draw order in its canvas), canvas, pressable, container, placedBy, anchors, in3d, text (text, fontSize, cut, overflows, neededW, neededH), file and line. A node turned in 3D (or sheared, or inside a Perspective) is given the bound of its outline as the canvas's camera draws it -- its four corners through the matrix its geometry is drawn with and the canvas's view projection -- so its rect is where the picture shows it; the line says turned in 3D, rect as drawn in perspective. When a corner is behind the eye it says rect approximate and gives the outline seen straight on (approximate in data.tree).

Which way a turned face looks

A reader that cannot see the picture cannot tell a panel that faces the middle of the screen from one that faces away, so layout says it in words. Each face turned in 3D -- a panel, a card, a board whose own plane leans 2 degrees or more from the face it sits in (or from the screen), 24 px or more each way -- gets a line before the tree; what lies on that face leans with it and is not listed again. The summary ends with a few words on each (In 3D: RosterLeft faces toward the centre, Board tilted back.):

Turned in 3D, as drawn (one line a face; the farther edge is drawn shorter):
  Panel RosterLeft, on the left: turned 14 degrees: faces toward the screen centre (right edge farther)
  Panel RosterRight, on the right: turned 14 degrees: faces away from the screen centre (right edge farther)
  Widget Board, in the middle: tilted back 35 degrees: top edge farther and narrower
  • The degrees are the face's plane against the screen's: about the vertical axis (turned) and about the horizontal one (tilted).
  • Which edge is farther is read off the picture, not off the properties: of two opposite edges, the one the canvas draws shorter, through the widget's drawn matrix (a Perspective folded in) and the canvas's camera; drawn alike, the deeper one. narrower says the farther edge is drawn narrower than the nearer.
  • Which way it faces is the way of its farther edge: right edge back, it faces right. A face whose centre is more than 8 % of the viewport's width left or right of the middle faces toward the screen centre or away from it; nearer the middle it faces left or right. Tilted back is the top edge farther, tilted forward the bottom one. A face turned past 90 degrees says its back is toward the viewer.

These are facts, not findings: no warning and no info, and whether a turn is the one the screen wants is the reader's call. At most 12 faces are listed; data.faces holds them all, per face name, path, file, line, centre (x, y), side (left, right, middle), turn (degrees, fartherEdge, faces, towardCentre), tilt (degrees, fartherEdge, leans: back or forward, fartherEdgeNarrower), back, and text, the line. preview gives the same lines as its text, the same words at the end of its summary, and data.faces. The signs that turn a face the way a screen usually wants are in Turned in 3D.

sizes lays the screen out at more viewports ("1280x720, 2560x1440, 1080x1920", up to five). A problem found at one of them and not at width x height is reported as DUI8006, naming the size.

The layout rules

They never fail a compile; they come out of layout (and DUI8007 out of preview) as warnings and infos, each with the node's path, the line that writes it (or the control that made it) and a hint. One problem in a branch is reported once, not again for every node inside it, and a problem inside a component placed several times is one entry that names the other instances ((the same at Root/CardB/Mute, ...)); any finding repeated at the same place says (reported N times). This holds for every answer, compile errors included: an error on a line of a style that several nodes wear is one entry, (raised 3 times by this one line, once for each node that uses it), and is counted once.

CodeSeverityReported whenThreshold
DUI8001warningwhat can show of a node (its rect cut to its clipping ancestors) reaches past an edge of the viewport, or lies wholly outside; or a text that does not fit its box spills off the screen (upward from a bottom-aligned box, both ways from a centred one) where nothing clips itmore than 1 px
DUI8002warninga text is cut short by its overflow policy, or laid out past its boxthe text's own measure (UDreamText::MeasureFit)
DUI8003warning (info for a plain widget with children)a node that draws, holds children or can be pressed has no width or height; a pressable control is smaller than a pointer needsunder 1 px; under 24 x 24 px (WCAG 2.2's minimum target)
DUI8004warningtwo pressable controls in the same canvas overlap on the screen, wherever they are in the tree (one inside the other aside): a press there reaches only the upper one. A small control lying at least 95 % on one at least four times its area (a button on a pressable card, a dialog on a click-away backdrop) is layered on purpose and not reported2 px or more on both axes
DUI8005infosiblings' left, right, top or bottom edges or centres nearly line up; a row or column of three or more has nearly even gaps. Inside a box no bigger than 128 px on either side, the plain visuals (no text, nothing to press) are the parts of a drawing, an icon drawn from shapes, and are not comparedmore than 0.5 and at most 3 px apart
DUI8006warningDUI8001–8004, DUI8008 or DUI8009 at one of sizes and not at the first viewportas the rule it repeats
DUI8007warning / infoin preview: a text's colour (at its alpha) against the median of the pixels on a one-pixel ring just inside its box. A control's own part painted within 1.1 : 1 of what is behind it (the tick of a toggle that is off) is hidden on purpose and not reportedWCAG contrast under 3 : 1 a warning; under 4.5 : 1 an info for text under 24 px
DUI8008warningwhat a node draws reaches past the panel or card it sits in: the nearest ancestor that draws a box (a visual other than text, 24 px or more each way), or, in an overlay, the last earlier sibling whose drawing fills the parent -- the face over a shadow. Not reported: a node tagged Bleed or inside one, a frame (or a node between) that clips, a frame the size of the screen (DUI8001's business), a plate at least 90 % of its frame each way lying over most of it (a face over its shadow, a glow behind a card)more than 4 px and at least 5 % of the node's own width or height on that side
DUI8009warninga visual that takes no pointer, drawn after a text in the same canvas (later in the file, or in a higher layer), covers its glyphs -- or, no bigger than the text's line, lies mostly in it. Not reported: what is drawn before the text (its backplate), an ancestor or a descendant of it, a control (DUI8004), an outline with no body (bEnableBody = false) or one fainter than 40 / 255, a veil over 90 % of the card the text is on, a scrim over 60 % of the screen, a node tagged Bleed, a control's own parts around its own label. Also a text laid across the edge of a shape drawn before it, some of its letters on the shape and the rest off it (a label slid onto the next badge), where the shape is no more than 8 times the glyphs' box -- a badge, an icon, the next item's picture, not a backdrop shape or a glow. Not reported: a shape that holds the text (its plate), one behind the panel or plate the text is on (drawn after the shape, see-through or not), the backplate of a panel the text is in, a ring or a line (outlines), a control, a node tagged Bleed. One finding a text12 % of the glyphs' box, or 30 % of the decoration in the line; either at least 4 px thick. Across an edge: 12 % to 88 % of the glyphs' box on the shape, at least 4 px thick
DUI8010infoa panel (a box-drawing node, or an overlay's plate, at least 240 x 120 px and 2 % of the screen, under 60 % of it) with text and three things or more in it, judged by what they draw (rules and accent bars under 6 px thin left out): its content keeps to one side, or leaves a band empty across its middle, or its rows (columns) are spread thin. The middle and the spread are not looked at along a bar or a sidebar (2.5 times longer than wide)one side 38 % empty with the opposite under a third of that, or 20 % where 60 % of that axis is empty; a middle band of 38 %; gaps between items taking 60 %

Two nodes are compared in the plane of one of them -- the frame's, the text's, the panel's -- through their widgets' transforms, so a card turned in 3D, a rotated badge or a screen inside a perspective keeps its edges straight; a node whose rect is approximate (a corner behind the eye) is left out. What a node draws is its visual's geometry: a text's glyphs, a polygon's corners (a turned shape is not measured by its box), an image's quad, a rect block's body, and for DUI8009 a rect block's outer shadow or glow too when it is at least 40 / 255 opaque. A shape a text lies across is measured by its convex outline (a polygon's corners, any other visual's four), and no more than what its clipping ancestors let show.

Going past the frame on purpose: @tag Bleed

A glow, a drop shadow, a corner bracket that bleeds off its card, a sheen laid over a title: tag the node Bleed and DUI8008 and DUI8009 leave it, and everything inside it, alone. A frame tagged Bleed is not measured against either.

RectBlock CardGlow {
    @tag Bleed
    AnchorData.SizeDelta = (360, 520)
}

A container that clips (Clipping = ClipToBounds) needs no tag: what it cuts away is not drawn.

What preview measures

The screen is drawn on the same stage into a render target the size of the picture, after the picture has held still for three frames with no shader compiling and no glyph pending (two minutes at most; the answer says when it ran out). Colours are the file's: an authored #1B1E26 reads back as #1B1E26. The same frame is then drawn over black and over white:

FigureDefinition
covereda pixel the same over black and over white within 8 per channel, or between that and 247 (partly transparent); one that follows the backdrop is not covered
coveragecovered pixels over all pixels
meanColor, meanColorNamethe mean of the covered pixels as the picture shows them, and a plain name for it (greys under saturation 0.12, tinted greys under 0.4)
luminanceRec. 709 weights on the PNG's encoded values: min, max, mean, standard deviation
nearWhite, nearBlackcovered pixels with every channel at 240 or above / 12 or below
flatluminance and every channel's standard deviation at most 0.012, and at most 16 covered pixels standing apart from the frame's mean colour by 24 or more on a channel; a plain backdrop with a control and a label on it is not flat, and the summary says how much is drawn on it

The summary leads with the one fact that matters most: the screen draws almost nothing (under 0.5 % covered), is near black (90 % or more), near white (30 % or more), one flat colour, or else its coverage, mean colour and luminance range; then how many texts are hard to read (DUI8007), how many layout problems layout would report, and the image's path. A strip of frames is described by all of them (Over its 16 frames it covers ..., with the least and most covered frame), never by the first alone.

background is what shows behind the screen: #RRGGBB (#1C1E26 by default) or checker. A timeline block does not play by itself: timeline names one of the file's to play from its start, looping, once the screen has settled. time runs the screen that many seconds before the picture, advancing the timeline, tweens and particles; frames (up to 16) spread over duration seconds are put side by side in one PNG (8192 px wide at most), and data.animation says whether they differ, by how much, and whether they zigzag (more frames or a shorter duration needed). A RenderTranslation key moves along X toward or away from the viewer (X is depth, Y right, Z up): (0, -400, 0) to (0, 400, 0) slides a node across, (-400, 0, 0) brings it 400 units nearer and draws it much larger.

Screens in 3D

WhatIn preview
A render transform that turns a widget out of the canvas plane (RenderRotation, RenderTranslation with depth)drawn in perspective, through the canvas's own camera, as the game draws a screen-space canvas
Layer effects, blend modes, clip masks, rect blocks, text effectsdrawn: they are part of the screen's own draw
A screen shown on a panel in a level (a world-space canvas), seen through a cameranot drawn: the stage draws the screen itself, flat, into its picture; put the screen in the level and look at it in the editor
Niagara particles in a screendrawn: the stage holds each system and steps it by the preview's own time, so time and the frames show the particles a game would after as many seconds; a system that waits for a pointer or a click (bAutoActivate = false) shows nothing until something starts it

See also

On this page