Contributing
How to report a problem, propose a change and get a pull request merged — the issue forms and the environment command, the repository's layout, building in a host project, the Quick test gate, what to update with a change, the docs and translation flow, and AI-assisted contributions.
DreamGUI takes bug reports, proposals, docs fixes and pull requests on GitHub. This page is the overview. The checklist a pull request is held to is CONTRIBUTING.md in the repository. An AI agent starts at AGENTS.md.
Reporting a problem
Issues are opened through forms; a blank issue is not offered.
| Form | For |
|---|---|
| Bug report | Wrong output, a crash, or behaviour that differs from these docs |
| Feature or syntax proposal | Something DreamGUI or .dui cannot express or do yet. Open one before a feature pull request |
| AI wrote it wrong | An AI tool wrote .dui that did not build, looked wrong, or used names that do not exist |
| Docs or translation | A page here that is wrong, unclear, missing, or badly translated |
The bug and AI forms ask for the output of the environment command. Run it from your game project's folder:
pwsh -NoProfile -File Plugins/DreamGUI/Tools/Get-DreamGUIEnvironment.ps1It prints the plugin's version and commit, the engine's version and kind, the system, its UI language and the shell.
It starts nothing and prints no paths. Pass -Project <path to>/<Project>.uproject when the plugin is not inside the
project's Plugins folder. Questions and ideas go to
Discussions.
The repository
| Folder | What it holds |
|---|---|
Source/ | The thirteen modules: eight runtime, four editor-side (UncookedOnly) and the test module (module layers) |
Shaders/, Config/, Content/, Resources/ | What the modules load: shaders, default settings, fonts and other assets, icons and the UMG parity tables |
Docs/ | This manual. English is the source; Docs/zh-CN/ is its translation |
Tools/Tests/ | The test runner, its presets, the static checks |
Tools/TestHost/ | The minimal host project the suite builds and runs in |
DLoc/ | The editor UI's translations, kept with DreamLoc |
ThirdParty/ | msdfgen, committed as a single-file copy, so a plain clone builds |
The whole layout is under What is in the plugin folder.
Building
You need Unreal Engine 5.8 (source or launcher), PowerShell 7.2 or later, Python 3.8 or later and git. Win64 is the
only platform built and run. Build in a project that has the checkout as Plugins/DreamGUI; the
test host is a minimal one, with the plugin as a git worktree of your clone:
pwsh -NoProfile -File Tools/TestHost/New-DreamGUITestHost.ps1 -Root <host folder> -RepoPath <your clone> -Branch <your branch> -Detach -EngineRoot <engine root>Its defaults are the maintainer's machine, so pass all four values. Build the whole editor target, never with
-Module=: a restricted build leaves the plugin's module manifest stale, and the plugin then fails to load as a whole.
The test gate
Every pull request runs the Quick preset first:
pwsh -NoProfile -File Tools/Tests/Invoke-DreamGUITests.ps1 -Project "<Project>/<Project>.uproject" -Engine "<engine root>"It runs the static checks, builds, checks the module manifest, and runs the headless suite in an unattended editor.
Close every editor of that project first. Exit code 0 is green, 1 is red, 2 means the run could not be judged.
It prints one line that starts with RESULT: paste that line into the pull request. The other presets (Rhi for
the pixel tests, Designer, Pie, All), the report, known issues and the static checks' rules are on
The automation suite. python Tools/Tests/static_checks.py runs the static checks alone,
without an engine.
What to update with a change
- The page here that describes the behaviour you changed.
CHANGELOG.md: a line under## Unreleased, in### New,### Changedor### Fixed, for anything a project can notice.- A new diagnostic code:
EDreamUIDiagnosticCode, and both tables, Diagnostics andDocs/diagnostics/codes.md. Codes are never renumbered or reused. - A changed reflected type: regenerate the class reference with the
DreamGUIReferenceDocscommandlet. It is never edited by hand. - A new or moved runtime file: its row in
Tools/Tests/module-owners.csv. - New tests: a name of the form
DreamGUI.<Area>.<Sentence>, and a higher floor for the preset inTools/Tests/presets.json. - A new property meta tag: the
DreamGUI_prefix (Property meta tags).
Docs and translations
English under Docs/ is the source of this site. After a change reaches main, CI translates what changed into
Docs/zh-CN/ with dreamdocs and opens a pull request of its own, so a
contribution changes the English only. A Chinese sentence is corrected by editing the Chinese page; the next run keeps
the edit. Docs/zh-CN/.align/ records which English paragraph each Chinese one came from and is never edited by hand.
AI-assisted contributions
They are welcome on the same terms as any other. Name the tool and model in the pull request, paste the RESULT line
of the test run, and review every line before you submit: the person who opens the pull request is responsible for
it. Bulk AI-generated pull requests without test evidence are closed. Working with AI agents
describes what an agent has to work with.
License and conduct
Contributions are licensed under the plugin's MIT license; there is no CLA. The code of conduct and the security policy apply to every repository of the project.