Development

How the repository is built, tested and released. The rules every contributor follows, human or AI agent, are in AGENTS.md.

Layout

• Packages/com.m4bwav.universe-generator/Runtime/: the one source folder. Unity compiles it as a package with no engine references; src/UniverseGenerator/ compiles the same files for NuGet.
• tests/: unit, golden, property, distribution, hierarchy and size tests. tests/Golden/v1/ holds the golden files of generator version 1.
• samples/ConsoleSample: every README example, run by the tests and by CI.
• kb/: the knowledge base: the feature matrix and the determinism, plausibility and design rules behind the generator.
• scripts/: the size gate, the package check, the JSON export generator and the history scan.

Build and test

The SDK is .NET 10 (global.json: 10.0.100 with latestFeature). From the repository root:

dotnet restore --locked-mode
dotnet format --verify-no-changes
dotnet build -c Release
dotnet test -c Release
dotnet pack src/UniverseGenerator -c Release -o artifacts

dotnet test runs the suite on net10.0 and net48; net48 runs only on Windows and exercises the netstandard2.0 build. On 2026-10-03 the suite had 272 tests on net10.0 and 271 on net48, all passing.

The rules that keep the seed promise

• Golden files are never regenerated to make a test pass. Once a golden file is in a release tag, CI refuses any change to it. A new field gets a new golden file, because the golden tests write an explicit list of fields per level.
• Determinism. The generator's own PCG32 and SplitMix64 streams, one per purpose; never System.Random, UnityEngine.Random, string.GetHashCode or Guid.NewGuid; decisions on integer draws; maths from + - * / and square root only; values rounded before they are stored. The reasons are on Same seed, same galaxy.
• A new option or field never adds draws to an existing stream. It uses a stream of its own, or changes values after every draw.
• Targets. The Runtime folder compiles as netstandard2.0 and net10.0 with C# 9, and in Unity 6: no newer APIs without a guard, no reflection, no data parsed in a static constructor.
• Every file in the Unity package has a committed .meta, and a GUID never changes.

Continuous integration

ci.yml runs on every push and pull request, on Ubuntu 24.04, Windows and macOS. It first checks that no released golden file changed. Then it restores in locked mode, checks the format, builds in Release and runs a NuGet audit. It runs the tests (net10.0 everywhere, net48 on Windows) and the console sample, checks the Unity .meta files, packs, checks what the package holds (no dependencies) and runs the size gate.

The size gate (scripts/size-gate.py) measures every build against green, yellow and red limits: nupkg under 1 MB, the largest DLL under 750 KB, the Unity package under 2 MB unpacked, Runtime file and line counts. At 1.0.0 everything was green: nupkg 441.0 KB, DLL 563.0 KB, Unity package 606.7 KB unpacked (CHANGELOG).

Releases

1. The CHANGELOG gets the version's heading with the date and the size numbers, and the project's <Version> is set; the pull request merges, and ci passes on master.
2. The maintainer tags v<version> on that commit and pushes the tag.
3. release.yml checks that the tag equals the project's version, that the commit is on master and passed ci, builds, tests on Linux and on Windows (net48 too), checks the package and the size gate, takes the release notes from the CHANGELOG and attests the nupkg.
4. The run waits at the nuget environment until the maintainer approves it, then pushes to nuget.org by Trusted Publishing (no API key exists) and creates the GitHub Release with the nupkg and snupkg.

The Unity package's OpenUPM listing builds from the same tags once it is live.

The wiki

This wiki's examples are checked against the published package by a program kept in the repository's ai-docs/notes/ (*-wiki-verify.cs) with its saved output beside it; the note *-github-wiki.md there says how to update the wiki for the next release.