Revision as of 11:04, 25 November 2019

The information in this Wiki Page applies to TANE, TRS19 and Trainz Plus.

Message Popup Icons

Message Popup Icons are small graphic icons that can be placed in browser message windows in Driver mode. The browser windows are created by the Message Popup Rule.

The icons used in Custom Message Popups belong to the class of Textures - Not Environmental

Information on creating and using Message Popups can be found on the Trainz Wiki pages at:-

How to Create a New Non-Environmental Texture Asset

Step 1: Create the Asset

From the Trainz Launcher

select Manage Content
in Content Manager open the Developer menu
select New Content

This will create a new asset and open it for editing.

A message window will appear that will (hopefully) report on the successful creation of a new asset.

Close the message window

Step 2: Find the New Asset

Set the CM Search Filter to Open for Editing

This will display only those assets that have been opened for editing (hopefully only your new and as yet unnamed asset will be shown)

Step 3: Open the Asset in Windows Explorer

Right mouse click on the entry New Asset
Select Open
Select Show in Explorer

Step 4: Open File in Notepad

There will only be a single item in the asset, its config.txt file

Double click on the file to open it in Notepad

Step 5: Edit the File

You will need to edit the contents of this file.

The next section, The Config.txt File, identifies the changes you will need to make.
The new name you give to the asset will not take effect until after it has been committed.
After editing, save the changes and exit Notepad.

Warning:
	Unless you know exactly what you are doing, DO NOT ALTER THE KUID NUMBER that has been added to the file

Step 6: Add Any "Extras"

You will need to add three additional files (possibly more depending on how the icon is created) to the asset folder:-

a thumbnail image as described in the section The Thumbnail Image
the icon image as described in the section The Icon Image
a texture text file as described in the section The Texture File

These file do not have to be added immediately but must be present before the new asset can be used. You can reopen the asset for editing later to add the files before it is committed.

THIS IS AN EXAMPLE ONLY

This is the minimum number of files needed in a Texture asset

Step 7: Finish Up

Close the Asset window
Commit the asset in Content manager

Right mouse click on the asset
Select Submit Edits

Hopefully there will be no errors.

Notes:
Because you still have the Filter Open for Editing in operation, the now closed and committed asset will vanish from the window display. To check that your asset has been correctly created and renamed, set the CM Search Filter to "Today".

Some of the most common errors that can occur when creating and committing a new asset are:-

no thumbnail image in the asset
typing errors in the config.txt or .texture.txt files
poorly formatted tags in the config.txt file
incorrect file types added to the asset folder
files missing from the asset folder
incorrect kuid value (despite the warning you changed it in Step 5)

The Config.txt File

This file should follow the same (or a similar) format as the example below. Entries in blue will be different for each asset. The order of the "tags" is not important:-

kuid                                    <kuid:this is an auto-generated number>
kind                                    "texture"
texture                                 "asset_name.texture"
username                                "place your selected asset name here"
category-class                          "JI"
trainz-build                            4.3

thumbnails
{
  0
  {
    width                               240
    height                              180
    image                               "name_of_thumbnail.jpg"
  }
  1
  {
    width                               64
    height                              64
    image                               "asset_name.texture"
  }
}
description                             "Place your description of what the icon represents here"

Settings:

For the above example:

The <kuid> is unique to every asset so it is not advisable to choose your own. This will be automatically generated by the Content Manager program when a new asset is created
The kind identifies the type of asset and the types of files that Trainz will expect to find in the asset. It also tells Trainz how to render and error check the asset. A list of asset kinds can be found at KIND Hierarchy
The texture is the name of the assets texture file. This will be a simple text file and will have the name asset_name.texture where asset_name will be a name you have selected for this asset - e.g. "ashpit.texture". The actual texture file itself will be named asset_name.texture.txt (e.g. "ashpit.texture.txt") but the filename ending ".txt" is not added to the name in the texture tag
The username is your name for the asset and the name that other users will see. It is a good idea to make it compact and meaningful.
The category-class identifies the intent of the asset and is important in classifying it for filtering and searching. A list of category classes can be found at Category-class
The trainz-build identifies the minimum Trainz version for this asset. A list of asset trainz-build numbers and their corresponding Trainz versions can be found at "Trainz-build"_number
The thumbnails container holds the preview images of the asset shown by the Content Manager program, the Web version of the DLS and the Message Popup Rule. It also contains the icon image. Information on thumbnails can be found at Thumbnails
- The first thumbnail (size 240 x 180) is the thumbnail image used by CM and the Web DLS Page for this asset. The thumbnail image container value "0" is simply a placeholder for the thumbnail image, its exact value does not matter
  - The image is the name of the thumbnail image - it must be a JPG format image
  - The width of the image must be 240 pixels
  - The height of the image must be 180 pixels
- The second thumbnail (size 64 x 64) is the icon image used by the Message Popup Rule for this asset. The icon image container value "1" is simply a placeholder for the icon image, its exact value does not matter but it must be different from the thumbnail image container
  - The image is the assets asset_name.texture.txt file (but without the ".txt" at the end)
  - The width of the image must be 64 pixels
  - The height of the image must be 64 pixels
The description provides more details for users than the username

The Icon Image

You will need image editing software to create the icon image or to change an existing image to the required dimensions and format.

(not to scale)

Settings:

The image must meet the following specifications:-

64 pixels wide and 64 pixels tall
bit depth should be 24 (no alpha channel or transparency) or 32 (if an alpha channel is used)
image file format can be any of:-
- bmp
- jpg (jpg does not support transparency)
- png
- tga (tga compression should not be used)

If your image will have a transparency, such as a transparent background, it is usually a lot easier to save the image in a format that supports an alpha channel (bmp, png or tga) and either

convert the background to a transparency or
remove the background and add a transparent layer to the image as its background

than it is to use a format that does not support an alpha channel and have to create a second image for the alpha channel. See

The Texture File below.

The Texture File

The .texture.txt file controls how an image icon is displayed, particularly its Alpha Channel (or transparency) data. The file must be present even if no transparency is used in the icon.


	Settings: the Texture File is a standard text file the filename is composed of:- a user selected asset_name followed by a period (.) the word texture followed by a period (.) the letters txt

A sample Texture File, "ashpit.texture.txt", is shown below:-

primary=ashpit.jpg
alpha=ashpit.bmp
tile=st


	Settings: primary - this is the name of the icon image file that contains the RGB colour image. Any alpha channel in this file will be ignored alpha - this is the name of the icon image file that contains the Alpha Channel (transparency) image (see Notes: below) tile=st - instructs Trainz to tile the image both horizontally and vertically. This has no effect on the icon in a message popup window but must be included for validation purposes No "white spaces" between the text characters is allowed.

Notes:

There are 3 general "scenarios" for the structure of the Texture File in a Texture Non Environmental asset.

If the icon has a transparency (an alpha channel) and is saved in a format that supports the alpha channel

Then:-

primary=ashpit.tga
alpha=ashpit.tga
tile=st

the primary and alpha images are the same file, as in the example shown left
the image must contain both the RGB colour data and the Alpha Channel (transparency) data (it must have a depth of 32 bits)

If the icon needs to have transparency (an alpha channel) but an alpha channel is not available (e.g. it is saved in the jpg file format) or is not suitable

Then:-

primary=ashpit.jpg
alpha=ashpit_alpha.jpg
tile=st

two different files (different file names or different image file formats) must be used as in the example shown left
both images must be the same size (64 pixels x 64 pixels)
both images must have a depth of 24 bits - so no alpha channel must be present in either image
the alpha image file should be a greyscale image or even just black and white

If the icon image does not have a transparency and no alpha channel is needed

Then:-

primary=ashpit.tga
tile=st

the alpha= line in the .texture.txt file is not needed, as in the example shown left
the primary file contains the RGB colour data and can be in any supported image format. If it also has alpha channel data then that data it will be ignored so the icon will be shown without any transparency

Image file formats supported by Trainz that have an alpha channel are:-

bmp
png
tga

Image file formats supported by Trainz that DO NOT have an alpha channel are:-

jpg

A detailed description of the .texture file format can be found on the Trainz Wiki Page at:-

Texture File

Using the Asset

Once the new asset has been committed it will be available for use in a Message Popup Rule. It will appear as a Texture Asset in the rule icon list.