LifePlay-Revival/Docs/Migration/etat/REL/MAPDL1/MAPDL1-E1-FICHE.md

Fiche MAPDL1-E1 — Niveau N3 — Modèle prévu sonnet (agent lp-impl ; escalade lp-impl-max) — Agent lp-impl — Skills sk-protocol, lp-city, lp-lot, ue-cpp-build

MAPDL1-E1 : états des villes et menu (C1 à C5 de MAPDL1-SPEC-05 v3), en C++, sans Blueprint

Décision de l'utilisateur, citée par Big Boss : « Oui : SPEC-05 v3 approuvée (S5-1 à S5-5, D10 = téléchargement HTTP dans le jeu avec navigateur en recours, D11 = un zip par pack). Lance la réalisation avec les modèles réduits ; l'hébergeur et le domaine, je les choisis plus tard. »

Hors moteur :

• aucun build, aucun commandlet, aucun éditeur. La compilation est l'étape E2, sous jeton ;
• aucun commit ;
• rien sous Mods\ ;
• aucun Blueprint modifié.

Le téléchargement HTTP (C6) n'est pas dans cette fiche : c'est E5.

Références à lire d'abord :

• MAPDL1-SPEC-05.md (v1, § 1-2), MAPDL1-SPEC-05-v3.md (§ 1), MAPDL1-E0-INV.md ;
• MAPDL1-L1-CART-02.md et MAPDL1-L4-CART-01.md (menu, lignes City_C, calcul « Installed ») ;
• modèle de code : Source/LifePlay/LPModInfoSubsystem.h/.cpp, TickModManager. Il trouve un UScrollBox par TObjectIterator, lit des variables de Blueprint par FindPropertyByName et modifie les lignes.

0. Avant toute écriture

1. Instantané, depuis pwsh, un chemin par appel :
   • .\Tools\Snapshot.ps1 -Lot MAPDL1-E1 -Path <chemin> pour chacun des fichiers du § 1 ;
   • les fichiers neufs sont notés absents.
2. Relever les MD5 (Get-FileHash -Algorithm MD5) des fichiers modifiés, et des fichiers de ville de STM1 non commités. Ces derniers ne doivent pas changer :
   • Source/LifePlay/LPCityWaterSubsystem.*, LPCityWaterMask.h, LPCityNamesSubsystem.*, LPCityHouses.h, LPCityLandmarks.h, LPAssetRegistryHelpers.*.
3. git status --short sur les fichiers du § 1 : aucune modification en cours attendue, sinon arrêt et rapport.

1. Fichiers (et seulement ceux-là)

Fichier	État	Contenu
Plugins/ModdingExtra/Source/ModdingExtra/Public/ModdingExtraBPLibrary.h	M	crochet du § 2.1
Plugins/ModdingExtra/Source/ModdingExtra/Private/ModdingExtraBPLibrary.cpp	M	crochet du § 2.1
Source/LifePlay/LifePlay.Build.cs	M	PrivateDependencyModuleNames : ajouter "ModdingExtra" et "Json", avec un commentaire « Lot MAPDL1 (SPEC-05) »
Source/LifePlay/LPCityMapsSubsystem.h et .cpp	A	§ 2.2 à 2.5
Content/Data/LPCityMaps.json	A	§ 2.6
Config/DefaultGame.ini	M	une ligne après la l. 74 (+DirectoriesToAlwaysStageAsNonUFS=(Path="Modules")) : +DirectoriesToAlwaysStageAsUFS=(Path="Data"), pour livrer le JSON dans le pak
Tools/IndexCartes.ps1	A	§ 2.7

Conventions :

• code dans le style des fichiers voisins (commentaires en français sans accents, // Lot MAPDL1 (MAPDL1-SPEC-05) :) ;
• Tools\*.ps1 en ASCII et LF ;
• pas de python -c, pas de heredoc ;
• outil Edit pour modifier (jamais sed ni -replace).

2. Contenu

2.1 Crochet dans ModdingExtra (C2)

Dans ModdingExtraBPLibrary.h, hors de la classe, ajouter :

/** Lot MAPDL1 (MAPDL1-SPEC-05) : filtre facultatif de la liste rendue par GetAllFilesFromFolder, pose par le module du jeu
 *  (ULPCityMapsSubsystem). Arguments : dossier demande et extension tels que recus, liste a modifier. Sans filtre : inchange. */
using FModdingExtraFileListFilter = TFunction<void(const FString& /*RootFolder*/, const FString& /*Ext*/, TArray<FString>& /*Files*/)>;
MODDINGEXTRA_API void ModdingExtraSetFileListFilter(FModdingExtraFileListFilter Filter);

Dans le .cpp :

• une variable statique de fichier FModdingExtraFileListFilter GLPFileListFilter; et la définition de ModdingExtraSetFileListFilter ;
• dans GetAllFilesFromFolder, garder une copie de Ext tel que reçu au début (la fonction le transforme en *.uasset) ;
• juste avant return true; (l. 224 actuelle) : if (GLPFileListFilter) { GLPFileListFilter(RootFolderFullPath, ExtRecu, Files); }.

Rien d'autre ne change. Le plugin ne dépend toujours pas du jeu.

2.2 ULPCityMapsSubsystem : index et états (C1)

UCLASS() class LIFEPLAY_API ULPCityMapsSubsystem : public UGameInstanceSubsystem

Index. Dans Initialize, lire le premier fichier présent parmi :

• (a) FPaths::ProjectSavedDir()/LPCityMaps.json : surcharge locale, pour les essais (MAPDL1-ESSAI-FJ F4) ;
• (b) FPaths::ProjectContentDir()/Data/LPCityMaps.json : copie livrée.

Lecture par FFileHelper::LoadFileToString puis FJsonSerializer.

• Champs (format 2, SPEC v3 § 1) : base[], licences{}, villes[] avec ville, pack, version, jeu_min, jeu_max, zip, octets, sha256, urls[], page, licences[], source.
• Journal : [LPCity] CARTES index <chemin> : base <n>, villes <n> (catégorie LogLPCity, celle de LPAssetRegistryHelpers.cpp).
• Index absent ou illisible : avertissement, et aucune ville téléchargeable. Les villes « base » prennent alors pour valeur par défaut CentralLondon et 00BathCC.

État d'une ville V, nom d'asset du jeu, calculé à la demande et mis en cache. Les packs sont montés au démarrage, et le cache de ResolveCityPath n'est jamais invalidé, ce qui est voulu :

• Installed si V est dans base, ou si, pour les deux chemins /Game/Heavy/StreetMap/V.V et /Game/Heavy/StreetMap/Static/V.V, ULPAssetRegistryHelpers::ResolveCityPath(p) != p ;
• sinon Downloadable si une entrée ville == V (casse ignorée) a au moins une URL, un sha256 de 64 caractères hexadécimaux, et jeu_min <= version du jeu <= jeu_max. La version du jeu est ProjectVersion (FLPModGuard::GetGameVersion()) ; comparaison par composantes séparées par des points, numérique quand les deux composantes sont des nombres, sinon textuelle ;
• sinon Unavailable.

API (UENUM(BlueprintType) ELPCityMapState { Installed, Downloadable, Unavailable }) :

• GetCityState(const FString& Ville) ;
• GetDownloadBytes(Ville) ;
• GetDownloadUrls(Ville) (C++).

Une ligne de journal par ville au premier calcul : [LPCity] ETAT <V> : <etat>.

Pose du crochet dans Initialize : ModdingExtraSetFileListFilter(...) avec un TWeakObjectPtr sur le sous-système. Le retirer dans Deinitialize (filtre vide). Le filtre n'agit que si :

• le dossier, une fois normalisé (\ devient /, sans / au début ni à la fin), vaut Heavy/StreetMap (casse ignorée) ;
• et l'extension reçue est uasset ou .uasset.

Il retire alors de Files toutes les entrées dont le nom de fichier sans extension est une ville dont l'état n'est pas Installed. Les entrées des villes installées ne sont pas touchées : le comptage d'origine du Blueprint UI/City, qui exige 2 entrées pour « Installed », doit rester intact. Journal, une fois par appel : [LPCity] LISTE Heavy/StreetMap : <n> entrees, <m> retirees.

E0 a établi que GetAllFilesFromFolder est appelé par 6 Blueprints (GI, Room, Builder, CharGen, StatMenu, CityMenu), mais que seul CityMenu porte le littéral Heavy/StreetMap. Le filtre ne touche que ce dossier.

2.3 Menu des villes (C3)

Un ticker FTSTicker de 0 s, comme TickModManager, actif tant que le sous-système existe. À chaque passage :

1. Trouver un UScrollBox nommé CityScrollBox, dont l'objet extérieur est de classe CityMenu_C et qui est à l'écran (IsVisible() et GetCachedWidget().IsValid()).
2. Pour chaque enfant de classe City_C, lire :
   • la variable City (FStructProperty), et dans cette structure le champ dont le nom commence par StreetMapName (FNameProperty ; les champs d'une structure Blueprint ont un suffixe). Le nom de ville est la partie après le dernier . du chemin, ou après le dernier / s'il n'y a pas de . ;
   • les variables InstalledText (UTextBlock) et CityButton (UButton).
3. Selon l'état :
   • Installed : ne rien toucher (texte et clic d'origine) ;
   • Downloadable :
     • InstalledText->SetText("Download (%d MB)"), arrondi au Mo supérieur ;
     • SetColorAndOpacity bleu (0.2, 0.6, 1.0) ;
     • relais de clic (point 5) ;
   • Unavailable :
     • InstalledText->SetText("Not available"), gris (0.5, 0.5, 0.5) ;
     • CityButton->SetIsEnabled(false) ;
     • opacité de la ligne à 0,6.
   • Réappliquer à chaque passage, car le Blueprint écrit InstalledText après un Delay 0.2 (MAPDL1-L4-CART-01).
4. Tri, une fois par instance de liste, et de nouveau si le nombre d'enfants change :
   • tri stable en trois groupes : Installed, puis Downloadable, puis Unavailable ; l'ordre d'origine est gardé dans chaque groupe ;
   • retrait de tous les enfants, puis réinsertion dans le nouvel ordre ;
   • relever le Padding, l'alignement horizontal et l'alignement vertical de chaque UScrollBoxSlot avant le retrait, et les remettre après.
   • GI.Cities n'est pas modifié.
   • Journal, une fois par instance : [LPCity] MENU tri : <i> installees, <d> telechargeables, <u> indisponibles.
5. Relais de clic des lignes Downloadable :
   • un petit UCLASS() ULPCityRowClick : UObject (même fichier) avec FString Ville, un TWeakObjectPtr vers le sous-système et UFUNCTION() void OnClicked();. Lié par CityButton->OnClicked.AddUniqueDynamic ;
   • le sous-système garde ces objets (UPROPERTY() TArray<TObjectPtr<ULPCityRowClick>>) et les vide quand la liste change d'instance ;
   • dans cette fiche, OnClicked ouvre urls[0] (ou page si elle n'est pas vide) par FPlatformProcess::LaunchURL. C'est le recours (c), en attendant la fenêtre de C6 en E5. Journal : [LPCity] CLIC <V> : navigateur <url>.

2.4 Bandeau des parties sauvegardées (C4)

Dans Initialize, s'abonner à ULPAssetRegistryHelpers::OnCityMapResolved() (LPAssetRegistryHelpers.h:19, deux paramètres : demandé, résolu). Si :

• le demandé est /Game/Heavy/StreetMap/V.V (pas Static/) ;
• le résolu est égal au demandé (aucun pack) ;
• l'état de V n'est pas Installed.

Alors afficher pendant 10 s, par GEngine->GameViewport->AddViewportWidgetContent (Slate, ordre Z élevé, en haut au centre), le texte :

• Map not installed - download it from the city menu si l'état est Downloadable ;
• Map not available sinon.

Une seule fois par ville et par session. Journal : [LPCity] BANDEAU <V> : <texte>. Se désabonner dans Deinitialize.

2.5 Ce qu'il ne faut pas faire

• Ne pas modifier ResolveCityPath, LPCityWaterSubsystem, LPCityNamesSubsystem, ni aucun fichier de STM1.
• Ne pas toucher GI.Cities, les sauvegardes, Content/Heavy.
• Aucun texte de jeu en dur hors de ceux du § 2.3 et du § 2.4.

2.6 Content/Data/LPCityMaps.json livré

Format 2 :

• "base": ["CentralLondon", "00BathCC"] ;
• "licences" :
  • osm : titre « Map data (c) OpenStreetMap contributors, ODbL 1.0 », fichier « Licenses/OpenStreetMap_Geodata_License.txt » ;
  • lifeplay_ancienne : titre = le texte validé (S5-5) de MAPDL1-SPEC-05-v2.md § 4, mot pour mot, fichier « Licenses/Vinfamy_License.txt » ;
• "villes": [] : aucun hébergeur n'est choisi (H1, H2). Une liste d'essai se pose dans Saved/LPCityMaps.json.

UTF-8 sans BOM, LF.

2.7 Tools/IndexCartes.ps1 (C5)

Il écrit un LPCityMaps.json format 2. Paramètres :

• -Villes A,B ou -Toutes : toutes les archives lpm_city_*-*-for-LifePlay-<jeu>.zip de <Publication>\Mods, en prenant la plus haute version par pack ;
• -Hebergeur Forgejo|GitHub|Modele, avec :
  • Forgejo : -ForgejoHote (défaut forgejo.edujiro5972.fr), -Owner, -Repo, -Tag, d'où https://<hote>/<owner>/<repo>/releases/download/<tag>/<zip> ;
  • GitHub : -Owner, -Repo, -Tag, d'où https://github.com/<owner>/<repo>/releases/download/<tag>/<zip> ;
  • Modele : -Modele "https://…/{zip}" ;
• -Miroir (facultatif) : un second modèle {zip}, ajouté en 2e URL ;
• -JeuMax (défaut 2026.12.99) ;
• -Sortie (défaut <Racine>\Saved\LPCityMaps.json ; écrire Content\Data\LPCityMaps.json exige -Livre) ;
• -ABlanc : affiche le JSON, n'écrit rien.

Pour chaque pack :

• ville : le nom d'asset, tiré de ModSources\<pack>\Content\StreetMap\<V>.uasset ;
• version : VersionName du .uplugin source ;
• zip, octets, sha256 calculés sur l'archive ;
• jeu_min : la version du jeu tirée du nom de l'archive ;
• licences : ["osm","lifeplay_ancienne"] ;
• source : la ligne - file … SHA-256 … du CREDITS source.

Racines lues par Get-LPProjet et Get-LPRacine. Codes : 0 écrit ; 2 usage, archive ou source manquante. ASCII et LF ; en-tête .SYNOPSIS.

Essai à faire (sans réseau), avec des valeurs fictives : -Villes Manila -Hebergeur Forgejo -Owner exemple -Repo exemple -Tag cartes-test-1 -ABlanc. Recopier la sortie.

3. Contrôles hors moteur à faire

1. git diff --stat des fichiers M, et liste des fichiers A.
2. MD5 avant et après de chaque fichier du § 1, et MD5 des fichiers de STM1 inchangés.
3. Fins de ligne : les fichiers .cpp, .h et .cs gardent leur convention, vérifiée par git ls-files --eol pour les fichiers suivis (LF attendu).
4. Analyse syntaxique PowerShell de IndexCartes.ps1 ([System.Management.Automation.Language.Parser]::ParseFile) : 0 erreur ; essai à blanc du § 2.7.
5. python -I -X utf8 -c est interdit ; pour valider le JSON, lancer Test-Json sous pwsh.

4. Livrable

Docs\Migration\etat\REL\MAPDL1\MAPDL1-E1-IMPL.md :

• en-tête sk-protocol, avec le modèle réellement utilisé ;
• fichiers, MD5 avant et après, diff résumé ;
• choix faits là où la fiche laisse une latitude ;
• points non sûrs, à vérifier à la compilation (E2) ;
• sorties des contrôles du § 3 ;
• compte rendu.

Budget : 60 tours. En cas de blocage (API introuvable, compilation impossible à anticiper), arrêt et rapport : on ne contourne pas.