Documentation for heightcheck MODULE

By Épiméthée and Kuertee

This module can be used to determine the height of a character or building.

Special Thanks

Based on Dr Mike's brilliant flightcheck detection concept, as developped by M25. A big thank too to Stumpy for his falling object slow down code, which made this up to twenty times more precise (!) and for his MissionObjVar and DATFiles modules.

Character Height Detection

Template_GetHeight(template)

If the building template is already present in heightcheckdata.py, returns the height of a template object if known. Otherwise, tries to return the height of another template using the same mesh.

checkHeight(templateList, precise = 'no', repeat = 0, replace = 0, giants = 1, campaign = 0)

Use this if the character templates' dimensions cannot be retrieved "on-the-fly". Their dimensions need to be stored in heightcheckdata.py by calling this from a game mission you'll be running for this purpose only.

From the console:

>>> AIPeace()
>>> import heightcheck
>>> heightcheck.checkHeight(["microwave", "the_ant", "supercollider"])

Notes:

• checkHeight() cannot be used on the fly, as the height determination process is very lengthy. (There should eventually be speed improvements for character height, as I've tested a completely different method; I just need to take the time to write the code. So contact me if you need a faster checkHeight(). – Épiméthée)
• Results for characters will be approximative. Those for generic objects should be far more exact.
• Doesn't work on buildings, as they cannot be spawned correctly and can't be destroyed afterward. (To detect an existing building's height, just spawn someone above it.)
• Doesn't work either on tanks (the 'crusher' attribute seems to be built-in for tanks and messes with detection?)
• Doesn't work with power proxies or powerups.
• Not every template object will give reliable results:
• Object whose apex isn't at the center (the T-Rex, for example) will give underestimated results.
• Objects with the attribute 'physical' set to 0 won't be processed, as they can't be hit. They will
  return an height of 0. Idem for those with 'avoid'=0 or generic objects with 'standon'-0.
• When using giants=0, objects taller than 60-110 units won't be detected correctly (for example,
  depending on gamespeed, the trex mesh (107 units) may or may not be detected correctly. Uncorrectly
  detected templates either return zero or a low number; for example, time_master may report as
  being 24 unit high, while its actual height is 170, as the mesh seems to have two hit targets or
  something...
  Even when using giants=1, objects taller than 255-260 units won't work (time_master is 170).
  Uncorrectly detected giants will return an height of 0.
• The smaller characters have a chance of returning an height of 0 if precise='no' and gamespeed
  is high enough, especially if repeat is set to a low value.
• A mesh's physical height for the game engine isn't necessarily exactly the same as it's visual height.
• While results for character height generally have a small enough error margin, there are sometimes
  aberrations with no known cause. Hence the use of multiple passes on characters (the repeat= argument)
  to reduce the problem. Occasionally, though, every result is worthless... I haven't found a pattern
  to this problem. :(
• Objects with invalid mesh path in templates.dat will return 0.
• Using the keyboard's plus/minus Easter egg will not influence results. ;)

Detecting height can be quite slow, especially when using precise='yes'. OK, extremely slow. Example, using the el_diablo template (height of 34):

precise = 'no', repeat = 0, giants = 1, game speed of 1.0X:
delay: 35 secs., normal error margin: 0-4, usually 1
precise = 'no', repeat = 0, giants = 0, game speed of 1.0X:
delay: 22 secs., normal error margin: 0-4, usually 1
precise = 'no', repeat = 0, giants = 1, game speed of 0.4X:
delay: 190 secs., normal error margin: 0-1
precise = 'yes', repeat = 0, giants = 1, game speed of 1.0X:
delay: 240 secs., normal error margin: 0-1
precise = 'no', repeat = 1, giants = 0, game speed of 1.0X:
delay: 4 secs., normal error margin: 0-4, but could be much higher

Note that occasional errors due to the object passing through the subject template instead of bouncing off it will
lenghten the process, as the next pass will start from the maximum possible height.

A generic object takes about 8 seconds to be detected at 1X speed.

The best solution for modmakers is to use checkHeight() themselves beforehand with checkHeight(newTemplatesList) running at 0.4X game speed if you've got only a few new templates and no existing templates with a new mesh. If your list is quite long (running every built-in templates took me a few hours), use instead checkHeight(modifiedCharacterTemplatesList, replace = 1) running at 0.4X game speed (or higher if you don't need as much precision) and checkHeight(modifiedGenericTemplatesList, replace = 1) running at 2X game speed.

Then, reserve the end-user in-game detection for custom characters added during the campaign, etc. Even then, you might wish to use it during cutscenes and/or in bases. Depending on how precise you need the detection to be, you could either use precise='yes' to compensate for the fact that user-selected game speed might be at up to 2X or you might set repeat = 10 to somewhat reduce the impact of erroneous results. Ex:

 height = Template_GetHeight(template)
 if height[1] == 0:
 	checkHeight([template], precise = 'no', repeat = 10)

Setting precise = 'yes' will temporarily reduce the time scale (game speed) to 3/10th of normal, as EVENT_TIMER can't occur often enough in normal time or faster, which may not be precise enough, giving an usual error margin of 0-10 at 2X speed. Most of the time, "precise = 'yes'" should give an error margin of 0-2 at 2X speed. Computer performance will also influence results. To put thing in perspective, el_diablo has an real height of 34 and a skull, of 11. Since game speed is irrelevant to generic object detection, precise = 'yes' will be ignored for them.

If repeat = 0, default value (8) will be used instead. Since the precision margin for generic objects is inferior to 0.1, repeat= will be ignored for them.

If replace = 1, values for templates already in heightcheckdata.py will be overwritten.

If giants = 0, giant-sized characters won't be detected correctly, but the first pass of the repeating detection will be speeded up considerably. This is currently ignored for generic templates.

If campaign = 1, custom heroes will be saved to heightcheckdata.py. Otherwise they won't, since their template name is generated on the fly, making the entry useless in skirmish. Note: there is now a workaround, it just needs to be implemented in HeightCheck.

To cancel checkHeight() after the current iteration of the current template, use checkHeightCancel().

checkHeightCancel()

Cancels checkHeight() after the current iteration of the current template.

Mesh/template management

Templates_AreSameMesh(template1, template2)

Returns 1 if two templates are using the same mesh path.

Template_GetMeshTemplates(template)

For a given template, returns a list of the different templates based on the same mesh founds in objects.dat.

Template_GetMesh(template)

For a given template, returns the mesh path as found in objects.dat.

Mesh_HasTemplates(mesh, template, verbose = 0)

For a given mesh, returns 1 if its list of templates include the templat4e passed as parameter.
verbose = 1 will activate the print comments

Mesh_GetTemplates(mesh)

For a given mesh, returns a list of the different templates founds in objects.dat

Mesh_AddTemplate(mesh, template, verbose = 0, save = 0)

Directly adds the template to the NIF_OBJECTS mesh path key and optionally to the heightcheckdata.py NIF_OBJECTS entry.
verbose = 1 will activate the print comments

Mesh_RemoveTemplate(mesh, template, verbose = 0, save = 0)

Removes the template from the NIF_OBJECTS mesh path key and optionally from the heightcheckdata.py NIF_OBJECTS entry.
verbose = 1 will activate the print comments

checkMeshes(mode = 'list', verbose = 0)

Gets the mesh for every entry in objects.dat and creates a dictionary with the mesh path as key and the list of templates using this mesh as value.
mode = 'list': (default) simply prints out the results
mode = 'add': adds the results to the NIF_OBJECTS mesh path key and to the heightcheckdata.py NIF_OBJECTS entry
mode = 'replace': replaces the content of the NIF_OBJECTS mesh path key and the heightcheckdata.py NIF_OBJECTS entry with the results
verbose = 1 will activate the print comments

checkHeightErrors()

Prints names and values of problematic objects.dat entries using the meshes list and returns a list of these entries.

Building Dimensions

BuildingTemplate_GetDimensions (template)

If the building template is already present in heightcheckdata.py, returns a dictionary with these keys and values:

{\t"nw": north-west offset from centre,
"se": south-east offset from centre,
"w": width,
"h": height,
"d": depth
}

isBuildingTemplate (ts)

Is the template a building?

getBuildingsToGetDimensionsOf (tevent = "", tbReplace = 0)

Use this if the buildings' dimensions cannot be retrieved "on-the-fly". Their dimensions need to be stored in heightcheckdata.py by calling this from a game mission you'll be running for this purpose only.

From the console:

>>> AIPeace()
>>> import heightcheck
>>> heightcheck.getBuildingsToGetDimensionsOf()

The process of measuring all buildings from the objects.dat file is quite slow and the tool only measures six buildings at a time. Restarts of the game-mode is required until all buildings have been measured.

The actual measurement routine is "hacky":

1. spawn 4 thugs at the top of the building.
2. trigger them to move outwards
3. if they get stuck before hitting the ground, teleport them a short distance forward
4. once they hit the ground, trigger them to move back towards the building
5. their position from the building's origin (i.e. the building's local (0,0,0)) is then used to generate the building's dimensions and note that the measurement occurs only on one building at a time. the time to take to measure the 6 buildings can be reduced if 24 "caliper" thugs are spawned at once. however, this is not really necessary.

These buildings don't spawn properlyy, and therefore have erroneous dimensions: cub_bldg_church, cub_bldg_white and ger_bldg_cathedral. Luckily, FFvsTTR has only 30 buildings.