Common pitfalls
Things that look like bugs and are not, or that cost an afternoon -- tweens on one property, angle conventions, raycast targets, colour literals, style overrides, fonts, world-space widgets, effects inside groups, pixelate strength, recording off-screen, and where UMG's names differ -- each with the page that explains it.
Each entry says what you see, why, and what to do; the page it links to has the detail.
Animation
- A fade, then the opposite fade, and the result flickers or ends wrong. Two tweens on one property used to both run.
A tween now stops the earlier ones on the same property when it starts;
SetReplacesEarlierTweens(false)opts one out (a looping breath that should coexist with a hover). Tweens in a sequence are never stopped. One tween per property. - A widget in a panel does not stay where
AnchoredPositionToputs it. The panel writes the position back. Move what is drawn:RenderOffsetTo,RenderScaleTo,RenderRotationTo,RenderPoseTo. Widgets inside panels. - A positive roll turns clockwise.
RenderRotation.Roll,SetRenderTransformAngleandRenderAngleToturn a widget clockwise on the screen (its right edge down), as UMG's angle does.
Angles
- The angle properties do not share a zero.
Ringmeasures from three o'clock, counter-clockwise;Native.RingMenu,Native.ProgressBarand text on a path measure from twelve o'clock, clockwise. A progress ring onRingisStartAngle = 90,EndAngle = 90 - 360 * progress. Angle conventions.
Input
- A label over a button takes no hover or clicks. Right: a
UDreamTextis not a raycast target by default. A text that is the thing to press setsbRaycastTarget = true. Visuals. bRaycastTargeton aWidgetnode is an error. It belongs to a visual. WriteRaycastable = Disabledon the widget. Properties and values.- A button the pad has selected shows nothing. A selectable's transition wears its Hovered look while it has focus,
unless Use Focused Visuals gives focus a look of its own. A look drawn by your own code from
OnSelectionStateChangedhearsFocused, notHovered: draw the two alike there. - Navigation driven from code takes no step. A press and its release given on one frame never reach a frame with the
direction down. Call
TapNavigation, which takes one step on the next frame; for a recording made frame by frame, turn on the event system's Navigation Repeat In Game Time, or a held direction repeats on real time and runs ahead. - Focus asked for in a widget's construct. A widget shown that frame takes it on the next frame;
SetKeyboardFocusanswers false meanwhile, so do not treat that answer as final.
The .dui language
Style.X = vchanges nothing. The instance'sStyleis used only whenStyleSourceisInline(or there is no style sheet), orProjectStyleSheetOverridewith the field'sbOverride_Xticked. A.duinever touches the bits, and they start ticked. In .dui and at run time.: A : BappliesBoverA, and a name twice is a warning. Styles apply left to right, bases first, each once, at its first appearance; the node's own lines come last. Naming a style that an earlier one already applied changes nothing and is DUI3025. Several styles.@slot Size <- F()is an error.Sizeis a shorthand forMinDesiredSizeandMaxDesiredSizewith one value, so it takes=only; bind the two properties separately (DUI4001).@slot Size.@tag Trimis a tag,@tag Trim { }is a node. A name after@tagis a tag line unless a block, a:or a(was: …)follows it, which makes it the old@Nameform of a node typed by a resource calledtag. A tag line in astyleor directly in aforbody is DUI2024. Tags.- A glow meant to spill out of its card is still DUI8008 until it says so.
layoutreports what draws past its panel and what is drawn over a text. A decoration that does either on purpose takes@tag Bleed; one that does not goes inside, or before the text in the file. Going past the frame. - A ring menu's items are written in the
.dui.Items = [{ "Lamp", Tag: Lamp }, …]: a map per item, the label first and without its key. A map written without a key anywhere else, or on a struct that has no primary field, is DUI4009. Structs as field maps. - A ring menu's template content is centred on its slice, not stretched over it. It takes the size its class's root
is authored at, or the style's
ContentWidthsquare when the root stretches, atContentRadius. Give the root fixed anchors for a size of its own. Ring menu. #8C8C94is darker than it looks. Colour literals are sRGB-encoded, and a tint is multiplied in linear space. Values.- A positive
AnchoredPositionY moves a node up, and(0, 0)anchors are the bottom-left. Y goes up, as in Unity. InRenderTranslationX is depth:(-40, 0, 0)brings a node nearer and draws it larger;(0, -40, 0)moves it left.RenderRotationis(Pitch, Yaw, Roll). Positions, sizes and axes. VAlign = Centeron a text is an error, and@slot VerticalAlignment = Middleis too. A text's own alignment saysMiddle(Top,Middle,Bottom); a slot's saysCenter(Top,Center,Bottom,Fill). The error names the right one.CornerRadius = (24, 24, 24, 24)draws a capsule, not 24 px corners. The radii are fractions by default (CornerRadiusUnitMode = Percentage, 1 rounding a corner fully); writeCornerRadiusUnitMode = Valuefor pixels.- A rect block's corners come out in the wrong places. Its
CornerRadiusruns bottom-right, top-right, top-left, bottom-left (asClippingCornerRadiusdoes), not clockwise from the top left: a shield with round bottom corners is(22, 6, 6, 22). Text = "Hello" @slot HorizontalAlignment = Fillon one line is DUI2001. An@right after a value is read as that value's annotation (@key,@note,@max,@noloc). End the value with;or start a new line:Text = "Hello"; @slot HorizontalAlignment = Fill.Padding = (@Gap, 0, @Gap, 0)is DUI4003. A resource stands for a whole value, never for one part of a tuple. Write the numbers, or give the whole value a name.- A
Colorprop does not driveBodyColor(DUI5004). Apropscolour is a linear colour, and a visual'sColorand a rect block'sBodyColorare not; neither can be bound to it. Show the right part instead: one node per colour, each withShown <- Rarity == 2on anIntegerprop, orShown <- Kind == "Rare"on aStringone.
Text and fonts
- Boxes, or nothing, where Chinese, Japanese or Korean text should be. The font has no glyph for the character, and
DreamGUI logged a warning once naming it. The default font covers these through
/DreamGUI/DefaultFont_DistanceField_CJK; a font of your own needs a fallback. Fonts. - Gaps or seams where a glyph's strokes cross. The font file keeps its strokes as overlapping contours — a static
instance cut from a variable font does unless its overlaps were removed — and DreamGUI logged a warning once naming the
glyph. Run the file through fontTools'
removeOverlapsand use the result. Fonts. - A control's text has the wrong typeface. Styles with a
Fontfield: text input, spin box, rich text, expandable area, ring menu. Styles.
Layout and world space
- The whole screen is drawn several times too large, or off the screen, at 1280 x 720. A
ScaleBoxaround a 1920 x 1080 design canvas measures the canvas by what is inside it, not by itsSizeDelta, and scales that up. Give the canvas@slot Size = (1920, 1080)as well. The root of a screen. - A short label, a chip or a key cap is 100 px wide. Every node starts 100 x 100 (
AnchorData.SizeDelta), and a box or an overlay that sizes itself to its children counts that size -- a backdrop filling an overlay included. Give the nodes it should measure by their contentAnchorData.SizeDelta = (0, 0); the presets'ui.FillSlotdoes. - What a host puts in a component's slot spills out of it. A slot with no layout box (
slot Badge { }) places what is put in it by its anchors, at its own size. Give that widgetui.FillParent(anchors at the four corners). - The text of a row in a vertical box stands one letter to a line. A vertical box gives a child the width the child
measures, and a node whose
SizeDeltawidth is 0 measures 0, so its text wraps after every character. Write@slot HorizontalAlignment = Fillon the row (or in its style), or give it a width. Positions, sizes and axes. - A list that opens or grows draws past its panel. A panel does not clip. Use a
ScrollBox, orClipping = ClipToBounds. The panels. - A world-space panel sits off its actor. The component's
Pivotand size go on the user widget; give the class's root node anchors from(0, 0)to(1, 1)and no size of its own. World-space UI. - A panel meant to face the middle of the screen faces away from it. A positive Yaw brings a node's right edge
nearer and a positive Pitch its top edge, so the signs run the other way from what a first guess gives: a panel on
the left faces the middle with a negative Yaw, one on the right with a positive Yaw; a plane laid back like a table
takes a negative Pitch; a row of cards that curves toward the player goes from a negative Yaw on the left to a positive
one on the right, largest at the ends.
layoutandpreviewsay which way each turned face looks as drawn (Panel RosterLeft, on the left: turned 14 degrees: faces toward the screen centre (right edge farther)); read that line after every turn. Turned in 3D.
// DUI/Pitfalls/Facing.dui
class /Game/UI/Pitfalls/WBP_Facing
use "Theme.dui" as ui
// The three turns, with their signs: a positive Yaw brings a node's right edge nearer, a positive Pitch its top edge.
style Side {
AnchorData.AnchorMin = (0.5, 0.5)
AnchorData.AnchorMax = (0.5, 0.5)
AnchorData.Pivot = (0.5, 0.5)
AnchorData.SizeDelta = (360, 280)
}
style ArcCard : ui.Card {
@slot Size = (100, 150)
}
Widget Root : ui.FillParent {
RectBlock Backdrop : ui.ScreenBackdrop : ui.FillParent
// Two panels that face the middle: on the left a negative Yaw, on the right a positive one.
RectBlock FacingLeft : ui.Panel : Side {
AnchorData.AnchoredPosition = (-620, 160)
RenderRotation = (0, -16, 0)
}
RectBlock FacingRight : ui.Panel : Side {
AnchorData.AnchoredPosition = (620, 160)
RenderRotation = (0, 16, 0)
}
// A plane laid back, its far (top) edge narrower: a negative Pitch.
RectBlock Table : ui.Panel : Side {
AnchorData.AnchoredPosition = (0, -250)
AnchorData.SizeDelta = (720, 300)
RenderRotation = (-35, 0, 0)
}
// Cards that curve toward the player: negative left of the middle, positive right of it, the ends turned most.
HorizontalBox Arc : Side {
Spacing = 20
AnchorData.AnchoredPosition = (0, 160)
AnchorData.SizeDelta = (580, 150)
RectBlock CardA : ArcCard { RenderRotation = (0, -24, 0) }
RectBlock CardB : ArcCard { RenderRotation = (0, -12, 0) }
RectBlock CardC : ArcCard { RenderTranslation = (-20, 0, 0) }
RectBlock CardD : ArcCard { RenderRotation = (0, 12, 0) }
RectBlock CardE : ArcCard { RenderRotation = (0, 24, 0) }
}
}Rendering
- A blur inside a faded or masked container is flat grey. A group (
GroupOpacity,GroupMask, ...) draws apart and a background effect inside it sees only the group. Put the blur outside and shape it withStrengthMap. Inside a layer group. - A material of mine ignores the clip or the mask transition. Shade through
MF_DreamUI_Shade. Clip masks. - A pixelate fade runs fast and then crawls. The strength is not a block size. Pixelate strength.
Code
NativeOnDestruct, notNativeDestruct. The C++ virtuals of a user widget have their own names, andGetWorld()may be null inNativeOnInitialized; useNativeOnConstruct. An instance's life cycle.
Tools
- A recording at the wrong scale, or two recordings spoiling each other. Pass
-ForceReswith the resolution, and run one capture at a time. Recording the UI off-screen. - Compiling
.duiclasses from a script. TheDreamUICompileWidgetscommandlet. Compiling from the command line.
Networking and multiplayer
Where UI is made in a networked game — only where a local player sees it; what a dedicated server and a listen server each do with DreamUI widgets, the play-in-editor net modes, and the warning a server world gives.
Property meta tags
The DreamGUI_ meta tags that place a property in DreamGUI's details panels, hide it, pick its control or make it an effect's switch -- a property without them is never dropped -- and how an extension's classes and customizations use them.