nikolaygekht/ballistic.calculator.app.avalonia / .claude/skills/ballistic-calculator
ballistic-calculator
VerifiedUse whenever writing, reviewing, or debugging .NET/C# code that uses the BallisticCalculator NuGet package (namespace BallisticCalculator) or its Gehtsoft.Measurements unit types — even when the user doesn't name the package explicitly but is clearly doing external/interior ballistics in .NET (bullet drop, velocity, energy, windage, spin drift, time of flight, zeroing a scope) for rifles, air rifles, bows, or artillery. Covers the full public API (Ammunition, Rifle, Atmosphere, Wind, ShotParameters, TrajectoryCalculator, TrajectoryPoint); standard, custom, .drg, and multi-BC drag tables; saving/loading data and building your own file format around it (BXml and System.Text.Json serialization); and building or rendering scope reticles (e.g. to SVG). Also use it for this library's Gehtsoft.Measurements Measurement<T> unit types (DistanceUnit, VelocityUnit, AngularUnit, WeightUnit, PressureUnit, …). Skip for: generic physics or projectile-motion exercises, a different ballistics library (e.g. GNU/JBM), game-engine or Unity projectile motion, plain unit conversions, and non-code ballistics questions (load-data or forensics advice). Self-contained: no access to the library source or binaries is required — prefer this over scanning the package to rediscover the API. Describes 1.1.13+, including the named ZeroRangeCantBeReachedException / TrajectoryCannotBeCalculatedException failures.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.8 KB |
| references/custom-drag.md | markdown | 3.8 KB |
| references/reticle.md | markdown | 6.5 KB |
| references/serialization.md | markdown | 7.8 KB |
references/serialization.md
View on GitHub# Serialization & persistence
Save/load the library's data objects (`Ammunition`, `Rifle`, `Atmosphere`, `AmmunitionLibraryEntry`,
`ReticleDefinition`, …) and — importantly — **build your own file format around them**: embed library
objects inside your own XML document, or decorate your own classes so they serialize with the same
machinery. Two independent mechanisms are available:
- **BXml** — the library's own compact XML serializer (namespace `BallisticCalculator.Serialization`).
- **System.Text.Json** — the same data classes are also JSON-annotated and round-trip through
`System.Text.Json.JsonSerializer` directly.
```csharp
using BallisticCalculator;
using BallisticCalculator.Serialization;
```
## 1. BXml — quick save / load
The easiest entry points are extension methods (`BallisticXmlExtensions`) plus static helpers.
```csharp
var ammo = new Ammunition(
weight: new Measurement<WeightUnit>(168, WeightUnit.Grain),
ballisticCoefficient: new BallisticCoefficient(0.223, DragTableId.G7),
muzzleVelocity: new Measurement<VelocityUnit>(2750, VelocityUnit.FeetPerSecond));
// --- write ---
ammo.BallisticXmlSerialize(@"ammo.xml"); // to a file
using (var ms = new MemoryStream())
{
ammo.BallisticXmlSerialize(ms); // to a stream
string xml = Encoding.UTF8.GetString(ms.ToArray()); // -> string (no direct string helper)
}
// --- read ---
Ammunition a1 = BallisticXmlDeserializer.ReadFromFile<Ammunition>(@"ammo.xml");
using (var input = File.OpenRead(@"ammo.xml"))
Ammunition a2 = input.BallisticXmlDeserialize<Ammunition>(); // extension on Stream
```
Signatures:
- `void value.BallisticXmlSerialize(string fileName)` and `void value.BallisticXmlSerialize(Stream stream)` (extensions, `T : class`).
- `T stream.BallisticXmlDeserialize<T>()` (extension, `T : class`).
- Statics: `BallisticXmlSerializer.SerializeToFile<T>(T, string)`, `SerializeToStream<T>(T, Stream)`;
`BallisticXmlDeserializer.ReadFromFile<T>(string)`, `ReadFromStream<T>(Stream)` (all `T : class`).
- There is **no** built-in serialize-to-string; use a `MemoryStream` as above.
## 2. BXml — embedding in your own document (build your own format)
`BallisticXmlSerializer.Serialize` returns a **detached** `XmlElement` owned by a document you control,
and never appends it itself — so it drops cleanly into any parent element you choose. This is the
supported way to wrap library data in your own schema.
```csharp
var doc = new XmlDocument();
var root = doc.CreateElement("my-loadout");
doc.AppendChild(root);
root.SetAttribute("profile", "match-308");
var serializer = new BallisticXmlSerializer(doc); // reuse YOUR document
root.AppendChild(serializer.Serialize(ammo)); // place the element wherever you like
root.AppendChild(serializer.Serialize(rifle));
doc.Save(@"loadout.xml");
// read a child back out of your document:
var child = (XmlElement)root.SelectSingleNode("ammunition");
Ammunition back = new BallisticXmlDeserializer().Deserialize<Ammunition>(child);
```
Key members:
- `new BallisticXmlSerializer()` / `new BallisticXmlSerializer(XmlDocument document)`; `Document` property.
- `XmlElement Serialize(object value, string forceName = null)` — element is created in `Document`, not appended.
- `new BallisticXmlDeserializer()`; `T Deserialize<T>(XmlElement) where T : class`,
`object Deserialize(XmlElement)` (auto-detects type by element name),
`object Deserialize(XmlElement, Type)`, `object Deserialize(XmlElement, Type[] possibleTypes)`.
- `Deserialize<T>` returns `null` if the element's resolved type isn't `T`. The parameterless
`Deserialize(XmlElement)` auto-detects by scanning `[BXmlElement]` names in **loaded** assemblies —
so for your own custom types prefer the explicit `Deserialize<T>` / `Deserialize(element, type)`.
## 3. BXml — making your own class serializable
Decorate with four attributes. Values of supported primitive types (`Measurement<>`, enums, `double`,
`float`, `int`, `bool`, `string`, `DateTime`, `TimeSpan`, `BallisticCoefficient`, and their `Nullable<>`)
become **XML attributes**; richer members become child elements or collections.
| Attribute | Target | Purpose |
|---|---|---|
| `[BXmlElement("name")]` | class | **Required** on any serializable type; sets its element name. |
| `[BXmlProperty("name")]` | property | A value → XML attribute `name`. |
| `[BXmlProperty("n", Optional = true)]` | property | Null is allowed; otherwise null throws on read/write. |
| `[BXmlProperty(ChildElement = true)]` | property | Serialize as a nested element (target needs its own `[BXmlElement]`/`[BXmlSelect]`). |
| `[BXmlProperty(Name="items", Collection = true)]` | property | An `IEnumerable<T>` (with an `Add` method) of `[BXmlElement]` items, wrapped in `<items>`. `Name` required. |
| `[BXmlProperty("p", FlattenChild = true)]` | property | Inline the child's props as `p`-prefixed attributes (no nested element; not for children with collections). |
| `[BXmlConstructor]` | constructor | Constructor the deserializer calls; param names must match property names. Needed for immutable types. |
| `[BXmlSelect(typeof(A), typeof(B))]` | class/interface | Enumerate concrete subtypes for polymorphic child/collection members. |
If there is no `[BXmlConstructor]`, the deserializer uses the parameterless constructor + property
setters. Immutable library types (e.g. `Atmosphere`, whose properties are read-only) mark their
constructor `[BXmlConstructor]` instead.
```csharp
using BallisticCalculator.Serialization;
using Gehtsoft.Measurements;
[BXmlElement("my-load")]
public class MyLoad
{
[BXmlProperty("name")] public string Name { get; set; }
[BXmlProperty("charge", Optional = true)] public Measurement<WeightUnit>? Charge { get; set; }
[BXmlProperty(ChildElement = true)] public Ammunition Ammunition { get; set; }
[BXmlProperty(Name = "alternatives", Collection = true, Optional = true)]
public List<Ammunition> Alternatives { get; } = new();
public MyLoad() { } // used on read (no [BXmlConstructor] here)
}
```
The library's own classes are the reference examples: `AmmunitionLibraryEntry`
(`[BXmlElement("ammunition-library-entry")]`, attribute + optional + `ChildElement` props), `Rifle`
(`ChildElement` for `Sight`/`Rifling`/`Zero`), `Atmosphere` (`[BXmlConstructor]`), `ReticleDefinition`
(`Collection` + `FlattenChild`), `ReticleElement` (`[BXmlSelect]`).
## 4. System.Text.Json
The data classes carry `System.Text.Json.Serialization` attributes and round-trip through the standard
serializer with no special options:
```csharp
using System.Text.Json;
string json = JsonSerializer.Serialize(ammo);
Ammunition back = JsonSerializer.Deserialize<Ammunition>(json);
```
- Each type marks its deserialization constructor `[JsonConstructor]` (`Ammunition`, `Rifle`,
`Atmosphere`, `AmmunitionLibraryEntry`, `BallisticCoefficient`).
- Optional properties use `[JsonIgnore(Condition = WhenWritingNull)]`; computed members (e.g.
`Atmosphere.SoundVelocity`/`Density`) are `[JsonIgnore]`.
- `BallisticCoefficient` serializes as its single string form (e.g. `"0.223G7"`) and rebuilds via its
`(string)` constructor.
- `Measurement<T>` JSON behavior comes from the `Gehtsoft.Measurements` package (it serializes as its
text form); it round-trips with the standard serializer. If you need a guarantee for every field,
round-trip-test your specific object once.
## Runtime note
Even the **BXml** path reflects over the data classes' `System.Text.Json` attributes at runtime, so
`System.Text.Json` (v9.x) must be loadable. It normally is — the package pulls it in transitively via
`Gehtsoft.Measurements` — so a standard `dotnet add package BallisticCalculator` needs nothing extra.
Only if your build trims/excludes it (or you reference the DLLs directly without their NuGet
dependencies) will BXml throw `FileNotFoundException` for `System.Text.Json`; add the package to fix it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |