NRF SDK 0.9Maintenance
Écrire un mod réactif et indépendant
Limiter le travail utile, gérer les reprises et mesurer sans confondre chargement, calcul et affichage.
Ce que le SDK prend en charge
Le SDK surveille les mods natifs compatibles. Il peut arrêter un mod qui plante ou dont un callback ne répond plus, tout en laissant fonctionner les autres mods. Pour l’auteur du mod, le contrat reste simple : utiliser les fonctions publiques, borner chaque calcul et rendre la main. Après un arrêt pour faute, corrigez la cause et relancez une session de test ; ne supposez pas que le callback sera rejoué automatiquement.
Un callback fait un travail borné puis rend la main
| Moment | Bonne organisation |
|---|---|
| Déclaration du mod | Préparer les modèles, réglages, descriptions d’images et règles fixes une fois. Garder stables les identifiants. |
| Observation de signalisation | Utiliser le réseau et les observations fournis. Créer les index utiles une fois par lot ; éviter une recherche complète de tous les signaux pour chaque signal. |
| service / onTick | Les callbacks de l’outil sont sérialisés. Calculer sur demande ; au repos, ne rien relire. Pendant un aperçu, renouveler les positions copiées. Pendant une commande, interroger son ticket. |
| onStop / worldId / generation | Libérer les données du mod à l’arrêt ; invalider les plans, index et événements d’une autre session. Ne conserver aucun ToolContext au-delà de son callback. |
Un intervalle d’observation est une cadence visée, pas une garantie de fréquence. Si un calcul dépasse cet intervalle, ne lancez pas une rafale de rattrapage. À haute vitesse, le temps simulé avance plus vite que les callbacks et que les images visibles : une animation ne peut pas promettre l’affichage de chaque phase.
Demander les données nécessaires
| Besoin | Dans un outil natif | Dans une application JVM |
|---|---|---|
| Horloge seule | ToolContext.clock() | Game.clock.read() |
| Familles de données trains | ToolContext.trains(TrainQuery(...)) | Game.trains.snapshot(query = TrainQuery(...)) |
| Géométrie du réseau | ToolContext.network() | Game.snapshot() |
Demandez les voyageurs, horaires, tags, caractéristiques ou compositions seulement si votre fonction les utilise. Une carte complète n’est pas nécessaire pour un formulaire de date. À l’inverse, ne remplacez pas une nouvelle lecture nécessaire par un cache fondé uniquement sur le temps écoulé : un monde, une voie ou une source peuvent avoir changé. Une valeur absente reste inconnue, pas zéro ni une liste vide inventée.
Les résultats copiés sont utiles pour calculer et afficher. Dans un callback natif, les demandes de trains déjà couvertes peuvent réutiliser la lecture du callback ; network() et un changement d’heure invalident cette réutilisation. Dans une application JVM, chaque demande de capture est une nouvelle lecture. Ouvrez et fermez explicitement votre connexion et libérez vos caches quand elle change.
Vérifier le comportement avant de promettre un gain
Testez hors jeu un callback lent, une exception, une donnée inconnue et plusieurs refus temporaires, puis le retour à la normale. Vérifiez que les autres fonctions continuent, que les files restent bornées et qu’une opération de pose n’est envoyée qu’une fois. Mesurez séparément le temps de lecture, le calcul du mod et la fréquence réellement observée. Une moyenne seule masque les pointes.
Pour une recette en jeu, conservez la version et l’empreinte des paquets, la partie de référence, les phases avant/après et les logs du bon démarrage. Attendez la fin du chargement avant la référence de mesure. Les compteurs depuis le démarrage incluent souvent cette phase : comparez des différences entre deux horodatages connus. Gardez les mêmes réglages de vitesse et de rendu entre les essais. Un clic qui répond ou une capture isolée ne mesure pas les temps de chaque image.
| Mesure | Ce qu’elle permet de conclure |
|---|---|
| Lecture ciblée | Taux de réussite et durée des demandes utiles ; comparez médiane, percentile 95 et maximum. |
| Horloge simulée | Rapport entre le temps du jeu et le temps réel écoulé. Le palier choisi dans l’interface ne prouve pas la vitesse atteinte. |
| Conduite et apparence | Testez séparément le passage de trains devant les signaux, la décision produite et les images réellement visibles. Une lecture rapide ne prouve pas un affichage instantané. |
| Récupération | Après la faute, vérifier que les autres fonctions progressent et que les délais reviennent dans leur plage habituelle, sans rejouer une mutation incertaine. |