clearance-probe - reproduction bench for the city building clearance bug
========================================================================

What it does
------------
Builds a grid of elevated roads over every city on the map, then forces the cities
to grow many times over. City growth and renovation both go through the code paths
that pick a building for a tile, so this exercises them thousands of times in a
couple of minutes instead of waiting for organic growth, which is far too rare to
observe - twelve minutes of ordinary play produced no cases at all.

How to run it
-------------
1. Copy this folder into your pak128.german installation as

       pak128.german/scenario/clearance-probe/

2. Copy the savegame that ships with the pakset in beside scenario.nut:

       pak128.german/SaveGames/PAK128German_Start.sve
         ->  pak128.german/scenario/clearance-probe/PAK128German_Start.sve

   The scenario refers to it by name; nothing else is needed.

3. Start:

       simutrans -set_basedir <your simutrans dir> -singleuser \
                 -objects pak128.german -scenario clearance-probe \
                 -lang en -debug 2 -fps 100

   Script output goes to stderr, not to the log file, so redirect it if you want
   to keep it.

What you should see
-------------------
    PROBE elevated way = Hochstrasse130
    PROBE map 896x768
    PROBE cities = 15
    PROBE elevated tiles = 278
    PROBE growth orders accepted = 4500
    PROBE done

The game never exits by itself - stop it when you have seen enough.

Seeing the bug
--------------
The bench on its own only creates the conditions. To count cases, add a temporary
warning in stadt_t::renovate_city_building() and stadt_t::build_city_building(),
just before the building is placed, comparing the chosen building's
get_height_clearance() against planquadrat_t::get_overhead_clearance() for every
tile of its footprint - not just the anchor. That is the whole bug in one line.

On the unpatched code that reports things like

    renovate Wasserturm_PrenzlauerBerg height=6 footprint=2x2
       anchor=(222,552) anchor_clearance=127 -> tile (222,553) clearance=1

With the patch applied, moving the same warning behind the new check turns it into
a count of prevented cases: nine in one run here.

Note on timing
--------------
Renovations keep happening while the world runs, after the script has finished.
Reading the counters the moment "PROBE done" appears can show zero and prove
nothing. Let it run.
