Since Tiled 1.3

Création de Script

Introduction

Tiled peut être étendu avec l’utilisation de JavaScript. Visitez l’API de Création de Script Tiled pour une référence de toutes les fonctionnalités disponibles.

Les définitions TypeScript de l’API sont disponibles dans le paquet NPM @mapeditor/tiled-api, qui peut fournir une auto-complétion dans votre éditeur. La référence de l’API est générée suivant ces définitions.

On startup, Tiled will execute any script files present in extension folders. In addition it is possible to run scripts directly from the console, as well as to evaluate a script file from the command-line. All scripts share a single JavaScript context.

Note

Quelques exemples de scripts et des liens vers des extensions de Tiled sont fournis dans le répertoire d’Extensions Tiled : https://github.com/mapeditor/tiled-extensions

JavaScript Host Environment

Tiled uses the JavaScript engine shipping with Qt’s QML module. The QML runtime generally implements the 7th edition of the standard, with some additions. See the JavaScript Host Environment documentation for details.

It may also be helpful to check out the List of JavaScript Objects and Functions that are available.

Note

The full scripting API and support for ECMAScript 7 features are only available for Tiled builds based on Qt 5.12 or later. This currently excludes the Windows XP and snap releases before Tiled 1.8.1.

Extensions Scriptées

Les extensions peuvent être placées dans une location pour un système spécifique ou un projet spécifique.

Le dossier pour les extensions pour un système spécifique peut être ouvert depuis l’onglet Greffons dans la fenêtre de Préférences. La location usuelle de chaque plateforme supportée est comme ceci :

Windows

C:/Users/<USER>/AppData/Local/Tiled/extensions/

macOS

~/Library/Preferences/Tiled/extensions/

Linux

~/.config/tiled/extensions/

Les dossier spécifiques à chaque projet est nommé « extensions » par défaut, relativement au dossier du fichier .tiled-project, mais cela peut être changé dans les Propriétés du Projet.

Avertissement

Depuis Tiled 1.7, les extensions spécifiques à un projet sont seulement activées par défaut pour les projets que vous avez créés. Lorsque vous ouvrez tout autre projet, un popup vous notifiera lorsqu’un projet a un dossier d’extensions scriptées, qui vous permet ensuite d’activer les extensions pour ce projet.

Faites toujours attention lors de l’activation d’extensions pour des projets que vous n’avez pas créés, car les extensions ont accès à vos fichiers et peuvent lancer des processus.

Une extension peut être placée directement dans un dossier extensions, ou dans un sous-dossier. Tous les scripts trouvés dans ces dossiers sont lancés au lancement de l’application.

Since Tiled 1.8

When using the .mjs extension, script files are loaded as JavaScript modules. They will then be able to use the import and export statements to split up their functionality over multiple JavaScript files. Such extensions also don’t pollute the global scope, avoiding potential name collisions between different extensions.

Quand tout script chargé est changé ou lorsque n’importe quel fichier est ajouté/enlevé du dossier extensions, le moteur de script est automatiquement réinitialisé et les scripts sont rechargés. De cette façon, il n’y a pas besoin de relancer Tiled lors de l’installation d’extensions. C’est aussi plus rapide lors de l’édition d’un script jusqu’à ce qu’il marche comme prévu.

Mis à part les scripts, les extensions peuvent inclure des images qui peuvent être utilisées en tant qu’icônes pour les actions scriptées ou les outils.

Vue Console

Dans la vue Console (Vue > Vues et Barres d’Outils > Console) vous allez voir une entrée de texte où vous pouvez écrire ou coller des scripts pour les évaluer.

Vous pouvez utiliser les touches Haut/Bas pour naviguer entre les expressions de scripts entrées précédemment.

Since Tiled 1.9

Command Line

To execute a script (.js) or to load a module (.mjs) from the command-line, you can pass the --evaluate option (or -e), followed by the file name. Tiled will quit after executing the script.

The UI will not be instantiated while evaluating scripts on the command-line. This means functions that rely on the UI being present will do nothing and some properties will be null. However, scripts are able to load and save maps and tilesets through the available formats (see tiled.mapFormats and tiled.tilesetFormats), as well as to make any modifications to these assets.

Any additional non-option arguments passed after the script file name are available to the script as tiled.scriptArguments.

If you want to evaluate several scripts, use --evaluate for each file. Note that evaluating the same JavaScript module (.mjs) does not work, since modules are loaded only once.

Référence de l’API

Visitez l’API de Création de Script Tiled.

La variable globale suivant n’est pour le moment pas documentée dans la documentation générée, car elle génère des conflits avec des types de nodejs :

__filename

Le chemin du fichier couramment évalué. Seulement disponible pendant l’évaluation initiale du fichier et non lorsque des fonctions de ce fichier sont appelées plus tard. Si vous en avez besoin, copiez cette valeur dans une variable locale.