ui-ugui

• references/scrollview-setup.md

  — Required hierarchy, setup rules, and common failures

Scope

• "proper buttons" → well-configured Button components
• "working UI" → valid hierarchy that renders
• "menu screen" → visual layout only

Critical Rules

• Always use fully qualified type names when creating or referencing UI components

• UnityEngine.UI.Image

  , not

  Image

• UnityEngine.UI.Button

  , not

  Button

• Other namespaces in the project can cause ambiguous type errors

• Always check what currently exists before making changes
• Confirm parent objects exist before adding children
• Verify components are present before modifying properties
• Never assume hierarchy state — query it first

• When fixing issues, make targeted corrections
• Never destroy and recreate entire hierarchies to fix problems — destroyed objects cause null reference cascades
• Prefer identifying the specific broken property and fixing only that over rewriting large sections
• When a fix fails, revert the change before trying an alternative approach

• Make a single change, then verify the result
• Do not batch multiple unrelated modifications
• Be careful not to inadvertently modify or remove adjacent elements when editing a specific one
• If something fails, understand why before trying alternatives
• Avoid "shotgun debugging" with multiple simultaneous changes

• Ensure text is readable by default: When choosing colors, ensure text contrasts with its background — but respect intentional low-contrast uses (disabled states, placeholder text, decorative elements)
• Check visibility for new elements: After creating UI elements, verify they have non-zero size and are within parent bounds. Elements intentionally created hidden (for later toggling, animation, etc.) are fine

• Honor user specifications exactly: When the user provides pixel dimensions, hex colors, positions, spacing, or other exact values, apply them precisely — do not approximate or substitute
• Minimize unrelated changes: When editing, avoid changing properties the user didn't ask about unless a related adjustment is necessary for the fix to work

Conventions

SubmitButton

submit-button

Assets/UI/Inventory/

Assets/Prefabs/UI/

Workflow

1. Verify state — Check what exists in the scene/hierarchy before any action.
2. Analyze — Determine exactly what's needed. No extras.
3. Search — Find existing prefabs, canvases, assets. Don't assume paths.
4. Follow project patterns — Match folder structure and naming.
5. Create or edit — Build structure with proper anchoring, or make targeted edits.
6. Confirm result — Verify the change worked before moving on.

Canvas Setup

Canvas (Screen Space - Overlay or Camera)
├── CanvasScaler (Scale With Screen Size recommended)
├── GraphicRaycaster
└── [UI Content]

• Default to UI Scale Mode "Scale With Screen Size" unless the project has a specific reason for "Constant Pixel Size" (e.g., pixel-art, fixed-resolution targets)
• Reference Resolution: Match project standards (e.g., 1920x1080)
• When creating a Canvas with Screen Space - Camera, read the camera's reference resolution first
• Match Width Or Height: 0.5 (balanced)
• If an existing Canvas uses "Constant Pixel Size", flag it and ask the user before changing
• Prefer anchors and Layout Groups over absolute pixel positions for layout

Layout Components

• When a parent has a Layout Group, it manages child RectTransforms
• Children's anchors and sizeDelta may be overridden by the parent
• Understand whether the parent or child controls size before setting values

• Control Child Size: determines if parent sets child dimensions
• Child Force Expand: determines if children stretch to fill space
• If Control Child Size is off, children must have explicit sizes

• Do not manually set child anchors/size when parent controls them
• Do not add Layout Group to an element that should have fixed size
• Nested Layout Groups require careful configuration of each level
• When layout is wrong, check parent settings before modifying child
• ContentSizeFitter on the same object as a Layout Group that has Control Child Size enabled = conflict
• ContentSizeFitter on a child whose parent has Control Child Size enabled = ContentSizeFitter is overridden (wasted)
• When using ContentSizeFitter with a Layout Group parent, disable Control Child Size on the parent for the relevant axis
• Common pattern: ScrollView Content should have ContentSizeFitter + VerticalLayoutGroup where VLG controls children but ContentSizeFitter sizes the Content itself

• For inventory grids, card layouts
• Cell Size must be set explicitly — children are sized to match
• Constraint controls row/column limits

• Horizontal/Vertical Fit: Preferred Size
• Use on containers that should size to their content
• Requires a layout element or text component to provide preferred size

RectTransform Anchoring

• Set explicit width/height via sizeDelta, or
• Use stretch anchors with proper offsets, or
• Let a parent Layout Group control size (with Control Child Size enabled)

1. Set anchor preset first (corner, edge, or stretch)
2. Then set position/offset values
3. Verify the resulting size is non-zero

• Stretch anchors — for responsive elements that fill available space
• Corner anchors — for fixed-position, fixed-size elements
• Edge anchors — for elements that stretch in one direction only

1. Determine if it's a corner (fixed point), an edge (stretch along one axis), or fill (stretch both axes)
2. Set anchor min and anchor max — for corners these are the same point; for edges/fill they span a range
3. Set pivot to match the anchor point — pivot must align with where the element is anchored, not left at the default (0.5, 0.5). A "top right" element needs pivot at the top-right corner; a "top bar" needs pivot at the top edge center
4. Set position/offset values after anchors and pivot are configured

• Width and height are both greater than zero
• Element is within parent bounds
• Element is not obscured by siblings (check hierarchy order)
• Image component has a sprite or color with alpha > 0

Common Components

Image

RawImage

Text (TMP)

Button

Toggle

Slider

ScrollRect

InputField (TMP)

Best Practices

• Use TextMeshPro for all text (not legacy Text)
• WorldSpace UI that have text should also use Text Mesh Pro, be sure to review the project and import the TMP essentials if they are not present in the project
• If the TextMeshPro Essentials were imported be sure to close the TMP Importer Windows and the Import Unity Package Window once the assets are imported
• Organize hierarchy logically (Header, Content, Footer)
• Use Layout Groups instead of manual positioning where possible
• Set Raycast Target = false on non-interactive images
• Use sprite atlases for performance

EditorApplication.ExecuteMenuItem("Window/TextMeshPro/Import TMP Essential Resources")

AssetDatabase.ImportPackage()

TMP_PackageResourceImporter.ImportResources()

Interaction Readiness

1. EventSystem must exist in the scene (exactly one)
2. GraphicRaycaster must be on the Canvas
3. Raycast Target = true on interactive elements (and false on non-interactive ones to avoid blocking)
4. Button.onClick should be wired (via inspector or script) — only when scripts or logic were requested

Understanding

• Identify the Canvas and its render mode
• Map the parent-child relationships
• Identify which Layout Groups control which children
• Check RectTransform anchor configurations

• "What does this button do?" → Explain component, hierarchy position, event wiring
• "How is this laid out?" → Describe Layout Groups, anchoring, hierarchy
• "Why is this invisible?" → Check size, anchors, parent bounds, component state
• "What controls this element's size?" → Trace Layout Group settings or anchors

Editing

1. Verify the target object exists
2. Identify the specific property or component to change
3. Make the minimal change required
4. Verify the result before proceeding

• Destroying objects cascades to null references elsewhere
• Fix properties in place rather than recreating
• If an element must be removed, update all references first

C# (Only When Requested)

• Use fully qualified UI types to avoid namespace conflicts
• Use

  [SerializeField]

  for inspector references
• Cache component references in Awake()
• Use events/delegates for button callbacks
• Place scripts in same folder as prefabs (follow project patterns)

• Verify referenced objects exist before accessing them
• Handle cases where serialized references may be null
• When wiring up references, confirm the target component is present

Error Recovery

• Identify the exact error or symptom
• Determine the root cause before attempting fixes
• Do not make speculative changes

• Address one issue at a time
• Verify each fix before moving to the next
• Keep track of what was changed

• "Start fresh" strategies destroy working elements along with broken ones
• Rebuilding entire hierarchies creates more problems than it solves
• Prefer surgical fixes to wholesale replacements

• Re-verify the current state of the hierarchy
• Check if previous changes were actually applied
• Consider if the approach itself is wrong rather than the implementation