PZ_Mapping_Tools/docs/TileZed/Automapper.html at main · Z3R0-BYT3Z/PZ_Mapping_Tools · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>TileZed Automapper</title>
  <style>
    body { max-width: 1080px; margin: 24px auto; padding: 0 20px; font: 15px/1.5 "Segoe UI", Arial, sans-serif; }
    code, pre { font-family: Consolas, monospace; }
    code { background: #eee; padding: .1em .3em; }
    pre { overflow: auto; padding: 12px; background: #eee; }
    table { width: 100%; border-collapse: collapse; }
    th, td { padding: 7px 9px; border: 1px solid #aaa; text-align: left; vertical-align: top; }
    .note, .warning { padding: 10px 14px; border-left: 4px solid #3977b8; background: #eef6ff; }
    .warning { border-left-color: #c58a00; background: #fff4d9; }
    @media (prefers-color-scheme: dark) {
      body { color: #eee; background: #202225; }
      code, pre { background: #151719; }
      .note { background: #203246; }
      .warning { background: #493b1d; }
    }
  </style>
</head>
<body>
<h1>TileZed Automapper</h1>

<p>Automapper matches tile or object patterns in a working TMX and copies the
corresponding output from one or more rule-map TMX files. The Automapper dock
shows loaded files, target layers, pattern counts, map properties, warnings,
and errors.</p>

<h2>The mental model</h2>
<p>Automapper does not generate a map from a script. It compares a small
example map against the map being edited:</p>
<ol>
  <li>The <strong>target TMX</strong> is the real map being edited.</li>
  <li>A <strong>rule-map TMX</strong> contains one or more small examples.</li>
  <li><code>Input_*</code> layers describe what must already exist in the
  target map.</li>
  <li><code>InputNot_*</code> layers describe what must not exist.</li>
  <li><code>Output_*</code> layers describe what Automapper will place.</li>
  <li>A <code>Regions</code> layer separates the rule-map into connected
  patterns. Automapper slides each pattern over the target map and applies its
  output wherever its complete input matches.</li>
</ol>
<p>The text manifest only establishes load order. The actual matching rules
live in the referenced TMX files.</p>
<div class="note">
  This reference describes and is checked against the Automapper
  implementation shipped in this TileZed build. The preferred manifest name
  and WorldEd-file isolation are PZTools compatibility policies; they do not
  change the rule-map matching format.
</div>

<h2>Smallest useful project</h2>
<pre><code>my-map/
  town.tmx
  automapping-rules.txt
  rules/
    grass-border.tmx</code></pre>
<p><code>automapping-rules.txt</code> contains:</p>
<pre><code># Load order matters.
rules/grass-border.tmx</code></pre>
<p>The target <code>town.tmx</code> and rule map both need a tile layer named
<code>Ground</code>. The rule map then uses these layers:</p>
<table>
<tr><th>Rule-map layer</th><th>What to paint in it</th></tr>
<tr><td><code>Regions</code></td><td>Any visible marker tile over the complete area used by the example. The marker tile itself is never copied.</td></tr>
<tr><td><code>Input_Ground</code></td><td>The ground tiles that must be present in the target map.</td></tr>
<tr><td><code>InputNot_Ground</code></td><td>Optional ground tiles that reject the match.</td></tr>
<tr><td><code>Output_Ground</code></td><td>The replacement or additional ground tiles to copy to the target map.</td></tr>
</table>
<p>For a first rule, paint one connected marker area in
<code>Regions</code>, put one known tile at the same coordinate in
<code>Input_Ground</code>, and put the desired result at that coordinate in
<code>Output_Ground</code>. Save both maps, open <strong>View >
Automapping</strong>, press <strong>Reload</strong>, inspect the rule entry,
and use <strong>Apply</strong>. Once the full-map result is correct, enable
<strong>Interactive</strong> if the workflow benefits from it.</p>
<div class="note">
  The layer suffix is the target layer name, not an arbitrary rule label.
  <code>Input_Ground</code> reads target layer <code>Ground</code>;
  <code>Output_Furniture</code> writes target layer
  <code>Furniture</code>. Names and layer types must match.
</div>

<h2>Loading rules</h2>
<p>Save the target map first. TileZed searches beside it for
<code>automapping-rules.txt</code>. For compatibility, an existing
<code>rules.txt</code> is accepted when it is an Automapper manifest. The
explicit <code>automapping-rules.txt</code> name always wins when both files
exist.</p>
<p>Each non-empty line that does not begin with
<code>#</code> or <code>//</code> names either a rule-map <code>.tmx</code> or
another <code>.txt</code> list:</p>
<pre><code># paths are relative to this list
rules/roads.tmx
rules/vegetation.txt
C:/shared-rules/signs.tmx</code></pre>
<p>Relative paths are resolved against the list containing them. Nested lists
are supported. Recursive includes, duplicate rule maps, missing files, and
unsupported extensions are reported rather than loaded repeatedly.</p>
<div class="note">
  WorldEd terrain/BMP files also use the name <code>Rules.txt</code>, but their
  <code>version</code>, <code>alias</code>, <code>rule</code>, and tile-block
  syntax is not an Automapper manifest. TileZed recognizes and ignores that
  file. It does not turn each terrain-rule line into a missing filename.
</div>

<h2>Rule-map layer names</h2>
<table>
<tr><th>Name</th><th>Purpose</th></tr>
<tr><td><code>Regions</code></td><td>Defines both input and output extents. Each connected region is one pattern.</td></tr>
<tr><td><code>RegionsInput</code></td><td>Input matching extent when it differs from output.</td></tr>
<tr><td><code>RegionsOutput</code></td><td>Output copy extent when it differs from input.</td></tr>
<tr><td><code>Input_Target</code></td><td>Positive pattern matched against tile layer or Object Group <code>Target</code>.</td></tr>
<tr><td><code>InputNot_Target</code></td><td>Pattern that must not match <code>Target</code>.</td></tr>
<tr><td><code>Output_Target</code></td><td>Tiles or objects copied to target layer/group <code>Target</code>.</td></tr>
</table>
<p>Prefixes are case-insensitive. The underscore is required. The part after
it is the exact target layer name and type.</p>

<h3>Indexes and alternatives</h3>
<p>An optional index between the prefix and underscore groups conditions and
outputs:</p>
<pre><code>Input1_Ground
InputNot1_Objects
Output1_Floor
Output1_Furniture

Input2_Ground
Output2_Floor</code></pre>
<p>For input groups, every named target inside one index must match; matching
any complete index is sufficient. Repeated Input or InputNot layers with the
same index and target provide accepted or rejected alternatives.</p>
<p>Each distinct Output index is an alternative output group. When several
exist, Automapper chooses one randomly for each match. Give layers the same
output index when they must be copied together.</p>

<h2>Rule-map properties</h2>
<table>
<tr><th>Property</th><th>Meaning</th></tr>
<tr><td><code>DeleteTiles</code></td><td>Clears affected output areas before copying output, removing results left by an older match.</td></tr>
<tr><td><code>AutomappingRadius</code></td><td>Expands the edited region by this many tiles during interactive automapping.</td></tr>
<tr><td><code>NoOverlappingRules</code></td><td>Prevents output regions produced by the same rule from overlapping on a target layer.</td></tr>
</table>
<p>Property spelling is case-insensitive. Values must convert to the required
boolean or integer type. Unknown or invalid properties produce warnings.</p>

<h2>Tile matching</h2>
<ul>
  <li>The target cell must be inside the target layer and not empty.</li>
  <li>A tile in a positive input layer accepts that exact tile.</li>
  <li>A tile in an InputNot layer rejects that exact tile.</li>
  <li>With only positive layers, an empty rule coordinate accepts tiles not
  used elsewhere by the positive pattern.</li>
  <li>With positive and negative layers together, positive coordinates must
  match an allowed tile and no negative tile may match.</li>
</ul>

<h2>Object Group matching</h2>
<p>Input and InputNot layers may also be Object Groups. A rule object compares
its shape, translated position, dimensions, polygon data, and custom
properties. Name and type are compared when their rule values are non-empty.
A rule property value of <code>*</code> means the candidate must contain that
property but its value may be anything.</p>
<p>All objects in a positive pattern must be found. A matching InputNot object
pattern rejects the rule.</p>

<h2>Applying and interactive mode</h2>
<ul>
  <li><strong>Reload</strong> rereads the manifest, nested lists, and rule TMX files.</li>
  <li><strong>Apply</strong> runs all loaded rules on the complete target map.</li>
  <li><strong>Interactive</strong> reruns relevant rules when tile regions or
  map objects are added, changed, or removed.</li>
</ul>
<p>Rules run in load order. The changed region produced by one rule is passed
to following rules, allowing multi-stage pipelines. Application is stored as
<strong>Apply AutoMap rules</strong> in the Undo stack.</p>

<div class="warning">
  Test new rule sets on a copy. Interactive mode can trigger a large pipeline
  after a small edit, especially with a large AutomappingRadius or recursive
  output dependencies.
</div>

<h2>Working example included with the source</h2>
<p><code>TileZed/examples/sewer_automap</code> is a complete multi-stage
example. Open <code>sewers.tmx</code>. Its manifest loads seven rule maps in
order:</p>
<ol>
  <li>fill the marked sewer region;</li>
  <li>choose transition tiles;</li>
  <li>place straight walls;</li>
  <li>place inner corners;</li>
  <li>place outer corners;</li>
  <li>correct ambiguous corners with <code>InputNot_set</code>;</li>
  <li>choose final corner stones from alternative inputs.</li>
</ol>
<p><code>rule_001.tmx</code> is the best starting point. It demonstrates
<code>Regions</code>, <code>Input_set</code>, three tile outputs, an Object
Group output, <code>DeleteTiles</code>, and
<code>AutomappingRadius</code>. Disable later lines in the manifest and apply
the maps one at a time to see how each stage changes the output.</p>

<h2>Design and performance guidelines</h2>
<ul>
  <li>Start with <strong>Apply</strong> and a copy of the target map. Enable
  interactive mode only after the complete pipeline is predictable.</li>
  <li>Keep <code>AutomappingRadius</code> as small as the largest pattern that
  must react around a changed tile.</li>
  <li>Put broad classification rules before detail and correction rules.</li>
  <li>Avoid having a late output recreate the input of an expensive early
  stage unless the pipeline intentionally needs that dependency.</li>
  <li>Use separate indexed outputs only for true random alternatives. Give
  layers the same output index when they must be applied together.</li>
  <li>Use <code>DeleteTiles</code> only after confirming which output area is
  owned by the rule.</li>
</ul>

<h2>Where diagnostics appear</h2>
<p>The Automapping dock shows the selected manifest, every loaded rule map,
pattern counts, output layers, radius, properties, warnings, and errors.
The same messages are written to the current TileZed log under
<code>settings/logs</code>. A missing or invalid manifest is attempted once
per document; after correcting it, press <strong>Reload</strong>. This prevents
ordinary brush strokes from repeatedly parsing the same bad file.</p>
<div class="note">
  <strong>Import Rules followed by Reload in the BMP Tool is not this
  Automapper reload.</strong> It loads WorldEd terrain/vegetation rules and
  activates BMP blending on the rule target layers. If painting becomes slow
  only after that sequence, report it as a BMP Blender performance issue and
  include the map, terrain <code>Rules.txt</code>, <code>Blends.txt</code>, and
  newest TileZed log.
</div>

<h2>Troubleshooting</h2>
<table>
<tr><th>Message or symptom</th><th>Check</th></tr>
<tr><td>No rules loaded</td><td>The target TMX is saved and <code>automapping-rules.txt</code>, or a compatible legacy <code>rules.txt</code>, is beside it.</td></tr>
<tr><td>Nearby Rules.txt is ignored</td><td>It is a valid WorldEd terrain/BMP definition. Keep it and create a separate <code>automapping-rules.txt</code>.</td></tr>
<tr><td>Brush pauses after a manifest error</td><td>A failed automatic load is attempted once per document. Correct the manifest, then press Reload; normal painting no longer retries it for every stroke.</td></tr>
<tr><td>Brush pauses after BMP Tool Import Rules + Reload</td><td>This is the separate BMP Blender path, not Automapper manifest loading. Attach the terrain Rules/Blends files and check the log for a slow dirty-region recalculation warning.</td></tr>
<tr><td>No input/output region layer</td><td>Add Regions, or both RegionsInput and RegionsOutput.</td></tr>
<tr><td>Layer not recognized</td><td>Check the underscore and accepted prefix.</td></tr>
<tr><td>Rule never matches</td><td>Verify target layer type/name, non-empty cells, input grouping, and InputNot exclusions.</td></tr>
<tr><td>Unexpected random output</td><td>Different Output indexes are alternatives.</td></tr>
<tr><td>Old output remains</td><td>Enable DeleteTiles in the owning rule map.</td></tr>
<tr><td>Output layer is skipped</td><td>Check the log for a duplicate or conflicting destination layer. The output suffix and layer type must identify one valid target; a genuinely missing output layer is normally created automatically.</td></tr>
<tr><td>A small edit changes a large area</td><td>Reduce AutomappingRadius and check whether earlier rule outputs trigger later stages.</td></tr>
</table>
<p>A complete sample is installed under <code>examples/sewer_automap</code>.</p>
</body>
</html>