MapSearch ======================================================================= Version: v1.3 Author: Inky (shubbng@gmail.com) Website: http://earthday.free.fr/Inkys-Hexen-II-Mapping-Corner/ Date: May 2020 ======================================================================= ================= WHAT IS THAT FOR? ================= This tool is intended to make it easier to search for entities inside .map files (Quake, Hexen II, etc.) on the basis of their classname and/or properties. It's an answer to a basic need I've had constantly as an Hexen II mapper: "How is that property used?", "Are there some examples where those guys at Raven used that spawnflags value?", "How does that damn func_monsterspawner work for spiders?", etc. But sometimes it's very time consuming to find accurate examples spread out among thousands of entities in dozens of maps made by Raven, ID or others. MapSearch is there for that. ------------------------------------------------------------------------------------------- If you use & like the tool, please credit me in your projects and put a link to my website. ------------------------------------------------------------------------------------------- Please also tell me if you find any funny corner case, bug or creative usage (or if you just want to thank me for the nice tool :D) I will get any feedback with most pleasure: I love the mythic Doom/Quake/Heretic/Hexen series and it's always a pleasure to exchange about them. ;) -Inky ============= PRE-REQUISITE ============= The exe works on Windows 7 & 10, but is provided as-is. No guarantee about any other platform. So just try it! You must have map files to search in. The tool is not able to seach inside compiled BSP files directly. They must be decompiled first (there are some tools for that, see the "My toolbox" page on my website). ===================== WHAT'S IN THE PACKAGE ===================== - This readme file which is the most reliable and up-to-date source of information about the tool. - The changelog to know what's new since the last version. - The exe (the actual tool, a small command line application). - The xml config file (topic covered below). ============ COMMAND LINE ============ Usage: MapSearch CLASSNAME [PROPERTYNAME] [VALUE] [OPTIONS] MapSearch is the name of the exe [OPTIONS] is a special argument, mainly for output preferences (topic covered below). Only CLASSNAME is mandatory (yet the exe won't crash if you don't even specify it). All the others are optional (but the more you give, the more precise your search will be). CLASSNAME, PROPERTYNAME and VALUE stand for the actual values you're looking for. They all support regexes. So you can look for exact matches, or you can specify patterns (the tool is coded in C# so cf. the corresponding regex specification). If you don't care about the value for one of the three, you can just provide no value, or the ".*" value (it's a regex meaning "anything"), or "*" (which is a shortcut to ".*"). Moreover, if VALUE is an integer it is searched as is but also as a possible set of checked values within "flags" properties (as far as such properties are not excluded from the search due to the other parameters). [OPTIONS] --------- This argument is a mix of "+", "-" and one or more of the letters below: l writes the detailed results into a log file. n sorts the detailed results by line number, instead of the default "classname then targetname then propertyname". p creates a pts file for each file with matching results (the same name as the map file and in same directory). Open the pts file in Trenchbroom to surf easily from one found entity to the next inside the map. d triggers the "developer mode" to get more debug info Letters following a "+" sign have the corresponding option switched on. Letters following a "-" sign have the corresponding option switched off. Omitted letters have the corresponding option taking its default value from the config file (see below). Examples: +l-p write a log file, don't make pts files, use the default sort order. -p+l does the same. l-p also does the same because "+" is assumed by default. lnp switches on options l, n and p. ==================== MapSearch-config.xml ==================== Contains some boring configuration you don't want repeat over and over each time you launch the exe. 1) Where are the map files to inspect. Put one or more directory paths, each on a separate line in the SearchIn section. "." means the same directory as where the exe is (use it if you want to simply put the exe at your map root directory). Each of those paths is searched along with all its subdirectories recursively. Paths to ignore can be put the same way in the Exclude section. "." means the same directory as where the exe is (if you want to ignore that directory). All excluded paths' subdirectories are ignored recursively as well. 2) FlagsProperties Each one is the name of a float property used to store flags values. They appear as a collection of checkboxes in Trenchbroom ("spawnflags" being the most famous example). I listed all the properties used that way in Hexen II and Quake maps, as well as in HexenC & QuakeC. Change the list if you want to use MapSearch for another game which may have a different collection of "flags" properties, or exclude some of the listed one if you don't think it's relevant to check them. 3) Ouput options Basically the same ones as with the above [OPTIONS] (except for "developer mode" which is command line only). Allow you to have your favorite settings always applied by default instead of providing them manually in the command line. The values in the config file are overriden by their [OPTIONS] counterparts when provided. PtsOutputDirectory can be set to write the pts files not in the same folder as the map files themselves (in case you don't want to "pollute" your map directory or it is read only or whatever). ========================= A note about the location ========================= Each matching entity is displayed with the x y z coordinates of the location it can be found within the map, in order to find it easly in TrenchBroom with Menu > View > Camera > Move Camera to... No problem with point entities as their origin is clearly specified among the other properties. Yet with brush entities, the coordinates are those of the first point defining the first plane of the first brush. In fact, nothing guarantees that point actually belongs to the brush. It might even be pretty far from it. In that case, once in TrenchBroom you might wonder where on earth the damn entity is?! Curiously I never faced the problem with Hexen II maps this far, but I did right away when testing with Quake maps. Sorry for that!!! I feel totally helpless as to how to fix this problem. Obviously the solution would be to take all the coordinates of the first brush into account to determine its center of gravity. I must sadly recognize it's far beyond my math skills. If anyone out there might help, I would be more than grateful!!! =============================== Examples (mostly using regexes) =============================== MapSearch .* spawnflags 64 Look for all entities (no matter their classname) whose spawnflags have the 64 checkbox checked (no matter the values of the other checkboxes, so 65 or 192 would match). MapSearch .* light 250 Look for all entities whose light value is 250, no matter their classname: light, light_torch_castle, light_candle, etc. (You would expect them all to be light_something but there is curiously a matching trigger_multiple hidden somewhere in the Tower of the Dark Mage!) MapSearch .* .* .*\.wav Look for all entities (no matter their type) having a property (no matter its name) referring to a wav file. MapSearch func_monsterspawner spawnflags 16 Look for all available examples of a func_monsterspawner spawning spiders. MapSearch func_train.* weaponmodel .* Look for all the occurrences of those nice "entity func_trains" introduced with Portal of Praevus (note how the pattern allow to take all the func_train and func_train_mp entities into account as well). MapSearch monster_fallen_angel_lord classname Look for all the occurrences of monster_fallen_angel_lord (by chance there are only 5 of them in the whole game, those chicks are tough!) Note that PROPERTYNAME is "classname" because no matter the type of entity you're looking for, this property always exist (it's the only one which always exists if I'm correct). If you give another value to PROPERTYNAME, you'll find only the monster_fallen_angel_lord with such a property. Try with "spawnflags" for example: there are 3 angels in the Cathedral but only one with spawnflags. If you give no value to PROPERTYNAME and just call "MapSearch monster_fallen_angel_lord", you'll get all the properties of all monster_fallen_angel_lord entities. MapSearch * * 128 Look for properties set to 128, no matter the classname or property name. It gives an interesting result for the Palace of the Pharaoh map: Line 49749: (breakable_brush) t47.spawnflags == 32960 [64][128][32768] at 704 1824 416 Line 43454: (func_door) t6.lip == 128 at 2584 288 208 The value 128 is a power of 2 and was found as a checked checkbox in a breakable_brush's spawnflags property (and we are informed about all the checked checkboxes by the way: [64][128][32768]). But 128 is also a regular integer value matching the lip size of a func_door. Unlike spawnflags, lip is not registered in the config as a "flags" property, so no decomposition into powers of 2 is shown (nor taken into account by the search engine). MapSearch breakable_brush spawnflags 96 Look for all breakable_brush entities with their "32" and "64" checkboxes checked in their spawnflags. Please note that AT LEAST both must be checked for the search to match, but some extra checkboxes may be checked as well. There is no regular way to ask MapSearch to look for occurrences with EXACTLY those 2 checkboxes checked and no other. If for some reason it's what you absolutely want, it's very easy to get anyways: you can post-filter the results with a standard text search, or (more sneaky!) exclude spawnflags from the list of recognized "flags" properties by removing it or renaming it with a weird prefix or suffix in the config file (but you won't have the decomposition into powers of 2 in the results anymore).