-- HW2 Map Converter v0.8.5 -- Created: 09/20/05 by Mikail -- Last updated: 04/25/06 -- Homepage: -- http://isometricland.com/homeworld/homeworld.php -- Discussion: -- http://forums.relicnews.com/showthread.php?t=73533 ---------------------------------------------------------------- INTRODUCTION This is a map converter for converting Homeworld levels to work with Homeworld 2's HW Classic Mod Rebalance. INSTALLATION 1) Extract the contents of this archive into a folder on your harddrive. 2) Copy the "data" folder to your "Homeworld2" folder. 3) Add the "-overrideBigFile" switch to the target line of your Homeworld 2 shortcut. Note: all players must possess the same files in their "data" folder in order to play against each other over multiplayer using maps converted by this converter. Note: Windows Scripting Host v5.6 must also be installed in order for this program to work. Note: HW Classic Mod Reblance must also be installed in order to properly use these maps. INSTRUCTIONS There are two ways in which you can use this program: 1) You can drag & drop a single level file onto the JS file, in which case a new file will be created with the same name name and in the same directory as the input file, but with an additional "HW1_" prefix added to the beginning of the filename. 2) You can run the program from the command-line. The command- line syntax is as follows: cscript [script] [Input File] [[Output File]] [[-debug]] [[-incFunctions]] [[-incVariables]] Where: [script] is the full path to "HW2_MapConverter.js". [Input File] is the full path to the HW1 level you wish to convert. [Output File] is the full path to the destination file. If [Output File] is omitted, then a new file will be generated with the same name and in the same directory as the input file, but with an additional "HW1_" prefix. [-debug] generates and additional file in the same directory as "HW2_MapConverter.js" that is helpful in debugging. [-incFunctions] causes the map-processing functions to be included using the "dofilepath" function instead of being added to the end of the outputted level file (the default). [-incVariables] causes the map-tweaking variables to be included using the "dofilepath" function instead of being added to the end of the outputted level file (the default). ADVANCED OPTIONS If you look in the outputted level file, you'll find a section called "Map-Tweaking Variables". The variables in this section make it possible to change basic characteristics of the map without having to rerun it through the converter. RUMulti (default: 4) Multiplier affecting the density of resources: larger values mean fewer resources with more RUs (makes HW2 less laggy). By changing this value you can decrease the number of asteroids and increase their respective RU values, thereby making large maps less leggy in HW2. The default value of four (4) means that maps will have four times fewer resources, but the resources will be worth four times as much as usual. (Note: this is not recommended for maps with small resource pockets due to round-off errors.) 16 is a good value if the map is still laggy at 4. PebMulti (default: 1) Only every Nth missing asteroid will be converted into a pebble. (Note: use this in conjunction with RUMulti.) RUScale (default: 2 * 700 / 575) Is equal to HW2 frigate cost / HW1 frigate cost. (Note: I then scaled this by an additional factor to compensate for research/upgrade costs.) MapScale (default: 161 / 325) Is equal to HW2 frigate speed / HW1 frigate speed. By default, maps are scaled by a factor related to the speeds of frigates in HW1 and HW2. To change this, simply modify the value of the "MapScale" variable. The default value is 161 / 325, or about 0.5. Alternatively, one could use the meter/feet ratio (since HW2's units are in meters, and HW1's units are in feet): 1 meter = 3.280839895 feet UniverseScale (default: 1.2) Increases the world bounds (the Sensors Manager pie- plate) by an additional 20%, since they seem to be a bit smaller, in HW2, in general. MinSensorsZoomOverride (default: 12000) Overrides the map's minimum sensors zoom distance. To use the map's original value, set this to equal -1. MaxSensorsZoomOverride (default: -1) Overrides the map's maximum sensors zoom distance. To use the map's original value, set this to equal -1. AdvancedGameRule (default: 0) A sophisticated gamerule is necessary to spawn player- owned ships. The default value of zero (false) means that only the starting positions will be used. (Note: don't turn this setting on if you don't have a gamerule to take advantage of it) ---------------------------------------------------------------- CREDITS • Luke 'B1FF' Moloney for the RU conversion formulas and modded asteroids in his Homeworld Classic mod. ---------------------------------------------------------------- CHANGE LOG v0.85 • The converter now also looks for the "UseAsMothership" and "NULL_FORMATION" flags, in addition to the "Mothership" and "Carrier" types, when determining which ship is the flagship. Still not perfect, but should handle nearly all cases. • Non-player mothership misspheres are now handled as if they were resource misspheres. They no longer count toward a "bogus" player total. • The converter now automatically removes ampersands and leading spaces from level names. • Increased the default value of RUMulti from 4 to 8. • PebMulti is now set to RUMulti / 4 by default. v0.84 • "IncFunctions.lua" was referencing "hgn_gunplatform", which is not a valid .ship file. • "IncFunctions.lua" was referencing "hgn_flakfrigate", which is not a valid .ship file. • Fixed issue with maps sometimes appearing completely white. ("IncFunctions.lua" was missing the "setGlareIntensity" and "setLevelShadowColour" functions.) v0.83 • Slight change to the "player" table in "IncFunctions.lua". v0.82 • The effect of using the "-incFunctions" and "-incVariables" switches has been reversed. Now, specifying the switches causes data to be read from an external file using the "dofilepath" function. • The orientation of the HW1 map-default squadrons has been corrected. v0.81 • Fixed the bug in "MapInclude.lua" that caused research ships to be added to a sobgroup, even though they hadn't been spawned. • Fixed the bug where a starting point was being added for every mothership, regardless of the number of players. • Fixed the bug where start points weren't being added in the correct order. • Fixed the bug where the "number" parameter of ships in the misspheres was being ignored. • "MapInclude.lua" has been renamed to "IncFunctions.lua" and was moved to the "Data" directory. • "MapVariables.lua" has been renamed to "IncVariables.lua" and was moved to the "Data" directory. • The "-include" command-line switch has been renamed to "- incFunctions". • Added the "-incVariables" command-line switch. • Fixed the bug in "IncFunctions.lua" where "Vgr_HeavyMissileFrigate" was misnamed as "Vgr_HeavyMissileCorvette". • Removed the "UsePebbles" and "UseStartPoints" tweaking variables. • Added the "UniverseScale" and "AdvancedGamerule" tweaking variables. • The ouput now has proper carriage-returns and new-lines. (Fix didn't work in last version.) • Strings are now converted to lower-case wherever possible to cut back on capitalization issues. • Unknown level background and music name-checking is now done in the Lua scripts instead of being set to a default value by the converter. v0.8 • Some memory and speed optimizations. • Refactored the program code so that it uses fewer function calls. Now, the program shouldn't run out of stack space when converting large file. (Didn't happen very often.) • The program no longer writes 0-byte files when it fails to convert a map. • Tidied up the output: put the different portions of the code into clearly labeled sections (e.g., converted level data first, then map-tweaking variables, then map-processing functions, etc.). • The ouput now has proper carriage-returns and new-lines. [wasn't fixed] • Added the "-debug" and "-include" switches. • Unknown level background and music is now set to a default value. v0.71 • Fixed the bug where the "MusicTable" table in "MapInclude.lua" started with index number 1 instead of 0. • Fixed the bug where a variable was misnamed in the "AddResources" function in "MapInclude.lua" (and could, as a result, produce divide by zero errors). • Fixed the bug in "MapInclude.lua" where the number of missing asteroids converted into pebbles wasn't being calculated correctly when the "PebMulti" variable was set to greater than 1. • Fixed the bug where missing backgrounds weren't being handled properly. v0.7 • Background and music conversion has been externalized to the outputted .level file. Original values are still stored in the .level files, but are then compared against the "BackgroundTable" and "MusicTable" tables, respectively. • "MapFunctions.lua" has been split into two files: "MapVariables.lua" and "MapInclude.lua". "MapInclude.lua" is no longer added at the end of each .level file during conversion. Rather, it resides in the "data\leveldata\" folder, and is read by the .level file when the level is loaded. • The "OverrideMinSensorsZoom" variable in "MapVariables.lua" has been renamed to "MinSensorsZoomOverride". • Added the "MaxSensorsZoomOverrride" variable to "MapVariables.lua". v0.63 • Fixed the bug where the program wasn't writing to the [Output File] switch when it was supplied as a command-line argument. • Added a multiplier to "MapFunctions.lua" that sets the number of missing asteroids that get replaced with pebbles. • The program no longer fails when the last line in "Description.txt" is not a blank line. v0.62 • Fixed the bug where the world bounds were misaligned. • Fixed the bug where the ships and starting points were still misaligned. • Multiplied all x-coordinates by -1 to match HW2's left-handed orientation. • 90 degrees are now subtracted from all z-axis rotations, instead of added. • Pebbles are substituted in place of missing asteroids when "RUMulti" is set to equal greater than 1. • Fixed the length parameter for the "Cylinder" layout. • Reduced round-off errors in RU calculations. • The default minimum Sensors Manager zoom distance can now be overridden. • Large asteroids are now used less often, reducing the likelihood of collectors getting "stuck". • Various display settings of the asteroids have been modified. v0.61 • The program no longer fails when the last line in a level file is not a blank line. • "RUMulti" has been reduced to 4. • RU values have been increased by a factor of 2 to cover the cost of upgrades and subsystems (non-existant in HW1). • The RU values for each asteroid type have been reduced to 100 in their respective .resource files. v0.6 • Fixed the bug where Derelicts weren't being added and would cause the program to crash. • Fixed the bug where list entries weren't parsed properly if they were separated by commas, only. • Distributions are now parsed properly if regen amounts are also specified. • Fixed a bug in "MapFunctions.lua" that would cause the game to crash. • Resource amounts are now calculated properly. • The length and radius parameters for the "Cylinder" and "Sphere" layouts are now calculated in the correct order. • The value of the "RUMulti" parameter has been set to 10 by default. • Squadrons are now placed correctly. • It is now possible to specify whether start points should be used (e.g. the default starting fleet), or whatever the author originally intended. • The program now works properly if "Description.txt" does not exist for the level. • All map data has now been externalized to Lua code. • Maps are now scaled by the amount specified in the "MapScale" variable. • Drag & drop support has been added. • Nebulas are now converted to asteroids. v0.51 • Squadrons are now rotated by an additional 90 degrees. • Fixed a bug regarding RU percentages. • Switched to using the modded asteroids from the Homeworld Classic mod. • Fixed the bug where DustClouds weren't being added. • More data has been externalized. • The prefix "HW1_" has been added to all map file names. Maps now appear with the prefix "HW1 - " in the level selection menu. v0.5 • Initial release. ---------------------------------------------------------------- KNOWN ISSUES • Add support for harvestable dust clouds and nebula chunks. [Scripting mostly done. Need the HODs.] • Add support for Cata map objects (i.e., crystals, slipgates). • Squadrons placed at the same coordinates should be offset a little bit (or put into a sobgroup and then put into parade formation using a gamerule). [Haven't actually encountered this problem, yet.] • The converter doesn't handle whitespace properly in comma- separated lists. [Bug. Doesn't occur very often. Solution: remove the whitespace in the source level file.] • I've been coming across a lot of weird names for map backgrounds and level music. • In HW1, the race of the player is specified in the level file. This causes problems in HW2 when the map contains player-owned ships, as there's no guarantee that the player will be of the same race -- and, thus, be unable to utilize ships effectively (or even build or research, in some cases). • It would maybe be good to configure the converter to dynamically adjust the "RUMulti" variable for maps with large numbers of objects. [This could be done at runtime. I would rather that the authors do this, themselves, though.] • Source maps that spell ship names using incorrect capitalization cause errors in HW2. [Could easily solve this by converting all strings to lowercase.] • Can level lighting be converted? • Default starting RUs amounts are not converted. • Maybe *only* megaliths should be used in place of ships in the "Derelicts" race, as non-aligned CPU players are still able to defend themselves in HW2 (unlike in HW1). • The "Traders" race shouldn't have any megaliths in it. • The "P3" race should only have working ships in it. • Need to remove ampersands in level names/descriptions. [Removing them automatically seems to pose only occasional problems.] • See: http://hw2.tproc.org/wiki/TutorialHW1Resources.