Add tooltips for building buttons and module selection buttons

bin/app/data/config/buildings.toml

@@ -1,5 +1,6 @@
 [[building]]
 id = "belt"
+tooltip = "Transports items one tile at a time in the direction it faces."
 cost = 2
 player_placeable = true
 construction_time_seconds = 0.2
@@ -7,6 +8,7 @@ surface_mask = ["A>"]
 
 [[building]]
 id = "splitter"
+tooltip = "Splits an incoming item stream between two outputs, with optional per-output filters."
 cost = 3
 player_placeable = true
 construction_time_seconds = 0.5
@@ -14,6 +16,7 @@ surface_mask = ["<A>"]
 
 [[building]]
 id = "tunnel_entry"
+tooltip = "Sends items underground to a matching tunnel exit, letting belts cross."
 cost = 5
 player_placeable = true
 construction_time_seconds = 0.5
@@ -21,6 +24,7 @@ surface_mask = ["A>"]
 
 [[building]]
 id = "tunnel_exit"
+tooltip = "Receives items from a matching tunnel entry and pushes them onward."
 cost = 5
 player_placeable = true
 construction_time_seconds = 0.5
@@ -28,6 +32,7 @@ surface_mask = ["A>"]
 
 [[building]]
 id = "miner"
+tooltip = "Extracts a selected ore from the asteroid; every tile yields any ore."
 cost = 15
 player_placeable = true
 construction_time_seconds = 1
@@ -37,6 +42,7 @@ surface_mask = [
 
 [[building]]
 id = "smelter"
+tooltip = "Melts ore or scrap into basic materials. No recipe selection needed."
 cost = 20
 player_placeable = true
 construction_time_seconds = 1
@@ -47,6 +53,7 @@ surface_mask = [
 
 [[building]]
 id = "assembler"
+tooltip = "Crafts a selected recipe from the production tree into intermediate or final parts."
 cost = 35
 player_placeable = true
 construction_time_seconds = 1
@@ -57,6 +64,7 @@ surface_mask = [
 
 [[building]]
 id = "reprocessing_plant"
+tooltip = "Consumes scrap and yields one random higher-tier product per cycle."
 cost = 40
 player_placeable = true
 construction_time_seconds = 1
@@ -68,6 +76,7 @@ surface_mask = [
 
 [[building]]
 id = "shipyard"
+tooltip = "Builds autonomous combat ships from a selected schematic and module layout."
 cost = 60
 player_placeable = true
 construction_time_seconds = 1
@@ -78,6 +87,7 @@ surface_mask = [
 
 [[building]]
 id = "salvage_bay"
+tooltip = "Drop-off point where salvage ships unload collected scrap onto belts."
 cost = 25
 player_placeable = true
 construction_time_seconds = 1

bin/app/data/config/modules.toml

@@ -32,6 +32,7 @@
 
 [[module]]
 id = "railgun_s"
+tooltip = "Small railgun. Fast-firing, short range, low damage; fits any hull."
 unlock_at_station_level = -1
 surface_mask = ["O"]
 materials = [{item = "railgun_s_module", amount = 1}]
@@ -47,6 +48,7 @@ attack_rate_hz = 2.0
 
 [[module]]
 id = "railgun_m"
+tooltip = "Medium railgun. Higher damage at longer range; needs a 2x2 slot."
 unlock_at_station_level = 2
 surface_mask = [
     "OO",
@@ -64,6 +66,7 @@ attack_rate_hz = 1.5
 
 [[module]]
 id = "railgun_l"
+tooltip = "Large railgun. Heavy damage at long range; needs a 3x3 slot."
 unlock_at_station_level = 6
 unlock_requires = ["railgun_m"]
 surface_mask = [
@@ -86,6 +89,7 @@ attack_rate_hz = 0.8
 
 [[module]]
 id = "salvager"
+tooltip = "Collects scrap from wrecks and stores it in the ship's cargo hold."
 unlock_at_station_level = -1
 surface_mask = ["O"]
 materials = [{item = "salvager_module", amount = 1}]
@@ -101,6 +105,7 @@ collection_rate_hz = 0.5
 
 [[module]]
 id = "repair_tool"
+tooltip = "Repairs damaged friendly ships and defence stations within range."
 unlock_at_station_level = 0
 surface_mask = ["O"]
 materials = [{item = "repair_tool_module", amount = 1}]
@@ -119,6 +124,7 @@ repair_range_m = 80
 
 [[module]]
 id = "afterburner"
+tooltip = "Greatly boosts top speed and forward acceleration."
 unlock_at_station_level = 2
 surface_mask = ["OOO"]
 materials = [{item = "afterburner_module", amount = 1}]
@@ -133,6 +139,7 @@ added_main_acceleration_mpss = 60
 
 [[module]]
 id = "maneuvering_thrusters"
+tooltip = "Improves top speed and lateral/braking acceleration."
 unlock_at_station_level = 1
 surface_mask = ["OO"]
 materials = [{item = "maneuvering_thrusters_module", amount = 1}]
@@ -150,6 +157,7 @@ added_maneuvering_acceleration_mpss = 10
 
 [[module]]
 id = "armor_plates"
+tooltip = "Adds a large flat bonus to the ship's hit points."
 unlock_at_station_level = 0
 surface_mask = ["OO"]
 materials = [{item = "armor_plates_module", amount = 1}]
@@ -163,6 +171,7 @@ added_hp = 1200
 
 [[module]]
 id = "sensor_booster"
+tooltip = "Extends the ship's sensor range."
 unlock_at_station_level = 1
 surface_mask = ["OO"]
 materials = [{item = "sensor_booster_module", amount = 1}]
@@ -179,6 +188,7 @@ added_sensor_range_m = 50
 
 [[module]]
 id = "weapon_upgrade"
+tooltip = "Increases the damage of all weapons on the ship."
 unlock_at_station_level = 4
 surface_mask = [
     "OO",
@@ -195,6 +205,7 @@ multiplied_damage = 1.2
 
 [[module]]
 id = "weapon_primer"
+tooltip = "Increases the fire rate of all weapons on the ship."
 unlock_at_station_level = 4
 surface_mask = [
     "OO",
@@ -211,6 +222,7 @@ multiplied_attack_rate_hz = 1.2
 
 [[module]]
 id = "weapon_stabilizer"
+tooltip = "Extends weapon range at the cost of some fire rate."
 unlock_at_station_level = 3
 surface_mask = [
     "OO",
@@ -234,6 +246,7 @@ multiplied_attack_rate_hz = 0.8
 
 [[module]]
 id = "drone_bay"
+tooltip = "Drone launch bay (capability not yet implemented)."
 unlock_at_station_level = 5
 surface_mask = [
     "OO",
@@ -246,6 +259,7 @@ glyph = "Db"
 
 [[module]]
 id = "drone_hangar"
+tooltip = "Large drone hangar (capability not yet implemented)."
 unlock_at_station_level = 9
 surface_mask = [
     "OOOOOO",

bin/test/data/config/buildings.toml

@@ -84,6 +84,7 @@ cost = 25
 player_placeable = true
 construction_time_seconds = 15
 output_buffer_capacity = 20
+tooltip = "Drop-off point for salvage ships."
 surface_mask = [
   "SAA",
   "SAA>",

bin/test/data/config/modules.toml

@@ -1,5 +1,6 @@
 [[module]]
 id = "armor_plate"
+tooltip = "Adds a large flat bonus to hit points."
 unlock_at_station_level = -1
 surface_mask = ["OO"]
 materials = [{item = "iron_ingot", amount = 2}]

docs/requirements.md

@@ -5,10 +5,10 @@
 Config files use the TOML format. The following config files drive game parameters:
 
 - **world.toml** — world dimensions, region widths, expansion amounts, building refund percentage, wave timing, boss wave timing, belt speed, starting building blocks, departure interval, ship orbit factor, rally orbit radius, scrap-per-threat conversion, combat target-selection parameters (target score formula, overclaim penalty formula, target hysteresis), artifact chance formula, artifact win count, and view pan speeds (slow and fast horizontal pan speed and pan ramp band width).
-- **buildings.toml** — building block cost and construction time per building type.
+- **buildings.toml** — building block cost and construction time per building type, plus an optional tooltip description string per building type (shown as the build button's hover tooltip, REQ-UI-BUILD-TOOLTIP; omitted when unset).
 - **recipes.toml** — crafting recipes: inputs, outputs, quantities, durations, and reprocessing plant probabilities. Assembler recipe entries may optionally define `unlock_at_station_level` (integer): -1 means the recipe is explicitly unlocked at game start; a value ≥ 0 means the recipe starts locked and a schematic for it can be awarded via defence station destruction (see REQ-LOCK-EXPLICIT, REQ-DEF-SCHEMATIC-DROP). An assembler recipe schematic entry may also define an optional `unlock_requires` list of prerequisite schematic ids (REQ-LOCK-PREREQ).
 - **ships.toml** — per schematic: a human-readable display name (used in the UI), hull stats (HP, max linear speed, sensor range, main acceleration, maneuvering acceleration, angular acceleration, max rotation speed) as plain values, required build materials, the station level at which the schematic becomes available for unlock (`unlock_at_station_level`; -1 means the player starts with the schematic already unlocked), an optional `unlock_requires` prerequisite list (REQ-LOCK-PREREQ), a layout grid defining the ship's module slots, and a `default_modules` list used for enemy wave ships (see REQ-WAV-DEFAULT-MODULES).
-- **modules.toml** — per module type: id, surface mask, materials list, production time, fill color, glyph, the station level at which the schematic becomes available for unlock (`unlock_at_station_level`; -1 means the player starts with the module schematic already unlocked), an optional `unlock_requires` prerequisite list (REQ-LOCK-PREREQ), and an optional capability section and/or stat modifier formulas. A module with a capability section (`[module.weapon]`, `[module.salvage]`, or `[module.repair]`) containing base stat formulas is a **capability module** that grants the ship a weapon, salvage bay, or repair tool per instance (see REQ-MOD-CONFIG for the full list of formulas per capability type). A module with only `added_*`/`multiplied_*` formulas is a **passive module** that modifies stats on the ship or on capability module instances (see REQ-MOD-STAT-CALC).
+- **modules.toml** — per module type: id, surface mask, materials list, production time, fill color, glyph, an optional tooltip description string (shown as the module selection button's hover tooltip, REQ-MOD-UI-MODULE-TOOLTIP; omitted when unset), the station level at which the schematic becomes available for unlock (`unlock_at_station_level`; -1 means the player starts with the module schematic already unlocked), an optional `unlock_requires` prerequisite list (REQ-LOCK-PREREQ), and an optional capability section and/or stat modifier formulas. A module with a capability section (`[module.weapon]`, `[module.salvage]`, or `[module.repair]`) containing base stat formulas is a **capability module** that grants the ship a weapon, salvage bay, or repair tool per instance (see REQ-MOD-CONFIG for the full list of formulas per capability type). A module with only `added_*`/`multiplied_*` formulas is a **passive module** that modifies stats on the ship or on capability module instances (see REQ-MOD-STAT-CALC).
 - **stations.toml** — HP, damage, range, fire rate, and scrap drop for player and enemy defence stations, defined as formulas of station level.
 - **visuals.toml** — rendering-only config (not game parameters): fill and outline colors and glyphs for every building type, item type, ship schematic, and station type; a distinct beam color per tool type (weapon, repair, salvage) and beam width; overlay and toast colors. Loaded by the UI at startup; the simulation does not read it.
 - **ship_layouts.toml** — named layout blueprints per ship type; written and read by the application to persist the layout blueprint panel (REQ-MOD-UI-BLUEPRINT-PANEL through REQ-MOD-UI-BLUEPRINT-FILE-LOAD). Not a game parameter file; the simulation does not read it.
@@ -269,6 +269,8 @@ Modules in `modules.toml` define a `surface_mask` — a list of strings that des
   - **Right** (below the grid): The layout blueprint panel (see REQ-MOD-UI-BLUEPRINT-PANEL through REQ-MOD-UI-BLUEPRINT-FILE-LOAD).
   - **Bottom**: A "Confirm" button and a "Cancel" button. Cancel discards all changes made in this dialog session and closes the dialog. Confirm applies the changes: the shipyard's configured layout is updated, the required materials and cycle time displayed in the selected building panel are recalculated, and the ship layout preview is refreshed.
 
+- REQ-MOD-UI-MODULE-TOOLTIP: Each module selection button in the layout configuration dialog (REQ-MOD-UI-DIALOG) shows a hover tooltip with the descriptive text defined for that module type in `modules.toml` (the optional per-module tooltip field). If a module type defines no tooltip text, its button shows no tooltip. The "Remove" button is not a module type and has no config-defined tooltip.
+
 - REQ-MOD-UI-STATS-PANEL: The **ship stats panel** in the layout configuration dialog shows the stats of the currently configured ship layout as they would be computed, incorporating all passive module modifiers per REQ-MOD-STAT-CALC. The panel updates in real time whenever modules are placed or removed in the layout grid.
 
   The panel always shows all hull stats as final computed values:
@@ -473,6 +475,7 @@ The screen is divided into two columns: a main column (75% width) containing the
 
 - REQ-UI-BUILD-GRID: All placeable building types are shown as a flat grid of buttons with no grouping.
 - REQ-UI-BUILD-COST: Each button caption shows the building name and its building block cost, e.g. "Belt: 2 Blocks".
+- REQ-UI-BUILD-TOOLTIP: Each building-type button shows a hover tooltip with the descriptive text defined for that building type in `buildings.toml` (the optional per-building tooltip field). This tooltip is distinct from the recipe/schematic selection tooltip (REQ-UI-SELECT-TOOLTIP). If a building type defines no tooltip text, its button shows no tooltip. The Demolish button (REQ-UI-DEMOLISH-BUTTON) is not a building type and has no config-defined tooltip.
 - REQ-UI-BUILD-DISABLED: Buttons for buildings the player cannot currently afford are shown as disabled.
 - REQ-UI-DEMOLISH-BUTTON: A dedicated **Demolish** button is shown in the build button grid. Clicking it toggles demolish mode on and off, equivalent to the Q demolish toggle (REQ-UI-HOTKEYS). The button is shown in a visually active/pressed state while demolish mode is active.
 

src/lib/config/BuildingsConfig.h

@@ -23,6 +23,9 @@ struct BuildingDef
     // Output-buffer holding size for buildings without a recipe-driven buffer.
     // Only the Salvage Bay sets this (REQ-BLD-SALVAGE-BAY).
     std::optional<int> outputBufferCapacity;
+
+    // Optional hover-tooltip text for the build button (REQ-UI-BUILD-TOOLTIP).
+    std::optional<std::string> tooltip;
 };
 
 struct BuildingsConfig

src/lib/config/ConfigLoader.cpp

@@ -343,6 +343,11 @@ BuildingsConfig ConfigLoader::loadBuildings(const std::string& path)
                 requireInt(mt["output_buffer_capacity"], file, elemPath + ".output_buffer_capacity"));
         }
 
+        if (mt.contains("tooltip"))
+        {
+            def.tooltip = requireString(mt["tooltip"], file, elemPath + ".tooltip");
+        }
+
         const std::optional<BuildingType> parsedType = parseBuildingType(def.id);
         if (!parsedType)
         {
@@ -603,6 +608,11 @@ ModulesConfig ConfigLoader::loadModules(const std::string& path)
         def.fillColor             = requireString(mt["fill_color"], file, elemPath + ".fill_color");
         def.glyph                 = requireString(mt["glyph"], file, elemPath + ".glyph");
 
+        if (mt.contains("tooltip"))
+        {
+            def.tooltip = requireString(mt["tooltip"], file, elemPath + ".tooltip");
+        }
+
         // Materials
         {
             const toml::array& materials = requireArray(mt["materials"], file, elemPath + ".materials");

src/lib/config/ModulesConfig.h

@@ -54,6 +54,10 @@ struct ModuleDef
     std::optional<ModuleWeaponCapability>  weaponCapability;
     std::optional<ModuleSalvageCapability> salvageCapability;
     std::optional<ModuleRepairCapability>  repairCapability;
+
+    // Optional hover-tooltip text for the module selection button
+    // (REQ-MOD-UI-MODULE-TOOLTIP).
+    std::optional<std::string> tooltip;
 };
 
 struct ModulesConfig

src/test/ConfigLoaderTest.cpp

@@ -113,6 +113,12 @@ TEST_CASE("ConfigLoader loads the committed bin/config/ configs end-to-end", "[c
     REQUIRE(salvageBayIt->outputBufferCapacity.has_value());
     REQUIRE(*salvageBayIt->outputBufferCapacity == 20);
 
+    // Optional per-building tooltip (REQ-UI-BUILD-TOOLTIP): the Salvage Bay
+    // defines one; the Miner leaves it unset.
+    REQUIRE(salvageBayIt->tooltip.has_value());
+    REQUIRE(*salvageBayIt->tooltip == "Drop-off point for salvage ships.");
+    REQUIRE_FALSE(minerIt->tooltip.has_value());
+
     // recipes.toml — reprocessing cycle has three weighted outputs.
     const auto reproIt = std::find_if(
         cfg.recipes.recipes.begin(), cfg.recipes.recipes.end(),
@@ -144,6 +150,21 @@ TEST_CASE("ConfigLoader loads the committed bin/config/ configs end-to-end", "[c
     REQUIRE(salvageShipIt != cfg.ships.ships.end());
     REQUIRE(salvageShipIt->defaultModules.empty());
 
+    // modules.toml — optional per-module tooltip (REQ-MOD-UI-MODULE-TOOLTIP):
+    // armor_plate defines one; salvager leaves it unset.
+    const auto armorPlateIt = std::find_if(
+        cfg.modules.modules.begin(), cfg.modules.modules.end(),
+        [](const ModuleDef& m) { return m.id == "armor_plate"; });
+    REQUIRE(armorPlateIt != cfg.modules.modules.end());
+    REQUIRE(armorPlateIt->tooltip.has_value());
+    REQUIRE(*armorPlateIt->tooltip == "Adds a large flat bonus to hit points.");
+
+    const auto salvagerModuleIt = std::find_if(
+        cfg.modules.modules.begin(), cfg.modules.modules.end(),
+        [](const ModuleDef& m) { return m.id == "salvager"; });
+    REQUIRE(salvagerModuleIt != cfg.modules.modules.end());
+    REQUIRE_FALSE(salvagerModuleIt->tooltip.has_value());
+
     // stations.toml
     REQUIRE(cfg.stations.playerStation.level == 5);
     REQUIRE(cfg.stations.playerStation.hpFormula.evaluate(5.0) == Approx(500.0));  // 300 + 40*5

src/ui/BuildButtonGrid.cpp

@@ -42,6 +42,10 @@ BuildButtonGrid::BuildButtonGrid(const GameConfig* config, QWidget* parent)
         QPushButton* btn = new QPushButton(label, this);
         btn->setCheckable(true);
         btn->setFixedHeight(48);
+        if (def.tooltip)
+        {
+            btn->setToolTip(QString::fromStdString(*def.tooltip));
+        }
         layout->addWidget(btn, row, col);
 
         const int idx = static_cast<int>(m_buttons.size());

src/ui/ShipLayoutDialog.cpp

@@ -461,6 +461,10 @@ ShipLayoutDialog::ShipLayoutDialog(const GameConfig* config,
         QPushButton* btn = new QPushButton(label, this);
         btn->setCheckable(true);
         btn->setFixedHeight(48);
+        if (def.tooltip)
+        {
+            btn->setToolTip(QString::fromStdString(*def.tooltip));
+        }
         buttonGrid->addWidget(btn, row, col);
         m_moduleButtons.push_back(btn);