Revision as of 17:09, 12 May 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".
• 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. The imported content folder(s) may include raw content files or CDP files. Note that 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.

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

Launch Window

The TANE Launcher currently uses a hard-coded session Asset ID for Start Trainz (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: Clicking Start prior to installing content will result in no game window opening.
• Known issue: The Settings window will accept your Planet Auran details but will not currently show a verification confirmation until you press 'Start Trainz'.

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.
  • Known issue: progress indication is not visible on Windows builds.
• 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-
  • TBD.
• 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.
  • TBD- effect on 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.

Content Tasks

TBD.

Download Task

Discussion and Sharing

The Developer Release build is only available to TPC and TEG members, and active discussion between group members is encouraged on the TPC and TEG forums. Since the build is not available to other members of the Trainz community and most aspects of the build will have changed prior to the retail release of TANE, broad discussion of the build on the public forums is not encouraged. N3V asserts ownership of the Developer Release build and does not permit redistribution of the build.