Integrate CultMath vectors into geometry

This commit is contained in:
Meta Vens 2026-07-22 02:58:42 +01:00
commit 364c9cdf48
4 changed files with 211 additions and 5 deletions

View file

@ -110,6 +110,26 @@ a broader stage gate.
available on the library's `netstandard2.1` target. It was removed rather
than papered over; structural managed-reference inspection is the owning
eligibility rule.
- CultMath candidate `0.1.0-geometry-migration.1` was packed from commit
`cb481b4c75444426a693781a0e5b35ade08a8938` with build servers disabled. The
123,307-byte package SHA-256 is
`07C0CE79453AF9BA29910809F8779916E7B8F92DCA7ACEB5E2B8F9D3EBED3E93`;
a local-feed consumer restored, compiled, and executed `CultMath.float3`.
- GameCult.Geometry consumes that candidate as an explicit NuGet dependency;
its sibling `.tools/local-feed` is only an optional restore source, not a
project-reference authority. Geometry owns strict positional formatters for
`float2`, `float3`, `float4`, and `quaternion`.
- `dotnet test tests/GameCult.Geometry.Tests/GameCult.Geometry.Tests.csproj
--no-restore --filter FullyQualifiedName~CultMathValueIntegrationTests
--verbosity minimal --disable-build-servers -p:UseSharedCompilation=false
-m:1`
passed 6/6. Evidence covers exact bytes, round trips, malformed-width
rejection, actual `Column<float2>`/`Column<float3>` access, and absence of
synthetic component columns.
- GameCult.Geometry candidate `0.1.0-geometry-migration.1` packed successfully;
its nuspec declares exact candidate dependencies on CultMath, CultCache, and
CultCache.MessagePack. The dedicated UPM artifact remains the open Stage 1
gate.
## Decisions and Deviations
@ -127,8 +147,7 @@ a broader stage gate.
## Next Actions
1. Establish the Geometry -> CultMath dependency through an explicit candidate
package/local-feed workflow rather than an implicit sibling checkout.
2. Add Geometry-owned exact vector/quaternion formatters and byte fixtures.
3. Prove actual `Column<float2>` and `Column<float3>` access from Geometry, then
inspect the NuGet and UPM artifacts before adopting vectors in v2 schemas.
1. Establish and inspect the dedicated `org.gamecult.geometry` UPM artifact.
2. Record the newly pinned Rust v1 byte/key witnesses and commit their
authoritative submodule change.
3. Begin Stage 2 only after the Unity dependency/layout gate is proven.

View file

@ -0,0 +1,106 @@
using CultMath;
using GameCult.Caching.MessagePack;
using MessagePack;
using MessagePack.Formatters;
[assembly: CultDocumentMessagePackResolvers(typeof(GameCult.Geometry.CultMathMessagePackResolver))]
namespace GameCult.Geometry;
/// <summary>
/// Owns the persisted positional representation of CultMath values used by
/// GameCult.Geometry documents. CultMath remains serialization-agnostic.
/// </summary>
public sealed class CultMathMessagePackResolver : IFormatterResolver
{
public IMessagePackFormatter<T>? GetFormatter<T>()
{
if (typeof(T) == typeof(float2)) return (IMessagePackFormatter<T>)(object)Float2Formatter.Instance;
if (typeof(T) == typeof(float3)) return (IMessagePackFormatter<T>)(object)Float3Formatter.Instance;
if (typeof(T) == typeof(float4)) return (IMessagePackFormatter<T>)(object)Float4Formatter.Instance;
if (typeof(T) == typeof(quaternion)) return (IMessagePackFormatter<T>)(object)QuaternionFormatter.Instance;
return null;
}
private static void RequireComponents(ref MessagePackReader reader, int expected, string typeName)
{
var actual = reader.ReadArrayHeader();
if (actual != expected)
{
throw new MessagePackSerializationException($"{typeName} requires exactly {expected} components; payload contained {actual}.");
}
}
internal sealed class Float2Formatter : IMessagePackFormatter<float2>
{
public static readonly Float2Formatter Instance = new();
public void Serialize(ref MessagePackWriter writer, float2 value, MessagePackSerializerOptions options)
{
writer.WriteArrayHeader(2);
writer.Write(value.x);
writer.Write(value.y);
}
public float2 Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
{
RequireComponents(ref reader, 2, nameof(float2));
return new float2(reader.ReadSingle(), reader.ReadSingle());
}
}
internal sealed class Float3Formatter : IMessagePackFormatter<float3>
{
public static readonly Float3Formatter Instance = new();
public void Serialize(ref MessagePackWriter writer, float3 value, MessagePackSerializerOptions options)
{
writer.WriteArrayHeader(3);
writer.Write(value.x);
writer.Write(value.y);
writer.Write(value.z);
}
public float3 Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
{
RequireComponents(ref reader, 3, nameof(float3));
return new float3(reader.ReadSingle(), reader.ReadSingle(), reader.ReadSingle());
}
}
internal sealed class Float4Formatter : IMessagePackFormatter<float4>
{
public static readonly Float4Formatter Instance = new();
public void Serialize(ref MessagePackWriter writer, float4 value, MessagePackSerializerOptions options)
{
writer.WriteArrayHeader(4);
writer.Write(value.x);
writer.Write(value.y);
writer.Write(value.z);
writer.Write(value.w);
}
public float4 Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
{
RequireComponents(ref reader, 4, nameof(float4));
return new float4(reader.ReadSingle(), reader.ReadSingle(), reader.ReadSingle(), reader.ReadSingle());
}
}
internal sealed class QuaternionFormatter : IMessagePackFormatter<quaternion>
{
public static readonly QuaternionFormatter Instance = new();
public void Serialize(ref MessagePackWriter writer, quaternion value, MessagePackSerializerOptions options)
{
writer.WriteArrayHeader(4);
writer.Write(value.x);
writer.Write(value.y);
writer.Write(value.z);
writer.Write(value.w);
}
public quaternion Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
{
RequireComponents(ref reader, 4, nameof(quaternion));
return new quaternion(reader.ReadSingle(), reader.ReadSingle(), reader.ReadSingle(), reader.ReadSingle());
}
}
}

View file

@ -5,10 +5,15 @@
<PackageTags>game;geometry;csg;lod;cultcache;cultmesh;vibegeometry;fensalir</PackageTags>
<PackageReadmeFile>README.md</PackageReadmeFile>
<NoWarn>$(NoWarn);1591</NoWarn>
<CultMathVersion>0.1.0-geometry-migration.1</CultMathVersion>
<CultMathCandidateFeed Condition="'$(CultMathCandidateFeed)' == ''">$(MSBuildThisFileDirectory)..\..\..\CultMath\.tools\local-feed</CultMathCandidateFeed>
<RestoreAdditionalProjectSources Condition="Exists('$(CultMathCandidateFeed)')">$(RestoreAdditionalProjectSources);$(CultMathCandidateFeed)</RestoreAdditionalProjectSources>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\GameCult.Caching\GameCult.Caching.csproj" />
<ProjectReference Include="..\GameCult.Caching.MessagePack\GameCult.Caching.MessagePack.csproj" />
<PackageReference Include="CultMath" Version="$(CultMathVersion)" />
<PackageReference Include="MessagePack" Version="3.1.7" />
<PackageReference Include="System.Text.Json" Version="9.0.10" />
</ItemGroup>

View file

@ -0,0 +1,76 @@
using System;
using System.Linq;
using System.Threading.Tasks;
using CultMath;
using GameCult.Caching;
using GameCult.Caching.MessagePack;
using MessagePack;
using NUnit.Framework;
namespace GameCult.Geometry.Tests;
public sealed class CultMathValueIntegrationTests
{
private static readonly MessagePackSerializerOptions GeometryOptions =
CultDocumentMessagePackSerialization.OptionsFor(typeof(CultGeometryDomainDocument));
[TestCaseSource(nameof(ValueEncodingCases))]
public void GeometryResolver_UsesExactPositionalVectorEncoding(object value, Type type, string expectedHex)
{
var payload = MessagePackSerializer.Serialize(type, value, GeometryOptions);
Assert.That(Convert.ToHexString(payload), Is.EqualTo(expectedHex));
Assert.That(MessagePackSerializer.Deserialize(type, payload, GeometryOptions), Is.EqualTo(value));
}
[Test]
public void GeometryResolver_RejectsWrongVectorWidth()
{
var twoComponents = Convert.FromHexString("92CA3F800000CA40000000");
Assert.That(
() => MessagePackSerializer.Deserialize<float3>(twoComponents, GeometryOptions),
Throws.TypeOf<MessagePackSerializationException>());
}
[Test]
public async Task GeometrySoa_ExposesCultMathVectorsAsIntactColumns()
{
var cache = new CultCache();
await cache.UpsertAsync(new VectorColumnDocument
{
Name = "probe",
Uv = new float2(0.25f, 0.75f),
Position = new float3(1f, 2f, 3f),
});
var table = cache.Soa<VectorColumnDocument>();
Assert.That(table.Column<float2>(nameof(VectorColumnDocument.Uv)).Span.ToArray(),
Is.EqualTo(new[] { new float2(0.25f, 0.75f) }));
Assert.That(table.Column<float3>(nameof(VectorColumnDocument.Position)).Span.ToArray(),
Is.EqualTo(new[] { new float3(1f, 2f, 3f) }));
Assert.That(() => table.Column<float>("Position.x"), Throws.TypeOf<System.Collections.Generic.KeyNotFoundException>());
}
private static object[] ValueEncodingCases =>
[
new object[] { new float2(1f, -2.5f), typeof(float2), "92CA3F800000CAC0200000" },
new object[] { new float3(1f, -2.5f, 0.5f), typeof(float3), "93CA3F800000CAC0200000CA3F000000" },
new object[] { new float4(1f, -2.5f, 0.5f, 4f), typeof(float4), "94CA3F800000CAC0200000CA3F000000CA40800000" },
new object[] { new quaternion(1f, -2.5f, 0.5f, 4f), typeof(quaternion), "94CA3F800000CAC0200000CA3F000000CA40800000" },
];
[CultDocument("tests.geometry_vector_column", "tests.geometry_vector_column.v1")]
private sealed class VectorColumnDocument
{
[Key(0), CultName]
public string Name { get; set; } = string.Empty;
[Key(1)]
public float2 Uv { get; set; }
[Key(2)]
public float3 Position { get; set; }
}
}