Skip to content

Commit 7f9eb72

Browse files
TemporalOroborosTemporalOroboros
committed
Doc comments for new SharedMapSystem methods
1 parent d8f4a28 commit 7f9eb72

2 files changed

Lines changed: 167 additions & 19 deletions

File tree

‎Robust.Shared/GameObjects/Systems/SharedMapSystem.Grid.Queries.cs‎

Lines changed: 154 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
using System;
12
using System.Collections.Generic;
23
using System.Diagnostics.CodeAnalysis;
34
using System.Numerics;
@@ -27,6 +28,15 @@ public abstract partial class SharedMapSystem
2728

2829
#region TryFindGridAt
2930

31+
/// <summary>
32+
/// Attempts to find a grid which overlaps with a given position on a given map.
33+
/// If the map is itself a grid and there is no other grid overlapping with the given position this will return the map itself as such a grid.
34+
/// </summary>
35+
/// <param name="mapEnt">The uid of the map to search for a valid grid.</param>
36+
/// <param name="worldPos">The exact position within and relative to the map to search for a valid grid.</param>
37+
/// <param name="uid">Returns the uid of the grid found, if any.</param>
38+
/// <param name="grid">Returns the component of the grid found, if any.</param>
39+
/// <returns>True if a grid overlapping with the given position within the given map was found, or false otherwise.</returns>
3040
public bool TryFindGridAt(EntityUid mapEnt, Vector2 worldPos, out EntityUid uid, [NotNullWhen(true)] out MapGridComponent? grid)
3141
{
3242
var rangeVec = new Vector2(0.2f, 0.2f);
@@ -56,12 +66,12 @@ public bool TryFindGridAt(EntityUid mapEnt, Vector2 worldPos, out EntityUid uid,
5666
// NOTE:
5767
// If you change this to use fixtures instead (i.e. if you want half-tiles) then you need to make sure
5868
// you account for the fact that fixtures are shrunk slightly!
59-
var chunkIndices = SharedMapSystem.GetChunkIndices(localPos, iGrid.ChunkSize);
69+
var chunkIndices = GetChunkIndices(localPos, iGrid.ChunkSize);
6070

6171
if (!iGrid.Chunks.TryGetValue(chunkIndices, out var chunk))
6272
return true;
6373

64-
var chunkRelative = SharedMapSystem.GetChunkRelative(localPos, iGrid.ChunkSize);
74+
var chunkRelative = GetChunkRelative(localPos, iGrid.ChunkSize);
6575
var chunkTile = chunk.GetTile(chunkRelative);
6676

6777
if (chunkTile.IsEmpty)
@@ -84,6 +94,8 @@ public bool TryFindGridAt(EntityUid mapEnt, Vector2 worldPos, out EntityUid uid,
8494
return grid != null;
8595
}
8696

97+
/// <inheritdoc cref="TryFindGridAt(EntityUid, Vector2, out EntityUid, out MapGridComponent?)"/>
98+
/// <param name="mapId">The id of the map to search for a valid grid.</param>
8799
public bool TryFindGridAt(MapId mapId, Vector2 worldPos, out EntityUid uid, [NotNullWhen(true)] out MapGridComponent? grid)
88100
{
89101
if (TryGetMap(mapId, out var map))
@@ -94,6 +106,8 @@ public bool TryFindGridAt(MapId mapId, Vector2 worldPos, out EntityUid uid, [Not
94106
return false;
95107
}
96108

109+
/// <inheritdoc cref="TryFindGridAt(EntityUid, Vector2, out EntityUid, out MapGridComponent?)"/>
110+
/// <param name="mapCoordinates">The map position to search for a valid grid.</param>
97111
public bool TryFindGridAt(MapCoordinates mapCoordinates, out EntityUid uid, [NotNullWhen(true)] out MapGridComponent? grid)
98112
{
99113
return TryFindGridAt(mapCoordinates.MapId, mapCoordinates.Position, out uid, out grid);
@@ -103,30 +117,62 @@ public bool TryFindGridAt(MapCoordinates mapCoordinates, out EntityUid uid, [Not
103117

104118
#region MapId
105119

106-
public void FindGridsIntersecting<T>(
120+
/// <summary>
121+
/// Adds every grid on the specified map which intersects the given region to the provided collection.
122+
/// </summary>
123+
/// <param name="shape">The shape of the region to check.</param>
124+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
125+
public void FindGridsIntersecting<TShape>(
107126
MapId mapId,
108-
T shape,
127+
TShape shape,
109128
Transform transform,
110129
ref List<Entity<MapGridComponent>> grids,
111130
bool approx = Approximate,
112-
bool includeMap = IncludeMap) where T : IPhysShape
131+
bool includeMap = IncludeMap) where TShape : IPhysShape
113132
{
114133
if (TryGetMap(mapId, out var mapEnt))
115134
FindGridsIntersecting(mapEnt.Value, shape, transform, ref grids, approx: approx, includeMap: includeMap);
116135
}
117136

118-
public void FindGridsIntersecting<T>(
137+
/// <summary>
138+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
139+
/// </summary>
140+
/// <param name="shape">The shape of the region to check.</param>
141+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
142+
public void FindGridsIntersecting<TShape>(
119143
MapId mapId,
120-
T shape,
144+
TShape shape,
121145
Transform transform,
122146
GridCallback callback,
123147
bool approx = Approximate,
124-
bool includeMap = IncludeMap) where T : IPhysShape
148+
bool includeMap = IncludeMap) where TShape : IPhysShape
125149
{
126150
if (TryGetMap(mapId, out var mapEnt))
127151
FindGridsIntersecting(mapEnt.Value, shape, transform, callback, approx: approx, includeMap: includeMap);
128152
}
129153

154+
/// <summary>
155+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
156+
/// Allows providing some additional <paramref name="state"/> to pass to the callback when it is invoked.
157+
/// </summary>
158+
/// <param name="shape">The shape of the region to check.</param>
159+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
160+
public void FindGridsIntersecting<TShape, TState>(
161+
MapId mapId,
162+
TShape shape,
163+
Transform transform,
164+
ref TState state,
165+
GridCallback<TState> callback,
166+
bool approx = Approximate,
167+
bool includeMap = IncludeMap) where TShape : IPhysShape
168+
{
169+
if (TryGetMap(mapId, out var mapEnt))
170+
FindGridsIntersecting(mapEnt.Value, shape, transform, ref state, callback, approx: approx, includeMap: includeMap);
171+
}
172+
173+
/// <summary>
174+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
175+
/// </summary>
130176
public void FindGridsIntersecting(
131177
MapId mapId,
132178
Box2 worldAABB,
@@ -138,6 +184,10 @@ public void FindGridsIntersecting(
138184
FindGridsIntersecting(mapEnt.Value, worldAABB, callback, approx: approx, includeMap: includeMap);
139185
}
140186

187+
/// <summary>
188+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
189+
/// Allows providing some additional <paramref name="state"/> to pass to the callback when it is invoked.
190+
/// </summary>
141191
public void FindGridsIntersecting<TState>(
142192
MapId mapId,
143193
Box2 worldAABB,
@@ -150,6 +200,9 @@ public void FindGridsIntersecting<TState>(
150200
FindGridsIntersecting(map.Value, worldAABB, ref state, callback, approx: approx, includeMap: includeMap);
151201
}
152202

203+
/// <summary>
204+
/// Adds every grid on the specified map which intersects the given region to the provided collection.
205+
/// </summary>
153206
public void FindGridsIntersecting(
154207
MapId mapId,
155208
Box2 worldAABB,
@@ -161,6 +214,9 @@ public void FindGridsIntersecting(
161214
FindGridsIntersecting(map.Value, worldAABB, ref grids, approx: approx, includeMap: includeMap);
162215
}
163216

217+
/// <summary>
218+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
219+
/// </summary>
164220
public void FindGridsIntersecting(
165221
MapId mapId,
166222
Box2Rotated worldBounds,
@@ -172,6 +228,10 @@ public void FindGridsIntersecting(
172228
FindGridsIntersecting(mapEnt.Value, worldBounds, callback, approx: approx, includeMap: includeMap);
173229
}
174230

231+
/// <summary>
232+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
233+
/// Allows providing some additional <paramref name="state"/> to pass to the callback when it is invoked.
234+
/// </summary>
175235
public void FindGridsIntersecting<TState>(
176236
MapId mapId,
177237
Box2Rotated worldBounds,
@@ -184,6 +244,9 @@ public void FindGridsIntersecting<TState>(
184244
FindGridsIntersecting(mapEnt.Value, worldBounds, ref state, callback, approx: approx, includeMap: includeMap);
185245
}
186246

247+
/// <summary>
248+
/// Adds every grid on the specified map which intersects the given region to the provided collection.
249+
/// </summary>
187250
public void FindGridsIntersecting(
188251
MapId mapId,
189252
Box2Rotated worldBounds,
@@ -199,6 +262,11 @@ public void FindGridsIntersecting(
199262

200263
#region EntityUid
201264

265+
/// <summary>
266+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
267+
/// </summary>
268+
/// <param name="shape">The shape of the region to check.</param>
269+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
202270
public void FindGridsIntersecting<TShape>(
203271
EntityUid mapEnt,
204272
TShape shape,
@@ -210,6 +278,12 @@ public void FindGridsIntersecting<TShape>(
210278
FindGridsIntersecting(mapEnt, shape, shape.ComputeAABB(transform, 0), transform, callback, approx: approx, includeMap: includeMap);
211279
}
212280

281+
/// <summary>
282+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
283+
/// Allows providing some additional <paramref name="state"/> to pass to the callback when it is invoked.
284+
/// </summary>
285+
/// <param name="shape">The shape of the region to check.</param>
286+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
213287
public void FindGridsIntersecting<TShape, TState>(
214288
EntityUid mapEnt,
215289
TShape shape,
@@ -222,6 +296,27 @@ public void FindGridsIntersecting<TShape, TState>(
222296
FindGridsIntersecting(mapEnt, shape, shape.ComputeAABB(transform, 0), transform, ref state, callback, approx: approx, includeMap: includeMap);
223297
}
224298

299+
/// <summary>
300+
/// Adds every grid on the specified map which intersects the given region to the provided list.
301+
/// </summary>
302+
/// <param name="shape">The shape of the region to check.</param>
303+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
304+
public void FindGridsIntersecting<TShape>(
305+
EntityUid mapEnt,
306+
TShape shape,
307+
Transform transform,
308+
ref List<Entity<MapGridComponent>> grids,
309+
bool approx = Approximate,
310+
bool includeMap = IncludeMap) where TShape : IPhysShape
311+
{
312+
FindGridsIntersecting(mapEnt, shape, shape.ComputeAABB(transform, 0), transform, ref grids, approx: approx, includeMap: includeMap);
313+
}
314+
315+
/// <summary>
316+
/// Adds every grid on the specified map which intersects the given regions to the provided collection.
317+
/// </summary>
318+
/// <param name="shapes">A set of regions to check.</param>
319+
/// <param name="transform">The transform, relative to the map, of the regions to check.</param>
225320
public void FindGridsIntersecting(
226321
EntityUid mapEnt,
227322
List<IPhysShape> shapes,
@@ -236,17 +331,9 @@ public void FindGridsIntersecting(
236331
}
237332
}
238333

239-
public void FindGridsIntersecting<TShape>(
240-
EntityUid mapEnt,
241-
TShape shape,
242-
Transform transform,
243-
ref List<Entity<MapGridComponent>> grids,
244-
bool approx = Approximate,
245-
bool includeMap = IncludeMap) where TShape : IPhysShape
246-
{
247-
FindGridsIntersecting(mapEnt, shape, shape.ComputeAABB(transform, 0), transform, ref grids, approx: approx, includeMap: includeMap);
248-
}
249-
334+
/// <summary>
335+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
336+
/// </summary>
250337
public void FindGridsIntersecting(
251338
EntityUid mapEnt,
252339
Box2 worldAABB,
@@ -258,6 +345,10 @@ public void FindGridsIntersecting(
258345
FindGridsIntersecting(mapEnt, shape, worldAABB, Robust.Shared.Physics.Transform.Empty, callback, approx: approx, includeMap: includeMap);
259346
}
260347

348+
/// <summary>
349+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
350+
/// Allows providing some additional <paramref name="state"/> to pass to the callback when it is invoked.
351+
/// </summary>
261352
public void FindGridsIntersecting<TState>(
262353
EntityUid mapEnt,
263354
Box2 worldAABB,
@@ -270,6 +361,9 @@ public void FindGridsIntersecting<TState>(
270361
FindGridsIntersecting(mapEnt, shape, worldAABB, Robust.Shared.Physics.Transform.Empty, ref state, callback, approx: approx, includeMap: includeMap);
271362
}
272363

364+
/// <summary>
365+
/// Adds every grid on the specified map which intersects the given regions to the provided list.
366+
/// </summary>
273367
public void FindGridsIntersecting(
274368
EntityUid mapEnt,
275369
Box2 worldAABB,
@@ -281,6 +375,9 @@ public void FindGridsIntersecting(
281375
FindGridsIntersecting(mapEnt, shape, worldAABB, Robust.Shared.Physics.Transform.Empty, ref grids, approx: approx, includeMap: includeMap);
282376
}
283377

378+
/// <summary>
379+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
380+
/// </summary>
284381
public void FindGridsIntersecting(
285382
EntityUid mapEnt,
286383
Box2Rotated worldBounds,
@@ -292,6 +389,10 @@ public void FindGridsIntersecting(
292389
FindGridsIntersecting(mapEnt, shape, Robust.Shared.Physics.Transform.Empty, callback, approx: approx, includeMap: includeMap);
293390
}
294391

392+
/// <summary>
393+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
394+
/// Allows providing some additional <paramref name="state"/> to pass to the callback when it is invoked.
395+
/// </summary>
295396
public void FindGridsIntersecting<TState>(
296397
EntityUid mapEnt,
297398
Box2Rotated worldBounds,
@@ -304,6 +405,9 @@ public void FindGridsIntersecting<TState>(
304405
FindGridsIntersecting(mapEnt, shape, Robust.Shared.Physics.Transform.Empty, ref state, callback, approx: approx, includeMap: includeMap);
305406
}
306407

408+
/// <summary>
409+
/// Adds every grid on the specified map which intersects the given regions to the provided list.
410+
/// </summary>
307411
public void FindGridsIntersecting(
308412
EntityUid mapEnt,
309413
Box2Rotated worldBounds,
@@ -317,6 +421,9 @@ public void FindGridsIntersecting(
317421

318422
#endregion
319423

424+
/// <summary>
425+
/// Enumerates all of the grids located on a given map.
426+
/// </summary>
320427
public IEnumerable<Entity<MapGridComponent>> GetAllGrids(MapId mapId)
321428
{
322429
var query = AllEntityQuery<MapGridComponent, TransformComponent>();
@@ -329,6 +436,11 @@ public IEnumerable<Entity<MapGridComponent>> GetAllGrids(MapId mapId)
329436
}
330437
}
331438

439+
/// <remarks>
440+
/// This version only provides the component without the uid and should not be used.
441+
/// </remarks>
442+
/// <inheritdoc cref="GetAllGrids(MapId)"/>
443+
[Obsolete("use GetAllGrids instead")]
332444
public IEnumerable<MapGridComponent> GetAllMapGrids(MapId mapId)
333445
{
334446
var query = AllEntityQuery<MapGridComponent, TransformComponent>();
@@ -339,6 +451,13 @@ public IEnumerable<MapGridComponent> GetAllMapGrids(MapId mapId)
339451
}
340452
}
341453

454+
/// <summary>
455+
/// Adds every grid on the specified map which intersects the given regions to the provided list.
456+
/// </summary>
457+
/// <param name="shape">The shape of the region to check.</param>
458+
/// <param name="worldAABB">The world-local axis aligned bounding box of the region to check.</param>
459+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
460+
[Access(typeof(IMapManager), Other = AccessPermissions.None)]
342461
public void FindGridsIntersecting<TShape>(
343462
EntityUid mapEnt,
344463
TShape shape,
@@ -359,6 +478,12 @@ public void FindGridsIntersecting<TShape>(
359478
);
360479
}
361480

481+
/// <summary>
482+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
483+
/// </summary>
484+
/// <param name="shape">The shape of the region to check.</param>
485+
/// <param name="worldAABB">The world-local axis aligned bounding box of the region to check.</param>
486+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
362487
private void FindGridsIntersecting<TShape>(
363488
EntityUid mapEnt,
364489
TShape shape,
@@ -375,6 +500,13 @@ private void FindGridsIntersecting<TShape>(
375500
);
376501
}
377502

503+
/// <summary>
504+
/// Invokes the provided callback on every grid on the specified map which intersect the given region.
505+
/// Allows providing some additional <paramref name="state"/> to pass to the callback when it is invoked.
506+
/// </summary>
507+
/// <param name="shape">The shape of the region to check.</param>
508+
/// <param name="worldAABB">The world-local axis aligned bounding box of the region to check.</param>
509+
/// <param name="transform">The transform, relative to the map, of the region to check.</param>
378510
private void FindGridsIntersecting<TShape, TState>(
379511
EntityUid mapEnt,
380512
TShape shape,
@@ -434,6 +566,9 @@ private void FindGridsIntersecting<TShape, TState>(
434566
state = gridState.State;
435567
}
436568

569+
/// <summary>
570+
/// Tests whether any of a collection of grid chunks intersect with a given region.
571+
/// </summary>
437572
private bool IsIntersecting<TShape>(
438573
ChunkEnumerator enumerator,
439574
TShape shape,

0 commit comments

Comments
 (0)