# skieomod — outils de création Par **Albatar (Élie Millon)**. Le [guide anglais](getting-started.md) présente l’installation et les premiers essais avec Veymont, incluse et du même auteur. `skieomod` crée et teste des cartes, des mods UE4SS et des `mapmod`. Steam Workshop est le catalogue de cartes/mods prévu pour la sortie du jeu. Avant son ouverture, les créateurs et testeurs utilisent aussi la CLI pour installer et mettre à jour Custom Map depuis le VPS `skieomap.emillon.fr`. ## Installer la commande Pour installer la dernière version publiée, utiliser cette commande stable : ```sh pipx install --force --index-url https://skieomap.emillon.fr/downloads/pypi/ skieo-custom-map ``` Les articles peuvent pointer vers [la dernière archive des outils](https://skieomap.emillon.fr/downloads/CustomMap-Tools.zip) et [la dernière archive du mod](https://skieomap.emillon.fr/downloads/CustomMap-Mod.zip). Ces liens restent identiques à chaque publication. L’archive des outils contient la wheel installable, les sources et la documentation de la version courante. Avec Python 3.10+ et pipx, depuis les sources : ```sh pipx install --force . skieomod --version ``` Ou installer la wheel distribuée : ```sh pipx install ./skieo_custom_map-1.11.0-py3-none-any.whl ``` Sans pipx, créer un environnement Python (`python -m venv .venv`), l’activer, puis utiliser `python -m pip install .` depuis les sources, ou installer la wheel avec `python -m pip install CHEMIN.whl`. Sous Windows, `py` peut remplacer `python`. Python est nécessaire aux utilisateurs de cette CLI pendant les tests ; le parcours des joueurs via Steam à la sortie n’en dépendra pas. ## Consulter l’aide ```sh skieomod skieomod help skieomod -h skieomod --help skieomod help create skieomod create map --help skieomod help publish ``` Chaque commande accepte `-h` et `--help`, avec une description de ses options et des exemples. `help COMMANDE` affiche la même aide. Sans argument, la CLI affiche l’aide générale. Ces commandes ne nécessitent ni jeu ni configuration. ## Créer, compiler et tester Dans un dossier vide, choisir un modèle : | Commande | Contenu | Exécution | | --- | --- | --- | | `skieomod create map` | Terrain R16 de 1 km, aperçu et script Lua commenté | Monde indépendant | | `skieomod create mod` | Mod UE4SS, `Scripts/main.lua` commenté | Démarrage du jeu | | `skieomod create mapmod` | Mod `runtime: map-api`, script commenté | Session d’une carte dépendante | ```sh skieomod create map --name "Ma station" --id author.ma-station --author "Mon pseudo" skieomod build skieomod test skieomod run ``` Les cartes peuvent dépasser 8 km et être rectangulaires : ```sh skieomod create map --output grande-carte --size 16000 12000 --spacing 8 ``` `--size LARGEUR LONGUEUR` exprime les deux dimensions en mètres ; `--spacing` choisit le pas du R16 (16 m par défaut). Chaque longueur doit être un multiple du pas. Le modèle ajuste `sample_step` pour limiter le maillage initial ; la création refuse les sources de plus de 32 Mio ou 16 384 sommets par axe. Le [guide des grandes cartes](large-maps.md) explique les résolutions natives. Les modèles fournissent le manifeste, le script commenté, `workshop.json`, `preview.png`, un README et un `.gitignore` commenté pour `bin/` et `obj/`. `docs/manifest.md` explique les champs JSON et les dépendances ; `docs/scripting.md` décrit le runtime Lua du modèle ; `docs/development.md` couvre la compilation, les tests et le dépannage ; `docs/workshop.md` guide la préparation d’une publication. Les cartes incluent aussi `docs/terrain.md` avec l’encodage R16, les dimensions et l’aperçu, ainsi que `docs/vegetation.md` et une forêt JSON d’exemple à modifier directement. Cette documentation est autonome et reste avec les sources. Les manifestes restent du JSON strict, sans commentaires : leurs explications sont dans les guides. Les fichiers existants ne sont pas écrasés, y compris la documentation. `create map --output DOSSIER` choisit un autre dossier ; passer ensuite ce dossier à `build`, `test`, `run` et `publish`, ou s’y placer. `new` reste un alias compatible de `create`. `build` valide le projet et produit une archive ZIP reproductible `bin/IDENTIFIANT-VERSION.skieomap` ou `.skieomod`. Elle sert aux tests locaux ; le contenu Workshop sera décompressé. `build --output FICHIER` choisit la sortie. Un échec conserve la dernière archive valide. `test` accepte aussi une archive existante. `--check-scripts` utilise Lua 5.4 / `luac5.4` ; `--check-dependencies` vérifie les manifestes actuellement installés par Steam. `run` reconstruit et installe le projet local, puis ouvre Steam. Un `mapmod` démarre dans une carte de test créée dans `obj/mapmod-preview` ; sa publication n’est pas nécessaire. Un mod UE4SS s’active au démarrage suivant : fermer le jeu avant `run`. Les sources précédentes d’un mod remplacé sont sauvegardées. Les dépendances externes sont lues dans leurs dossiers Workshop, gérés par Steam. Aucun dépôt HTTP n’est interrogé. ## Construire à partir d'un heightmap Le [tutoriel illustré en anglais](https://skieomap.emillon.fr/tutorials/heightmap/) présente le parcours sans éditeur graphique. Depuis la CLI 1.10, le JSON définit la source et ses unités ; `skieomod build ma-carte` prépare le terrain : ```json "build": { "heightmap": { "file": "Terrain/source-heightmap.png", "spacing_meters": 8, "elevation_meters": [800, 2200] } } ``` Ajouter cette propriété au premier niveau de `custom-map.json`. Le PNG doit être en niveaux de gris 16 bits, sans alpha et sans entrelacement ; ses dimensions sont lues automatiquement et aucune dépendance supplémentaire n'est nécessaire. Pour du R16 brut, ajouter `"vertices": [513, 513]` et `"format": "r16le"` ou `"r16be"`. Les données doivent être des entiers non signés 16 bits sans en-tête. Les chemins sont relatifs au projet. Conserver l'entrée sous un nom distinct de `Terrain/heightmap.r16`, réservé à la sortie générée. `elevation_meters` contient les altitudes réelles des échantillons les plus bas et les plus hauts. Si l'exporteur fournit l'encodage, utiliser plutôt `height_scale_meters` et `height_offset_meters`. `row_order` vaut `north_to_south` par défaut ; `south_to_north` inverse l'ordre des lignes. Les colonnes vont d'ouest en est, avec un pas identique sur les deux axes. Le build calcule les sommets, l'emprise, l'origine centrée, les altitudes, l'échelle et l'aperçu normalisé, puis crée un paquet avec un R16LE portable. Après validation, il met à jour les champs dérivés de `terrain` dans le JSON et le R16 généré ; les fichiers remplacés sont sauvegardés dans `.heightmap-backups/`. L'entrée originale et la configuration `build` sont conservées dans le projet ; elles ne sont pas incluses dans le paquet. Un échec laisse la dernière archive valide et les fichiers du projet intacts. `test` prépare le même terrain sans modifier les sources. `run` reconstruit avec la même configuration. La source est limitée à 32 Mio d'échantillons et 16 384 sommets par axe. Le build choisit un pas de rendu initial pour limiter le nombre de cellules ; `build.heightmap.sample_step` permet de le remplacer pour ajuster le détail. ## Configurer temporairement le jeu ```sh skieomod setup skieomod config ``` `setup` installe temporairement Custom Map/UE4SS et mémorise les chemins du jeu, de la démo et des bibliothèques Steam secondaires. Un choix est demandé si une installation manque ou est ambiguë. Les chemins sont enregistrés dans `%APPDATA%/skieomod/config.json` ou `~/.config/skieomod/config.json` (`XDG_CONFIG_HOME` respecté). Aucun chemin de carte n’est nécessaire ensuite. Veymont est incluse et installée automatiquement dans le dossier des cartes. Relancer le jeu dans Steam, puis choisir **New Game → Custom Map → Veymont** pour découvrir son terrain, sa neige, sa forêt et sa station. `--game-dir`, `--maps-dir`, `--ue4ss-mods`, `--app-id` corrigent la détection. `setup --workshop-app-id APPID` sélectionne explicitement un autre Workshop si le développeur confirme cet accès pour la démo. `setup` n’enregistre plus le protocole `skieomod://`. Sous Linux, lancer une première fois le jeu avec Steam pour créer le préfixe Proton, puis le fermer. Le setup conserve les overrides existants et ajoute `dwmapi=native,builtin` avec sauvegarde du registre. Windows et Linux/Proton sont pris en charge ; les outils de création fonctionnent sur macOS, mais pas le lancement du jeu Windows. ## Mettre à jour avant Workshop Fermer le jeu avant d’appliquer une mise à jour : les scripts et DLL seront chargés au lancement suivant. Après une première installation avec `setup` : ```sh skieomod update --check skieomod update ``` La commande lit [la dernière version du chargeur](https://skieomap.emillon.fr/downloads/loader-latest.json), télécharge son archive versionnée en HTTPS et vérifie sa taille, son SHA-256, son manifeste et l’empreinte de chaque fichier avant toute modification du jeu. `--check` télécharge et valide la version disponible, affiche les versions installée/disponible et les changements, puis laisse l’installation intacte. Une CLI 1.7.0 peut installer les versions suivantes du chargeur tant que le protocole reste compatible ; le mod et la CLI ne doivent pas être mis à jour ensemble à chaque itération. La configuration de la CLI, les chemins Workshop, les demandes de lancement, les cartes et les autres mods sont conservés. Les fichiers remplacés ou supprimés sont sauvegardés dans `SkiEO-CustomMaps/.skieomod-backups/`. Les modules obsolètes connus sont supprimés lorsqu’ils n’ont pas été modifiés localement ; les fichiers personnels sont conservés. Une erreur d’écriture restaure les fichiers déjà remplacés. Une installation ancienne sans suivi de version peut être migrée ; sa version initiale est affichée comme inconnue. Pour une version particulière envoyée à un testeur, ou pour revenir à une version précédente après une régression : ```sh skieomod update --archive ./CustomMap-Mod-1.5.0.zip --check skieomod update --archive ./CustomMap-Mod-1.5.0.zip ``` Ces archives contiennent le chargeur, ses DLL, ses guides, `loader-release.json` et Veymont dans `Examples/`. `setup` et `update` installent la carte d’exemple si cette version est absente, sans remplacer une copie existante. Elles ne mettent pas à jour UE4SS lui-même. Une archive ancienne sans manifeste de version est refusée. `update --bundled` applique hors ligne le chargeur livré avec la CLI installée. Pour installer ou actualiser la CLI avec la wheel du VPS : ```sh pipx install --force --index-url https://skieomap.emillon.fr/downloads/pypi/ skieo-custom-map ``` Joindre la sortie de `skieomod --version` et `skieomod update --check` aux retours utilisateurs pour identifier la CLI et le chargeur testés. ## Préparer la publication Workshop ```sh skieomod publish --prepare ``` Cette commande fonctionne sans client Steamworks et produit : - `bin/workshop/content/` : manifeste et ressources décompressées ; - `bin/workshop/preview.png` : image séparée ; - `bin/workshop/publish-request.json` : requête de publication native ; - `bin/workshop/workshop.vdf` : configuration de test SteamCMD. Remplacer l’aperçu du modèle par une capture de votre création. `workshop.json` définit l’AppID consommateur, l’ID d’article (`"0"` pour créer), la visibilité initialement privée et l’image. `--item-id`, `--app-id`, `--preview`, `--visibility`, `--changenote` les ajustent. L’ID retourné par Steam est mémorisé afin de mettre à jour le même article à la publication suivante. Les dépendances requises doivent préciser leur `workshop_id`. La contrainte de version vérifie le paquet installé ; elle ne sélectionne pas une ancienne version Steam. Voir le [contrat Workshop](steam-workshop.md). ## Commandes raccordables au client Steamworks Le client natif n’est pas encore livré : `publish` sans `--prepare`, `list`, `install` et `play` signalent son absence. Ils n’appellent aucun ancien dépôt. Quand le jeu fournira le client : ```sh skieomod --steam-client CHEMIN config skieomod publish skieomod list --kind map --search neige skieomod install 1234567890 skieomod play 1234567890 ``` Ces identifiants sont des articles Workshop. Il n’y a plus de `--repository`, de `CUSTOM_MAP_TOKEN`, de `login` ou de sélection distante `--version`. `list --installed` fonctionne hors ligne avec l’inventaire local de Steam. L’enregistrement des mods UE4SS téléchargés au démarrage reste à raccorder avec le développeur du jeu ; un téléchargement seul ne les active pas. ## English `skieomod create map`, `create mod` and `create mapmod` scaffold working projects with commented Lua scripts, a README and self-contained guides in `docs/`. `new` remains an alias. `skieomod help COMMAND` and `COMMAND --help` explain every command with examples; invoking the CLI without arguments shows help. `build`, `test` and `run` validate and test them locally. A mapmod runs in an automatically generated preview map. `setup` temporarily installs Custom Map/UE4SS and remembers detected Steam paths; it no longer registers a URI handler. The included Veymont example, also by Albatar (Élie Millon), is installed automatically: choose **New Game → Custom Map → Veymont** in the game. Before Workshop opens, `update` downloads a versioned loader release from the VPS and verifies its SHA-256. `update --check` reports versions and planned changes; `--archive FILE` applies a specific test release, and `--bundled` works offline. Close the game first. Settings and maps are preserved; replaced files are backed up. Steam Workshop is the only remote catalogue. `publish --prepare` creates unpacked content, a separate preview, a native publication request and a VDF for SteamCMD testing. The native Steamworks client is not shipped yet. Remote `publish`, `list`, `install` and `play` report this explicitly. `list --installed` reads Steam’s local inventory. Required dependencies pin a decimal-string `workshop_id`; semantic versions describe installed package compatibility, not historical Workshop release selection. ## Construire la distribution Depuis les sources : ```sh python3 tools/build_custom_map_release.py --tools-only ``` Les fichiers sont produits dans `build/custom-map-downloads/` : la wheel `skieo_custom_map-1.11.0-py3-none-any.whl` et `CustomMap-Tools.zip`. L’archive contient la wheel, les sources installables, les guides, les schémas et l’éditeur. La wheel embarque les modèles de projet, la documentation et le chargeur avec ses DLL de dépôt et de terrain natif, ainsi que les sources de Veymont. Le guide anglais est aussi disponible sous le lien stable [`getting-started.md`](https://skieomap.emillon.fr/downloads/getting-started.md). Les ressources installées se trouvent dans `share/skieomod/` sous le préfixe de l’environnement Python. Pour une compilation hors ligne, si `setuptools>=77` et `wheel` sont déjà installés, ajouter `--no-build-isolation`. Le script produit également `CustomMap-Mod-1.11.0.zip`, son alias `CustomMap-Mod.zip` et `loader-latest.json`. Veymont est toujours incluse dans les paquets ; `--tools-only` omet seulement son téléchargement séparé. `--loader-ref REVISION` choisit une révision Git du chargeur. La distribution utilise sinon les fichiers du répertoire de travail. `--loader-archive ARCHIVE` permet de reprendre le code et les exemples vérifiés d’une publication existante pour une mise à jour de la CLI, sans embarquer des changements du jeu encore en cours. UE4SS utilise le build testé `UE4SS_v3.0.1-1152-ge3ba1016.zip`, conservé sous une URL versionnée sur `skieomap.emillon.fr`. `setup` vérifie son SHA-256 ; une rotation du tag GitHub `experimental-latest` ne change pas le build installé. La construction exige cette archive locale et la copie dans les téléchargements ainsi que dans les sources du ZIP des outils. Pour la première construction : ```sh python3 tools/build_custom_map_release.py --tools-only \ --ue4ss-archive /chemin/vers/archive-UE4SS-testee.zip ``` Les constructions suivantes réutilisent le fichier versionné présent dans `build/custom-map-downloads/`. `--output-dir` permet de préparer les fichiers dans un autre répertoire. Le script ne sélectionne pas automatiquement un nouveau build amont. Un changement de build UE4SS exige des tests dans le jeu, puis la mise à jour volontaire du nom et de son empreinte dans `skieo_install.py`. Vérifier la wheel dans un environnement isolé, sans accéder au jeu ni à Steam : ```sh python3 tests/check_skieomod_distribution.py \ build/custom-map-downloads/skieo_custom_map-1.11.0-py3-none-any.whl \ --loader-archive build/custom-map-downloads/CustomMap-Mod-1.11.0.zip ``` Ce contrôle installe uniquement la wheel fournie, vérifie l’aide et les ressources du chargeur, puis crée, compile, teste et prépare les trois modèles pour Workshop. Il simule aussi une installation ancienne et vérifie la mise à jour hors ligne du mod, la conservation des paramètres et les sauvegardes. ## Publier une itération sur le VPS Après les tests, lancer depuis les sources : ```sh python3 deployment/publish_loader_updates.py ``` Le script utilise SSH vers `root@skieomap.emillon.fr` et le dossier déjà servi en HTTPS `/opt/custom-map/current/downloads`. Il vérifie et publie d'abord l'archive UE4SS testée, puis la wheel, le ZIP du mod et les sources sous des noms versionnés, puis remplace `loader-latest.json` en dernier par renommage atomique. Le pointeur précédent est conservé dans `loader-latest.previous.json`. Une version publiée ne peut pas être remplacée par des octets différents : augmenter la version avant de republier une modification. Les anciennes archives restent disponibles pour tester une régression. `CustomMap-Tools.zip` et `CustomMap-Mod.zip` suivent automatiquement les nouveaux fichiers par des liens symboliques remplacés atomiquement. L’index `/downloads/pypi/skieo-custom-map/` expose uniquement la wheel courante, avec son SHA-256, pour que la commande `pipx` publiée dans un article reste valable. Nginx impose la revalidation des liens stables, du flux de mise à jour et de l’index Python afin de ne pas servir une ancienne version depuis un cache HTTP. La CLI 1.6 a introduit les archives d’exemple vérifiées dans `Examples/`. Le minimum passe à 1.7.0 avec Veymont 0.6 : son archive dépasse l’ancienne limite de téléchargement de 16 Mio. Les nouvelles limites sont 64 Mio pour l’archive du chargeur et 128 Mio décompressés. Les testeurs utilisant une CLI antérieure doivent réexécuter la commande d’installation stable une fois. Ce minimum ne doit ensuite augmenter que si le protocole change. Aucun redéploiement de l’ancien catalogue HTTP ni raccordement Workshop n’est nécessaire pour publier ces fichiers. ## Traitement et végétation au build `build.heightmap.processing` configure le lissage, l’érosion thermique, l’érosion suivant le drainage et le bruit facultatif. `build.vegetation` configure la limite des arbres, l’humidité, la température, le vent, les pentes, la densité, l’espacement et la couverture herbe/roche. Chaque build repart de la source et recalcule les altitudes ainsi que l’aperçu. Pour les arbres placés à la main, `build.forest.file` désigne le JSON source. Le build le compile en SKXY ; le chargeur 1.11 ne lit plus les forêts JSON. La forêt automatique produit directement du SKXY et prend la priorité. Le [guide](vegetation.md) et le [tutoriel](https://skieomap.emillon.fr/tutorials/heightmap/#bake) contiennent la configuration complète et les limites des modèles.