Troubleshooting

The module will not load#

For public installation, use the official pinned URL from Installation and confirm game:HttpGet and loadstring are available. An HTML/error response is not a library: do not pass it to loadstring. Check the approved manifest/SHA256 before execution. For the optional local workflow, confirm readfile and AroynUI/Aroyn.lua in the executor workspace. The artifact requires native Roblox services and is not a plain Lua desktop module.

No navigation icons#

Check Aroyn.Distribution.Assets.Status and Errors for the standalone artifact. writefile plus getcustomasset/getsynasset must work; without makefolder, AroynUI/assets must exist. Registration success does not prove the executor renders the URI correctly. Check Aroyn.IconAtlas before creating pages and pass Logo=Aroyn.Logo to CreateWindow. Use the library’s 896×128 seven-cell atlas, not the Hub’s grid.

Rendering looks soft#

The current library avoids persistent CanvasGroup compositing and whole-window scaling. Inspect any parent UIScale, fractional host transform or incompatible atlas adapter you added. Real device sampling and text measurement need in-game observation; a browser screenshot cannot prove Roblox sharpness.

Callback is not running#

Defaults and SetValue(value) are silent. Use SetValue(value, true) to notify on a changed value. Disabled and modal-blocked controls reject user input. TextInput with SubmitOnEnter=true commits only when FocusLost follows Enter. Keybind Callback handles rebinding; use OnActivate for activation.

Dropdown opens then closes unexpectedly#

One Window has one active Dropdown/ColorPicker popup. Opening a second closes the first. Page changes, modal entry, hide, minimize or disable also close it. Use Open/Close/IsOpen; avoid private GUI fields or a second global outside handler that competes with the library.

A configuration does not survive rerun#

local status = window:GetConfigStatus()
print(status.Mode, status.Namespace, status.Path)
local ok, info = window:SaveConfig("main")
print(ok, info.Code, info.Message)

Session mode lasts only for this window. File mode means readfile/writefile are present, not that every path is writable. Folder APIs or pre-existing directories are needed. Inspect WriteFailed, FolderFailed and partial FileSaved/IndexWriteFailed results. A custom adapter must throw on failed writes.

A loaded preference is missing#

Declare the same Flag and compatible type. Without a Flag it is not saved. Sensitive/Persist exclusions remove it. Removed options normalize; missing entries preserve current state. Inspect Applied, Deferred, Skipped and Warnings. Reset does not rewrite the saved profile.

AutoSave destination seems wrong#

AutoSaveConfig stays independent of LoadConfig. Loading another profile does not switch the destination. Call SetConfigAutoSave explicitly to change it. Destroy cancels a pending write without flushing; save explicitly before shutdown when appropriate.

A mobile window does not fit#

Standalone CreateWindow has a desktop minimum width of 440px. The documentation site is responsive, but that is separate from library compatibility. Use a deliberate host adapter and test native portrait/landscape input. Mobile compatibility and other executors remain unverified.

Testing evidence#

Local mock tests verify state and event logic, not native pixel quality, real touch gestures or executor file behavior. The Phase 5B user report confirms 11 PASS, 0 FAIL, one empty-folder cleanup SKIP on PC Potassium; general manual approval followed. The executor version was not supplied. These docs do not turn that into an all-executor claim.

Supported environments and distribution#

Version 0.1.0 is an early product version, not a permanently frozen API promise. Missing filesystem/custom-asset capabilities use documented Session/degraded asset behavior. No Dashboard authentication is required.