draw glyph for output port at the target tile during build mode

bin/app/data/config/world.toml

@@ -11,6 +11,7 @@ departure_interval_seconds = 20
 orbit_factor = 0.8
 rally_orbit_radius_tiles = 5.0
 building_blocks_tooltip = "Building blocks are the currency for construction. Spend them to place buildings and to expand the asteroid. Produce building blocks in your assemblers and deliver them to the HQ on a belt to grow your stock."
+artifact_tooltip = "Artifacts are the key to victory. Earn one by choosing the artifact reward when you destroy a set of enemy defence stations. Collect enough of them to win the game."
 
 [regions]
 asteroid_width_tiles = 60

bin/test/data/config/world.toml

@@ -11,6 +11,7 @@ departure_interval_seconds = 20
 orbit_factor = 0.8
 rally_orbit_radius_tiles = 5.0
 building_blocks_tooltip = "Spend building blocks to build; deliver them to the HQ to gain more."
+artifact_tooltip = "Choose the artifact reward when destroying enemy stations; collect enough to win."
 
 [regions]
 asteroid_width_tiles = 40

docs/requirements.md

@@ -4,7 +4,7 @@
 
 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, view pan speeds (slow and fast horizontal pan speed and pan ramp band width), and an optional building blocks tooltip string (shown as the header bar's building blocks stock hover tooltip, REQ-UI-BLOCKS-TOOLTIP; omitted when unset).
+- **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, view pan speeds (slow and fast horizontal pan speed and pan ramp band width), an optional building blocks tooltip string (shown as the header bar's building blocks stock hover tooltip, REQ-UI-BLOCKS-TOOLTIP; omitted when unset), and an optional artifact tooltip string (shown as the header bar's artifact count hover tooltip, REQ-UI-ARTIFACTS-TOOLTIP; omitted when unset).
 - **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).
@@ -424,6 +424,7 @@ The screen is divided into two columns: a main column (75% width) containing the
 
 - REQ-UI-HEADER: The header bar spans the width of the game world column (75% of the screen width) and always shows the elapsed survival time, the current global building blocks stock, and the artifact count (REQ-WIN-ARTIFACT-COUNT) displayed as `Artifacts: x/y` (where `x` is the current artifact count and `y` is `world.toml [world].artifact_win_count`) on the left, the boss wave counter and boss countdown (REQ-UI-BOSS-STATUS) and an asteroid expansion button (REQ-UI-EXPAND-BUTTON) to the left of the speed buttons, and game speed controls on the right.
 - REQ-UI-BLOCKS-TOOLTIP: The header bar's building blocks stock display (REQ-UI-HEADER) shows a hover tooltip with the descriptive text defined in `world.toml [world].building_blocks_tooltip` — intended to tell the player what building blocks are used for and how to obtain them. If the field is unset, the stock display shows no tooltip. This tooltip is distinct from the build/module button tooltips (REQ-UI-BUILD-TOOLTIP, REQ-MOD-UI-MODULE-TOOLTIP).
+- REQ-UI-ARTIFACTS-TOOLTIP: The header bar's artifact count display (REQ-UI-HEADER) shows a hover tooltip with the descriptive text defined in `world.toml [world].artifact_tooltip` — intended to tell the player what artifacts are, how they are obtained (REQ-DEF-SCHEMATIC-DROP), and that collecting `world.toml [world].artifact_win_count` of them wins the game (REQ-WIN-ARTIFACT-COUNT). If the field is unset, the artifact count display shows no tooltip. This tooltip is distinct from the building blocks tooltip (REQ-UI-BLOCKS-TOOLTIP) and the build/module button tooltips (REQ-UI-BUILD-TOOLTIP, REQ-MOD-UI-MODULE-TOOLTIP).
 - REQ-UI-BOSS-STATUS: The header bar displays, to the left of the speed buttons, the current boss wave counter (REQ-WAV-BOSS-COUNTER) and the time remaining on the boss countdown (REQ-WAV-BOSS-COUNTDOWN). The boss wave counter is shown as `Boss Wave #<x>` and the countdown as `Next boss: <M:SS>`, where `<M:SS>` is the remaining seconds formatted as whole minutes and two-digit seconds. Both values update continuously as the simulation runs.
 - REQ-UI-SPEED: The game speed controls in the header bar are buttons for 0×, 0.5×, 1×, 2×, and 10× speed. The currently active speed is shown as selected. All game simulation (production, movement, threat accumulation, wave timing) scales with the selected speed. 0× pauses the game.
 - REQ-UI-PAUSE-BORDER: While the game is paused (speed 0×, whether set via the speed controls (REQ-UI-SPEED), the Space toggle (REQ-UI-HOTKEYS), or an auto-pausing modal), a vignette border is drawn around the edges of the game world view to make the paused state hard to miss. The border is black and fades in the alpha channel from fully transparent at its inner (center-facing) edge to 50% opacity at the viewport edge, over a thickness of 100 pixels (capped at half the smaller viewport dimension on very small views).
@@ -444,6 +445,7 @@ The screen is divided into two columns: a main column (75% width) containing the
   Because the contest-zone boundaries shift as the scrollable area grows with each push (REQ-GW-PUSH-EXPAND, REQ-GW-SCROLL-LIMIT), the ramp bands are recomputed from the current contest-zone boundaries. This is a presentation-only concern and does not affect the simulation, consistent with REQ-UI-NO-ZOOM.
 - REQ-UI-CONSTRUCTION-PROGRESS: Construction sites display the building's glyph centered on the footprint (same as an operational building). Below the glyph — or centered on the footprint if the building has no glyph — a construction progress percentage is shown (integer, e.g. `42%`), increasing from 0% to 100% as construction completes.
 - REQ-UI-PORT-GLYPH: Every output port of every building is indicated by a directional glyph drawn on the port's tile. The glyph is a `>` rotated to face the port's exit direction (`>` for East, `^` for North, `<` for West, `v` for South). It is drawn at the midpoint between the tile center and the tile edge that the port exits through (i.e. halfway from center toward the exit edge). The indicator is rendered for all building states: operational buildings, construction sites, and the builder-mode ghost. Buildings with multiple output ports (e.g. splitters) show one indicator per port.
+- REQ-UI-PORT-TARGET-GLYPH: While in builder mode (REQ-BLD-BUILDER-MODE), the builder-mode ghost additionally shows, for each of the building's output ports, a directional glyph drawn centered in the port's **target cell** — the cell immediately outside the footprint that the port pushes into, i.e. the cell the surface-mask output-port indicator occupies (see Surface Mask Format). As in REQ-UI-PORT-GLYPH the glyph is a `>` rotated to face the port's exit direction (`>` East, `^` North, `<` West, `v` South), previewing where the port's output will go before placement. This is in addition to the on-tile port glyph of REQ-UI-PORT-GLYPH, and — unlike that indicator — is shown only for the builder-mode ghost, not for operational buildings, construction sites, or the blueprint-placement ghost (REQ-UI-BLUEPRINT-PLACE). A building with multiple output ports (e.g. a splitter) shows one target-cell glyph per port. The target-cell glyph is drawn larger than the on-tile port glyph so it stands out as the flow-direction preview. Exceptions: the Tunnel Entry shows no target-cell glyph, because it receives items (which may arrive from any of its non-mouth edges, REQ-BLD-TUNNEL-ENTRY) rather than emitting into a single adjacent cell; the Shipyard shows none either, because its output port is a ship-spawn point (REQ-SHP-SPAWN-PLAYER) rather than a belt-item output (REQ-MAT-OUTPUT-EMERGE).
 - REQ-UI-HP-BARS: All entities with HP — the HQ, player and enemy defence stations, and player and enemy ships — render an HP bar below them. The bar is always visible regardless of current HP. The bar's filled portion represents the fraction of current HP to maximum HP.
 - REQ-UI-NO-ZOOM: The view has a fixed zoom level; the player cannot zoom in or out.
 - REQ-UI-HOTKEYS: Global keyboard shortcuts:

src/lib/config/ConfigLoader.cpp

@@ -279,6 +279,12 @@ WorldConfig ConfigLoader::loadWorld(const std::string& path)
         cfg.buildingBlocksTooltip = *tip;
     }
 
+    if (const std::optional<std::string> tip =
+            tbl["world"]["artifact_tooltip"].value<std::string>())
+    {
+        cfg.artifactTooltip = *tip;
+    }
+
     cfg.regions.asteroidWidth_tiles     = static_cast<int>(requireInt(tbl["regions"]["asteroid_width_tiles"],      file, "regions.asteroid_width_tiles"));
     cfg.regions.playerBufferWidth_tiles = static_cast<int>(requireInt(tbl["regions"]["player_buffer_width_tiles"], file, "regions.player_buffer_width_tiles"));
     cfg.regions.contestZoneWidth_tiles  = static_cast<int>(requireInt(tbl["regions"]["contest_zone_width_tiles"],  file, "regions.contest_zone_width_tiles"));

src/lib/config/WorldConfig.h

@@ -82,6 +82,10 @@ struct WorldConfig
     // (REQ-UI-BLOCKS-TOOLTIP). Presentation-only; the simulation ignores it.
     std::optional<std::string> buildingBlocksTooltip;
 
+    // Optional hover-tooltip for the header artifact count display
+    // (REQ-UI-ARTIFACTS-TOOLTIP). Presentation-only; the simulation ignores it.
+    std::optional<std::string> artifactTooltip;
+
     WorldRegions regions;
     WorldExpansion expansion;
     WorldPush push;

src/test/ConfigLoaderTest.cpp

@@ -88,6 +88,11 @@ TEST_CASE("ConfigLoader loads the committed bin/config/ configs end-to-end", "[c
     REQUIRE(*cfg.world.buildingBlocksTooltip ==
             "Spend building blocks to build; deliver them to the HQ to gain more.");
 
+    // Optional header artifact tooltip (REQ-UI-ARTIFACTS-TOOLTIP).
+    REQUIRE(cfg.world.artifactTooltip.has_value());
+    REQUIRE(*cfg.world.artifactTooltip ==
+            "Choose the artifact reward when destroying enemy stations; collect enough to win.");
+
     // Spot-check that a config-derived formula computes as expected.
     // threat_rate_formula = "x": evaluates to the input value.
     REQUIRE(cfg.world.waves.threatRateFormula.evaluate(1.0) == Approx(1.0));

src/ui/GameWorldView.cpp

@@ -895,31 +895,39 @@ void GameWorldView::placeAtTile(QPoint tile)
 // Port glyph helper
 // ---------------------------------------------------------------------------
 
-void GameWorldView::drawPortGlyph(QPainter& painter, QPoint bodyTile,
-                                   Rotation direction, const QColor& color)
+void GameWorldView::drawPortGlyph(QPainter& painter, QPoint tile,
+                                   Rotation direction, const QColor& color,
+                                   bool centered)
 {
     const float px = getTilePx();
-    const QRectF tr = tileRect(bodyTile);
+    const QRectF tr = tileRect(tile);
     const QPointF center(tr.x() + static_cast<qreal>(px) * 0.5,
                          tr.y() + static_cast<qreal>(px) * 0.5);
 
-    QPointF offset;
+    QPointF edgeOffset;
     const char* ch;
     switch (direction)
     {
-    case Rotation::East:  offset = QPointF(px * 0.25f,  0);       ch = ">"; break;
-    case Rotation::West:  offset = QPointF(-px * 0.25f, 0);       ch = "<"; break;
-    case Rotation::North: offset = QPointF(0,  -px * 0.25f);      ch = "^"; break;
-    case Rotation::South: offset = QPointF(0,   px * 0.25f);      ch = "v"; break;
+    case Rotation::East:  edgeOffset = QPointF(px * 0.25f,  0);   ch = ">"; break;
+    case Rotation::West:  edgeOffset = QPointF(-px * 0.25f, 0);   ch = "<"; break;
+    case Rotation::North: edgeOffset = QPointF(0,  -px * 0.25f);  ch = "^"; break;
+    case Rotation::South: edgeOffset = QPointF(0,   px * 0.25f);  ch = "v"; break;
     default:              return;
     }
 
-    const qreal half = static_cast<qreal>(px) * 0.3;
+    // Centered glyphs sit in the middle of the tile (used for a port's target
+    // cell, REQ-UI-PORT-TARGET-GLYPH) and are drawn 150% larger to stand out;
+    // otherwise offset toward the exit edge of the port's body tile
+    // (REQ-UI-PORT-GLYPH).
+    const QPointF offset = centered ? QPointF(0.0, 0.0) : edgeOffset;
+    const qreal glyphScale = centered ? 1.5 : 1.0;
+
+    const qreal half = static_cast<qreal>(px) * 0.3 * glyphScale;
     const QPointF pos = center + offset;
     const QRectF textRect(pos.x() - half, pos.y() - half, half * 2.0, half * 2.0);
 
     QFont f = painter.font();
-    f.setPixelSize(std::max(6, static_cast<int>(px * 0.4f)));
+    f.setPixelSize(std::max(6, static_cast<int>(px * 0.4f * glyphScale)));
     painter.setFont(f);
     painter.setPen(color);
     painter.drawText(textRect, Qt::AlignCenter, QString::fromLatin1(ch));
@@ -991,7 +999,7 @@ void GameWorldView::drawBuildings(QPainter& painter)
         for (const Port& port : b.outputPorts)
         {
             drawPortGlyph(painter, portBodyTile(port.tile, port.direction),
-                          port.direction, bv.outline);
+                          port.direction, bv.outline, /*centered*/ false);
         }
 
         // HP bar below the HQ footprint; the HQ's HP lives on its proxy entity.
@@ -1070,7 +1078,8 @@ void GameWorldView::drawBuildings(QPainter& painter)
             {
                 const QPoint absBody = s.anchor
                     + portBodyTile(port.tile, port.direction);
-                drawPortGlyph(painter, absBody, port.direction, bv.outline);
+                drawPortGlyph(painter, absBody, port.direction, bv.outline,
+                              /*centered*/ false);
             }
         }
     }
@@ -1571,7 +1580,8 @@ void GameWorldView::drawOverlays(QPainter& painter)
     if (m_builderType.has_value())
     {
         drawBuildingGhost(painter, *m_builderType, m_ghostTile,
-                          m_ghostRotation, m_ghostValid);
+                          m_ghostRotation, m_ghostValid,
+                          /*showPortTargetGlyphs*/ true);
     }
 
     // Blueprint placement ghost
@@ -1581,7 +1591,8 @@ void GameWorldView::drawOverlays(QPainter& painter)
         {
             const QPoint anchor = m_blueprintGhostTile + bb.offset;
             const bool   valid  = isValidPlacement(bb.type, anchor, bb.rotation);
-            drawBuildingGhost(painter, bb.type, anchor, bb.rotation, valid);
+            drawBuildingGhost(painter, bb.type, anchor, bb.rotation, valid,
+                              /*showPortTargetGlyphs*/ false);
         }
     }
 
@@ -1634,7 +1645,7 @@ void GameWorldView::drawOverlays(QPainter& painter)
 
 void GameWorldView::drawBuildingGhost(QPainter& painter, BuildingType type,
                                       QPoint anchorTile, Rotation rotation,
-                                      bool valid)
+                                      bool valid, bool showPortTargetGlyphs)
 {
     const BuildingDef* def = findBuildingDef(type);
     if (!def) { return; }
@@ -1688,7 +1699,24 @@ void GameWorldView::drawBuildingGhost(QPainter& painter, BuildingType type,
     for (const Port& port : parsed.outputPorts)
     {
         drawPortGlyph(painter, anchorTile + portBodyTile(port.tile, port.direction),
-                      port.direction, lineColor);
+                      port.direction, lineColor, /*centered*/ false);
+    }
+
+    // REQ-UI-PORT-TARGET-GLYPH: while in builder mode, additionally mark each
+    // output port's target cell (the cell just outside the footprint the port
+    // pushes into) with a directional glyph, previewing where output will flow.
+    // The Tunnel Entry is excluded — it receives items from any of its non-mouth
+    // edges rather than emitting into a single adjacent cell. The Shipyard is
+    // excluded too — it spawns a ship rather than emitting a belt item.
+    if (showPortTargetGlyphs
+        && type != BuildingType::TunnelEntry
+        && type != BuildingType::Shipyard)
+    {
+        for (const Port& port : parsed.outputPorts)
+        {
+            drawPortGlyph(painter, anchorTile + port.tile, port.direction,
+                          lineColor, /*centered*/ true);
+        }
     }
 
     painter.setOpacity(1.0);

src/ui/GameWorldView.h

@@ -175,11 +175,13 @@ private:
     std::vector<BuildingId> buildingsInBox(QPoint cornerA, QPoint cornerB) const;
     QVector2D  widgetToWorld(QPoint widgetPt) const;
 
-    void     drawPortGlyph(QPainter& painter, QPoint bodyTile,
-                           Rotation direction, const QColor& color);
+    void     drawPortGlyph(QPainter& painter, QPoint tile,
+                           Rotation direction, const QColor& color,
+                           bool centered);
 
     void     drawBuildingGhost(QPainter& painter, BuildingType type,
-                               QPoint anchorTile, Rotation rotation, bool valid);
+                               QPoint anchorTile, Rotation rotation, bool valid,
+                               bool showPortTargetGlyphs);
 
     void     placeBlueprintAtTile(QPoint center);
 

src/ui/HeaderBar.cpp

@@ -32,6 +32,11 @@ HeaderBar::HeaderBar(const GameConfig* config, QWidget* parent)
             QString::fromStdString(*config->world.buildingBlocksTooltip));
     }
     m_artifactsLabel = new QLabel(tr("Artifacts: 0/?"), this);
+    if (config->world.artifactTooltip)
+    {
+        m_artifactsLabel->setToolTip(
+            QString::fromStdString(*config->world.artifactTooltip));
+    }
     m_bossLabel      = new QLabel(tr("Boss Wave #1  Next boss: 5:00"), this);
     layout->addWidget(m_timeLabel);
     layout->addWidget(m_blocksLabel);