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.
| Kind | editor service, in the DreamGUIEditor module (Source/DreamGUIEditor/Private/MCP/) |
| Protocol | DreamMCP 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 |
| Route | http://127.0.0.1:<port>/dream/gui, tool name dream_gui |
| Port | 47800, 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 address | 127.0.0.1 only, proven at startup |
| Authentication | the 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 |
| Hosts | the 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
| Process | Endpoint | mode | Draws |
|---|---|---|---|
| The user's editor | yes, once the engine has initialized | editor | yes |
A render host: the editor with -DreamMCPHost -RenderOffscreen, no -run= | yes | host | yes |
A headless host: -run=DreamGUIHost -nullrhi -DreamMCPHost, or another Dream plugin's host commandlet | yes | host | no |
Any other commandlet (-run=DreamUICompileWidgets, a cook), an automation run, a game | no | — | — |
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
| Action | Long | Writes | Arguments | Answers |
|---|---|---|---|---|
check | yes | no | file, or all: true | parses 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 |
compile | yes | yes | file, force | builds 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 |
diagnostics | no | no | file | what the engine holds from the last check or compile of each file, errors first, without compiling |
lookup | no | no | name, kind, limit | an 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) |
layout | yes | yes | file, width, height, sizes, root, depth, force | compiles the screen as compile does, lays it out at the viewport size without drawing it, and lists every node and the problems (below) |
preview | yes | yes | file, width, height, background, timeline, time, frames, duration, force | compiles, draws the screen into a PNG, and measures it (below). Needs a process that draws |
info | no | no | — | 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=28Each 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
Perspectivefolded in) and the canvas's camera; drawn alike, the deeper one.narrowersays 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 centreoraway fromit; nearer the middle it facesleftorright. 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.
| Code | Severity | Reported when | Threshold |
|---|---|---|---|
| DUI8001 | warning | what 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 it | more than 1 px |
| DUI8002 | warning | a text is cut short by its overflow policy, or laid out past its box | the text's own measure (UDreamText::MeasureFit) |
| DUI8003 | warning (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 needs | under 1 px; under 24 x 24 px (WCAG 2.2's minimum target) |
| DUI8004 | warning | two 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 reported | 2 px or more on both axes |
| DUI8005 | info | siblings' 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 compared | more than 0.5 and at most 3 px apart |
| DUI8006 | warning | DUI8001–8004, DUI8008 or DUI8009 at one of sizes and not at the first viewport | as the rule it repeats |
| DUI8007 | warning / info | in 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 reported | WCAG contrast under 3 : 1 a warning; under 4.5 : 1 an info for text under 24 px |
| DUI8008 | warning | what 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 |
| DUI8009 | warning | a 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 text | 12 % 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 |
| DUI8010 | info | a 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:
| Figure | Definition |
|---|---|
| covered | a 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 |
coverage | covered pixels over all pixels |
meanColor, meanColorName | the 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) |
luminance | Rec. 709 weights on the PNG's encoded values: min, max, mean, standard deviation |
nearWhite, nearBlack | covered pixels with every channel at 240 or above / 12 or below |
flat | luminance 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
| What | In 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 effects | drawn: 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 camera | not 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 screen | drawn: 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
- Working with AI agents: the skills, the scripts, and what an agent without DreamMCP does.
- Diagnostics: every
DUInnnncode. - Compiling from the command line: the commandlet
.skill/dui.ps1drives.
Working with AI agents
What an AI agent has to work with when it writes .dui — AGENTS.md, the language reference, the symbols file, the headless DreamUICompileWidgets commandlet and the diagnostics file — and the loop that gets a file from a request to a compiled widget Blueprint.
Fonts and packaging
What a DreamGUI text needs to look in a packaged game the way it does in the editor — which fonts ship by themselves, how to add colour emoji, which ICU data to package, and how to check a package.