[#151] Add --entry to dump and serialized-file to read a SerializedFile inside an archive - #152

Summary

Fixes #151.

An archive (AssetBundle, Player data.unity3d, Content Directory content0.archive) often holds several SerializedFiles. Until now dump could only write all of them to files, or use --stdout if the archive had exactly one, and serialized-file refused archives entirely, so reaching one SerializedFile meant running archive extract first. Scripts that wanted to avoid that cost ended up mounting archives themselves through UnityFileSystemApi.

This adds -e / --entry <name> to dump and to every serialized-file subcommand. UnityDataTool mounts the archive, reads the named SerializedFile in place, and unmounts it. Nothing is extracted to disk.

UnityDataTool dump scenes.bundle -e BuildPlayer-SampleScene.sharedAssets --stdout
UnityDataTool sf objectlist content0.archive -e CAB-<hash> -f Json

The name is what archive list shows. It is also the serialized_file column of object_view, so an agent can go straight from a query result to a dump.

Changes

• New UnityBinaryFormat/MountedSerializedFile helper: mounts the archive and selects the SerializedFile. On failure it throws SerializedFileSelectionException, which says what failed and lists the SerializedFiles. Program.cs turns that into the --entry error messages, so the CLI wording stays out of UnityBinaryFormat. Both commands follow the same rules:
  • With --entry: that SerializedFile is used. An unknown name or a non-SerializedFile entry (e.g. .resS) is an error that lists the SerializedFiles in the archive.
  • Without --entry: if the archive has exactly one SerializedFile, it is used. This was already how dump --stdout worked, and it now applies to serialized-file too. If there are several, the error lists them and shows the --entry syntax.
  • --entry on a file that is not an archive is an error.
• serialized-file: reads through a Stream, either a FileStream or a buffered UnityFileStream on the mounted entry, using the existing Stream overloads of SerializedFileDetector. It no longer rejects archives.
• dump: --entry, or --stdout on an archive, dumps one SerializedFile. dump <archive> without either still dumps every SerializedFile to its own .txt.
• Docs: command-dump.md, command-serialized-file.md (the "SerializedFile vs Archive" section, which said to extract first, is replaced), agent-guide.md (the dump example now passes -e <serialized_file>, so it works for multi-file bundles), assetbundle-format.md.

Testing

• dotnet test: full suite green.
• New tests in SerializedFileCommandTests and DumpTests cover:
  • --entry selection, both to stdout and to a file.
  • A single-SerializedFile archive used without --entry, including a legacy bundle and a bundle without TypeTrees.
  • The errors: multiple SerializedFiles without --entry, an unknown entry, a non-SerializedFile entry, and --entry on a plain file.
• Two old tests that expected serialized-file to refuse archives were removed. The existing dump --stdout multi-file test was updated for the new message.
• Checked by hand against the 2022.1 scenes and assetbundle test bundles.