HTML UI Debugger

The HTML UI Debugger is an interactive tool for inspecting and manipulating the game's User Interface. It provides a visual tree view of all components, making it easier to understand hierarchies than using console commands alone.

Experimental Feature

This tool is highly experimental. While functional, bugs and unexpected behavior are to be expected. Feedback, bug reports, and suggestions are highly welcome and critical for the tool's refinement.

Please report issues on the GitHub Repository.

Recommended Tool

This is the standard way to debug UI in Rome II, Attila, and ToB as of version 0.8.0. It provides a live view of the UI state and allows for direct interaction with components.

Launching the Debugger

To open the debugger, type the following command in the Consul console:

/debug_html

This will generate the necessary debugger files and automatically open the interface in your default web browser.

Safe Path

To bypass browser security restrictions (which block access to Program Files), the debugger now saves all state and command files to a "neutral" system location: C:\Users\Public\consul\<GAME>\uidebug

Connecting the Debugger

Because the debugger runs as a web page, it requires permission to read the state files generated by the game.

1. Copy the Path: In the browser window, look for STEP 1. Click the dashed box to copy the expected debug path to your clipboard.
2. Click Connect: Click the Connect to Folder button (STEP 2).
3. Paste & Select: In the folder picker that appears, paste the path into the address bar at the top and press Enter. Then click Select Folder.
4. Grant Access: Click Select Folder in the browser's security popup.

Key Features

1. Interactive Hierarchy Tree

The sidebar displays the entire UI tree starting from the root.

• Auto-Sync: The debugger automatically highlights the component you are currently hovering over in-game (note: some elements may not trigger this depending on their configuration).
• Auto-Expand: Folders automatically open to show the path to the hovered component.
• Manual Selection: Click any node in the tree to "Lock" the view to that specific component.

2. Property Inspector

The main panel shows all properties of the selected component in real-time.

• Live Updates: Values like Position, Width, and Text update instantly as they change in-game.
• Direct Editing: Change values (like Visible, Priority, or Text) directly in the browser. The changes are sent back to the game immediately.
• Actions: Trigger actions like SimulateClick, DestroyChildren, or Layout with a single click.

3. Lock & Follow Mode

In the inspector header, you can toggle between two modes:

• 🖱️ FOLLOWING MOUSE: (Default) The inspector automatically switches to whatever you hover over in the game.
• 🔒 LOCKED: The inspector stays on the current component, allowing you to move your mouse without losing your place.

4. Global Search

Use the search bar at the top of the sidebar to find components by:

• ID (e.g., button_ok)
• Address (e.g., 0x12345)
• Text content (e.g., "Declare War")
• Tooltip text

Matches are highlighted in the tree, and you can navigate through multiple results using the arrow buttons.

5. Drag and Drop (Hierarchy Manipulation)

You can rearrange the UI hierarchy directly from the tree:

• Adopt: Drag one component onto another to make it a child (calls Adopt in-game).
• Reorder: Drag a component between its siblings to change its index (calls Adopt with an index).

Workflow Tips

Finding IDs for Scripts

Enable the debugger and hover over any element in the game. The ID will instantly appear in the inspector. This is the fastest way to find targets for consul.ui.find("id").

Testing UI States

You can manually change the CurrentState of a component in the inspector to see how it looks in different states (e.g., hover, active, down) without actually interacting with it in-game.

Persistent Customization

• Hide Properties: If there are properties you never use, click the × next to them. This preference is saved in your browser's local storage.
• Restore: Use the "Restore Hidden" button to bring them back.

Capture Toggle (F7 / F5 in ToB)

You can pause the game-side data stream by pressing F7 (or F5 in ToB) in-game. This stops the game from writing updates to the state file, which is useful if you want to freeze the entire debugger state.

How It Works (Technical Overview)

The UI Debugger uses a "File-based Bridge" to communicate between the game engine and your web browser.

1. Game Side (Lua)

The game acts as the Data Provider. When you hover, click, or move components, a Lua script snapshots the UI state and writes it to a local file (consul_debug_ui_state.txt). It also polls a second file (consul_debug_ui_commands.txt) for instructions sent from the browser.

2. Browser Side (JavaScript)

The browser acts as the Interface. When you click "Connect", it uses the File System Access API to monitor the state file. It polls the file for changes every 250ms and updates the visual tree. When you trigger an action in the browser, it writes a command to the command file for the game to execute.

3. The Bridge

The local filesystem serves as the communication layer. This allows for a "live" experience without needing an external web server or complex network protocols, keeping the tool lightweight and compatible with the game's restricted environment.