← Web to Widget

Commandlet and CLI reference

Every entry point (editor menu, CLI, commandlet, tests) runs the same import service, so behaviour cannot differ between a human clicking a button and a build agent.

CLI

python Plugins/DigitalBunkerWebUMG/Tools/webumg.py import <file-or-dir> --project <Game.uproject> [options]
python Plugins/DigitalBunkerWebUMG/Tools/webumg.py lint   <file-or-dir> --project <Game.uproject> [options]
python Plugins/DigitalBunkerWebUMG/Tools/webumg.py reimport <file-or-dir> --project <Game.uproject> [options]

The engine is located from the project's EngineAssociation (launcher installs and registered source builds), UE_ENGINE_DIR, or --engine. Standard library only, no packages to install.

Option	Default	Meaning
`--dest`	`/Game/UI/Web`	Content path for the Widget Blueprint(s)
`--report`	`Saved/WebUMG/report.json`	Machine-readable report
`--manifest`	`auto`	`auto` writes `<name>.webumg.json` next to the source; `none`; or a path
`--headers <dir>`	off	Generate `<Widget>Base.h` binding headers
`--api`		API macro for the header, e.g. `MYGAME_API`
`--viewport`	1920	Design width for responsive Tailwind variants
`--dark`	off	Apply `dark:` variants
`--root-canvas`	off	Wrap the root in a full-screen Canvas Panel
`--no-string-table`	off	Literal text instead of a String Table
`--no-textures`	off	Do not import images
`--parent`		Re-parent to a class, e.g. `/Script/MyGame.MyHudBase`
`--name`		Override the Widget Blueprint name (single file)
`--font`	`/Engine/EngineFonts/Roboto`	Font asset for all text
`--preflight`	`auto`	Tailwind Preflight defaults: auto-detect, on, off
`--force`	off	Overwrite a Widget Blueprint this importer did not create

Exit codes: 0 success, 2 one or more inputs failed (see report), 3 bad arguments, environment, or crash. The CLI derives its exit code from the report, not from the editor process, because Unreal returns 1 whenever any system logged an error during startup (an unrelated project setting, a port in use), even when the import succeeded.

Render (visual and geometric verification)

python Plugins/DigitalBunkerWebUMG/Tools/webumg.py render /Game/UI/Web/WBP_Hud --project <Game.uproject> [--out <file.png>] [--width 1920] [--height 1080] [--scale 1]

Renders the imported Widget Blueprint offscreen to a PNG and writes <file>.geometry.json with the absolute rectangle and visibility of every widget. Compare the rectangles with the browser's getBoundingClientRect() for the same ids to verify layout numerically; compare the PNG with a browser screenshot for colours and text. This needs a real graphics device, so it launches the editor process without NullRHI and takes a few seconds longer than an import. The equivalent console command is DBWebUMG.Render <Asset> <OutPng> [Width] [Height] [Scale].

Commandlet

UnrealEditor-Cmd.exe <Game.uproject> -run=DBWebUMGImport -Input=<file|dir> [-Dest=/Game/UI/Web] [-Lint]
    [-Report=<file.json>] [-Manifest=auto|none|<file>] [-Headers=<dir>] [-Api=MYGAME_API] [-Viewport=1920] [-Dark]
    [-RootCanvas] [-NoStringTable] [-NoTextures] [-NoSave] [-Font=/Path/To/Font] [-Parent=/Script/Module.Class]
    [-Name=WidgetName] [-Force] [-Preflight=auto|on|off]
    -unattended -nop4 -nosplash -NullRHI -NoSound

Same exit codes. Directories are scanned recursively for *.html and *.htm, sorted, and imported in order.

Report format

One object per input (an array under files when several). Fields:

status: ok or failed; mode: import or lint
source, sourceHash (SHA1 of the HTML), planHash (SHA1 of the plan JSON), widgetName, title, tailwindMode
stats: elements, widgets, maxDepth, warnings, errors, parseMs, cascadeMs, mapMs, classCounts
diagnostics[]: severity, code, message, line, column, element
bindings[]: kind (widget or event), name, widget, widgetClass
texts[]: key, text, widget
assets[]: source, widget, usage
unknownClasses[]
manifest, header paths when written
emit: success, asset, file, stringTable, reimport, widgetsCreated, emitMs, diff (added, kept, reclassed, removed), textures (source to asset path)
totalMs

See Docs/examples/hud.report.json.

Manifest format

The plan: schemaVersion, widgetName, title, sourceHash, tailwindMode, widgetCount, maxDepth, classCounts, bindings, texts, assets, and root, a tree of { name, class, variable, bind, event, sourceId, sourcePath, sourceLine, text, textKey, properties, slot, states, children }. Property values use a small typed grammar (linear(r,g,b,a), margin(l,t,r,b), vec2(x,y), vec4(x,y,z,w), anchors(minx,miny,maxx,maxy), asset(/Path), file(relative.png), list(a|b|c), numbers, booleans, enum names). Keys are sorted, so two imports of the same design produce identical text and the manifest diffs cleanly in code review.

See Docs/examples/hud.webumg.json.

Provenance

Each imported Widget Blueprint records DBWebUMG.SourceFile, DBWebUMG.SourceHash, DBWebUMG.PlanHash and DBWebUMG.ImporterVersion as package metadata. The Content Browser Reimport from HTML action and the foreign-overwrite refusal read these.