better transparency handling for structure recognizer

[kostmo]

Some recognizable structures have "transparent" cells. However, the Aho-Corasick algorithm doesn't support "wildcards", which is essentially what transparent cells are, for the purpose of matching. So, for a structure template that contains transparent cells to be recognized, the cells of the world must also have "empty" cells in the same place.

Despite this, we can accommodate certain instances of structure recognition when the transparent cells are "overlapped" (or "encroached upon") by some other entity. We do this by "masking out" entities from the world that don't participate in the set of structures we're trying to match against.

This often works well, except when the set of structures to be recognized contains:

• one structure S1 with transparent cells
• another structure S2 with some additional type of entity E not participating in S1
• The entity E occupies a transparent cell of S1.

E can't be masked out since we're trying to simultaneously recognize structures of type S2 in the same Aho-Corasick pass. So a legitimate instance of S1 will fail to be recognized.

Workaround

We can make multiple Aho-Corasick passes: one pass for each distinct set of "masked entities". Notably:

• If no structures have transparent cells, we don't need to mask at all
• If all of the structures that contain transparent cells have an identical set of participating entities, they can all be handled in the same pass
• Not implemented: A structure with no transparency (i.e. with an empty "mask set") can be handled in the same pass as a a transparent structure, if they have an identical participating entity set.

Caveats

Note that this fundamental limitation of Aho-Corasick still exists for "encroaching entities" of the same type as the entity participants in the structure to be recognized.

E.g., if we have a structure defined as:

 X
XX

then, depending on the order of entity placement, the following occurrence in the world will not be recognized:

XX
XX

Testing

scripts/test/run-tests.sh --test-options '--pattern "structure-recognizer"'

Also in this PR

• improved docs/logging

[xsebek]

LGTM. 👍 Is there a playable challenge/tutorial where this would make it easier for the player to build the structure?

[kostmo]

Is there a playable challenge/tutorial where this would make it easier for the player to build the structure?

Not specifically. So far, the scenarios with structure recognition have been crafted to avoid this kind of issue.