Repository navigation
Expand file tree
/
Copy pathdoc-mapping.html
More file actions
368 lines (356 loc) · 19.6 KB
/
Copy pathdoc-mapping.html
File metadata and controls
368 lines (356 loc) · 19.6 KB
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
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
<!doctype html>
<html lang="en">
<head>
<!-- Required meta tags -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link rel="icon" href="images/TotalAILogoTrans32.png" type="image/x-icon">
<link rel="preconnect" href="https://fonts.gstatic.com">
<link href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600|Roboto Mono&display=swap" rel="stylesheet">
<link href="https://fonts.googleapis.com/css2?family=Goldman&display=swap" rel="stylesheet">
<!-- Bootstrap CSS -->
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/css/bootstrap.min.css" integrity="sha384-9aIt2nRpC12Uk9gS9baDl411NQApFmC26EwAOH8WgZl5MYYxFfc+NcPb1dKGj7Sk" crossorigin="anonymous">
<link rel="stylesheet" href="main.css">
<title>Total AI</title>
</head>
<body>
<nav class="navbar sticky-top tai-navbar">
<a class="navbar-brand" style="margin-top: -8px; margin-bottom: -8px;" href="index.html">
<img src="images/TotalAILogoTrans.png" height="40" alt="" loading="lazy">
</a>
<ul class="nav mr-auto">
<li class="nav-item">
<a class="nav-link" href="index.html">Home <span class="sr-only">(current)</span></a>
</li>
<li class="nav-item">
<a class="nav-link active" href="doc-introduction.html">Guide</a>
</li>
<li class="nav-item">
<a class="nav-link" href="insp-introduction.html">Inspectors</a>
</li>
<li class="nav-item">
<a class="nav-link" href="script-introduction.html">Scripts</a>
</li>
<li class="nav-item">
<a class="nav-link" href="videos.html">Videos</a>
</li>
<li class="nav-item">
<a class="nav-link" href="contributors.html">Contributors</a>
</li>
<li class="nav-item">
<a class="nav-link" href="about.html">About</a>
</li>
<li class="nav-item" style="padding-left: 25px;">
<a class="nav-link" href="contrib-introduction.html">Contribute</a>
</li>
</ul>
<ul class="nav justify-content-end">
<li class="nav-item">
<a class="nav-link" target="_blank" href="https://discord.gg/PfKUm42Zax">
Discord
<svg width="1em" height="1em" viewBox="0 0 20 20" class="bi bi-box-arrow-up-right" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/>
<path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/>
</svg>
</a>
</li>
<li class="nav-item">
<a class="nav-link" target="_blank" href="https://github.com/TotalAI/TotalAI">
GitHub
<svg width="1em" height="1em" viewBox="0 0 20 20" class="bi bi-box-arrow-up-right" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/>
<path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/>
</svg>
</a>
</li>
<li class="nav-item">
<a class="nav-link" target="_blank" href="https://patreon.com/zacwarren">
Patreon
<svg width="1em" height="1em" viewBox="0 0 20 20" class="bi bi-box-arrow-up-right" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
<path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/>
<path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/>
</svg>
</a>
</li>
</ul>
</nav>
<main style="width: 100%">
<div class="container-fluid">
<div class="row flex-xl-nowrap">
<div class="col-md-3 col-xl-2" style="position: sticky; top: 0; z-index: 1000; height: calc(100vh - 4rem); order: 0; overflow-y: auto; padding-top: 10px; padding-bottom: 40px;">
<h3 class="nav-header">Getting Started</h3>
<ul class="nav flex-column">
<li class="nav-item">
<a class="nav-link" href="doc-introduction.html">Introduction</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-installation.html">Install & Setup</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-demo.html">Demo Worlds</a>
</li>
</ul>
<h3 class="nav-header">Entities</h3>
<ul class="nav flex-column navbar-light">
<li class="nav-item">
<a class="nav-link" href="doc-agent.html">Agent</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-worldobject.html">WorldObject</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-agentevent.html">AgentEvent</a>
</li>
</ul>
<h3 class="nav-header">Levels</h3>
<ul class="nav flex-column navbar-light">
<li class="nav-item">
<a class="nav-link" href="doc-drive.html">Drive</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-action.html">Action</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-attribute.html">Attribute</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-tag.html">Tag</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-role.html">Role</a>
</li>
<h3 class="nav-header">Agent</h3>
<ul class="nav flex-column navbar-light">
<li class="nav-item">
<a class="nav-link" href="doc-agent-main-loop.html">Main Loop</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-movementtype.html">Movement Type</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-animationtype.html">Animation Type</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-sensortype.html">Sensor Type</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-memorytype.html">Memory Type</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-decider.html">Decider</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-plannertype.html">Planner Type</a>
</li>
<li class="nav-item">
<a class="nav-link active" href="doc-mapping.html">Plans & Mappings</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-behavior.html">Behavior</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-historytype.html">History Type</a>
</li>
</ul>
<h3 class="nav-header">AI Types</h3>
<ul class="nav flex-column navbar-light">
<li class="nav-item">
<a class="nav-link" href="doc-fsm.html">FSM</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-goap.html">GOAP</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-utility-ai.html">Utility AI</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-deep-rl.html">Deep RL</a>
</li>
</ul>
<h3 class="nav-header">Other</h3>
<ul class="nav flex-column navbar-light">
<li class="nav-item">
<a class="nav-link" href="doc-typematching.html">Type Matching</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-inventory.html">Inventory</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-design-principles.html">Design Principles</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-scriptableobjects.html">ScriptableObjects</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-selector.html">Selector</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-utility-curve.html">Utility Curve</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-utility-function.html">Utility Function Type</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-included-ui.html">UI & Placement</a>
</li>
<li class="nav-item">
<a class="nav-link" href="doc-more-resources.html">External Links</a>
</li>
</ul>
</div>
<div class="col-md-1">
</div>
<div class="col content" style="padding-top: 40px; padding-bottom: 40px; line-height: 1.6em; color: #304455; font-size: 1rem;">
<h1>Plans & Mappings</h1>
<h3>What are Plans?</h3>
<hr>
<p>
Plans are for a single Drive Type and have a list of Root Mappings. A Root Mapping is the start of the Plan Tree
and contains the Mapping Type that has an OutputChange that reduces the Drive Type Level. Plans are generated by
the <a class="text-link" href="doc-plannertype.html">Planner Type</a>.
<br><br>
Plans also contain information on the status (Not Complete, Complete, Running, Finished, or Interrupted) of each Plan.
</p>
<h3>What is a Mapping?</h3>
<hr>
<p>
A Mapping represents one unit of a Plan. Think of it as a single action that has Input Conditions that need to be
satisfied for it to start and then once it is started, Output Changes can occur. The Ouput Changes can occur anytime during
Mapping and there are currently ten ways to control the timing of an Output Change: On Finish, On Animation Event,
Repeating, On Behavior Invoke, Before Start, On Trigger Enter, On Collision Enter, After Game Minutes, On Interrupt,
and On Quit Agent Event.
<br><br>
A Mapping is a C# class that has a parent and children, so it is a Node in the Plan Tree. If the parent is null
it means the Mapping is a Root Mapping and will have at least one Output Change that reduces the Plan's DriveType.
If the Mapping has no children then the Mapping is a leaf in the Plan Tree. If all of the leaves in a Plan Tree have
all of their Input Conditions satisified then the Agent can perform this Plan. TAI considers the Plan to be "Complete".
<br><br>
Also if the Mapping's MappingType has at least one Input Condition Type (ICT) that requires an Entity Target
then the Mapping will have an Entity target. An Entity
target is passed to the Behavior Type, the code that actually runs the Mapping, so it can perform logic related to the
target. The Entity target is also passed to the Output Changes that are set to TargetType of "ToTargetEntity".
</p>
<h3>How is a Mapping Created?</h3>
<hr>
<p>
Mappings are usually created by the Planner Type when generating Plan Trees but special GoTo Mappings can also be generated
while a Plan is being run by an Agent. These are generated if the Mapping has an Entity Target and needs to get within
interaction distance of the Entity Target. By generating this GoTo Mappings only when running a Plan the overall
number of Mappings in generated Plans is greatly reduced. The GoToActionType is set on the Mapping Type and determines
what Behavior Type should be used.
</p>
<h3>Mapping Type</h3>
<hr>
<p>
<a class="text-link" href="insp-mappingtype.html">Inspector Reference</a>
<br>
<a class="text-link" href="script-mappingtype.html">Script Reference</a>
<br><br>
A Mapping Type defines the configuration and logic of a Mapping. A Mapping Type inherits from ScriptableObject and can
be created similar to other ScriptableObjects by right clicking in the Project File View and following the menu.
(Create -> Total AI)
<br><br>
Mapping Types contain the following main fields:
<ul>
<li><b>Action Type</b>: Acts as a grouping of Mapping Types and also specifies the Behavior Type that will occur.</li>
<li><b>Behavior Type Selectors</b>: Selectors for choosing attributes values to send to the Behavior Type.</li>
<li><b>Utility Modifiers</b>: Utility AI style modifiers to change the Utility of the Mapping.</li>
<li><b>Target Factors</b>: Utility AI style selectors for picking an Entity and/or inventory Target(s).</li>
<li><b>Input Conditions</b>: What needs to be true for an agent to perform this MappingType?</li>
<li><b>Output Changes</b>: What changes will occur at various times when running this MappingType?</li>
</ul>
</p>
<h3>Input Conditions</h3>
<hr>
<p>
<a class="text-link" href="insp-inputcondition.html">Inspector Reference</a>
<br>
<a class="text-link" href="script-inputcondition.html">Script Reference</a>
<br><br>
A MappingType can have zero to many Input Conditions (ICs). Each IC represents one check to see if the Agent
can perform this Mapping Type. If all checks pass then the Mapping will be marked as "Completed". If the
Agent is using the GOAPPlannerType or any Planner Type that can generate planning trees and an IC fails, the planner type
will try to find a Mapping Type with an Output Change that "fixes" the Input Condition. If it finds a fix, a
new child Mapping will created. For more information on how GOAPPlannerType generates Plan Trees see
<a class="text-link" href="doc-GOAP.html">GOAP Info</a>.
<br><br>
The two main fields on an IC is its type, Input Condition Type (ICT), and what match type (Match multiple Entity Types)
of object it is checking. The final fields on an IC define the values the ICT needs to do the check.
The required values along with the specific match type are dependent on the ICT, so the ICT contains an
TypeInfo class that will dynamically change the shown inspector fields to only show fields the ICT
needs along with descriptions and tooltips. It can also make the Type fields more specific. For example if
the ICT is for an Agent Type, the editor will only allow you to select Agent Type ScriptableObject assets.
</p>
<h3>Output Changes</h3>
<hr>
<p>
<a class="text-link" href="insp-outputchange.html">Inspector Reference</a>
<br>
<a class="text-link" href="script-outputchange.html">Script Reference</a>
<br><br>
A Mapping Type can have zero to many Output Changes (OCs). An OC's Target Type can be for the Agent (To Self) or
for the Target (To Entity Target). An OC also has ten Timing options: On Finish, On Animation Event,
Repeating, On Behavior Invoke, Before Start, On Trigger Enter, On Collision Enter, After Game Minutes, On Interrupt,
and On Quit Agent Event. Behavior Invoked relies on the Behavior Type to specifically call an Output Change
check. AnimationEvent relies on Unity's
<a class="text-link" target="_blank" href="https://docs.unity3d.com/Manual/script-AnimationWindowEvent.html">
AnimationEvent
</a>
feature. The AnimationEvent's Function name should be exactly "AnimationOutputChange".
<br><br>
An OC is similar to IC in that it's main field is a type, Output Change Type (OCT). Similar to an ICT, an OCT
has an TypeInfo class in order to make the OC inspector dynamic based on the OCT.
<br><br>
An OC can contain Change Conditions if the OC needs to have specific logic causing it not to run.
</p>
<h3>Target Factors</h3>
<hr>
<p>
<a class="text-link" href="script-targetfactor.html">Script Reference</a>
<br><br>
If a MappingType has at least one ICT that requires an Entity Target, the Mapping will need to select an Entity Target
that passes ALL of the Entity Type ICs. The logic for this can be specified in the Decider Type or Planner Type.
<br><br>
If there are multiple Entities found that pass all of the EntityType ICs, TargetFactors (TFs) come into play. They
provide a Utility AI like mechanism for choosing the best Entity.
<br><br>
A Mapping can have zero to many TFs. If there are multiple TargetFactors you can supply a weight for each TargetFactor.
The weights will be normalized. For example if you have two TargetFactors, one with a weight of 0.5 and one with a weight
of 1.0, the first one will count for 0.5/1.5 = 1/3 and the second one for 1.0/1.5 = 2/3.
<br><br>
The TargetFactor abstract class inherits from ScriptableObject. All TargetFactors then inherit from TargetFactor.
There is only one method that needs to be implemented, Evaluate. Evaluate must return a value between 0-1 or -1.
-1 is a special value denoting a veto. If any TF returns -1, that Entity will be removed from consideration.
</p>
<h3>Selectors</h3>
<hr>
<p>
<a class="text-link" href="script-selector.html">Script Reference</a>
<br><br>
Selectors are required to select the desired values for the Behavior Type.
They are also used by Ouput Changes to select values.
<br><br>
See <a class="text-link" href="doc-selector.html">Selector Guide</a>.
</p>
</div>
<div class="col-md-3">
</div>
</div>
</main>
<script>
$(document).ready(function() {
$(window).resize(function() {
resize();
});
function resize() {
var myheight = $(window).outerHeight(true) - 0;
$('.main').outerHeight(myheight);
}
resize();
});
</script>
<script src="https://code.jquery.com/jquery-3.5.1.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.0/js/bootstrap.min.js" integrity="sha384-OgVRvuATP1z7JjHLkuOU7Xw704+h835Lr+6QL9UvYjZE3Ipu6Tp75j7Bh/kR0JKI" crossorigin="anonymous"></script>
</body>
</html>