- scrap mechanic api : utilisez la référence Lua API publiée comme source pour les fonctions exposées et leur disponibilité.
- Environnement Lua : le scripting de Scrap Mechanic utilise LuaJIT avec un comportement de langage compatible Lua 5.1.
- Structure de base : séparez les visuels client, l'autorité du serveur, le réseau et le stockage persistant.
- Flux UI : construisez les interfaces via les outils GUI disponibles et mettez-les à jour depuis la logique côté client.
- Priorité au débogage : testez séparément la fusion des shapes, les raycasts, les collisions des bodies et la synchronisation multijoueur.
scrap mechanic api : ce qu’il couvre
Le scrap mechanic api est l’interface publiée pour le scripting dans Scrap Mechanic. Elle expose les fonctions, objets, signatures et indications de disponibilité que les mods peuvent utiliser. La référence est présentée via la documentation Scrap Mechanic Lua API, une interface consultable non officielle basée sur le matériel publié à scrapmechanic.com/api.
Le site de documentation ne prétend pas remplacer les fichiers API d’origine. Sa valeur réside dans l’organisation : des entrées recherchables facilitent la localisation d’une fonction avant de la tester dans un mod. C’est important, car l’API publiée peut contenir des entrées incomplètes ou des omissions ; les tests pratiques restent donc une partie du processus de développement.
L’environnement de scripting utilise LuaJIT, avec un langage couvert par le manuel de référence Lua 5.1. La référence API se concentre sur les fonctions exposées de Scrap Mechanic plutôt que de documenter chaque fonctionnalité générale de Lua.
Points forts de la vidéo :
- Construire un pistolet à peinture personnalisé via le scripting Lua
- Créer une GUI pour les réglages de dispersion, vitesse, taille et couleur
- Travailler avec les raycasts, les shapes, les bodies et les données de création
- Gérer les paramètres client-serveur et les valeurs sauvegardées
- Tester la fusion des shapes et le comportement des collisions sur de grandes créations
| Zone de l’API | Usage typique | Question de développement |
|---|---|---|
| Langage Lua | Variables, tables, fonctions, boucles | La logique respecte-t-elle une syntaxe Lua 5.1 valide ? |
| Objets du jeu | Shapes, bodies, outils, créations | Quel objet possède la fonction ? |
| Logique client | UI, effets, mises à jour locales | Cela doit-il s’exécuter pour chaque joueur ? |
| Logique serveur | Autorité et état partagé | Le serveur doit-il valider le résultat ? |
| Réseau | Requêtes et synchronisation | Quelles valeurs doivent atteindre les autres clients ? |
| Stockage | Paramètres persistants du mod | La valeur doit-elle rester après le rechargement ? |
Cherchez d’abord l’entrée API, puis vérifiez sa signature, sa disponibilité et l’objet qui la possède avant d’écrire la logique autour. Cela évite de nombreuses erreurs de scripting évitables.
Les principaux systèmes API à apprendre en premier
Une bonne façon d’aborder l’API consiste à regrouper les fonctions par responsabilité plutôt qu’à mémoriser des noms isolés. Un outil comme un pistolet à peinture peut combiner raycasts, données de shape, couleurs, particules, contrôles GUI, requêtes réseau et stockage. Chaque système doit néanmoins avoir un rôle clair.
Lua et fonctions de jeu exposées
Lua gère la structure du programme, tandis que Scrap Mechanic fournit les fonctions orientées jeu. Les tables sont particulièrement importantes, car les données de shape, les paramètres, les listes de points et les charges utiles réseau peuvent être représentés sous forme de valeurs regroupées.
Shapes, bodies et créations
Les opérations basées sur les shapes exigent une attention particulière à la propriété. Un seul objet visible peut faire partie d’un body ou d’une création plus grande, et modifier une pièce peut affecter la géométrie connectée. Les grandes créations rendent également les boucles inefficaces plus visibles.
Raycasts et effets
Les outils interactifs utilisent souvent un raycast ou un résultat de collision similaire pour déterminer où un effet doit apparaître. Le résultat peut ensuite servir à identifier une shape, calculer une position ou générer un effet visuel. Testez toujours la différence entre le point d’impact, la shape touchée et l’objet qui la possède.
GUI et interaction joueur
Une interface personnalisée appartient généralement au client. Le client peut afficher les contrôles et recueillir les entrées, tandis que le serveur peut valider les paramètres qui affectent le gameplay partagé ou l’état du monde.
Tables Lua
Stockez des valeurs regroupées comme les paramètres, les données de points, les enregistrements de shapes et les tables de recherche temporaires.
Données de shape
Suivez soigneusement les positions, couleurs, limites et identifiants lorsqu’un outil modifie des pièces de construction.
Constructeur de GUI
Utilisez la logique d’interface côté client pour exposer des contrôles lisibles au lieu de coder en dur chaque valeur.
Réseau
N’envoyez que les valeurs qui nécessitent une synchronisation, puis validez les changements partagés sur le serveur.
| Système | Mieux géré par | Responsabilité exemple |
|---|---|---|
| Affichage GUI | Client | Afficher les contrôles et mettre à jour les libellés |
| Lecture des entrées | Client | Détecter l’interaction avec un outil |
| Modification du monde | Serveur | Valider les changements de shapes ou de créations partagés |
| Particules visuelles | Client ou contexte d’effet | Afficher un retour d’impact |
| Configuration sauvegardée | Serveur ou contexte de stockage propriétaire | Conserver les paramètres sélectionnés |
| Sortie de débogage | Build de développement | Afficher des valeurs lors de tests isolés |
Ne supposez pas qu’un code exécuté sur un client peut contrôler sans risque l’état partagé du monde. Séparez la présentation des changements autoritatifs, surtout dans les mods multijoueur.
Flux de configuration client-serveur et GUI
Un mod fiable établit généralement son modèle d’exécution avant d’ajouter des comportements avancés. Le flux suivant convient à un outil interactif avec des paramètres configurables.
Confirmer l’entrée API
Identifiez l’objet, le callback, la signature de fonction et l’indication de disponibilité pour chaque appel API que vous prévoyez d’utiliser. Si une entrée est incomplète, créez un petit test au lieu de l’intégrer immédiatement dans une grande fonctionnalité.
Créer l’objet de base
Mettez en place l’outil ou le bloc avec le minimum de fonctions de cycle de vie nécessaires à la création, à l’interaction et au nettoyage. Gardez la première version sans GUI ni paramètres persistants.
Ajouter l’interface client
Construisez la GUI côté client et n’exposez que des contrôles utiles. Les valeurs comme la dispersion, la vitesse, la taille ou le mode doivent être affichées d’une manière qui rende leur état actuel évident.
Envoyer les paramètres via le serveur
Lorsqu’un joueur modifie un paramètre partagé, envoyez une requête ciblée au serveur. Le serveur doit stocker la valeur acceptée et diffuser l’état résultant lorsque d’autres clients en ont besoin.
Tester séparément les effets sur le monde
Testez séparément les raycasts, les modifications de shapes, les particules et les grandes créations. Il devient ainsi plus facile d’identifier si une panne vient du réseau, de la géométrie ou du comportement de fusion propre au jeu.
Un tableau de configuration pratique peut contenir des valeurs comme spread, speed, size et un indicateur de mode. Gardez ces valeurs dans une seule table de paramètres plutôt que d’éparpiller des constantes dans tout le script. Cela simplifie la gestion des mises à jour de GUI, de la validation et du stockage.
| Paramètre | Fonction dans un outil | Validation suggérée |
|---|---|---|
| Spread | Contrôle la variation directionnelle | Limiter à une plage d’angle prévue |
| Speed | Contrôle le déplacement de l’effet | Exiger une valeur numérique non négative |
| Size | Contrôle la zone affectée | Exiger une taille minimale valide |
| Mode | Sélectionne un comportement comme bucket ou single target | N’accepter que des noms de mode connus |
| Color | Définit la couleur appliquée ou affichée | Valider le format de couleur attendu |
Laissez la GUI modifier un objet de paramètres local, envoyez une requête propre, validez-la sur le serveur, puis renvoyez l’état accepté aux clients.
Modification des shapes, fusion et performance
La modification des shapes est l’un des domaines les plus exigeants de l’expérimentation API. Un script peut trouver la bonne cible tout en produisant malgré tout des résultats inattendus lorsque le jeu sépare, recrée ou fusionne des shapes de construction. Repeindre une zone existante peut donc se comporter différemment de la pose d’un nouveau bloc.
Lorsqu’un outil agit sur des shapes voisines, comparez plus que la position. Un contrôle robuste peut devoir prendre en compte :
- L’existence d’un point ou d’une clé correspondante
- La direction de la prochaine limite
- La couleur associée aux données de la shape
- L’appartenance de l’objet au body attendu
- Le fait que l’objet soit une part, une shape ou une création plus grande
- Le fait que l’opération s’exécute du bon côté de la frontière client-serveur
Les grandes créations sont de bons tests de résistance, mais elles peuvent aussi masquer l’origine d’un bug. Commencez par un petit mur ou un véhicule compact. Testez ensuite une structure plus grande une fois que l’opération de base fonctionne de manière cohérente.
| Cas de test | Ce qu’il faut observer | Pourquoi c’est important |
|---|---|---|
| Une shape non colorée | Détection de collision et première modification | Confirme le chemin de base |
| Deux couleurs adjacentes | Repeinture et comparaison des couleurs | Révèle le comportement lié à la fusion |
| Véhicule connecté | Propriété du body et de la création | Teste les relations entre objets |
| Grand mur | Coût des boucles et latence visuelle | Met en évidence la pression sur les performances |
| Plusieurs outils | Modifications dupliquées et synchronisation | Teste des interactions de type course |
Une optimisation courante consiste à éviter de rescanner en permanence des données qui peuvent être indexées. Des tables de recherche temporaires peuvent enregistrer les points ou identifiants de shapes déjà traités, réduisant ainsi le travail en double au cours d’une même opération. Videz la table au bon moment du cycle de vie afin que les anciennes entrées n’affectent pas les interactions suivantes.
Les raycasts méritent eux aussi des tests ciblés. Une particule ou un effet peut sembler traverser une surface alors que le vrai problème est sa position de génération, sa vitesse, son timing de collision ou une cible placée trop près. Déplacer légèrement l’effet loin de la surface touchée peut aider à distinguer le comportement de collision du chevauchement visuel.
Mesurez le comportement sur de grandes créations seulement après que le petit test fonctionne. Si une boucle touche chaque shape à répétition, réduisez les scans dupliqués avant d’ajouter davantage de fonctionnalités GUI ou d’effets.
| Optimisation | Cas d’usage | Compromis |
|---|---|---|
| Table de recherche | Vérifications répétées de points ou d’identifiants | Nécessite un nettoyage |
| Raycast ciblé | Petits outils précis | Ciblage moins tolérant |
| Création de test plus petite | Débogage initial | Ne représente pas la charge maximale |
| Validation côté serveur | Actions partagées sur le monde | Ajoute de la gestion de requêtes |
| Mises à jour GUI limitées | Sliders et entrées répétées | Nécessite un timing de rafraîchissement délibéré |
Checklist de débogage API et pratiques de documentation
Le développement API est plus simple lorsque chaque erreur est réduite à un petit test reproductible. Évitez de modifier en même temps les raycasts, le réseau, le stockage et le code GUI. Confirmez d’abord que l’objet existe, puis la valeur renvoyée, et seulement ensuite son raccord avec le système suivant.
Utilisez cette checklist avant de considérer qu’une fonctionnalité de mod est prête :
Checklist de test de l’API :
- Confirmez chaque nom de fonction, signature et indication de disponibilité dans la référence API publiée
- Testez indépendamment les callbacks client et serveur
- Validez les données de shape, body, création et couleur avant de modifier des objets
- Limitez les valeurs de la GUI et rejetez les modes inconnus
- Testez les paramètres sauvegardés après rechargement et synchronisation multijoueur
Tenez un tableau de notes API
Une petite référence de projet peut faire gagner du temps lorsque les entrées officielles publiées sont brèves. Notez le nom de la fonction, l’objet propriétaire, le contexte du callback, la valeur de retour et un résultat de test minimal. Ne considérez pas une hypothèse comme une fonctionnalité API confirmée.
| Champ de note | Contenu d’exemple |
|---|---|
| Fonction | Nom exact publié de la fonction |
| Propriétaire | Objet shape, body, création, GUI ou outil |
| Contexte | Client, serveur, callback ou partagé |
| Retour | Type de valeur ou résultat documenté |
| Testé | Résultat d’une petite reproduction |
| Risque | Entrée manquante, comportement de fusion ou souci multijoueur |
Lier la bonne référence
Pour consulter l’API actuelle, utilisez la référence consultable Scrap Mechanic Lua API. Le site indique comme source la référence publiée de Scrap Mechanic et affiche une date de build 2026-07-24 UTC. Pour une entrée douteuse, comparez-la avec le matériel API du fournisseur d’origine plutôt que de vous fier uniquement à une interprétation communautaire.
Affichez une seule valeur utile à la fois : le résultat du hit, l’identifiant, la couleur, les limites ou la charge utile réseau. De petits journaux sont plus faciles à interpréter qu’un grand flot d’états mélangés.
FAQ pour le modding Lua de Scrap Mechanic
Q: Qu’est-ce que l’API de Scrap Mechanic ?
C’est l’interface de scripting publiée pour les fonctions et objets exposés à Lua dans Scrap Mechanic. Le site consultable SM Docs organise cette référence sans prétendre remplacer les fichiers API d’origine.
Q: Quelle version de Lua utilise Scrap Mechanic ?
Scrap Mechanic utilise LuaJIT, et la documentation API indique que LuaJIT est couvert par le manuel de référence Lua 5.1. Utilisez un comportement linguistique compatible Lua 5.1 lors de la conception des scripts.
Q: Le code GUI doit-il s’exécuter côté client ou côté serveur ?
La présentation GUI et l’interaction locale appartiennent généralement au client. Les paramètres qui affectent l’état partagé du monde doivent être envoyés via un chemin de requête approprié et validés par le serveur.
Q: Pourquoi le repeinture des shapes peut-il se comporter de façon inattendue ?
Les modifications de shapes peuvent interagir avec les comportements de séparation et de fusion. Un script peut recréer ou fusionner des pièces avant qu’une opération de couleur ultérieure ne s’achève, il faut donc tester séparément les positions, couleurs, limites, propriété et ordre des opérations.
Un bon mod API ne se définit pas seulement par l’apparence impressionnante de l’outil final. Il doit aussi avoir une propriété prévisible, des paramètres lisibles, un trafic réseau maîtrisé et des tests qui expliquent ses cas d’échec. Commencez par la référence publiée, construisez un système à la fois, et utilisez de petites créations avant de passer à de grands scénarios multijoueur.
Considérez la référence API comme votre contrat, mais traitez les tests en jeu comme une validation essentielle pour la géométrie, les callbacks, le comportement de la GUI et l’état multijoueur.