Revision as of 17:42, 26 June 2014

This page describes the TANE Developer Release build, which is available to members of the Trainz Pioneer Council and the Trainz Enthusiast Group. Information provided on this page is publicly visible and not covered by any NDA, however it should be noted that the features described here are NOT available to the public, and may never be available to the public in their current form. The features described here do not relate to any retail version of Trainz and should not be assumed to relate to any future retail version of Trainz. This page may include descriptions of in-development features which are not currently available in the Developer Release build.

Installation

Installation instructions are provided with each Developer Release build, however the following overview may be useful in understanding the layout of the build.

Build Installation: Windows

To install the Developer Release build on Windows 7 or Windows 8, simply unzip the archive and copy the contained TANE folder to your desired installation location. The default location of the retail build will be the Windows Program Files folder, however you may choose to place the build in any suitable location. Do not attempt to merge the TANE folder contents with an existing installation. If you wish to replace an existing installation, then delete that folder first before copying in the new build.

Build Installation: Mac OS X

To install the Developer Release build on Mac OS X, simply unzip the archive and copy the contained Trainz.app to your desired installation location. The default location of the retail build will be the Mac OS X Application Folder, however you may choose to place the app in any suitable location.

Directory Layout

The Developer Release build aims to follow Windows and Mac OS X "best practices" for on-disk layout, which may vary substantially from what existing Trainz users are familiar with. Specifically, for Windows users, any user-modifiable files are no longer stored alongside the exe files in the Windows Program Files folder. On both platforms, the user-modifiable files are stored in the standard per-user application data locations, specifically:

Windows: The "N3V Games\TANE" subfolder of the application local data folder is currently used. This typically defaults to "C:\Documents and Settings\username\Local Settings\Application Data\N3V Games\TANE".

Note: If Windows cannot access your Docs folder, it will most likely choose the following path: C:\Users\<username here>\AppData\Local\N3V Games\TANE

Mac OS X: The "com.n3vgames.tane" subfolder of the containers folder is currently used. This typically defaults to "/Users/username/Library/Containers/com.n3vgames.tane". The "/Users/username/Library" folder is hidden by default, and must not be confused for the "/Library" folder. If in doubt, hold down the "option" key and use the "Go > Library" menu from Finder.

Use of the OS-standard locations for this data have the following pros and cons:

PRO: A default install does not require admin privileges to run, reducing the footprint of any potential security vulnerability.
PRO: Multi-user machines behave as expected with user accounts and data being per-user instead of per-machine.
PRO: Compatibility with vendor requirements, such as Games for Windows, the Mac App Store, etc.
CON: A default install requires sufficient storage space in the system default data location (typically the boot drive.) Some machines are configured with minimal boot drives with the expectation that large data files will be kept in non-standard locations.
CON: Multi-user machines, where the users explicitly wish to share the Trainz installation and user settings, will need custom configuration.
CON: Multiple installs of the game on a single user account are not possible without customisation. (This has always been true, of course, but the extent of customisation required has increased.)

Custom Layout

It is expected that install-time and post-install options to move the user data files will be introduced in the future. A the current time, power users can add a text file named "override-data-path.txt" next to the TANE.exe or TANE.app file which contains the full (absolute) path to an alternative user data folder. If the folder does not exist or the path is otherwise invalid, the developer release build will use the default location. If the folder does exist but is not writable, the developer release build may fail to start.

It is also feasible that multiple data sources may be introduced in the future (such as a shared location for DLS/payware content and a separate per-user location for locally modified content. This is not expected for the TANE retail release.

Installing Default Content

At the current time, the Developer Preview build does not come with any installed content beyond the most basic files required to start TANE. The zip archive distribution will typically contain a content set which can be installed into TANE in the regular fashion using the "File > Import Content" menu.

Installing Additional Content

The Developer Preview build supports importing of content folders using the "File > Import Content" menu or by dragging content folders from Windows Explorer/Finder onto any in-game "Trainz Content" window (opened by clicking 'Manage Content' from the Launcher window.) The imported content folder(s) may include raw content files or CDP files. Note that when using the "Import Content" menu, you need to import the folder that contains the items (i.e. not a .cdp file directly). Users should keep in mind that many content types are not supported or are incompletely supported - these should import correctly but may not function within the game environment. The Developer Preview build does not support asset validation at the current time; faulty content may simply fail to load correctly, or may crash the build.

Cleaning the Build

In order to completely clean the build back to a fresh install state, the following steps should be taken:

Close all windows relating to the developer build, and wait for the process to fully exit.
Locate the user data path (see above) and delete all contents, leaving only an empty top-level folder.

Upgrading the Build

Each release of the developer build is a fresh install and may not maintain backwards compatibility with the user data of previous developer builds. It is strongly recommended that the user data is cleaned from the machine (see above) before a new build is used. It is strongly recommended that multiple developer builds are NOT installed on the same machine, unless the "override-data-path.txt" mechanism is used and confirmed working for each installation.

Running Multiple Copies

As all installations of the developer build default to the same user data location, it is not possible for a single user to use (simultaneously, or sequentially) multiple separate installations of the developer build without customising the user data location (see above.)

It is also not possible to run multiple simultaneous instances of the same installation at the current time. The first-started process will lock the user data files, and subsequent startup attempts will "hang" waiting for access. If you accidentally start a duplicate copy of TANE.exe (Windows only), you may need to use Task Manager to terminate it.

Using an older version of TANE after having used a newer version of TANE may corrupt your installed data. This may require a database rebuild or complete clean to resolve. (Power users can avoid this problem by using different data paths for each build.)

Major Program Features

GUI

The Windows "Launcher", "Content Manager", "Trainz Game" process division does not exist in the Developer Release build. This functionality is all provided by a single executable process. Separate windows still exist for each task, and multiple game and content windows can be opened simultaneously.

Launch Window

The Launch window is displayed when opening TANE, allowing you to navigate to the desired area of the game. The following commands are available from the Launch window:

'Start Trainz' - Attempts to open a game window using a hard-coded session Asset ID, which may vary from build to build. Other routes, sessions, etc. can be loaded using through the Manage Content 'View Asset In Game" command.
- Known issue: The Settings window will accept your Planet Auran details but will not currently show a verification confirmation until you press 'Start Trainz'.
- Known issue: Certain systems must complete loading before any 3D windows can be opened. If loading is still in progress, attempts to open 3D windows will respond slowly. A user-visible progress indicator should be shown here but is not yet implemented.
'Manage Content…' - Opens a Content window defaulted to displaying all installed content.
'Settings…' - Opens the game settings window.
'Purchase Content…' - Opens a window displaying payware content available for purchase.
- Known Issue: no payware content is available to the Developer Build at the current time.
'(?)' - Opens a help website in the system default browser.

The Trainz build number is displayed at the bottom right of the launch window.

Known issue: The build number is not rendered correctly on any platform.
Known issue: The displayed build number is currently a placeholder and should not be used.

Main Menu

The main menu offers a quick way to access various functionality in the Developer Release build.

The following menu commands are notable:

'File > New Launch Window' - Reopens the launch window.
'File > New Content Window' - Opens a new Content window.
'File > Close Window' - Closes the active window.
'File > View Online Documentation' - Opens the documentation web site.
- Known Issue: The site is a placeholder.
'File > Start Trainz' - Opens a new Game window.
'File > Open Test Track' - Opens Test Track, the new physics testing module.
'File > Import Content' - Allows importing of content from the local disk.
- Known issue: Only entire folders of content can be selected for imported at the current time. The content within the folder may be in source form, or CDP.
'Developer > New Content' - Creates a new item of content, and opens a Content window with the item displayed.
'Developer > Run TrainzUtil Command…' - Prompts for a TrainzUtil command-line, runs it, and displays the result.
- Known issue: TrainzUtil is not present in the current Developer Release build.
'Developer > Rebuild Content' - Rebuilds the Trainz Asset Database by scanning all installed content. Slow and rarely beneficial. Recommended as a last resort only.
'Developer > Show Logs' - Displays a log viewer window. Additional details can be found below.
'Developer > Clear Logs' - Permanently clears any existing log entries.
'Developer > Show Script Debugger' - Shows a script debug window. This is powerful, but exceedingly primitive and as such is only useful to power-users.

Command-Line

"TrainzUtil" does not exist in the Developer Release build. This will be re-introduced at a later date.

"TADDaemon" does not exist in the Developer Release build. This will be re-introduced at a later date.

Crash Reporting

In the event of a crash, a log is typically generated which may give the development team clues as to the cause of the crash. This log is provided in the following locations and should be emailed to N3V games at <crashreport@auran.com>:

WINDOWS - The crash dump file is titled "crashdump.dmp" and is written to the current working directory of the process. By default, this is the same folder as TANE.exe. If no write access is available to this folder, no crash dump is generated. This file should be attached to the report email. It is recommended that you zip the dump file to save time.

Mac OS X - No file is generated, however a crash report window may be displayed containing extensive details of the crash. The full text of the report (several pages of text) should be copied and pasted into the report email.

When sending any such emails, please use the subject "TANE Developer Release" - ideally followed by the build number, if you know it.

Content Management

Trainz Content Window

The content management interface in the Developer Release build is accessed by clicking the "Manage Content" button from the launch window. Once opened, the window has the following elements:

A search filter popup button. If set to "custom", this drops down a custom search filter editor.
- Known issue: at the current time, it is not possible to customise the list of preset filters.
A content listing displaying all content matching the current filter. After the filter has been changed, a progress indication is displayed over the content list until the list has been fully refreshed. You may continue to operate on the content list while the filter is refreshing, but be aware that the list of content may not correctly match the filter. You will also see this progress indication whenever a change to the content set requires a refresh.
- Known issue: when changing from a large list of content to a smaller one, the list scroll position is not reset. If you are below the bottom of the new list, you will need to scroll up to view any content.
- Known issue: scroll bars do not auto-hide when appropriate.
Right clicking on any content in the list displays a popup contextual menu which allows various content management commands (see below.) Holding down appropriate modifiers while selecting content allows for multiple selection.
- Known issue: The Mac OS X user interface guidelines call for any essential contextual menu command to have an alternative in the main menu bar. This does not currently exist.
- Known issue: Menu-key alternatives to these commands do not currently function.
A list header is available allowing the resize and repositioning of the various list columns. Right click to add or remove columns.
- Known issue: list column configuration is not saved.
A status bar is displayed at the bottom of the window.

Content Management Commands

Contextual Menu

The following commands are available from the content list contextual menu:

Copy- Copies a textual description of the selected assets. Each asset is on a new line, with the Asset ID first followed by the asset name.
Select All- Selects all rows of the current list.
Get Info- Opens Asset Info windows for each selected asset, or brings the appropriate window to the front if it already exists.
Copy Details- Copies a textual description of the selected assets. Each asset is on a new line, with the Asset ID first followed by the asset name.
- Known issue: in the main view, this is identical to 'copy'.
Download- Opens a single Download Window for the selected assets. This will begin the process of downloading these assets and any required dependencies. The download may be cancelled by closing the window.
Export to CDP- Exports the selected assets to a single CDP file. This will prompt for a save name and filepath.
- Known issue: CDP files are currently limited to approximately 2GB in size for legacy reasons.
Upload to DLS- Uploads the selected assets to the Download Station.
Open for Editing- Opens the selected asset(s) for editing. This copies the source files of the asset into the "Editing" folder, but does not open any new windows.
Edit Config File- TBD
Edit Config File Text- Opens the selected asset(s) for editing. This copies the source files of the asset into the "Editing" folder. The config.txt file is then opened in the system-default text editor.
- Known issue: While it is possible to configure the system-default text editor on most operating systems, it may not be possible to configure a separate editor for "config.txt" files alone.
Edit in Explorer / Edit in Finder- Opens the selected asset(s) for editing. This copies the source files of the asset into the "Editing" folder, and then opens the folder in the appropriate system shell.
Edit Primary Script- Opens the selected asset(s) for editing. This copies the source files of the asset into the "Editing" folder. The primary script file specified in the asset configuration (if any) is then opened in the system-default editor.
Submit Edits- Submits any edits made to the specified asset(s) from the "Editing" folder. This results in the modifications being saved into the Trainz Asset Database, and the "editing" sub-folder for the specified asset(s) to be trashed.
Delete- If the asset is not built-in or packaged, this will delete any local files belonging to the asset. This includes any editing files which may have been open. If the asset is not on the Download Station, all memory of the asset is removed from the Trainz Asset Database; otherwise a placeholder is kept with the basic details of the asset. If an asset is built-in or packaged, it is skipped.
Revert Unsubmitted Edits- Discards any edits made to the specified asset(s) from the "Editing" folder. Edits which have previously been submitted are not removed. The "editing" sub-folder for the specified asset(s) is trashed.
Revert to Original- If the asset(s) are modified, and "original" unmodified versions are locally available, this causes the modifications to be deleted, leaving the unmodified versions in place. This also reverts any unsubmitted edits.
Revert if Unchanged- If the asset(s) are open for edit, but it is determined that the source files have not been modified, the null edits are discarded. The "editing" sub-folder for the specified asset(s) is trashed where appropriate.
View Errors and Warnings- Opens a new results window and runs a validation of the specified asset(s). Any validation results, including diagnostics, warnings, and errors, are displayed in the results window. If an asset's validation status differs from that stored in the Trainz Asset Database, the database is also updated appropriately. Dependencies are not automatically validated by this process. Dependants are not automatically validated by this process, however if an asset's validation status differs, the dependants may be flagged as requiring validation.
View Dependencies- Opens a new content window with a custom filter set to display the dependencies of the specified asset(s). All dependencies are displayed, including any Asset IDs unknown to the local install. Where a given dependency is locally obsolete, the local head revision is displayed instead.
View Dependants- Opens a new content window with a custom filter set to display the local dependants of the specified asset(s). All local dependants are displayed, including those which are configured to depend on an older version of the specified asset.
View Asset Versions- Opens a new content window with a custom filter set to display all versions of the specified asset(s), including both assets which are made obsolete by the specified asset(s), and content which would make the specified asset(s) obsolete. This operation is performed locally and complete results are given to the extent that the local installation can determine. Assets which are related via an obsolete-table which is not locally installed may not be detected.
View Assets In New Window- Opens a new content window with a custom filter set to display the specified asset(s).
View Asset In Game- For compatible asset types, this will open a viewer window which previews the specified asset. Only available when exactly one asset is selected. Currently compatible with Mesh Objects, Routes, and Sessions.
Edit Asset in Surveyor- For compatible asset types, this will open a Surveyor window which allows editing of the specified asset. Only available when exactly one asset is selected. Currently compatible with Routes and Sessions.
Open Asset in Driver- For compatible asset types, this will open a Driver window which allows driving of the specified asset. Only available when exactly one asset is selected. Currently compatible with Routes and Sessions.

Content Tasks

Download Task

Various actions in the Developer Release build, especially the above content management commands, will open a Task Window. This window will show the current activity and a progress bar. Further details can be revealed by clicking on the disclosure triangle to view an activity log. If the task completes successfully and the log has not been opened, the window will close automatically. Otherwise, the window will stay open and you may close the window after optionally reviewing the log. Closing the task window while the task is in progress will cancel the remainder of the task. Cancellation will not always occur immediately (some actions cannot be interrupted) and any changes already completed will not be rolled back.

Rows in the log can be selected (use modifier keys to allow multiple selection) and a content contextual menu can be displayed by right clicking. In cases where the log row relates to a specific asset, the command will operate on that specific asset. In other cases, the text of the log will be scanned for a KUID and the command will act upon the asset with that ID.

Log Window

A global log viewer may be accessed via the "Developer > Show Logs" menu. This displays game logs equivalent to TS12's "Content Manager Log Panel". As per TS12, this logs all content operations that have occurred recently, allowing you to review the recent actions that you have taken and the success or failure of each action. The logs also include messages from the game runtime, including script messages, script exception logs, and resource load failures.

Known Issue: There is currently no mechanism for filtering or searching the logs.
Known Issue: There is currently no way to expand or contract parent entries to show/hide the children.
Known Issue: The icon on parent entries does not necessarily indicate the status of child entries.

Test Track

Test Track is a testing environment for train physics. This is intended to both allow content creators to tune their vehicle engine parameters, and for N3V Games to tune and test the game physics systems under different scenarios.

TBD.

Script Debugger