Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
--VertAlert 1.0.0-- Find, display, and optionally round floating point plane coordinates in Source engine .vmf files. Standalone executables have no dependencies, Python script requires either Python 2.7 or 3.3. Supports Windows, Linux, and OS X. Latest release hosted at http://www.gyroshot.com/vertalert.htm Comments and questions can be sent by email to firstname.lastname@example.org or via Twitter to @ItEndsWithTens. --Usage-- The standalone executables and Python script share the same parameters: vertalert [-h] [-f] [-fn FIXNAME] [-t THRESH] [-sl SNAPLO] [-sh SNAPHI] input -h, --help Shows usage information. -f, --fix Writes out a new .vmf with rounded coordinates. Will overwrite existing output file without prompting. If you use this flag, please be careful to rename the resulting file before building cubemaps; not only do cubemaps break if the filename changes after the fact, but you may not be able to build them at all if the filename is too long. -fn, --fixname The filename for use with --fix. The default is to append _VERTALERT to the end of the input filename, before the extension. -t, --thresh Threshold between snaplo and snaphi. A setting of 0 will display all float coordinates, effectively disabling rounding. Default snaplo * 0.2. -sl, --snaplo Coordinates with deviations less than thresh will be rounded to the nearest multiple of this value; said multiple also serves as the basis for calculating a coordinate's deviation. Default 1. -sh, --snaphi Coordinates with deviations equal to or greater than thresh will be rounded to the nearest multiple of this value. Default None. --Tech notes-- VertAlert currently uses a very primitive means of examining the .vmf file, and as a side effect it only looks through VisGroups that you've enabled. The critic in me notes that this is born of my laziness, but I try to think of it as helping you narrow down the source of your problems, and lets you focus on fixing one area at a time. If the --fix flag is specified, and you've used a large enough threshold, VertAlert will use the so-called "Banker's Rounding", where values of exactly 0.5 will be rounded to the even number. If you'd rather use something else, you'll need to modify the Python script. When not using snaphi, brushes whose max deviation is less than thresh will have their float coordinates rounded, while brushes with even one coordinate equal to or greater than thresh will be left completely untouched. If you are using snaphi, on the other hand, coordinates are treated individually, and a given brush might have some rounded to snaplo and some to snaphi, depending on their distance from snaplo. The test map test_snaphi was created by using the spike tool to create an eight-sided spike measuring 64x64x64. Scaling the result down to 32x32x32 produces a spike whose corner vertices (northeast, southwest, etc.) land at exactly 0.5 units between one grid line and the next. Duplicate the spike, then move the whole group slightly. Move the group back where it was, save, close, and reopen the file, and you should get an invalid solids error. Run VertAlert on the file, though, and those spikes should be corrected, allowing the vmf to open in Hammer without a problem. --Hammer setup-- Through use of the --fix and --fixname options, the standalone version of this tool can be easily integrated with your Hammer compile options. Bring up the Run Map dialog in Hammer with F9, then click Edit next to the drop-down list of Configurations. Highlight Default, for the sake of this example, and click Copy. Provide a new name, I'll use "VertAlert (Default)" to demonstrate. Close the Run Map Configurations dialog box, then choose the new configuration from the list. Click New to be given a blank command, then hit Move Up until it's all the way at the top. Now, with it selected, use the right hand pane to set Command to point to the VertAlert executable, wherever you placed it. Next, set Parameters to $path\$file.$ext --fix so VertAlert will produce a new .vmf with all the problematic coordinates rounded. Check the box labeled "Ensure file post-exists:", and set its value to $path\$file_VERTALERT.vmf After that, it's simply a matter of going through each command (bsp, light, rad, Copy File, game) and replacing each instance of $path\$file with the alternative $path\$file_VERTALERT (though be careful with Copy File, you don't want to accidentally delete the .bsp file extension). Once finished, the program should be transparent. You work on the original VMF, the toolchain runs VertAlert to produce an altered file, compiles that instead, and launches the modified version for you. The original map file, and your original compile settings, remain untouched, and you can easily switch back to compiling things as usual. --Background-- My original reason for developing VertAlert is moot, as it turns out. The initial motivation was the tendency of Hammer to occasionally throw some brush vertices off the grid ever so slightly upon opening a map, suggesting some sort of problem. That phenomenon is the result of the fact that the .vmf file format, in contrast to the older .rmf format, does not store actual vertices for the brushes it contains. Instead, it defines only three points per surface, the minimum necessary to define a plane in 3D space. Each brush is computed upon load, by intersecting the various planes that make up said object. Sometimes, however, the result can be a bit off. Computed vertices can end up slightly off of the grid, with floating point instead of integer positions. At my level of understanding, or lack thereof, I have little choice but to attribute this phenomenon to the mythical "rounding errors" that I love to dread plague the world of floating point operations. It so happens, however, that the first step in the map compilation process, VBSP, already accounts for this. Some admittedly informal testing shows that the program snaps everything to the nearest whole number if it's less than 0.2 units away, which most (perhaps all) Hammer rounding errors are. This behavior can be readily demonstrated by compiling test_threshold.vmf, bundled with the VertAlert source distribution, as-is. It includes an outer wall brush that creates a 0.15 unit gap, exposing the inside of the map to the void, but VBSP handles it without issue. Since most of the larger errors are either the result of intentional brush rotations or accidental scales, and should be visually examined one by one, the --fix option is of limited utility unless combined with --snaphi. --Changes-- 1.0.0 - March 28th, 2013 Add snaplo and snaphi parameters 0.2.1 - January 1st, 2013 Update fix_plane's use of string replace method 0.2.0 - November 27th, 2012 Added --thresh Added shebang line Fixed writing out OS-specific line endings 0.1.0 - November 24th, 2012 Initial release