Home

TileCutter is a tool designed to allow easy creation of multi-tile or multi-view building graphics for use with the Simutrans game. Its primary purpose is to take an image (or set of images) of a building and cut them into the individual paksize tiles used by the game to display the building. It can output source files (.dat and .png), a .pak file (by integrating with the Simutrans Makeobj utility) or both.

• Interface
  • GUI
  • CLI
• Basic Usage
  • GUI
  • Command Line
• Default File Locations

Interface

TileCutter has two interfaces, a cross-platform graphical user interface (GUI) provided by wxWidgets and a command line interface (CLI). The GUI is used to configure all of the attributes of a cutting operation. The configuration can then be saved to a TileCutter Project .tcp file. The CLI can then be used to "compile" the .tcp file and source images into either Simutrans object source files or a compiled .pak file.

GUI

The GUI is laid out around the image display view-port. This displays the currently selected image. You can tell which image is currently selected by observing the settings in the left-hand image selection pane. Simutrans objects can have a number of different "views", for Front and Back Image, Facing Direction and Seasons. See the Basic Usage section for more info.

Above the image display view-port are controls to select an image file for this view, there is also a button to allow you to reload the source image (this is done automatically at export, TileCutter does not store the source images so you are free to edit them in another application). Below the image display view-port there are controls for the various paths associated with the project. The _ Project Save Location_ is the current location of the project save file. All other paths are relative to this one, this allows you to move the project save file and still keep the same relative paths for exporting files and reading source files. Below this there are three output locations, for the .dat, .png and .pak files. If the .pak output is left blank, or is set to a directory (with a trailing slash) then the default .pak file naming scheme is used by Makeobj.

TileCutter also has a menu bar with the standard functions for saving/loading project files. Under the Tools menu you can set up the .dat file parameters for the project, change the language of the GUI and configure preferences. There is also a function to load the currently selected image for all views in the project - this is useful if you have one source image with multiple views of the building, and want to quickly load it.

CLI

TileCutter's CLI is designed only to allow the scripted processing of .tcp files into .dat/.png and/or .pak files. It allows you to set up many projects and then rebuild them all at once (e.g. for pakset maintainers). It also allows for platform-specific build scripts to be produced, e.g. as part of an automated process for outputting rendered building images. See the Command Line Usage section for more

If TileCutter is run with the -c command line argument the GUI is suppressed and the files specified on the command line will be processed automatically. If the -c option is not specified then the files specified on the command line will be opened in GUI mode. The available options can be found by running the command:

tilecutter -h

For example:

Usage: tilecutter.py [options] filename1 [filename2 ... ]

Options:
  -h, --help    show this help message and exit
  -c            run program in CLI mode (must be specified or program will run
                in GUI mode and load the first file specified on the command
                line)
  -i DIRECTORY  override .png file output location to DIRECTORY
  -I FILENAME   override .png file output name to FILENAME
  -n            disable .dat file output (if -m specified, dat info will be
                output to tempfile)
  -d DIRECTORY  override .dat file output location to DIRECTORY
  -D FILENAME   override .dat file output name to FILENAME
  -m            enable .pak file output (requires Makeobj)
  -p DIRECTORY  override .pak file output location to DIRECTORY
  -P FILENAME   override .pak file output name to FILENAME
  -v            enable verbose output
  -q            suppress stdout

You can override the per-project settings for output directories if needed, this is useful when working with project files made by others.

Basic Usage

GUI

This step-by-step guide will take you over the basics of project creation with TileCutter

1. After opening TileCutter the first thing we need to do is add our source images. You do this either by typing the location of the image in the top bar or by clicking the Browse button next to it. This will open a standard platform-specific file picker dialogue. Select the source image (this must be in .png format) and select Open.
2. You should now see your source image loaded into the view-port window. The path to the specific image is displayed in the top bar.
3. For most projects you will want to specify multiple image views, these could be for a simple purpose like having a different image for the building in the Winter season (or the Snow climate), or more complex needs like Front/BackImages which can be used when creating buildings which vehicles interact with. You can also configure multiple direction views (which is mandatory for odd-shaped buildings, more on this later) so the building looks right when rotated. All of these views are cumulative, so you can have both Summer and Winter images for each rotation, for example.
4. To use these additional views check the checkboxes in the seasons list and "Enable FrontImage" for having front and back images. To enable multiple direction views, select the number of views from the drop-down menu. This will enable the radio buttons which can be used to switch views. Notice that switching views causes the image to vanish from the view-port display. This is normal, and if you move back to the original view the image will come back.
5. If you have one source image with multiple views of an object you may wish to load this one source image for all views. Rather than doing this manually for each view, there is a menu item provided under the Tools menu which can do this for you. Simply load one view with your source image and then select "Same File For All Images" from the menu. The image will be loaded for all views, active or not.
6. For multi-tile buildings it is of course necessary to configure the size and offset. On the main window display-port you may have noticed the red line. This is the cutting mask. Everything inside the red shape will appear in the object when it is compiled and inserted into the game. By default the cutting mask is set to 1 tile by 1 tile. You can change this using the Dimensions control. Key controls here are:

• Paksize - this alters the pixel dimensions of an individual tile, commonly used settings in paksets are 64, 96 and 128 - this must be set to the same as the pakset you are developing an object for
• X dimension - this alters the number of tiles this building takes up in the "North-South" direction (from bottom left to top right of the game screen)
• Y dimension - same as for the X dimension, but for the "East-West" direction (from top left to bottom right of the game screen)
• Z dimension - the height of the building

7. You can also use the Mask Offset to move the mask around the image. This is useful to correct minor alignment errors in the output image, or to select one of multiple views in a source image. The Fine checkbox switches between paksize adjustment and pixel adjustment.
8. Once you have your views configured you may wish to alter the .dat file properties for your project. This can be done using the .dat File Options menu item (or by pressing shortcut Ctrl+D). At present this is just a text entry box where you can specify any object properties you need to. You can find out about the various options at the Simutrans Wiki. The .dat file properties are saved in the project file, so no separate .dat file is required.
9. You should be ready to export your project now. Please check the output locations at the bottom of the screen. All three output locations are relative paths from the Project Save Location. You may wish to change these depending on your environment. On Windows, path sections highlighted in Yellow are ones which do not exist. Please ensure that all directories exist since TileCutter will not create them and will raise an error. If you leave the ".pak Output Location" blank, or specify a directory (with a trailing slash) then the default pakfile naming system of Makeobj will be used. You can override this with your own name if you wish.
10. Once you've configured the output paths you can click on "Cut Image" to export the .dat and .png files to the locations selected. If you don't want to export the .dat file you can deselect the "Write out .dat file" option.
11. If you wish to have TileCutter compile a .pak file for you as part of the export process you can click on the "Compile .pak" button. Please note that you need to have Makeobj available since TileCutter uses this to make .pak files. By default TileCutter will look for a copy of Makeobj in its installation directory, but you can specify an alternative location using the Preferences dialog accessible from the Tools menu.

Command Line

The CLI interface to TileCutter is designed to allow scripted processing of pre-produced .tcp project files. It does not support direct project creation (use the GUI for that). After creating your project file you can feed it into TileCutter at the command line by running a command such as:

tilecutter -c my_project.tcp

This will then process the project file, producing .dat and .png output as defined by the paths specified in the project.

If you wish to run the output through Makeobj, suppress .dat creation, override the creation directories, among other options, you can do so by running the command with flags. For example, the following command switches on .pak file creation and redirects the .pak file creation to ./pakset/ for processing the two projects my_project.tcp and my_second_project.tcp:

tilecutter -c -m -p ./pakset/ my_project.tcp my_second_project.tcp

This interface can be used as part of scripted pakset generation, as part of a workflow for automatically creating rendered objects (e.g. render, post-processing, cutting, Makeobj export) or just to allow one-click object creation as part of an OS-specific script (e.g. Windows Batch file, or Unix Shell Script). If you have a suggestion for an extension to the script interface please let me know.

Default File Locations

Since version 0.5.7 TileCutter attempts to store its configuration and log files in the standard location for the platform it is running on. The configuration file is called tilecutter.config and can be found under one of these locations:

• On Mac OSX: ~/.tilecutter/tilecutter.config
• On Windows: %USERPROFILE%\Application Data\tilecutter\tilecutter.config
• On other platforms: ~/.tilecutter/tilecutter.config

TileCutter will also read configuration from a tilecutter.config file placed in the installation directory. For backwards compatibility only it will similarly read from a tc.config file from an earlier version located in the installation directory.

The log file is called tilecutter.log and can be found under the following locations:

• On Mac OSX: ~/Library/Logs/tilecutter.log
• On Windows: %USERPROFILE%\Application Data\tilecutter\tilecutter.log
• On other platforms: ~/.tilecutter/tilecutter.log

The Windows version can also create a log file called TileCutter.exe.log which will always be found in the directory where the main TileCutter.exe executable is located. This log file will only appear in the case of an exception with the executable). The location of the log file can be controlled by specifying the "logfile" parameter in the configuration file. This is set to "system_default" by default which indicates that the above logic will be used to determine the log file location.