improve Mayors Seal GUI

Author: dashuaibia

diary/2026-07-28_20-24-14_mayors-seal-cui-gui.md

@@ -0,0 +1,82 @@
+# Mayor's Seal GUI rebuilt on the CUI framework with town statistics
+
+- Time: `2026-07-28 20:24:14 +0800`
+- Author: `Kimi-K3 coding agent`
+- Status: `completed`
+- Scope: `item/townmanager`, `content/town` (data), lang files
+
+## Completed
+
+- Rewrote `item/townmanager/TownManagerScreen` from a vanilla `Screen` (with
+  legacy `chorda.client.widget` buttons and todo-ridden placeholder modes) to a
+  Chorda CUI `PrimaryLayer`, visually matching town building GUIs:
+  `townworkerblock.png` 176x222 frame + left-side `TabImageButtonElement` tabs.
+- Four tabs (`TownManagerTab` subclasses, opened client-only via
+  `CUIScreenWrapper.open`, no container menu):
+  - Town Overview (`TownOverviewTab`, reuses `tabs/TownInfoPanel`): town name,
+    population, building/workable counts, average health/mental,
+    homeless/unemployed counts, day-over-day deltas from history.
+  - Residents (`TownResidentsTab` + `TownResidentsPanel`): scrollable resident
+    list + detail (attributes, education, house/work assignment with localized
+    building names, work proficiencies). Mirrors `TownWorkforcePanel` layout.
+  - Town Buildings (`TownBuildingsTab` + `TownBuildingsPanel`): building list
+    (unworkable shown red) + detail (type, coordinates, workable state with
+    failure reasons, resident capacity via `ITownResidentBuilding`).
+  - Statistics (`TownStatisticsTab` + `TownStatisticsPanel`): three line
+    charts (population auto-scaled; avg health/mental fixed 0-100) with latest
+    value + delta, middle reference line, scale labels, collecting hint when
+    history has fewer than 2 entries.
+- Added `content/town/TownHistoryEntry` (record + Codec): daily snapshot
+  (day, population, avgHealth, avgMental, buildings). `TeamTownData` now keeps
+  up to 30 entries (`MAX_HISTORY_ENTRIES`), recorded at the end of
+  `tickMorning` (same-day settlements overwrite), persisted through the
+  existing CODEC field `history` and synced to clients by the existing
+  per-tick `TeamTownDataS2CPacket` full sync. `TeamTown#getHistory` exposes it.
+- `TownManagerClientHelper.openScreen()` now opens via `CUIScreenWrapper`.
+- Added `gui.frostedheart.town_manager.*` keys (zh_cn + en_us), including
+  per-building-type names under `...town_manager.building.*` with
+  `translatableWithFallback` fallback to the class simple name.
+
+## Decisions
+
+- History rides the existing full-data sync instead of a new packet: 30 small
+  entries are negligible and no sync cadence changes were needed.
+- Item GUI stays client-only (no Menu/NetworkHooks) because the seal is a
+  read-only observer; this matches how the old screen and EditUtils work.
+- Panels read fresh data through `Supplier<TeamTown>/Supplier<TeamTownData>`
+  every render, so the GUI follows sync updates live; selection is normalized
+  by UUID/BlockPos when entries disappear.
+- Old `town_manage_screen.png` texture is now unreferenced but left in the
+  asset tree untouched.
+
+## Validation
+
+- `JAVA_HOME='C:\Program Files\Java\jdk-17' ./gradlew build --offline` passed.
+  NOTE: system JAVA_HOME points to JDK 11 and makes Gradle worker daemons
+  crash with `GradleWorkerMain` ClassNotFoundException; always set JDK 17.
+- Both lang JSON files parse; `git diff --check` clean.
+- No references to the removed old screen API remain.
+
+## Remaining
+
+- Not run in game: verify tab hit areas, scrollbar feel, chart readability,
+  and text widths at common GUI scales.
+- Statistics need two daily settlements before charts appear (by design).
+- Pre-existing issue noticed but untouched: `TeamTownData` codec constructor
+  ignores the decoded `labour`/`maxLabour` (assigns 0), so labour values reset
+  on save reload.
+
+## Follow-up: HouseBuilding resident count fix (20:51)
+
+`TownBuildingsPanel` initially used `ITownResidentBuilding.getResidentsID()` to
+display resident counts. HouseBuilding's CODEC does not serialize
+`residentsUUID` (only `maxResident`; the `HouseMenu` works around this by
+filtering `Resident.housePos`). This caused houses to always show 0/X on the
+client. Fixed by counting residents in the position-based way:
+
+```
+boolean isHouse = !(building instanceof ITownResidentWorkBuilding);
+for (Resident r : town.getAllResidents())
+    if (pos.equals(isHouse ? r.getHousePos() : r.getWorkPos()))
+        count++;
+```

src/main/java/com/teammoeg/frostedheart/content/town/TeamTown.java

@@ -221,6 +221,16 @@ public TeamTownResourceHolder getResourceHolder() {
         return data.resources;
     }
 
+    /**
+     * Get the daily snapshot history of the town, newest entry last.
+     * Used by information GUIs such as the Mayor's Seal.
+     *
+     * @return unmodifiable view is not guaranteed; treat as read-only
+     */
+    public List<TownHistoryEntry> getHistory() {
+        return data.getHistory();
+    }
+
     //@Override
     public Optional<TeamTownData> getTownData() {
         return Optional.of(data);

src/main/java/com/teammoeg/frostedheart/content/town/TeamTownData.java

@@ -90,7 +90,10 @@ public class TeamTownData implements SpecialData{
         .fieldOf("labour").forGetter(o -> o.labour),
 
         CodecUtil.defaultSupply(CodecUtil.catchingCodec(Codec.INT), () -> 0)
-        .fieldOf("maxLabour").forGetter(o -> o.maxLabour)
+        .fieldOf("maxLabour").forGetter(o -> o.maxLabour),
+
+        CodecUtil.defaultSupply(CodecUtil.catchingCodec(TownHistoryEntry.CODEC.listOf()), ArrayList::new)
+        .fieldOf("history").forGetter(o -> o.history)
 
         )
 
@@ -121,14 +124,25 @@ public class TeamTownData implements SpecialData{
     int labour=0;
     @Getter
     int maxLabour=0;
+    /**
+     * 城镇每日快照历史，最新条目在末尾，最多保留 {@link #MAX_HISTORY_ENTRIES} 条。
+     * 随存档持久化，并随城镇数据全量同步下发客户端。
+     * <p>
+     * Daily snapshot history of the town, newest entry last, capped at
+     * {@link #MAX_HISTORY_ENTRIES} entries. Persisted with the save and synced
+     * to clients with the full town data sync.
+     */
+    @Getter
+    List<TownHistoryEntry> history = new ArrayList<>();
 
     @Getter
     private final DataSyncCache dataSyncCache = new DataSyncCache();
 
 
 
-    public TeamTownData(String name, TeamTownResourceHolder resources, Map<BlockPos, ITownBuilding> buildings, Map<UUID, Resident> residents, Map<TerrainResourceType, TerrainResourceData> terrainResource,int labour,int maxlabour) {
+    public TeamTownData(String name, TeamTownResourceHolder resources, Map<BlockPos, ITownBuilding> buildings, Map<UUID, Resident> residents, Map<TerrainResourceType, TerrainResourceData> terrainResource,int labour,int maxlabour, List<TownHistoryEntry> history) {
         super();
+        this.history = new ArrayList<>(history);
         this.name = name;
         this.resources = resources;
         // 在批量 put 之前绑定 attach/detach，使反序列化得到的建筑/居民也自动接上（或解除）dataSyncCache 监听器
@@ -216,6 +230,39 @@ public void tickMorning(ServerLevel world) {
         residents.values().forEach(Resident::resetDailyProficiencyGrowth);
         this.buildingsWork(world);
         this.recoverResources();
+        this.recordDailySnapshot(world);
+    }
+
+    /**
+     * 历史快照的最大保留条数。
+     * <p>
+     * Maximum number of retained history entries.
+     */
+    public static final int MAX_HISTORY_ENTRIES = 30;
+
+    /**
+     * 在每日结算完成后记录一条城镇快照。同一天重复结算时覆盖当天条目，
+     * 超过 {@link #MAX_HISTORY_ENTRIES} 条时丢弃最旧的记录。
+     * <p>
+     * Records a daily town snapshot after settlement. Repeated settlements on
+     * the same day overwrite that day's entry; oldest entries are dropped once
+     * {@link #MAX_HISTORY_ENTRIES} is exceeded.
+     *
+     * @param world 服务端世界 / server world instance
+     */
+    void recordDailySnapshot(ServerLevel world) {
+        long day = world.getDayTime() / 24000L;
+        double avgHealth = residents.values().stream().mapToDouble(Resident::getHealth).average().orElse(0);
+        double avgMental = residents.values().stream().mapToDouble(Resident::getMental).average().orElse(0);
+        TownHistoryEntry entry = new TownHistoryEntry(day, residents.size(), avgHealth, avgMental, buildings.size());
+        if (!history.isEmpty() && history.get(history.size() - 1).day() == day) {
+            history.set(history.size() - 1, entry);
+        } else {
+            history.add(entry);
+        }
+        while (history.size() > MAX_HISTORY_ENTRIES) {
+            history.remove(0);
+        }
     }
 
     /**

src/main/java/com/teammoeg/frostedheart/content/town/TownHistoryEntry.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2026 TeamMoeg
+ *
+ * This file is part of Frosted Heart.
+ *
+ * Frosted Heart is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, version 3.
+ *
+ * Frosted Heart is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Frosted Heart. If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package com.teammoeg.frostedheart.content.town;
+
+import com.mojang.serialization.Codec;
+import com.mojang.serialization.codecs.RecordCodecBuilder;
+
+/**
+ * 城镇每日快照。每日城镇结算（tickMorning）后记录一条，
+ * 用于镇长印章 GUI 中的数据统计折线图。
+ * <p>
+ * Daily snapshot of a town. Recorded after the daily town settlement
+ * (tickMorning), used by the Mayor's Seal GUI to draw statistic charts.
+ *
+ * @param day 记录时的世界天数 / the world day when recorded
+ * @param population 居民数量 / resident count
+ * @param avgHealth 居民平均生命 / average resident health (0-100)
+ * @param avgMental 居民平均精神 / average resident mental (0-100)
+ * @param buildings 城镇建筑数量 / town building count
+ */
+public record TownHistoryEntry(long day, int population, double avgHealth, double avgMental, int buildings) {
+
+    public static final Codec<TownHistoryEntry> CODEC = RecordCodecBuilder.create(t -> t.group(
+            Codec.LONG.fieldOf("day").forGetter(TownHistoryEntry::day),
+            Codec.INT.fieldOf("population").forGetter(TownHistoryEntry::population),
+            Codec.DOUBLE.fieldOf("avgHealth").forGetter(TownHistoryEntry::avgHealth),
+            Codec.DOUBLE.fieldOf("avgMental").forGetter(TownHistoryEntry::avgMental),
+            Codec.INT.fieldOf("buildings").forGetter(TownHistoryEntry::buildings)
+    ).apply(t, TownHistoryEntry::new));
+}

src/main/java/com/teammoeg/frostedheart/content/town/buildings/warehouse/WarehouseBuilding.java

@@ -43,6 +43,8 @@ public class WarehouseBuilding extends AbstractTownBuilding {
                     BlockPos.CODEC.optionalFieldOf("pos",BlockPos.ZERO).forGetter(o -> o.pos),
                     Codec.BOOL.optionalFieldOf("isStructureValid",false).forGetter(o -> o.isStructureValid()),
                     OccupiedVolume.CODEC.optionalFieldOf("occupiedVolume",OccupiedVolume.EMPTY).forGetter(o -> o.getOccupiedVolume()),
+                    Codec.BOOL.optionalFieldOf("initialized", false).forGetter(o -> o.isInitialized()),
+                    Codec.BOOL.optionalFieldOf("occupiedAreaOverlapped", false).forGetter(o -> o.isOccupiedAreaOverlapped()),
 					Codec.DOUBLE.optionalFieldOf("capacity",0D).forGetter(o -> o.getCapacity()),
 					Codec.INT.optionalFieldOf("area",0).forGetter(o -> o.getArea()),
 					Codec.INT.optionalFieldOf("volume",0).forGetter(o -> o.getVolume()),
@@ -77,15 +79,19 @@ public WarehouseBuilding(BlockPos pos) {
      * @param area the area
      * @param volume the volume
      */
-    public WarehouseBuilding(BlockPos pos, boolean isStructureValid, OccupiedVolume occupiedVolume, double capacity, int area, int volume,int decorationAmount) {
-        this(pos, isStructureValid, occupiedVolume, capacity, area, volume, decorationAmount, List.of());
+    public WarehouseBuilding(BlockPos pos, boolean isStructureValid, OccupiedVolume occupiedVolume, boolean initialized,
+                             boolean occupiedAreaOverlapped, double capacity, int area, int volume, int decorationAmount) {
+        this(pos, isStructureValid, occupiedVolume, initialized, occupiedAreaOverlapped, capacity, area, volume, decorationAmount, List.of());
     }
 
-    public WarehouseBuilding(BlockPos pos, boolean isStructureValid, OccupiedVolume occupiedVolume, double capacity,
+    public WarehouseBuilding(BlockPos pos, boolean isStructureValid, OccupiedVolume occupiedVolume, boolean initialized,
+                             boolean occupiedAreaOverlapped, double capacity,
                              int area, int volume, int decorationAmount, List<BlockPos> interfacePositions) {
         super(pos);
         this.setIsStructureValid(isStructureValid);
         this.setOccupiedVolume(occupiedVolume);
+        this.setInitialized(initialized);
+        this.setOccupiedAreaOverlapped(occupiedAreaOverlapped);
         this.setCapacity(capacity);
         this.setArea(area);
         this.setVolume(volume);