HolgerSandmann
Resource contributor
- Messages
- 392
- Country
-
Hi all,
not surprisingly, the issue of manipulating the global terrain.cfg file keeps coming up. Below are my thoughts and ideas about this matter, meant to continue discussion and exchange of ideas and approaches for dealing with the cfg file. Primarily, I'd like to focus on design features for auto-installers that can handle any number of product/user modifications "thrown at" the terrain.cfg in any possible order or combination. A truly modest goal, I know
I realize that what should be expected of a payware product can't necessarily be expected of freeware projects; coding auto-installers that include config tweaking is no easy task. Thus, perhaps we can also brainstorm about a freeware generic terrain.cfg tool that would take new custom entries supplied by the addon (in a defined format) and deal with them in the same manner as custom autoinstallers for commercial projects.
The Issue:
FSX uses a global terrain.cfg file (located in the FSX root folder) that sets key parameters for all polygon and vector textures and their associated autogen annotations. Unlike FS9, the only way us FSX developers can use our own textures for, say, streams, or alter the width of our roads, is by changing the corresponding parameters in this terrain.cfg file. Given that these changes have global effect it's obvious that changing default entries should be discouraged. The alternative is to provide custom entries and add these to the terrain.cfg file. However, since all entries need to respect the required packed-sequential numbering system (no duplicate texture numbers or gaps in the number's sequence) this approach raises questions as to how the modifications of different projects or developers can all be combined into a single working terrain.cfg.
Adding entries to the terrain.cfg file:
The process of adding custom entries to the terrain.cfg is pretty straightforward and explained in the "Terrain Configuration File.html" document of the FSX Terrain Software Development Kit (SDK), included with FSX Deluxe. Obviously, the new entries themselves need to have correct parameter specifications, including a unique GUID associated with each entry. Other than that only the [Texture.xxx] line of each new entry needs to respect the packed sequential numbering format (no duplicates or gaps) and the "DefaultTextureCount" value in the [General] section need to reflect the new total number of entries. Slightly different rules apply for new vector autogen entries (sections [Autogen.x.x.x] and counter "AutogenCount"); see the information about the [General} section in "Terrain Configuration File.html".
Known limitations:
It is possible that there is a limit to the overall number of entries allowed in the terrain.cfg. However, the SDK doesn't mention this nor am I aware of anyone encountering such a limitation (yet). Similarly, there may be issues in regards to FSX performance or display with increasing numbers of terrain.cfg entries. Again, I'm not aware of such issues. However, we should be aware that these or other limits may exist and should try to test for them, wherever possible. Those knowable unknowns, you know?
Proposed specs for a "neutral" auto-installer for adding/removing custom terrain.cfg entries:
For me, a key requirement of any terrain.cfg auto-installer is that it respects the integrity of the existing terrain.cfg. That means that the developer should make no assumptions as to what the user's terrain.cfg should contain. Instead, it merely adds the new entries to any existing state of the config file (provided it isn't internally corrupted) and removes them safely upon uninstallation. In other words, the new entries form a parallel set of cfg entries inside the existing terrain.cfg.
A second key requirement is that we cannot assume that the "average" users are willing or capable of making manual adjustments to their terrain.cfg file. As Jeff ("Quantumleap") posted elsewhere: "They will not know one exists, they will not know where it is, they will not know what it does and they will not understand what will happen if you change it. Also, no matter the amount of documentation provided to the end user, the majority will still not understand, and again, they should not need to."
What follows is the proposed list of installer features that is based on those two key requirements:
* a safety backup of existing terrain.cfg, either with a name that indicates which product made the backup or to a cache folder inside the project's scenery folders
* initial check for correct packed-sequential numbering of the existing entries, correcting any mistakes found. This is a required feature because adding a new block of entries to an already corrupt terrain.cfg won't work anyway
* correctly adding the block of new entries to the existing terrain.cfg. The physical location of the block inside the terrain.cfg doesn't appear to be of concern as long as the overall packed-sequential format is met
* a repair function that doesn't require a re-installation of the product should the user .cfg file become corrupted. This can either be a repair option in the auto-installer (as implemented by our Vancouver+ FSX), or, if applicable, a background check tied to the configurator utility (e.g., as implemented by Ultimate Terrain FSX)
* clearly advising the users about changes made to the terrain.cfg, how to detect situations that indicate that something is wrong with the terrain.cfg, and what to do in those cases (repair, reinstall, forum posts, etc.)
* upon uninstalling, correctly removing the custom block from the current terrain.cfg file, even if other add-ons with custom entries were installed afterwards (i.e., the ability to renumber other blocks of custom entries to fill gaps)
* removal of the safety backup to prevent clutter (and confusion) in the FSX folders
======================================
The "special case" of the Richard Ludowise/Luis Féliz-Tirado modifications (RL/LFT mods): fsx_modified_terrain_cfg.zip, at AVSIM http://library.avsim.net/esearch.php?CatID=fsxscen&DLID=93289
Richard and Luis started working on changes to the default terrain.cfg while FSX was still in Beta. Their initial motivation was to check for mistakes and inconsistencies in the Beta versions so that ACES could correct these prior to the release of FSX. Unfortunately, from their fairly long list of proposed changes ACES integrated only a few into the retail version of FSX (and no further changes in SP1), which prompted the two to upload their modified version to AVSIM and elsewhere.
The complete list of changes is listed in the read-me file of fsx_modified_terrain_cfg.zip.
It was the hope of Richard and Luis to have the community (both users and developers) adopt their modifications so that everyone benefited from the fixes and that developers had already a number of changes and additions to work with, minimizing the need for additional changes to the cfg file. However, it appears that these wishes have not been fulfilled. One the one hand, while many thousand FSX users have downloaded the RL/LFT mods there are many more that haven't (and there's some confusion as to whether the mods are still useful post-SP1; the answer being yes). Also, developers, including myself, have found the need to add new entries to the terrain.cfg in order to regain or exceed the options we had with FS9.
One reason why I decided not to include the RL/LFT mods into our own auto-installer (i.e., FSAddon products) is that the mods don't match with the key idea of being "neutral". For example, one of the main changes of the RL/LFT mods is that it suppresses the new FSX feature to automatically change water textures to rock textures on slopes steeper than a specific threshold. What if a user prefers the original FSX approach? Yes, the user can make these changes manually but that is awkward and error prone (and may be reversed upon re-installing or by error-checking codes). The alternative is to make the treatment of water textures an option, giving the user the choice upon installation. However, this requires additional installer code and user education.
Instead, I would prefer that the RL/LFT mods themselves are re-issued in the form of a "neutral" auto-installer as outlined above. Like I said, I don't expect this of a free contribution but perhaps one of our installer "gurus" can jump in or we can raise the funds to hire someone to write a generic tool for the freeware community. This tool would be able to install/unisntall external sets of custom entries supplied by an addon (in a defined format) and at the same time could include the RL/LFT mods as a basic install option.
=========================================
Any feedback and ideas are welcome. I'd appreciate if we could keep this discussion technical, free of arm waiving and finger pointing
I don't think it's reasonable to expect that the outcome of this discussion will be a single standard endorsed by all users and developers; in fact, I do not believe in standards for FS design, full stop, since many of the most innovative and popular add-ons don't adhere to SKDs or standards. Rather, I'd like this to be an educational thread, with people sharing ideas and commenting on ideas of others.
Kind regards,
Holger Sandmann
not surprisingly, the issue of manipulating the global terrain.cfg file keeps coming up. Below are my thoughts and ideas about this matter, meant to continue discussion and exchange of ideas and approaches for dealing with the cfg file. Primarily, I'd like to focus on design features for auto-installers that can handle any number of product/user modifications "thrown at" the terrain.cfg in any possible order or combination. A truly modest goal, I know
I realize that what should be expected of a payware product can't necessarily be expected of freeware projects; coding auto-installers that include config tweaking is no easy task. Thus, perhaps we can also brainstorm about a freeware generic terrain.cfg tool that would take new custom entries supplied by the addon (in a defined format) and deal with them in the same manner as custom autoinstallers for commercial projects.
The Issue:
FSX uses a global terrain.cfg file (located in the FSX root folder) that sets key parameters for all polygon and vector textures and their associated autogen annotations. Unlike FS9, the only way us FSX developers can use our own textures for, say, streams, or alter the width of our roads, is by changing the corresponding parameters in this terrain.cfg file. Given that these changes have global effect it's obvious that changing default entries should be discouraged. The alternative is to provide custom entries and add these to the terrain.cfg file. However, since all entries need to respect the required packed-sequential numbering system (no duplicate texture numbers or gaps in the number's sequence) this approach raises questions as to how the modifications of different projects or developers can all be combined into a single working terrain.cfg.
Adding entries to the terrain.cfg file:
The process of adding custom entries to the terrain.cfg is pretty straightforward and explained in the "Terrain Configuration File.html" document of the FSX Terrain Software Development Kit (SDK), included with FSX Deluxe. Obviously, the new entries themselves need to have correct parameter specifications, including a unique GUID associated with each entry. Other than that only the [Texture.xxx] line of each new entry needs to respect the packed sequential numbering format (no duplicates or gaps) and the "DefaultTextureCount" value in the [General] section need to reflect the new total number of entries. Slightly different rules apply for new vector autogen entries (sections [Autogen.x.x.x] and counter "AutogenCount"); see the information about the [General} section in "Terrain Configuration File.html".
Known limitations:
It is possible that there is a limit to the overall number of entries allowed in the terrain.cfg. However, the SDK doesn't mention this nor am I aware of anyone encountering such a limitation (yet). Similarly, there may be issues in regards to FSX performance or display with increasing numbers of terrain.cfg entries. Again, I'm not aware of such issues. However, we should be aware that these or other limits may exist and should try to test for them, wherever possible. Those knowable unknowns, you know?
Proposed specs for a "neutral" auto-installer for adding/removing custom terrain.cfg entries:
For me, a key requirement of any terrain.cfg auto-installer is that it respects the integrity of the existing terrain.cfg. That means that the developer should make no assumptions as to what the user's terrain.cfg should contain. Instead, it merely adds the new entries to any existing state of the config file (provided it isn't internally corrupted) and removes them safely upon uninstallation. In other words, the new entries form a parallel set of cfg entries inside the existing terrain.cfg.
A second key requirement is that we cannot assume that the "average" users are willing or capable of making manual adjustments to their terrain.cfg file. As Jeff ("Quantumleap") posted elsewhere: "They will not know one exists, they will not know where it is, they will not know what it does and they will not understand what will happen if you change it. Also, no matter the amount of documentation provided to the end user, the majority will still not understand, and again, they should not need to."
What follows is the proposed list of installer features that is based on those two key requirements:
* a safety backup of existing terrain.cfg, either with a name that indicates which product made the backup or to a cache folder inside the project's scenery folders
* initial check for correct packed-sequential numbering of the existing entries, correcting any mistakes found. This is a required feature because adding a new block of entries to an already corrupt terrain.cfg won't work anyway
* correctly adding the block of new entries to the existing terrain.cfg. The physical location of the block inside the terrain.cfg doesn't appear to be of concern as long as the overall packed-sequential format is met
* a repair function that doesn't require a re-installation of the product should the user .cfg file become corrupted. This can either be a repair option in the auto-installer (as implemented by our Vancouver+ FSX), or, if applicable, a background check tied to the configurator utility (e.g., as implemented by Ultimate Terrain FSX)
* clearly advising the users about changes made to the terrain.cfg, how to detect situations that indicate that something is wrong with the terrain.cfg, and what to do in those cases (repair, reinstall, forum posts, etc.)
* upon uninstalling, correctly removing the custom block from the current terrain.cfg file, even if other add-ons with custom entries were installed afterwards (i.e., the ability to renumber other blocks of custom entries to fill gaps)
* removal of the safety backup to prevent clutter (and confusion) in the FSX folders
======================================
The "special case" of the Richard Ludowise/Luis Féliz-Tirado modifications (RL/LFT mods): fsx_modified_terrain_cfg.zip, at AVSIM http://library.avsim.net/esearch.php?CatID=fsxscen&DLID=93289
Richard and Luis started working on changes to the default terrain.cfg while FSX was still in Beta. Their initial motivation was to check for mistakes and inconsistencies in the Beta versions so that ACES could correct these prior to the release of FSX. Unfortunately, from their fairly long list of proposed changes ACES integrated only a few into the retail version of FSX (and no further changes in SP1), which prompted the two to upload their modified version to AVSIM and elsewhere.
The complete list of changes is listed in the read-me file of fsx_modified_terrain_cfg.zip.
It was the hope of Richard and Luis to have the community (both users and developers) adopt their modifications so that everyone benefited from the fixes and that developers had already a number of changes and additions to work with, minimizing the need for additional changes to the cfg file. However, it appears that these wishes have not been fulfilled. One the one hand, while many thousand FSX users have downloaded the RL/LFT mods there are many more that haven't (and there's some confusion as to whether the mods are still useful post-SP1; the answer being yes). Also, developers, including myself, have found the need to add new entries to the terrain.cfg in order to regain or exceed the options we had with FS9.
One reason why I decided not to include the RL/LFT mods into our own auto-installer (i.e., FSAddon products) is that the mods don't match with the key idea of being "neutral". For example, one of the main changes of the RL/LFT mods is that it suppresses the new FSX feature to automatically change water textures to rock textures on slopes steeper than a specific threshold. What if a user prefers the original FSX approach? Yes, the user can make these changes manually but that is awkward and error prone (and may be reversed upon re-installing or by error-checking codes). The alternative is to make the treatment of water textures an option, giving the user the choice upon installation. However, this requires additional installer code and user education.
Instead, I would prefer that the RL/LFT mods themselves are re-issued in the form of a "neutral" auto-installer as outlined above. Like I said, I don't expect this of a free contribution but perhaps one of our installer "gurus" can jump in or we can raise the funds to hire someone to write a generic tool for the freeware community. This tool would be able to install/unisntall external sets of custom entries supplied by an addon (in a defined format) and at the same time could include the RL/LFT mods as a basic install option.
=========================================
Any feedback and ideas are welcome. I'd appreciate if we could keep this discussion technical, free of arm waiving and finger pointing
I don't think it's reasonable to expect that the outcome of this discussion will be a single standard endorsed by all users and developers; in fact, I do not believe in standards for FS design, full stop, since many of the most innovative and popular add-ons don't adhere to SKDs or standards. Rather, I'd like this to be an educational thread, with people sharing ideas and commenting on ideas of others. Kind regards,
Holger Sandmann
