Merge pull request #118 from BigBang1112/dev

GBX.NET 2.0.6

.github/workflows/publish.yml

@@ -60,7 +60,17 @@ jobs:
 
     strategy:
       matrix:
-        lib: [GBX.NET, GBX.NET.Hashing, GBX.NET.Imaging, GBX.NET.Imaging.SkiaSharp, GBX.NET.LZO, GBX.NET.ZLib, GBX.NET.NewtonsoftJson]
+        lib:
+        - GBX.NET
+        - GBX.NET.Hashing
+        - GBX.NET.Imaging
+        - GBX.NET.Imaging.SkiaSharp
+        - GBX.NET.Imaging.ImageSharp
+        - GBX.NET.LZO
+        - GBX.NET.ZLib
+        - GBX.NET.NewtonsoftJson
+        - GBX.NET.Tool
+        - GBX.NET.Tool.CLI
 
     name: Publish ${{ matrix.lib }}
     runs-on: ubuntu-latest

Benchmarks/GBX.NET.Benchmarks/MapParseBenchmarks.cs

@@ -11,7 +11,7 @@ public class MapParseBenchmarks
 
     public MapParseBenchmarks()
     {
-        Gbx.LZO = new MiniLZO();
+        Gbx.LZO = new Lzo();
         stream = new MemoryStream(File.ReadAllBytes(Path.Combine("Gbx", "CGameCtnChallenge", "GBX-NET 2 CGameCtnChallenge TMU 001.Challenge.Gbx")));
     }
 

Generators/GBX.NET.Generators/ChunkL/ChunkLPropertiesWriter.cs

@@ -263,11 +263,11 @@ private void AppendPropertiesRecursive(IEnumerable<IChunkMember> members, HashSe
 
                 sb.Append(" Get");
                 sb.Append(propName);
-                sb.Append("(GbxReadSettings settings = default) => ");
+                sb.Append("(GbxReadSettings settings = default, bool exceptions = false) => ");
                 sb.Append(fieldName);
                 sb.Append("File?.GetNode(ref ");
                 sb.Append(fieldName);
-                sb.Append(", settings) ?? ");
+                sb.Append(", settings, exceptions) ?? ");
                 sb.Append(fieldName);
                 sb.AppendLine(";");
             }

Generators/GBX.NET.Generators/ChunkL/MemberSerializationWriter.cs

@@ -359,6 +359,11 @@ private void AppendWrite(int indent, ChunkProperty chunkProperty)
             sb.Append("Array");
         }
 
+        if (chunkProperty.Type.PrimaryType == "data")
+        {
+            sb.Append("Data");
+        }
+
         var mappedType = MapType(chunkProperty.Type.PrimaryType, out var noMatch);
 
         if (noMatch)

README.md

@@ -29,6 +29,7 @@ For any questions, open an issue, join the [GameBox Sandbox Discord server](http
   - [Modify and save a map](#modify-and-save-a-map)
   - [Processing multiple Gbx types](#processing-multiple-gbx-types)
   - [Read a large amount of replay metadata quickly](#read-a-large-amount-of-replay-metadata-quickly)
+- [Tool framework](#tool-framework)
 - [Clarity](#clarity)
   - [Differences between `Gbx.Parse/Header/Node`](#differences-between-gbxparseheadernode)
   - [Do not repeat `gbx.Node.[any]` too often!](#do-not-repeat-gbxnodeany-too-often)
@@ -172,7 +173,7 @@ C# code:
 using GBX.NET;
 using GBX.NET.LZO;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 ```
 
 You should run this line of code **only once** for the whole program lifetime.
@@ -194,7 +195,7 @@ using GBX.NET;
 using GBX.NET.Engines.Game;
 using GBX.NET.LZO;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 
 var map = Gbx.ParseNode<CGameCtnChallenge>("Path/To/My.Map.Gbx");
 
@@ -221,7 +222,7 @@ using GBX.NET;
 using GBX.NET.Engines.Game;
 using GBX.NET.LZO;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 
 var gbx = Gbx.Parse<CGameCtnChallenge>("Path/To/My.Map.Gbx");
 var map = gbx.Node; // See Clarity section for more info
@@ -269,7 +270,7 @@ using GBX.NET;
 using GBX.NET.Engines.Game;
 using GBX.NET.LZO;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 
 var node = Gbx.ParseNode("Path/To/My.Gbx");
 
@@ -336,6 +337,42 @@ This code should only crash in case of a file system problem. Other problems wil
 > [!NOTE]
 > It is still valuable to parse the full Gbx even when you just want a piece of information available in header, because **body info overwrites header info**. So you can use the benefit of full parse to fool people tackling with the Gbx header.
 
+## Tool framework
+
+Tool framework (`GBX.NET.Tool*` libraries) is a simple way to create rich tools that can be adapted to different environments.
+
+Currently supported environments:
+- **Console** (`GBX.NET.Tool.CLI`)
+
+Planned environments:
+- Blazor (`GBX.NET.Tool.Blazor`) - both server and WebAssembly
+- HTTP server (`GBX.NET.Tool.Server`)
+- Discord bot (`GBX.NET.Tool.Discord.Bot`)
+
+The tool framework guides you with this project structure:
+
+```mermaid
+graph LR
+    A(GBX.NET.Tool) --> B(YourToolProject)
+    C(GBX.NET.Tool.CLI) --> D(YourToolProjectCLI)
+    B --> D
+    A --> C
+    E(GBX.NET) --> A
+    F(GBX.NET.LZO) --> C
+    E --> F
+    G(Spectre.Console) --> C
+```
+
+- Structure: Tool library (`YourToolProject`) and at least 1 implementation application of it (`YourToolProjectCLI`).
+- Tool library references `GBX.NET.Tool` and implementation application references `GBX.NET.Tool.CLI`.
+- `GBX.NET.Tool.CLI` currently uses LZO by default, no need to reference it additionally.
+
+Tool library has a primary tool class that implements `ITool` interface. There should be only one.
+
+Tool class accepts input through constructors (best one is picked according to input provided by implementation). The tool can output as "produce" (`IProductive`), which creates objects without mutating the input (for example, create MediaTracker clip from replay inputs), or "mutate" (`IMutative`) which creates objects while also causing changes to the input (for example, modifying a map without having to recreate it again).
+
+Samples are available [here](Samples/Tool/).
+
 ## Clarity
 
 This section describes best practices to keep your projects clean when using GBX.NET 2.
@@ -436,6 +473,22 @@ GBX.NET is a huge library when everything is included (over 1.5MB), so please us
 > [!NOTE]
 > Expect this to work only with `dotnet publish`.
 
+However, in case you wanna use reflection on GBX.NET, it is strongly recommended to simply turn off trimming of this library. **In case of Blazor WebAssembly specifically, it's worth noting that the release build trims automatically**, so in case you're using reflection, modify your library reference:
+
+```xml
+<PackageReference Include="GBX.NET">
+    <IsTrimmable>false</IsTrimmable> <!-- add this line -->
+</PackageReference>
+```
+
+In case this is not enough, you can specify `TrimmerRootAssembly` on the project you're building that this library should absolutely not be trimmed:
+
+```xml
+<ItemGroup>
+    <TrimmerRootAssembly Include="GBX.NET" />
+</ItemGroup>
+```
+
 ### Explicit vs. Implicit parse
 
 *In the past, the difference between these two used to be only to reduce the amount of written code by the consumer and making the type more strict, the performance was exactly the same.*
@@ -528,7 +581,7 @@ Make sure you have these framework SDKs available:
 
 **Visual Studio 2022** should be able to install those with default installation settings. Using Visual Studio 2019 will likely not work.
 
-You should also have **.NET WebAssembly Build Tools** installed additionally to build the full solution. It may not be required, but it will definitely help figuring out some problems.
+You should also have **.NET WebAssembly Build Tools** installed additionally to build the full solution. It is required for Gbx Explorer to work properly, as it uses native LZO implementation compiled into WebAssembly.
 
 In Visual Studio, you can just use Build Solution and everything should build. JetBrains Rider has been tested and also works.
 

SUPPORTED_GBX_FILE_TYPES.md

@@ -37,5 +37,6 @@ Older extensions | Latest extension | Class | Read (whole) | Write | Read (heade
 | | Material.Gbx | [CPlugMaterial](Src/GBX.NET/Engines/Plug/CPlugMaterial.cs) | Up to TM2 | No
 | | Texture.Gbx | [CPlugBitmap](Src/GBX.NET/Engines/Plug/CPlugBitmap.cs) | Up to TMUF | No
 | | Light.Gbx | [CPlugLight](Src/GBX.NET/Engines/Plug/CPlugLight.cs) | Yes | Yes
+| | Prefab.Gbx | [CPlugPrefab](Src/GBX.NET/Engines/Plug/CPlugPrefab.cs) | Yes | Yes
 
 - <sup>1</sup>Safety reasons. Consider extracting `CGameCtnGhost` from `CGameCtnReplayRecord`, transfer it over to `CGameCtnMediaBlockGhost`, add it to `CGameCtnMediaClip`, and save it as `.Clip.Gbx`, which you can then import in MediaTracker.

Samples/Advanced/Blik/Program.cs

@@ -4,7 +4,7 @@
 using GBX.NET.LZO;
 using GBX.NET.ZLib;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 Gbx.ZLib = new ZLib();
 
 var gbxMap = Gbx.Parse<CGameCtnChallenge>(args[0]);

Samples/Advanced/ItemPacker/Program.cs

@@ -4,7 +4,7 @@
 using GBX.NET.LZO;
 using Microsoft.Extensions.Logging;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 
 var logger = LoggerFactory.Create(builder =>
 {

Samples/Beginner/EnvimixForTM2020/Program.cs

@@ -5,7 +5,7 @@
 using System.Text;
 using TmEssentials;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 Gbx.CRC32 = new CRC32();
 
 var cars = new[] { "CarSport", "CarSnow", "CarRally", "CarDesert", "CharacterPilot" };

Samples/Beginner/FixDesertUpdatePillarsAfterConversion/Program.cs

@@ -2,7 +2,7 @@
 using GBX.NET.Engines.Game;
 using GBX.NET.LZO;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 
 var gbxMap = Gbx.Parse<CGameCtnChallenge>(args[0]);
 

Samples/Beginner/FullMapInfo/Program.cs

@@ -11,7 +11,7 @@
 
 var watch = Stopwatch.StartNew();
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 var map = Gbx.ParseNode<CGameCtnChallenge>(args[0]);
 
 watch.Stop();

Samples/Beginner/Legomania/Program.cs

@@ -8,7 +8,7 @@
     return;
 }
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 
 var map = Gbx.ParseNode<CGameCtnChallenge>(args[0]);
 

Samples/Beginner/SolidExtract/Program.cs

@@ -3,7 +3,7 @@
 using GBX.NET.Engines.Plug;
 using GBX.NET.LZO;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 
 foreach (var filePath in args)
 {

Samples/Tool/GhostExtract/GhostExtractTool.cs

@@ -7,19 +7,22 @@ namespace GhostExtract;
 
 public class GhostExtractTool : ITool, IProductive<IEnumerable<Gbx<CGameCtnGhost>>>
 {
+    private readonly Gbx gbx;
     private readonly string? fileName;
     private readonly IEnumerable<CGameCtnGhost> ghosts;
     private readonly ILogger logger;
 
     public GhostExtractTool(Gbx<CGameCtnReplayRecord> gbxReplay, ILogger logger)
     {
+        gbx = gbxReplay;
         fileName = Path.GetFileName(gbxReplay.FilePath);
         ghosts = gbxReplay.Node.GetGhosts();
         this.logger = logger;
     }
 
     public GhostExtractTool(Gbx<CGameCtnMediaClip> gbxClip, ILogger logger)
     {
+        gbx = gbxClip;
         fileName = Path.GetFileName(gbxClip.FilePath);
         ghosts = gbxClip.Node.GetGhosts();
         this.logger = logger;
@@ -31,11 +34,13 @@ public IEnumerable<Gbx<CGameCtnGhost>> Produce()
         {
             logger.LogInformation("Extracting ghost {GhostIndex} from {FileName}...", i + 1, fileName);
 
-            return new Gbx<CGameCtnGhost>(ghost)
+            return new Gbx<CGameCtnGhost>(ghost, gbx.Header.Basic)
             {
                 FilePath = ghost.CanBeGameVersion(GameVersion.MP3)
-                    ? Path.Combine("Replays", "GbxTools", "GhostExtract", $"{GbxPath.GetFileNameWithoutExtension(fileName ?? "Ghost")}_{i + 1:00}.Gbx.Gbx")
-                    : Path.Combine("Tracks", "Replays", "GbxTools", "GhostExtract", $"{GbxPath.GetFileNameWithoutExtension(fileName ?? "Ghost")}_{i + 1:00}.Gbx")
+                    ? Path.Combine("Replays", "GbxTools", "GhostExtract", $"{GbxPath.GetFileNameWithoutExtension(fileName ?? "Ghost")}_{i + 1:00}.Ghost.Gbx")
+                    : Path.Combine("Tracks", "Replays", "GbxTools", "GhostExtract", $"{GbxPath.GetFileNameWithoutExtension(fileName ?? "Ghost")}_{i + 1:00}.Ghost.Gbx"),
+                ClassIdRemapMode = gbx.ClassIdRemapMode,
+                PackDescVersion = gbx.PackDescVersion,
             };
         });
     }

Samples/Tool/InputExtract/InputExtractConfig.cs

@@ -0,0 +1,8 @@
+using GBX.NET.Tool;
+
+namespace InputExtract;
+
+public class InputExtractConfig : Config
+{
+    public string Format { get; set; } = "test";
+}

Samples/Tool/InputExtract/InputExtractTool.cs

@@ -3,8 +3,10 @@
 
 namespace InputExtract;
 
-public class InputExtractTool : ITool
+public class InputExtractTool : ITool, IConfigurable<InputExtractConfig>
 {
+    public InputExtractConfig Config { get; } = new();
+
     public InputExtractTool(CGameCtnReplayRecord replay)
     {
 

Samples/Tool/InputExtractCLI/InputExtractCLI.csproj

@@ -9,6 +9,7 @@
 
     <ItemGroup>
         <ProjectReference Include="..\..\..\Src\GBX.NET.Tool.CLI\GBX.NET.Tool.CLI.csproj" />
+        <ProjectReference Include="..\InputExtract\InputExtract.csproj" />
     </ItemGroup>
 
 </Project>

Samples/Tool/InputExtractCLI/Program.cs

@@ -1,2 +1,4 @@
-// See https://aka.ms/new-console-template for more information
-Console.WriteLine("Hello, World!");
+using GBX.NET.Tool.CLI;
+using InputExtract;
+
+await ToolConsole<InputExtractTool>.RunAsync(args);

Src/GBX.NET.Hashing/README.md

@@ -17,7 +17,7 @@ using GBX.NET.Engines.Game;
 using GBX.NET.LZO;
 using GBX.NET.Hashing;
 
-Gbx.LZO = new MiniLZO();
+Gbx.LZO = new Lzo();
 Gbx.CRC32 = new CRC32(); // You need to add this
 
 var map = Gbx.ParseNode<CGameCtnChallenge>("Path/To/My.Map.Gbx");