Common problems and troubleshooting¶
A UI that "does not show up", "does not refresh" or "does not respond to clicks" is rarely random. It is usually one of four causes: the document did not compile, the data key does not match, the layout computed to a zero size, or the host does not deliver the events. This page gives the investigation order, a log reference table and fixes for common symptoms.
Investigation order¶
- Read the log. Silica sends every compile error, warning and runtime problem through
runtime::SetLogSink; first check whether the most recent load reported anything. - Confirm the compile succeeded. A single
error:makesCompileFile(filepath, fallback)discard the file content and use the fallback interface instead. A UI that "looks like the default" has usually fallen back. - Check the data keys. A binding that cannot read its key gets
nulland reports nothing; a misspelled name only shows up as "the value stays at the default". - Check the layout. In an absolute layout a node without an explicit size is 0×0; a container does not automatically stretch beyond its children along the layout direction.
- Reduce to a minimal document. Delete everything except the failing node, then add the properties back one at a time; this usually pinpoints which value causes the problem immediately.
Literals first, bindings later
First get position and size right with constants, then replace the values with @bindings. Tuning layout and bindings at the same time makes it hard to tell which layer the problem is in.
Log format¶
A diagnostic has the form:
source:line:column: severity: message
For example:
D:/LeviLamina/mods/SilicaTest/ui/panel.sil:857:21: error: unknown style 'demo_row_box'
error:means the compile failed. With fallback loading, the whole file is replaced.warning:means a property or script was skipped, the widget keeps its default value, and the rest of the document loads normally.- A single parse keeps at most 200 diagnostics; fix the earlier errors, reload and look again.
Route the log into your own logging system:
silica::Silica::SetLogSink([](std::string_view line) {
mymod::Log(line); // write to a file or the console
});
When no sink is set, logs go to standard error and the Win32 debug output.
Compile-time errors¶
| Message | Cause | Fix |
|---|---|---|
cannot open '<path>' |
the file does not exist, or the path resolved incorrectly | check SetRootPath and the relative path; confirm the file name casing |
the document does not define any component |
the file only has definitions and no UI node | write at least one top-level node (Container, Panel...) |
unknown component 'X' (register it with WidgetFactory or define a Component) |
the node type is misspelled, or the custom widget is not registered | compare against the type names in the widget reference; register custom widgets with WidgetFactory::Register first |
unknown style 'X' |
class: / style: references a style that does not exist |
check the style name; names are case-insensitive and ignore -/_, but the style must actually be defined |
style 'X' extends itself |
style inheritance forms a cycle | remove the self-reference, or extend another base style |
'X' cannot contain 'Y' |
a child widget was put into a leaf widget | only Container, ScrollView and ForEach accept arbitrary child widgets; leaf widgets accept only Part |
'Slot' can only be used inside a Component definition |
Slot was written outside a component definition |
move Slot into the root node of the Component |
component 'X' instantiates itself recursively |
the component references itself directly or indirectly | a component cannot be instantiated recursively; turn the recursive part into ForEach or write the levels out by hand |
components nest too deeply (limit 32) / (limit 64) |
the number of nested components exceeds the limit | split the components to remove one level of nesting |
styles nest too deeply |
the extends chain is too long |
flatten the inheritance chain |
styles cannot run scripts; 'X' is only valid on a component |
an event script was written in a Style |
a script can only be written on a UI node or on a node of a Component |
'ForEach' needs a data parameter |
ForEach is missing data: |
write ForEach (data: @rows, item: @row) { ... } |
multiple component roots need a 'Container' component |
the component has several root nodes, but Container is not registered |
register the built-in widgets or a custom Container; normally you call WidgetFactory::RegisterBuiltins() |
missing ';' after property 'X' |
the property value lacks a semicolon, and the next line is taken as a new property | add the ;; several space-separated values in one property also trigger this |
missing '}' for 'X' opened at line N |
a node block or script block is not closed | starting at the reported line, look for the unclosed { |
unterminated string / unterminated block comment |
a string or a /* */ comment is not closed |
add the closing quote or */ |
expected ':' after parameter 'X', expected ',' or ')' after parameter 'X' |
the parameter list is malformed | follow the Component Name(a, b: default) form |
expected hex digits after '#' |
no valid hexadecimal digits after the # in a color |
use #RGB, #RGBA, #RRGGBB, #RRGGBBAA |
expected a name after '@' / '$' |
a bare @ or $ was written |
add the key name; to show @ in text, put it in a quoted string |
Compile-time warnings¶
Warnings do not prevent loading, but the affected property or script does not take effect. The specific reason for cannot bind and cannot attach follows after a colon.
| Message | Usual cause | Fix |
|---|---|---|
unknown property 'X' on 'Y' |
the property name is misspelled, or the property does not belong to this widget | compare against the property tables in the widget reference; property names must be lowercase with hyphens, fontSize is not converted automatically |
cannot bind property 'X' on 'Y': ... |
the expression failed to parse, or the property does not support bindings | simplify the expression; confirm the property is one that ApplyProperty can set |
cannot attach the script on 'X' of 'Y': ... |
the script has a syntax error, or the event name is not an event property | check the statements, brackets and semicolons inside { ... }; a script can only be attached to events such as onClick, onChange, onSubmit |
cannot evaluate the argument 'X': ... |
the argument expression passed to a component failed to parse | fix the argument expression; the component is instantiated with empty values |
component 'X' is missing the argument 'Y' |
the parameter has no default value and was not passed | pass the argument, or give the parameter a default value |
unknown argument 'X' on component 'Y' |
the call passes an argument the component does not declare | remove the argument, or add it to the parameter list of the component |
component 'X' has no Slot; its children are ignored |
the component definition has no Slot, but the call site writes child nodes |
add a Slot in the component root node, or remove the child nodes at the call site |
component 'X' has the same name as a builtin widget; the builtin is used |
the component name collides with a built-in widget | give the component a different name |
duplicate property 'X'; the last value wins |
the same property is written twice on one node | delete the earlier one |
duplicate variable 'X'; the last value wins / duplicate style 'X' / duplicate component 'X' |
a document-level definition has a duplicate name | merge or rename them |
variable '$X' refers to itself |
the value of the Var references itself directly or indirectly |
make it a constant, or split it into two variables |
Warnings are clues too
When part of the UI "has no effect at all", search the log for warning: first. A misspelled property does not fail the whole document, it only makes that line be skipped silently.
Runtime logs¶
These are not compile diagnostics; they appear only while loading or drawing.
| Log | Meaning | Fix |
|---|---|---|
silica: '<file>' is unavailable, compiling the fallback source |
the file has errors or cannot be read, so the fallback source is used | scroll up to the error: lines from the same batch, fix them and reload |
silica: reloaded '<absolute path>' |
the reload succeeded | nothing to do |
silica: reload of '<path>' failed; keeping the previous tree |
the reloaded document has errors, so the old interface is kept | fix the document as the log says and reload again |
silica: ReloadUI('<file>') before CompileFile; nothing to replace |
a reload was called before anything was loaded | call CompileFile before ReloadUI, or use CompileFile instead |
silica: ForEach truncated N rows to 512 (the data array is too large) |
the array has more than 512 items, so only the first 512 rows are rendered | paginate, filter, or avoid feeding one huge array at once |
silica: image texture not available: <src> |
the texture name does not exist, or the resource pack is not ready yet | check the path spelling and the resource pack; see Images |
silica: packed image '<path>' as <texture name> |
the disk image was imported into the resource pack | informational; useful to confirm where the path resolved to |
silica: image import needs SetRootPath (the mod directory) |
there is no root directory, so disk images cannot be imported | call SetRootPath at startup |
silica: refusing image outside the mod directory: <path> |
the absolute image path falls outside the root directory | put the asset inside the mod directory and use a relative path |
silica: cannot write the image pack manifest in <directory> / cannot copy image into the pack: ... |
the resource pack directory is not writable | check the permissions of the mod directory or whether a file is locked |
silica: texture api unavailable (ResourceLocation/TexturePtr symbols not resolved) |
the texture API of this game version was not resolved | confirm the framework version matches the game version; until then images can only show a placeholder box |
Troubleshooting by symptom¶
The UI does not show at all¶
| Possible cause | How to tell | Fix |
|---|---|---|
| the compile failed and fell back | the log contains error: and is unavailable |
fix the errors first |
| the root node came back empty | CompileFile returns nullptr |
check whether the fallback source itself is valid; the log of CompileFile states the reason |
| the host does not draw the widget tree | other interfaces do not show either | confirm you call root->Render(context) and FlushDraws(context) every frame |
| the root node has a zero size | the width or height is 0 after layout | give the top-level container an explicit width / height |
| the root node is off screen | log x/y/width/height, or add a temporary stroke |
check whether the coordinates are GUI units rather than pixels |
| hidden by opacity/visibility | visible: false, opacity: 0, or a binding that evaluates to false |
temporarily replace it with a literal to verify |
A widget does not show or is misplaced¶
- Child nodes in a leaf widget are rejected: the log shows
'X' cannot contain 'Y'. Only container classes accept arbitrary child widgets. - The absolute layout has no size:
Containerdefaults toabsolute, so child nodes are not arranged automatically; you must writex/y/width/height, or switch the container tolayout: vertical|horizontal. - Only a 0 on the cross axis fills: in a vertical layout
width: 0means fill the container width; a hard-coded number keeps that width. Along the layout direction it is the opposite: the container wraps its child content, and child nodes are not stretched taller automatically. marginonly applies to the trailing edge: in a vertical layoutmarginis the bottom spacing, andmargin-topis the top spacing;margin-lefthas no effect in a vertical layout.paddingonly affects the inner layout: text insets in leaf widgets use their own properties (such astext-padding), notpadding.- Clipped:
ScrollViewclips child nodes beyond the viewport; overlays should be placed outside theScrollView, or leave enough space. - Covered by a sibling: a larger
z-orderdraws later and wins in hit testing; check whether a container covering the whole screen is in front.
Clicks do nothing¶
- Press and release must be inside the same widget. Pressing, dragging out of the widget and then releasing does not count as a click.
- Disabled propagates to the whole subtree. When a parent container has
disabled: true, child buttons receive no input. - Invisible means no hit testing. A node with
visible: falseneither renders nor responds. - No handler. When neither an
onClickscript nor a C++ named callback is registered, a click only produces the hover/press visual change. - A script suppresses the C++ handler of the same name. When the same event has both a script and a named callback, the script runs first and the C++ callback is no longer called.
- An upper node intercepts the hit. A transparent container with a high
z-ordertakes the pointer first as long as its rectangle covers the point.
The text box cannot be typed into¶
TextBoxmust have focus first: click it, or let the focus cycle of the host switch to it.- The host must forward keys to the current
FocusManagerwidget; forwarding the mouse alone is not enough to enter text. - Input beyond
max-length(32 by default) is truncated, not dropped. - When the widget or any ancestor is
disabled, focus does not land there and the keyboard is not received.
The wheel does not scroll¶
- The cursor must be inside the rectangle of the
ScrollView, and the host must hand wheel events toPointerRouter::Wheel. - Nothing scrolls while the content does not exceed the viewport; that is expected behavior.
- When the cursor rests on a disabled row, the wheel keeps looking outward for an enclosing scroll view; if no outer view can scroll either, nothing happens.
Bindings do not refresh¶
| Possible cause | Fix |
|---|---|
| the data key is misspelled | a binding that cannot read gets null with no error; log the result of DataStore::Get to compare |
the array/object inside a Variant was modified directly |
containers are shared by handle and have no mutation API; build a new container and Set it |
| array elements were changed in place | same as above: rebuild the whole array and Set it, so the deep comparison emits a notification |
| a two-way binding was written on a path | only a single identifier (@name) can write back; @item.name is read-only |
the host does not call TickTree / Update every frame |
dynamic binding evaluation and deferred rebuilds both happen during the frame update |
the ForEach data is not set yet |
anything that is not an array (including null) gives 0 rows; the list rebuilds automatically once the data arrives |
Scripts have no effect¶
cannot attach the scriptin the log: the script failed to parse, and the whole block is discarded.- An assignment target can only be a single identifier:
@health,health,$local;@config.volumeor an array index cannot be written. - Scripts have no
for,whileor function definitions; put complex logic in C++. - Division by 0, or a result that is not finite, is normalized to 0;
NaN/Infinityis never written. - A
$variable exists only during this run of the script and is not kept until the next event.
Images do not show¶
- Game texture names and disk files are distinguished by suffix:
textures/ui/iconuses game assets,textures/ui/icon.pnguses the mod directory. Getting the wrong form lands you on a placeholder box. - Disk images support only
.pngand.tga, and must be inside the directory given toSetRootPath. - On the first load the resource pack may not be ready yet; the widget draws a placeholder box first and retries on later frames. A
packed imagelog line means the import succeeded. - Images are stretched to the widget rectangle without proportional cropping; adjust
width/heightwhen the aspect ratio is wrong.
The list is empty or its row content does not change¶
data:onForEachmust evaluate to an array; objects, strings andnullare all treated as an empty list.- The
item/indexnames in the row template are determined by the parameters and default toitem/index; after renaming them, use the new names in the template too. - After the array changes, the rebuild is scheduled for the
Updateof the next frame, so new rows are not visible immediately within the same frame. - The row limit is 512, and truncation beyond it is logged.
Animations do not run¶
- The
@keyframesname must match the one written inanimation:exactly (case-sensitive); when the name does not exist, nothing plays and no message is shown. - Keyframes support only
opacityandtransform: scale/scale; other properties are not interpolated even if written. transitiononly takes effect onbackground,color,border-colorandopacity, and only fires when such a property changes because of a binding or a dynamic value.- Hover, press and disabled state colors switch instantly and do not go through
transition; for a smooth change, drive a plainbackgroundfrom a binding. - The host must call
TickTree(root, deltaTime)with the real frame delta, and the delta is limited to a reasonable range.
Known limitations¶
- Expressions have no
&&,||or function calls; aggregate compound conditions with nested ternaries or in C++. - There is no built-in "list delta update" beyond the configurator:
ForEachrebuilds all rows each time and does not reuse rows by key. - Scripts cannot write field paths or array elements, only single identifiers.
Componentcannot be instantiated recursively; component nesting is limited to 32, document node nesting to 64.- There is only a uniform
padding, no per-side padding. options:onDropdownis comma-separated, and the option text itself cannot contain a comma.TextBoxis single-line input with a default limit of 32 characters.- Images accept only
.png/.tga, and must be inside the mod directory. - HTML/CSS/JavaScript is not rendered, and the game's native menus are not taken over.
What to include when reporting a problem¶
- The complete lines from the log starting with
error:/warning:, with file, line and column. - The
.silsnippet of the failing node (unrelated properties may be removed). - How the host calls
TickTree,Update,RenderandFlushDrawsevery frame. - The framework and game versions, and whether the problem appears on the first load or after
ReloadUI.