A C# file unpacking library for World of Warships Replays, inspired by Monstrofil's replays_unpack.
The library supports only World of Warships replays starting with version 0.10.10. Trying to use an older replay can result in unexpected errors when processing the replay.
Install NuGet
Then, install from the package manager console:
PM> Install-Package Nodsoft.WowsReplaysUnpack
Or from the .NET CLI as:
dotnet add package Nodsoft.WowsReplaysUnpack
Add the service to an IServiceCollection
services.AddWowsReplayUnpacker();Get the factory, get the unpacker from the factory and call the Unpack method with either a Stream or byte[]
ReplayUnpackerFactory replayUnpackerFactory = serviceProvider.GetService<IReplayUnpackerFactory>();
UnpackedReplay unpackedReplay = replayUnpackerFactory
.GetUnpacker()
.Unpack(File.OpenRead("my-replay.wowsreplay"));You can provide custom implementations of certain services.
services.Snippet.AddWowsReplayUnpacker(builder =>
{
builder.AddReplayController<MyCustomReplayController, MyCustomReplay>();
builder.WithReplayDataParser<MyCustomReplayDataParser>();
builder.WithDefinitionLoader<MyCustomDefinitionLoader>();
builder.WithDefinitionStore<MyCustomDefinitionStore>();
})Responsible for managing, giving access and caching the .def files (used for type and property mapping).
Uses the IDefinitionLoader for resolving non-cached files once.
Your custom definition store has to implement IDefinitionStore or extend DefaultDefinitionStore
Responsible for loading the actual definition files.
Your custom definition store has to implement IDefinitionLoader.
The default loader is the AssemblyDefinitionLoader.
You can optionally use the FileSystemDefinitionLoader
by installing the Nodsoft.WowsReplaysUnpack.FileStore nuget package.
Responsible for parsing the binary packets to the specific network packets.
Your custom replay data parser has to implement IReplayDataParser or extend DefaultReplayParser
Responsible for handling parsed network packets and filling the UnpackedReplay with information.
Your custom replay controller has to implement IReplayController<T> but it is strongly suggested
to use ReplayControllerBase<T> where T is your custom replay class.
Only one controller can be registered for any replay type.
An example of this is the ExtendedDataController.
To use your custom controller add the replay type to the GetUnpacker() method.
UnpackedReplay unpackedReplay = replayUnpackerFactory
.GetUnpacker<MyCustomReplay>()
.Unpack(File.OpenRead("my-replay.wowsreplay"));CVE Check Only Implementation
In the library you get a custom implementation ready to use for when you only want to check the CVE .
CveCheckOnlyController
It skips all network packets except the affected ones.
You can add it with the AddCveCheckController() method and get the unpacker with GetCveCheckUnpacker()
Extend the replay data
When implementing your own controller and extending ReplayControllerBase<T>;
The replay class has to extend UnpackedReplay.
That way you can add extra properties.
You can see this in action here
When implementing your own controller and extending ReplayControllerBase<T> you can subscribe to EntityMethods and EntityProperty calls by adding a method with an attribute.
You will have to install the Nodsoft.WowsReplaysUnpack.Generators nuget package and add the [ReplayController] attribute to your controller class.
This will generate the required logic to make the dynamic subscriptions work.
MethodSubscription("EntityName", "MethodName")
You have a few extra properties on the attribute to configure how the method will be called:
bool IncludeEntity => When true it will include the Entity entity parameter
bool IncludePacketTime => When true it will include the float packetTime parameter
bool ParamsAsDictionary => When true the last paremeter will be Dictionary<string, object?> arguments / When false the parameters have to match the actual packet parameters in order and type exactly. When they don't match you will get an exception telling you the required parameters.
bool Priority => Defines the order in which methods are called when you have multiple subscriptions on the same method. Smaller = Earlier. Don't use -1.
Example:
[MethodSubscription("Avatar", "onArenaStateReceived")]
public void OnArenaStateReceived(Entity entity, float packetTime, ...)
{
}PropertySubscription("EntityName", "PropertyName")
There are no extra properties available and the Entity entity parameter is always there.
Example:
[PropertySubscription("Avatar", "selectedWeapon")]
public void SelectedWeaponChanged(Entity entity, uint selectedWeaponId)
{
}You can install the Nodsoft.WowsReplaysUnpack.ExtendedData package from nuget to get a ready to use implementation that fills the replay with more information than the default controller.
Currently included in the ExtendedDataReplay:
- Player Information
- Chat Messages
services.AddWowsReplayUnpacker(builder =>
{
builder.AddExtendedData();
});
ExtendedDataReplay unpackedReplay = replayUnpackerFactory
.GetExtendedDataUnpacker()
.Unpack(File.OpenRead("my-replay.wowsreplay"));The replay contains a multitude of other entities. If you want to retreive those you have two convenient options we provide.
// Step 1 - Retreive the entity properties you're interested in
var battleLogicProperties = replay.Entities.Single(e => e.Value.Name == "BattleLogic").Value.Properties;
// Step 2 - Use extension methods to cast the properties to their actual type
battleLogicProperties.GetAsDict("propertyName");
battleLogicProperties.GetAsArr("propertyName");
battleLogicProperties.GetAsValue<short>("propertyName");An example of this can be seen here in the ManualExtensions method.
Requires the Nodsoft.WowsReplaysUnpack.Generators nuget package.
// Step 1 - Create a class representing the entity annotated with the SerializableEntity attribute
[SerializableEntity]
public class BattleLogic {
[DataMember(Name = "state")]
public State State { get; set; } = null!;
...
}
// Step 2 - Use extension method on the replay to deserialize the entity
var battleLogic = replay.DeserializeEntity<BattleLogic>("BattleLogic");For collections only List<T> is currently supported.
The property mapping is case-sensitive. So you either have to name your properties exactly like they are in the entities properties dictionary or use the DataMember attribute.
An example of this can be seen here in the Serializer method.