GUI modding

From Imperator Wiki
Revision as of 18:12, 22 October 2019 by Long Game Short (talk | contribs) (reordered a paragraph)
Jump to navigation Jump to search

Imperator's user interaface (UI) is highly moddable, but for this reason UI mods disable achievements, since a player could cheat with them.

The game also includes a powerful GUI editor, making UI modding easier to learn.

Example from Compact Events mod

Modders can:

  • change the visual style of the interface
  • make windows movable and resizable
  • change and remove elements
  • add new buttons
  • show more information from the code

Modders can’t:

  • add new hotkeys (only reuse the existing ones)
  • make multiple windows visible (like Treasury and Trade views at the same time)
  • display information from one window in another, unless it was pre-configured by the developers


Basics

Code from select_office.gui, opened in Visual Studio with the CWTools extension

The interface in Imperator is created through .gui files in the game/gui folder, which are somewhat similar to html files.

As such, you can edit them with a notepad, but a proper text editor is recommended.


Imperator uses .dds files for textures, which are saved inside the game/gfx/ folder.

To edit or save .dds files use either Photoshop with Intel plugin or GIMP with this plugin.

Export with settings set to Alpha with no compression for better results.


There are two important console commands available for UI modding: “reload gui” and “reload texture”, for updating changes to .gui files and .dds files respectively, without restarting the game.

To use the console and the GUI editor, right-click the game on Steam, choose Properties, Set Launch Options, add "-debug_mode -develop" (without quotes).

Use this mod to hide the purple debug tooltip if it gets in the way.


Note, that using the debug mode changes the checksum, so you won’t be able to get achievements. Also, do not load any ironman saves with it, as this will corrupt them.

Creating a GUI mod

Creating gui mod.png

1. Start the game launcher, go to Mods, Mod Tools and fill in all the fields, including tags.

Clicking Create will create a new folder and a .mod file in Documents/Paradox Interactive/Imperator/mod.

2. Next, create a “gui” folder inside this new mod folder and copy the files you want to mod there, from game/gui.

So, to mod the topbar, we will end up with the following: best_topbar_mod/gui/ingame_topbar.gui.

  • If you don’t know which file is needed, enable the mod in the launcher anyway, start the game and use the GUI editor to help locate it.

GUI Editor

GUI editor: Outliner and Properties

GUI Editor is a developer tool for editing the UI right in the game. It is very convenient, but has its limitations and is prone to crashing.

To use it you need to launch the game with -developer and -debug_mode options.

Right-click the game on Steam, choose Properties, Set Launch Options, add "-debug_mode -develop" (without quotes).


To open the editor, either:

  • press Ctrtl+F8
  • open the console with the ` key (below Esc), click 2D Tools at the bottom and choose GUI Editor
  • open the console, type “gui_editor” (without quotes) and press Enter.

The game will freeze when loading it for the first time, don’t be alarmed.

Features

By default the editor starts with the Edit mode enabled. You can disable it in the top window, called Outliner. Hotkey “E”.

  • The edit mode is similar to the Inspect mode in browsers. While it’s enabled you can’t interact with the game, but it allows you to select elements of the UI and change them in the Properties window below.
  • Drag any dev windows to move it. Drag any edge to resize the window.
  • Yellow border indicated the selected element. You can use the scroll wheel to switch between other elements on the screen. Uncheck “Show Hierarchy” in the Outliner to hide other borders (Hotkey “S”).
  • Holding the right mouse button allows you to move the selected element. You can right-click anywhere on the screen, not necessarily on the element.
  • You can change or add new properties (by clicking the plus symbol) in the Properties window.
  • To undo anything you can press Ctrl+Z or the undo button in the Outliner. Redo is next to it, Ctrl+Y.
  • Ctrl+S saves changes to the .gui file.
GUI editor: UI Components


By clicking "Window" in the Outliner, you can open two more windows: UI components and Registered Data Types.

  • UI Components is like a palette from which you can drag new elements to the UI. gui/shared/standard.gui and gui/defaults.gui contain the most common things, like buttons, icons and text.
  • Registered Data Types may be used to look up what functions are available to display dynamic data from the game (like country stability or ruler popularity) or to duplicate some of the existing buttons. Examples below.

Important: pay attention to which .gui file is selected. It is displayed in yellow at the top of the Outliner. If you don’t have a copy of it in your mod, the editor will save changes to the game files!

If your mod is enabled, you can copy the needed files to the mod folder without restarting the game, and continue editing.

If you do accidentally change the game files, you can reset them by validating: right-click the game on Steam, go to Properties, Local Files, Verify Integrity of Game Files.


Also, it is often easy to select a template by mistake, changing which will affect all instances of it in the UI. Blue header in Properties that starts with “Type:” indicates a template, so be careful not to edit this part, unless you intend to.

/todo

Examples

Adding the Timelapse button

Adding text

Adding more stats

Manual editing

Examples

Adding toggles with PdxGuiWidget

Scripted GUIs

Adding toggles

Adding a cheat button

Displaying a variable

Hiding an object

UI components

Containers

Data lists

Objects

Textures

Resources