Repository navigation
Expand file tree
/
Copy pathIMapData.cs
More file actions
328 lines (290 loc) · 19 KB
/
Copy pathIMapData.cs
File metadata and controls
328 lines (290 loc) · 19 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
using SS.Core.Map;
using System;
using System.Collections.Generic;
using System.Collections.Immutable;
using System.IO;
using System.Threading.Tasks;
namespace SS.Core.ComponentInterfaces
{
/// <summary>
/// Info about an lvz file.
/// </summary>
public readonly struct LvzFileInfo
{
public readonly string Filename;
public readonly bool IsOptional;
public LvzFileInfo(string filename, bool isOptional)
{
ArgumentException.ThrowIfNullOrWhiteSpace(filename);
Filename = filename;
IsOptional = isOptional;
}
}
public interface IMapData : IComponentInterface
{
#region File Info
/// <summary>
/// Gets the path of a map file used by an arena.
/// </summary>
/// <remarks>
/// This function should be used rather than try to figure out the map filename yourself based on arena settings.
/// </remarks>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="mapname"><see langword="null"/> if you're looking for an lvl, or the name of an lvz file.</param>
/// <returns>The path if the lvl or lvz file could be found; otherwise, <see langword="null"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
Task<string?> GetMapFilenameAsync(Arena arena, string? mapname);
/// <summary>
/// Gets info about lvz files in use by an arena.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <returns>A collection of lvz file info.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
IAsyncEnumerable<LvzFileInfo> LvzFilenamesAsync(Arena arena);
#endregion
#region LVL Info
/// <summary>
/// Gets a named attribute of the map in an arena.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="key">The key of the attribute to retrieve.</param>
/// <returns>The value if found; otherwise, <see langword="null"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
string? GetAttribute(Arena arena, string key);
/// <summary>
/// Gets unprocessed chunk data of a specified type for a the map in an arena.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="chunkType">The type of data to retrieve.</param>
/// <returns>A collection of chunk payloads (chunk header not included).</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
IEnumerable<ReadOnlyMemory<byte>> ChunkData(Arena arena, uint chunkType);
/// <summary>
/// Gets the number of tiles on the map in an arena.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <returns>The # of tiles.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
int GetTileCount(Arena arena);
/// <summary>
/// Gets the number of turf (static) flags on the map in an arena.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <returns>The # of flags.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
int GetFlagCount(Arena arena);
/// <summary>
/// Gets non-fatal load error descriptions for the map in an arena.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <returns>A collection of error descriptions.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
IReadOnlyList<string> GetErrors(Arena arena);
/// <summary>
/// Get the map tiles checksum.
/// </summary>
/// <remarks>
/// <para>
/// Used by the Security module to validate clients.
/// Used by the Recording module to make sure the recording plays on the same map that is was recorded on.
/// </para>
/// <para>
/// For the CRC-32 checksum (Continuum only), use <see cref="TryGetCrc32(Arena, out uint)"/> instead.
/// </para>
/// </remarks>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="key">The key to calculate the checksum with.</param>
/// <returns></returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
uint GetChecksum(Arena arena, uint key);
/// <summary>
/// Gets the map tiles CRC-32 checksum. (Continuum only)
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="crc32">When this method returns, contains the CRC-32 checksum of the <paramref name="arena"/>'s map, if loaded; otherwise, 0.</param>
/// <returns><see langword="true"/> if the map is loaded; otherwise <see langword="false'"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
bool TryGetCrc32(Arena arena, out uint crc32);
#endregion
#region LVL Tile / Coordinates Methods
/// <summary>
/// Gets a single tile by coordinates.
/// </summary>
/// <remarks>
/// This does not include any temporarily placed tiles (bricks and dropped flags).
/// Use <see cref="GetTile(Arena, TileCoordinates, bool)"/> to access temporary tiles.
/// </remarks>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="coordinates">The coordinates to check.</param>
/// <returns>The tile. <see cref="MapTile.None"/> indicates no tile.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
MapTile GetTile(Arena arena, TileCoordinates coordinates);
/// <summary>
/// Gets a single tile by coordinates.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="coordinates">The coordinates to check.</param>
/// <param name="includeTemporaryTiles">Whether to include temporary tiles such as bricks and dropped flags.</param>
/// <returns>The tile. <see cref="MapTile.None"/> indicates no tile.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
MapTile GetTile(Arena arena, TileCoordinates coordinates, bool includeTemporaryTiles);
/// <summary>
/// Gets the coordinates of a static, turf-style flag.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="flagId">Id of the flag to get the coordinate of.</param>
/// <param name="coordinates">The coordinates of the flag.</param>
/// <returns><see langword="true"/> if the coordinate could be retrieved. Otherwise, <see langword="false"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
bool TryGetFlagCoordinates(Arena arena, short flagId, out TileCoordinates coordinates);
/// <summary>
/// Tries to find an empty tile nearest to the given coordinates.
/// </summary>
/// <param name="arena">The arena.</param>
/// <param name="x">The X-coordinate to start searching from. Upon return, the resulting X-coordinate if an empty spot was found.</param>
/// <param name="y">The Y-Coordinate to start searching from. Upon return, the resulting Y-coordinate if an empty spot was found.</param>
/// <returns>
/// True if a coordinate with no tile was found. Otherwise, false.
/// </returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
bool TryFindEmptyTileNear(Arena arena, ref short x, ref short y);
#endregion
#region LVL Regions
/// <summary>
/// Gets the number of regions on a map in an arena.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <returns>The # of regions.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
int GetRegionCount(Arena arena);
/// <summary>
/// Gets a region by name.
/// </summary>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="name">Name of the region to search for.</param>
/// <returns>The region if found; otherwise, <see langword="null"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
MapRegion? FindRegionByName(Arena arena, string name);
/// <summary>
/// Gets the regions at a specified pair of coordinates.
/// </summary>
/// <remarks>Similar to asss' Imapdata.EnumContaining, but without using a callback.</remarks>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="coordinates">The coordinates to check.</param>
/// <returns>A set of regions (empty if the coordinate is not in a region).</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
ImmutableHashSet<MapRegion> RegionsAt(Arena arena, TileCoordinates coordinates);
/// <summary>
/// To get the regions that are at a specific coordinate.
/// </summary>
/// <remarks>Similar to asss' Imapdata.EnumContaining, but without using a callback.</remarks>
/// <param name="arena">The arena to retrieve the map info for.</param>
/// <param name="x">X coordinate to check.</param>
/// <param name="y">Y coordinate to check.</param>
/// <returns>A set of regions (empty if the coordinate is not in a region).</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
ImmutableHashSet<MapRegion> RegionsAt(Arena arena, short x, short y);
#endregion
#region Temporary Tile Placement
/// <summary>
/// Adds temporarily placed map tile(s) for a brick.
/// </summary>
/// <param name="arena">The arena to add temporarily placed tile(s) to.</param>
/// <param name="brickId">The Id of the brick.</param>
/// <param name="start">The starting coordinates of the brick.</param>
/// <param name="end">The ending coordinates of the brick.</param>
/// <returns><see langword="true"/> if a change was made; otherwise, <see langword="false"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
bool TryAddBrick(Arena arena, int brickId, TileCoordinates start, TileCoordinates end);
/// <summary>
/// Removes temporarily placed map tile(s) for a brick.
/// </summary>
/// <param name="arena">The arena to remove the temporarily placed tiles from.</param>
/// <param name="brickId">The Id of the brick.</param>
/// <returns><see langword="true"/> if a change was made; otherwise, <see langword="false"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
bool TryRemoveBrick(Arena arena, int brickId);
/// <summary>
/// Adds a temporarily placed map tile for a carriable flag that was dropped on the map.
/// </summary>
/// <remarks>
/// If the flag is already on the map, it will be moved.
/// </remarks>
/// <param name="arena">The arena to add the temporarily placed tile to.</param>
/// <param name="flagId">The Id of the flag.</param>
/// <param name="coordinates">The coordinates the flag is being dropped at.</param>
/// <returns><see langword="true"/> if a change was made; otherwise, <see langword="false"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
bool TryAddDroppedFlag(Arena arena, short flagId, TileCoordinates coordinates);
/// <summary>
/// Removes a temporarily placed map tile for a carriable flag that was dropped on the map.
/// </summary>
/// <param name="arena">The arena to remove the temporarily placed tile from.</param>
/// <param name="flagId">The Id of the flag.</param>
/// <returns><see langword="true"/> if a change was made; otherwise, <see langword="false"/>.</returns>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
bool TryRemoveDroppedFlag(Arena arena, short flagId);
#endregion
#region Image Generation
/// <summary>
/// Saves an image of the map to a file.
/// </summary>
/// <param name="arena">The arena of the map to save.</param>
/// <param name="path">The path of the file. The image format is automatically determined based on the filename extension.</param>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentException">The <paramref name="path"/> is null or white-space.</exception>
/// <exception cref="ArgumentException">The <paramref name="path"/> file extension specifies an unsupported image format.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
/// <exception cref="Exception">Error encoding image.</exception>
void SaveImage(Arena arena, string path);
/// <summary>
/// Saves an image of the map to a file.
/// </summary>
/// <param name="arena">The arena of the map to save.</param>
/// <param name="stream">The stream to write the image data to.</param>
/// <param name="imageFormat">The format to save the image as. Supported formats: 'png', 'jpg', and 'webp'.</param>
/// <exception cref="ArgumentNullException"><paramref name="arena"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException"><paramref name="stream"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentException">Unsupported image format for the provided <paramref name="imageFormat"/>.</exception>
/// <exception cref="InvalidOperationException">The module is not loaded.</exception>
/// <exception cref="InvalidOperationException">The <paramref name="arena"/> data is not loaded.</exception>
/// <exception cref="Exception">Error encoding image.</exception>
void SaveImage(Arena arena, Stream stream, ReadOnlySpan<char> imageFormat);
#endregion
}
}