Aspid.MVVM

A high-performance Source Generator-based MVVM framework for Unity. Enables clean separation between View, ViewModel, and business logic with zero reflection in bindings and minimal memory allocations.

Project Structure

Projects/Aspid.MVVM/
├── Aspid.MVVM/                        # Main Unity project
│   └── Packages/
│       ├── tech.aspid.mvvm/           # MVVM package (embedded local UPM package)
│       │   ├── Source/                # Core framework implementation
│       │   │   ├── ViewModels/        # IViewModel interface, attributes, extensions
│       │   │   ├── BindableMembers/   # Binding member resolution
│       │   │   ├── Binders/           # Data binding implementations
│       │   │   ├── Commands/          # IRelayCommand interfaces and implementations
│       │   │   ├── Mode/              # BindMode enum (OneWay, TwoWay, OneTime, OneWayToSource)
│       │   │   ├── Views/             # View components and initialization
│       │   │   ├── Generation/        # Attributes for source generation
│       │   │   ├── Exceptions/        # Framework-specific exceptions
│       │   │   └── Helpers/           # Utility functions
│       │   ├── StarterKit/Runtime/    # Ready-to-use components
│       │   │   ├── Binders/           # UI binders (Text, Image, Toggle, Slider, etc.)
│       │   │   ├── Converters/        # Value converters
│       │   │   ├── Collections/       # Virtualized lists, dynamic collections
│       │   │   ├── Commands/          # Command implementations
│       │   │   └── ViewModels/        # DynamicViewModel
│       │   ├── Unity/                 # Unity integration layer
│       │   └── Samples~/              # Path 01–06 (Counter, Greeter, BindModes, Stats, TodoList, CustomBinder) + features (VirtualizedList, DynamicViewModel, DiIntegration, ExampleScripts); scenes and code only, the tutorials live in Docs/tutorials/
│       └── tech.aspid.fasttools/      # Aspid.FastTools (embedded local UPM package)
├── Aspid.MVVM.Generators/             # Roslyn source generator
│   ├── Aspid.MVVM.Generators/         # Generator implementation
│   └── Aspid.MVVM.Generators.Tests/   # Generator unit tests
├── Aspid.MVVM.Analyzers/              # Roslyn code analyzer
│   ├── Aspid.MVVM.Analyzers/          # Analyzer implementation
│   └── Aspid.MVVM.Analyzers.Tests/    # Analyzer unit tests
├── Aspid.MVVM.Unity.Generators/       # Unity-specific generators
├── Docs/                              # Docusaurus site (GitHub Pages): docs/, tutorials/ (one README.md per sample), migration/ (one guide per version), i18n/ru/ translations; the package holds no docs or media
└── README.md

Key Technologies

• C# / .NET Standard 2.0 — core framework
• Roslyn Incremental Source Generators — code generation at build time
• Unity 2022.3+ — target runtime
• Zenject / VContainer — DI framework integrations
• UniTask — async utilities
• .NET SDK 10.0.300 — for generator/analyzer projects (root global.json); test projects target net9.0

Architecture

The framework uses Source Generators to eliminate boilerplate and reflection:

1. [ViewModel] — marks a partial class for source generation; generates IViewModel implementation
2. [Bind] — marks fields for binding generation; supports BindMode argument
3. [RelayCommand] — transforms a method into an IRelayCommand property
4. Binders — MonoBehaviour components that connect View UI elements to ViewModel bindable members
5. Observable Collections — thread-safe, change-notifying collections with filtering/sorting

Code Conventions

Naming:

• PascalCase for classes, interfaces, methods, properties
• camelCase for local variables and parameters
• _camelCase prefix for private fields
• I prefix for interfaces (IViewModel, IRelayCommand)
• Binder suffix for binding components, Attribute suffix for attributes

Namespaces:

• Root: Aspid.MVVM
• Sub-namespaces: Aspid.MVVM.StarterKit, Aspid.Collections.Observable
• Editor code lives in .Editor sub-namespaces

Code Style:

• All classes requiring source generation must be partial
• Explicit access modifiers on all members
• Nullable reference types (T? for optional values)
• XML documentation comments on all public APIs; conventions in global skill asp-xmldoc. Aspid-specific <param> phrasing: binding mode The binding mode. [constraints], converter The converter used to transform X to Y., bound enum value The bound enum value received from the ViewModel., target object The X to bind.
• ReSharper suppression comments on generated/special code

Solutions

Testing

• Generator tests: Aspid.MVVM.Generators/Aspid.MVVM.Generators.Tests/
• Analyzer tests: Aspid.MVVM.Analyzers/Aspid.MVVM.Analyzers.Tests/
• Runtime tests: Unity Test Framework, Zenject integration tests
• Manual validation: Sample projects under Samples~ (each sample's README.md is its tutorial)
• CI (.github/workflows/ci.yml): package files, version files, scripts/*.test.mjs, the committed Roslyn DLLs, the .NET tests, and the Unity EditMode + PlayMode tests on every Unity 6000.x line (UNITY_VERSIONS) in a throwaway project from scripts/make-unity-test-project.sh. pr-checks.yml checks the PR title (Conventional Commits, known scope) and that shipped package code comes with an entry in both CHANGELOGs (or the needs-changelog label until the entry is written). The unity-quick label limits a PR to the first and the last Unity version.

Commands

Generator/analyzer solutions build independently of Unity:

# Rebuild the three Roslyn DLLs in Release and copy them into the package (commit the result)
scripts/build-roslyn-dlls.sh

# Run generator tests
dotnet test Aspid.MVVM.Generators/Aspid.MVVM.Generators/Aspid.MVVM.Generators.Tests/

# Run analyzer tests
dotnet test Aspid.MVVM.Analyzers/Aspid.MVVM.Analyzers/Aspid.MVVM.Analyzers.Tests/

# Run the tests of the CI scripts
node --test scripts/*.test.mjs

# Set the release version: package.json, README install URLs, the dated CHANGELOG sections and links
scripts/set-version.sh 1.1.0-rc.1

Releases

Only a pushed v<version> tag on a commit of main starts .github/workflows/release.yml: preflight (SemVer, the commit is in main, upm/<version> is new, package.json, the CHANGELOG section) → the whole ci.yml with Unity required → one atomic push of the upm (stable) or upm-preview (prerelease) subtree branch and its upm/<version> tag, with the English CHANGELOG bundled into the package → the GitHub release (gh). There is no manual run: the Release tags ruleset lets only admins push v* tags. Skill asp-mvvm-release walks the release (bump PR, merge, tag, watching the run).

Unity Editor automation (Unity CLI)

Editor automation goes through the official Unity CLI (unity) and the com.unity.pipeline package, which is declared in Aspid.MVVM/Packages/manifest.json. A running Editor exposes ~140 commands over its Pipeline server, called as unity command <group> <name> (Pipeline 0.9+):

# Open the project and check that the Pipeline server is up
unity open Aspid.MVVM
unity status --json

# Discover / run Editor commands
unity command                                  # list every command the Editor exposes
unity command <group>                          # list the commands of one group
unity command script recompile --json          # compile check after C# edits
unity command package resolve --json           # re-resolve packages after a manifest change
unity command console get --json               # read the Editor console
unity command test run --mode editor --json    # Unity Test Framework run (EditMode)
unity command script eval --code 'return Application.unityVersion;'

When several Unity Editors are open, add --project-path ./Aspid.MVVM — otherwise the CLI can't pick an instance and errors out.

Gotchas

• Generator artifacts are committed. Built DLLs (Aspid.MVVM.Generators.dll, Aspid.MVVM.Analyzers.dll, Unity/Aspid.MVVM.Unity.Generators.dll) live under Aspid.MVVM/Packages/tech.aspid.mvvm/ and are checked into the repo. After changing a generator or an analyzer, run scripts/build-roslyn-dlls.sh and commit the refreshed DLLs — Unity consumes the DLL, not source. The Roslyn DLLs job of CI rebuilds them and fails on any byte of difference; the root Directory.Build.props makes the Release build reproducible.
• The .NET SDK is pinned to 10.0.300 by the root global.json (rollForward: disable): another compiler gives other DLL bytes. The test projects target net9.0, so dotnet test also needs the .NET 9 runtime.
• Classes using [ViewModel], [Bind], [RelayCommand] must be partial — the generator emits a second partial; without the modifier you get compile errors instead of generated members.

Roslyn sources

Aspid.MVVM.Generators/, Aspid.MVVM.Analyzers/ and Aspid.MVVM.Unity.Generators/ were separate repositories consumed as git submodules; their full history is merged here, and their old tags carry the generators/, analyzers/ and unity-generators/ prefixes. A change to one of them goes in the same PR as the DLL it rebuilds. A clone made before the merge runs git submodule deinit -f --all once before it checks out a commit without the submodules; otherwise git cannot replace the old submodule folders with tracked ones.

Aspid.Collections is consumed as a UPM git package (tech.aspid.collections).

Branch Strategy

• main — stable releases; target for PRs
• Version/Aspid.MVVM-x.x.x — version development branches
• Feature/* — feature branches

Documentation

Project skills live in .claude/skills/; .agents/skills/ links there for other agents. On Windows the link needs a clone with -c core.symlinks=true (Developer Mode on); without it, read .claude/skills/ directly.

• Full docs: https://vpdpersonal.github.io/Aspid.MVVM/ — Docusaurus site in Docs/, pages in Docs/docs and Docs/tutorials; see skill docs-site
• Unity Asset Store: https://assetstore.unity.com/packages/slug/298463
• XML doc conventions: global skill asp-xmldoc
• Code style: skill aspid-code-style — member ordering, formatting, nullable, comments
• StarterKit layout: skill starterkit-layout — folder taxonomy and naming inside StarterKit/
• Writing a converter: skill starterkit-converter-authoring
• Writing a binder: skill starterkit-binder-authoring
• Releasing a version: skill asp-mvvm-release (/asp-mvvm-release <version>)
• Key entry points for new contributors:
  • README.md — project overview
  • Aspid.MVVM/Packages/tech.aspid.mvvm/Samples~/01. Counter/ — minimal example
  • Aspid.MVVM.Generators/Aspid.MVVM.Generators/Aspid.MVVM.Generators/Generators/ViewModels/ViewModelGenerator.cs — source generator pipeline
  • Source/ViewModels/IViewModel.cs — core interface