The information in this Wiki Page applies to '''TANE''', '''TRS19''' and '''Trainz Plus'''. The large "introduction windows" and smaller popup "message windows" that can be added to a Session are (mostly) '''HTML assets'''. This Wiki Page describes how '''HTML assets''' are created, what they contain and how they can be added to a Session.<br>

<table> <!-- BEGIN Nav Buttons Table -->

<td width=729><span id="stepHTML"></span>&nbsp;</td>

='''HTML Assets'''=

<table cellpadding="4" bgcolor=#c1e7e7> <!-- BEGIN Summary table -->

<td colspan=2><span style="font-size: 17px;"><b>In Summary:</b></span></td>

<td>[[image:DotPoint.JPG|link=]]</td>

<td>'''HTML assets contain the text information, graphic images and sounds (those that are not built into locos and other assets) that can be displayed and played during a session''' in

*large browser windows during the running of a session<td>

<td>[[image:DotPoint.JPG|link=]]</td>

<td>'''A single HTML asset can provide all the text, graphic and sound data for an entire session and for multiple sessions.'''<td>

<td>[[image:DotPoint.JPG|link=]]</td>

<td>'''At the most basic level you do not have to create a HTML asset for your session.''' You can use existing resources (graphics and sounds) and add your own text to simple on-screen '''Popup Messages''' using '''Session Rules'''. See the section [[image:PageLink.PNG|link=]] '''[[#Adding a Message Popup to a Session|Adding a Message Popup to a Session]]''' below.<td>

</table> <!-- END Summary table -->

 

<table bgcolor="black" width=704> <!-- BEGIN Notes table -->

<td>[[image:NotePad.PNG|link=]]</td>

HTML assets in '''Trainz''' consist of:-

*a '''config.txt file''' which is mandatory

*one or more '''graphic files''' of type '''JPG''', '''TGA''', '''PNG''' or '''BMP'''. One of these '''must be the asset thumbnail'''

and as '''options only''' (not compulsory):-

*one or more '''HTML formatted text files''' of type '''HTM''' or '''HTML'''

*one or more '''sound files''' of type '''WAV'''

<table> <!-- BEGIN Nav Buttons Table -->

<td width=729><span id="stepCreate"></span>&nbsp;</td>

<table cellpadding="4" bgcolor=#ffffff> <!-- BEGIN Step table -->

</tr>

<td>[[image:Steps.PNG|link=]]<br><br>

<span style="font-size: 17px; font-weight: 700;">Steps</span></td>

<td>From the '''Trainz''' Launcher

#select <span style="color: white; background-color: black; font-weight: 700; font-size: 15px;">&nbsp;Manage Content&nbsp;</span>

#in '''Content Manager''' open the '''Developer''' menu

#select '''New Content'''

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

<br><br>

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

</table> <!-- END Step 1 table -->

<tr>

----</td>

<td>&nbsp;</td>

<table> <!-- BEGIN Step 2 table -->

*Set the '''Content Manager''' 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)

</table> <!-- END Step 2 table -->

<tr>

----</td>

<td>&nbsp;</td>

<table> <!-- BEGIN Step 3 table -->

#Right mouse click on the entry '''New Asset'''

#Select '''Open'''

#Select '''Show in Explorer'''

<tr>

<td colspan="2">

----</td>

</tr>

<td>&nbsp;</td>

<td>[[image:DotPoint4.JPG|link=]]&nbsp;<span style="font-size: 17px; font-weight: 700;">Open Config.txt File in Notepad:</span><br>

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

*Double click on the file to open it in '''Notepad'''</td>

</table> <!-- END Step 4 table -->

<tr>

----</td>

<td>&nbsp;</td>

<td>You will need to edit the contents of this file.  

*The next section, [[image:PageLink.PNG|link=]] '''[[#The Config.txt File|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 '''Submitted'''.

*After editing, save the changes and exit '''Notepad'''.</td>

</table> <!-- END Step 5 warning table -->

<tr>

<td colspan="2">

----</td>

</tr>

<td>&nbsp;</td>

<table> <!-- BEGIN Step 6 table -->

*You will need to add at least one file to the asset folder, a thumbnail image as described in the section [[image:PageLink.PNG|link=]] '''[[#Graphic Files|Graphic Files]]''' below.

*Other files, such as additional images, sound (wav) files and HTML files may need to be added depending on the type of HTML asset that is being created. These topics are covered in the sections [[image:PageLink.PNG|link=]] '''[[#Graphic Files|Graphic Files]]''', [[image:PageLink.PNG|link=]] '''[[#Audio Files|Audio Files]]''' and [[image:PageLink.PNG|link=]] '''[[#HTML Files|HTML Files]]''' below.

<br>

These files 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 '''Submitted'''.<br><br><span style="font-size: 17px;">'''THIS IS AN EXAMPLE ONLY'''</span><br></td>

<tr>

<td colspan="2">

----</td>

</tr>

<td>&nbsp;</td>

<table> <!-- BEGIN Step 7 table -->

*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.<br><br>

<table width=604 bgcolor=#000000> <!-- BEGIN Step 7 Notes table -->

<table width=600 bgcolor=#ffffb0> <!-- BEGIN Step 7 Notes table -->

<td>[[image:NotePad.PNG|link=]]</td>

<table cellpadding="4" bgcolor=#ff0000> <!-- BEGIN Step 7 errors table -->

*no '''''thumbnail image''''' in the asset

*typing errors in the config.txt file

*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''')</td>

<table> <!-- BEGIN Nav Buttons Table -->

<td width=729><span id="stepConfig"></span>&nbsp;</td>

<table cellpadding="4" bgcolor=#c1e7e7> <!-- BEGIN Dot point table -->

<td>[[image:DotPoint.JPG|link=]]</td>

<table cellpadding="4" bgcolor=#eeeeee> <!-- BEGIN Settings table -->

<td><span style="font-size: 17px;">'''Settings:'''</span><br>

The HTML asset must have a '''config.txt''' text file that '''must''' include the following tags:-

*'''kind''' set to "html-asset"

*'''username''' set to the asset title or name

*'''kuid''' a unique ID code

*'''thumbnails''' set to a 240 by 180 pixel JPG image

While not mandatory, the following tag is useful:-

*'''category-class''' set to "YH"'''

This file should follow the same (or a similar) format as the example below.<br>

*entries in&nbsp;<span style="background-color: red; color: white; font-weight: 700;">&nbsp;red&nbsp;</span>&nbsp;must not be changed

*the indenting of the lines and the spacing ("tabbing") between the "tags" on the left and their contents on the right are purely to make it easier for humans to read

*the use of the '''{}''' braces is to group tags into common "containers". These containers must not be broken up and the number of '''{''' characters must match the number of '''}''' characters

*the order of the "tags" is not important

  '''kuid'''                                    <span style="background-color: red; color: white; font-weight: 700;"><kuid: this is an auto-generated number ></span>

<table cellpadding="4" bgcolor=#eeeeee> <!-- BEGIN Settings table -->

<td>[[image:Gears.PNG|link=]]</td>

'''For the above example:'''<br>

*The&nbsp;<span style="background-color: black; color: white; font-weight: 700;"> kuid </span>&nbsp;is unique to every asset so it is&nbsp;<span style="background-color: red; color: white; font-weight: 700;">&nbsp;not a good idea to choose your own&nbsp;</span>&nbsp;. This will be automatically generated by the '''Content Manager''' program when a new asset is created

*The&nbsp;<span style="background-color: black; color: white; font-weight: 700;"> username </span>&nbsp;is your name for the asset and the name that other users will see. It is a good idea to make it short and meaningful.

*The&nbsp;<span style="background-color: black; color: white; font-weight: 700;"> trainz-build </span>&nbsp;identifies the ''minimum'' Trainz version needed for this asset. A list of asset trainz-build numbers and their corresponding Trainz versions can be found at [[image:WikiLink.PNG|link=]] '''[["Trainz-build"_number]]'''

*The&nbsp;<span style="background-color: black; color: white; font-weight: 700;"> kind </span>&nbsp;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 [[image:WikiLink.PNG|link=]] '''[[KIND_TrainzBaseSpec#KIND_Hierarchy|KIND Hierarchy]]'''

*The&nbsp;'''<span style="background-color: black; color: white; font-weight: 700;"> description </span>'''&nbsp;provides more details for users than the '''username'''.

*The&nbsp;<span style="background-color: black; color: white; font-weight: 700;"> category-class </span>&nbsp;identifies the ''intent'' of the asset and is important in classifying it for filtering and searching. For a HTML-Asset the category-class is "<span style="background-color: red; color: white; font-weight: 700;">YH</span>". A list of category classes can be found at [[image:WikiLink.PNG|link=]] '''[[Category-class]]'''

*The&nbsp;<span style="background-color: black; color: white; font-weight: 700;"> thumbnails </span>&nbsp;container holds the ''preview'' images of the asset shown by the '''Content Manager''' program, the Web version of the ''DLS'' and, for '''some assets''', the Surveyor main menu image(s) and asset textures. Information on thumbnails can be found at [[image:WikiLink.PNG|link=]] '''[[Thumbnails]]'''

**The&nbsp;<span style="background-color: black; color: white; font-weight: 700;">&nbsp;Default&nbsp;</span>&nbsp;is the '''container ID''' or '''placeholder''' for the thumbnail (some types of assets can have several thumbnails) and its ''exact label'' (or number - eg. "Default", "00", "01", etc) is not important but each thumbnail if there are more than one must have a different label. '''Default''' and '''0''' are commonly used placeholder labels for the 240 x 180 thumbnail image

**The '''image''' is the name of the thumbnail image. It does not have to be called '''<span style="color: black;">thumbnail.jpg</span>''' but it '''must''' be a JPG format image

**The '''width''' of the image in pixels must be <span style="background-color: red; color: white; font-weight: 700;">240</span>

**The '''height''' of the image in pixels must be <span style="background-color: red; color: white; font-weight: 700;">180</span>

</table> <!-- END Settings table -->

<table cellpadding="4" bgcolor=#ffffb0>

If you are going to use the '''String Table''' method of adding HTML message windows, then the '''config.txt''' file will need a '''string-table''' container. For example:-

The "tags", '''warning_message_stop''' and '''warning_message_speed''' in the example shown above, are called "String Table Tokens" and are used to identify which message is to be displayed.<br>

For more details of string-tables, see the section [[image:PageLink.PNG|link=]] '''[[#Option 3: A String Table|Option 3: A String Table]]''' below.<br>

 

<table> <!-- BEGIN Nav Buttons Table -->

<td width=729><span id="stepGraphic"></span>&nbsp;</td>

<table border="1" cellpadding="5" bgcolor=#c1e7e7>

*lossy compression

*no transparency</td>

*lossless but no compression

*limited transparency</td>

*lossless compression

*transparency</td>

*lossless with optional compression

*optional transparency</td>

<td>Use if compatibility with older Trainz versions is needed</td>

*a text file containing the names of image files

*controls how the images are displayed</td>

The above are not the only image file formats supported by '''Trainz''' but those unlisted formats are not common and are not usually recommended.

 

<table cellpadding="4" bgcolor=#c1e7e7>

<td>[[image:DotPoint.JPG|link=]]</td>

<table bgcolor="black" width=804>

<td>[[image:NotePad.PNG|link=]]</td>

*must be in '''JPG''' format.

*must be '''240''' pixels wide by '''180''' pixels tall.

*'''does not''' have to be named ''thumbnail.jpg'' as long as the name used is in the '''Thumbnails''' container in the '''config.txt''' file.

 

<table cellpadding="4" bgcolor=#c1e7e7>

<td>[[image:DotPoint.JPG|link=]]</td>

<td>While '''Trainz''' supports compressed TGA format files, the current advice is '''NOT to use compression when saving images in this format'''.</td>

JPGs are still the most widely used image format for web pages and all Trainz versions support this format. The main problem with JPG is that it uses a "lossy" compression method - image data is thrown away or deleted every time a JPG image is saved. If you are constantly loading, editing and then saving the same JPG image, then the quality of the image will noticeably decline over time.

<br><br>

<table bgcolor="black" cellpadding=2>

<table bgcolor=#ffffb0 cellpadding=2>

*keep the original image in a lossless format such as '''PNG''' or '''TGA'''

*when editing the image, ''always'' save the edited image in a lossless format

*only when all the editing has been completed, export the image as a '''JPG'''

 

<table cellpadding="4" bgcolor=#c1e7e7>

<td>[[image:DotPoint.JPG|link=]]</td>

<table cellpadding=5>

<table cellpadding="4" bgcolor=#ffffb0>

<td>[[image:NotePad.PNG|link=]]</td>

<td>&nbsp;</td>

<td>

*The '''texture''' format ''does not'' replace the other supported image formats ('''BMP''', '''JPG''', '''PNG''' or '''TGA''') but simply provides additional options for controlling how those image files are used, particularly their '''alpha channels'''.

*In earlier versions of '''Trainz''' the '''texture''' files were actually graphic files. They are still used as graphic files in '''built-in''' and '''base''' assets to speed-up asset loading and this is the reason why built-in and base assets cannot be transferred from one version of Trainz to another by using '''.cdp''' files.</td>

<table cellpadding="4" bgcolor="Aquamarine">

<table cellpadding="4" bgcolor=#c1e7e7>

<td>[[image:DotPoint.JPG|link=]]</td>

Transparencies in images are essentially colours or ''layers'' that are rendered invisible when the image is displayed. This makes parts of the image transparent so the colours or patterns behind the image, such as the background page, can be seen.

 

Shown below is the '''Message Popup''' browser window from a '''Trainz Session'''. The two images it contains are from the same original image but displayed in two different image formats.

 

<td>[[image:TransparencyDemo.JPG|link=]]</td>

*The STOP sign on the left has been exported as a '''JPG''' which has no transparency (or alpha channel) so the image background is shown as a colour, in this case white.

*The STOP sign on the right has been exported as a '''TGA''' with its background layer saved as an '''Alpha Channel''' which is rendered transparent so the background colour of the browser window shows through.

 

There is a wide variety of graphical software applications available that would be suitable for creating '''Trainz''' ready images, both commercial and freeware.

 

<td>[[image:NotePad.PNG|link=]]</td>

<td><span style="font-size: 17px; font-weight: 700;">'''Notes:'''</span><br>

The minimum requirements for a suitable graphics package for use in creating '''Trainz HTML''' assets would be:-

*load and save (or export) images in '''JPG''' and either '''TGA''' or '''PNG''' formats

*support for an alpha channel

"Nice to have" features would include:-

*support for layers

*text editing

 

<table> <!-- BEGIN Nav Buttons Table -->

<td width=729><span id="stepHTML2"></span>&nbsp;</td>

='''HTML Files'''=

 

'''HTML''' (Hyper Text Markup Language) is the "language" that creates web pages. Creating HTML files (or web pages) is not a simple process. If you have never worked with HTML before then there will be a learning curve. Fortunately it is possible to start at a very basic level and progress as you learn.

 

<table cellpadding="4" bgcolor=#c1e7e7>

<td>[[image:DotPoint.JPG|link=]]</td>

A HTML page is constructed by "tags", words and codes enclosed by '''"&lt;"''' and '''"&gt;"''' symbols. These tags control the layout of the page and how the text and images are displayed.

If the above page is loaded into a normal web browser, this is what you would see.

'''The problems:'''

What happened to the:-

*blank line between the heading and the first line of text?

*'''Return Key''' codes (or '''end-of-line''' characters) at the ends of each line?

*extra spaces placed between the sentences in the first line of text?

 

<table bgcolor=#ff0000 width=900>