1Using Commands
2==============
3
4The Command Button allows you to create and run shell commands (other
5programs) from Tiled.
6
7You may setup as many commands as you like. This is useful if you edit
8maps for multiple games and you want to set up a command for each game.
9Or you could setup multiple commands for the same game that load
10different checkpoints or configurations.
11
12The Command Button
13------------------
14
15It is located on the main toolbar to the right of the redo button.
16Clicking on it will run the default command (the first command in the
17command list). Clicking the arrow next to it will bring down a menu that
18allows you to run any command you have set up, as well as an option to
19open the Edit Commands dialog. You can also find all the commands in the
20File menu.
21
22Apart from this, you can set up custom keyboard shortcuts for each
23command.
24
25Editing Commands
26----------------
27
28The 'Edit Commands' dialog contains a list of commands. Each command has
29several properties:
30
31Name
32    The name of the command as it will be shown in the drop
33    down list, so you can easily identify it.
34
35Executable
36    The executable to run. It should either be a full
37    path or the name of an executable in the system PATH.
38
39Arguments
40    The arguments for running the executable.
41
42Working directory
43    The path to the working directory.
44
45Shortcut
46    A custom key sequence to trigger the command. You can use 'Clear'
47    to reset the shortcut.
48
49Output in Debug Console
50    If this is enabled, then the output (stdout and stderr) of this
51    command will be displayed in the Debug Console. You can find the
52    Debug Console in *View > Views and Toolbars > Debug Console*.
53
54Save map before executing
55    If this is enabled, then the current map will be saved before
56    executing the command.
57
58Enabled
59    A quick way to disable commands and remove them from the drop down list.
60    The default command is the first enabled command.
61
62Note that if the executable or any of its arguments contain spaces,
63these parts need to be quoted.
64
65Substituted Variables
66~~~~~~~~~~~~~~~~~~~~~
67
68In the executable, arguments and working directory fields, you can use
69the following variables:
70
71``%mapfile``
72    the full path of the current file (either map or tileset).
73
74``%mappath``
75    the path in which the current file is located.
76
77.. raw:: html
78
79   <div class="new new-prev">Since Tiled 1.4</div>
80
81``%projectpath``
82    the path in which the current project is located.
83
84``%objecttype``
85    the type of the currently selected object, if any.
86
87``%objectid``
88    the ID of the currently selected object, if any.
89
90``%layername``
91    the name of the currently selected layer.
92
93.. raw:: html
94
95   <div class="new">New in Tiled 21.4</div>
96
97``%tileid``
98    a comma-separated list with the IDs of the selected tiles, if any.
99
100For the working directory field, you can additionally use the following
101variable:
102
103``%executablepath``
104    the path to the executable.
105
106
107Example Commands
108----------------
109
110Launching a custom game called "mygame" with a -loadmap parameter and
111the mapfile:
112
113::
114
115    mygame -loadmap %mapfile
116
117On Mac, remember that Apps are folders, so you need to run the actual
118executable from within the ``Contents/MacOS`` folder:
119
120::
121
122    /Applications/TextEdit.app/Contents/MacOS/TextEdit %mapfile
123
124Or use ``open`` (and note the quotes since one of the arguments contains
125spaces):
126
127::
128
129    open -a "/Applications/CoronaSDK/Corona Simulator.app" /Users/user/Desktop/project/main.lua
130
131Some systems also have a command to open files in the appropriate
132program:
133
134-  OSX: ``open %mapfile``
135-  GNOME systems like Ubuntu: ``gnome-open %mapfile``
136-  FreeDesktop.org standard: ``xdg-open %mapfile``
137