[FEATURE] Expose vehicle color metadata

[ifBars]

What would you like to see?

Add a read-only catalog for the game's native vehicle colors.

Each entry should expose the S1API vehicle color value, display name, material color, and UI color through managed metadata snapshots.

Why would this help?

Vehicle menus and customization tools need to display the same names and colors as the base game. Today they must access VehicleColors directly or duplicate the catalog.

Extra Context (Optional)

This should mirror ClothingMetadataCatalog. Arbitrary RGB colors, selection-UI patching, custom persistence, and new save representations should remain separate work.

[ifBars]

@Diffuin Create an implementation plan

[diffuin]

Implementation plan

Summary

Add an additive, read-only vehicle color metadata catalog backed by the native color library. It will expose immutable managed snapshots and leave color selection, UI patching, persistence, and networking unchanged.

Design decisions

1. Add S1API.Vehicles.VehicleColorMetadata and VehicleColorCatalog with Colors, GetColor(VehicleColor), and TryGetColor(VehicleColor, out VehicleColorMetadata?) as additive public API.
2. Copy fields from native colorLibrary into immutable managed snapshots. Preserve the native Color material value and Color32 UI value; keep native library order and omit Custom when it has no native entry.
3. Read the typed VehicleColors singleton only after InstanceExists succeeds. Do not cache native objects, reconstruct missing colors, or use reflection or name-based fallback.

Implementation

1. Define the public contract — Add the managed metadata surface without changing existing vehicle APIs.
   • Create VehicleColorMetadata with read-only Color, DisplayName, MaterialColor, and UIColor properties plus XML documentation. (S1API/Vehicles/VehicleColorMetadata.cs)
   • Create VehicleColorCatalog with Colors, GetColor, and TryGetColor, documenting empty/null behavior before the native singleton is ready. (S1API/Vehicles/VehicleColorCatalog.cs)
2. Bridge the native catalog — Convert native entries into managed snapshots across both build targets.
   • Add conditional Mono and IL2CPP aliases and an internal provider that checks VehicleColors singleton readiness before reading colorLibrary. (S1API/Vehicles/VehicleColorCatalog.cs)
   • Build a fresh read-only snapshot in native library order, validate requested enum values, and return false for unknown or absent values such as Custom. (S1API/Vehicles/VehicleColorCatalog.cs)
3. Freeze the contract and document it — Cover observable catalog behavior without a game runtime dependency.
   • Add a non-parallel test collection and fake provider for the catalog's static test seam. (S1API.Tests/Vehicles/VehicleColorCatalogCollection.cs, S1API.Tests/Vehicles/VehicleColorCatalogTests.cs)
   • Test lookup fields, ordered immutable snapshots, unavailable runtime behavior, invalid values avoiding the provider, and read-only metadata properties. (S1API.Tests/Vehicles/VehicleColorCatalogTests.cs)
   • List the new catalog in the vehicle module overview and state that it exposes native metadata only. (S1API/docs/modules-overview.md)
4. Verify compatibility and runtime integration — Confirm the direct bridge compiles and behaves consistently without expanding feature scope.
   • Run restore, build, and the full contract suite separately for MonoMelon and Il2CppMelon. (S1API.sln, S1API.Tests/S1API.Tests.csproj)
   • Record an additive compatibility audit: new public symbols only, no changed durable IDs, persistence, saves, or network payloads.
   • Manually validate on alternate Mono and regular IL2CPP after the main scene loads: compare all native menu names and colors, verify Custom is absent, and confirm early access returns empty/null without errors.

Implementation gates

• Before implementation, verify that the current IL2CPP generated wrapper exposes VehicleColors.colorLibrary and its entry fields with the expected typed surface. If it does not, stop for a compatibility decision rather than adding reflection.

Evidence and validation

Evidence inspected

• Issue [FEATURE] Expose vehicle color metadata #241 requires native display, material, and UI colors while explicitly excluding arbitrary RGB values, UI patches, persistence, and save representations.
• Both stripped Mono branches declare VehicleColors as a singleton with colorLibrary entries containing EVehicleColor, colorName, MaterialColor, and UIColor; S1API.VehicleColor has the same enum order.
• The retained Main scene serializes 16 library entries from Black through Dark Green. It contains no Custom entry, although VehicleColor.Custom exists.
• ClothingMetadataCatalog already defines the repository pattern: read-only per-access snapshots, null/empty results before readiness, enum validation, and an internal provider fake for contract tests.

Validation performed

• Read issue [FEATURE] Expose vehicle color metadata #241 and its comments through the read-only GitHub broker.
• Inspected current vehicle and clothing catalog code, tests, documentation, coding standards, and repository cleanliness.
• Inspected regular and beta stripped-source signatures for VehicleColors and EVehicleColor.
• Inspected retained AssetRipper scene metadata for the serialized native color library. No game assets or source will be committed or redistributed by this worktree inspection.

Runtime validation remaining

• No MonoMelon or Il2CppMelon restore, build, or test command was run because this is a read-only plan.
• Human runtime validation is required on alternate Mono and regular IL2CPP; Mono source cannot prove generated IL2CPP wrapper shape or runtime behavior.
• No in-game UI, multiplayer, save/load, or end-to-end validation was performed. The planned catalog has no mutable, persisted, or synchronized state, but this must be confirmed during integration testing.

• Create a pull request to implement this plan and close this issue when merged.

Diffuin run details

• Provider: codex
• Model: gpt-5.6-terra
• Reasoning: high (Luna advisor: complexity (high); baseline source-backed technical request)
• Elapsed: 264s
• Codex thread: 019ffd99-2592-7bf0-ab18-3694e336c020

---

AI notice: Generated with AI assistance and not guaranteed accurate. Verify findings and plans against the current source and runtime.

[diffuin]

I opened #268