Alternative Source Generator for Unity ====================================== Alternative Source Generator is built on the Unity native functions. - ✅ Unity Package Manager Support - ✅ No Complicated IDE Environment Setup - ✅ No Additional Package Installation As you already know, Roslyn's source generator is too sophisticated. This framework provides more simple, ease of use and good enough functions for source code generation.

日本語 / JA

超簡単に使える Unity 向けソースジェネレーターです。

![](https://camo.githubusercontent.com/85cf73a959252b89cb60c26d5c95391379ea1f3df496b2433c5a5b9e785ada7f/68747470733a2f2f646c2e64726f70626f782e636f6d2f73636c2f66692f6a696a636c6e6172727275786474353930767373312f5553475f50616e656c2e706e673f726c6b65793d6b34346c633973776b306d6d7569383439636b37746170706b26646c3d30) - [USG Control Centre ^{^_*New*}](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#usg-control-panel--window) - [Breaking Changes in v2.0](https://github.com/sator-imaging/Unity-AltSourceGenerator/blob/main/CHANGELOG.md) - [TODO](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#todo)

Table of Contents

- [Sample Code](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#sample-code) - [Method Generator](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#method-generator) - [How to Use](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#how-to-use) - [Result](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#result) - [Self-Emit Generator](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#self-emit-generator) - [Result](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#result-1) - [Output Directory and File Name](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#output-directory-and-file-name) - [Coding Goodies](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#coding-goodies) - [Utility Functions for Build Event](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#utility-functions-for-build-event) - [Technical Notes](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#technical-notes) - [Naming Convention](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#naming-convention) - [`` Tag](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#auto-generated-tag) - [Unity Editor Integration](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#unity-editor-integration) - [Installation](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#installation) - [USG Control Panel \& Window](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#usg-control-panel--window) - [Context Menu](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#context-menu) - [Troubleshooting](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#troubleshooting) - [Copyright](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#copyright) - [License](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#license) - [Devnote](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#devnote) - [TODO](https://github.com/sator-imaging/Unity-AltSourceGenerator/raw/main/#todo)

Sample Code =========== Here is minimal implementation of source generator.

日本語 / JA

最小限のソースジェネレーターの構成はこちら。`StringBuilder` が渡されるので書き込んで `true` を返せば `context.OutputPath` に内容を書き込みます。`false` を返せば書き込みを中止できます。

## Method Generator This example will add `Panic()` method to target class.

日本語 / JA

ターゲットのクラスに `Panic()` メソッドを追加するサンプル。

```csharp public class PanicMethodGenerator { static string OutputFileName() => "PanicMethod.cs"; // -> PanicMethod...g.cs static bool Emit(USGContext context, StringBuilder sb) { if (!context.TargetClass.IsClass || context.TargetClass.IsAbstract) return false; // return false to tell USG doesn't write file. // code generation sb.Append($@" namespace {context.TargetClass.Namespace} {{ internal partial class {context.TargetClass.Name} {{ public void Panic() => throw new System.Exception(); }} }} "); return true; } } ``` ### How to Use ```csharp using SatorImaging.UnitySourceGenerator; namespace Sample { // Add attribute to target class to use method generator. // Note that class must be defined as partial class. [UnitySourceGenerator(typeof(PanicMethodGenerator), OverwriteIfFileExists = false)] internal partial class MethodGeneratorSample { } } ``` ### Result Generated code looks like this. ```csharp // PanicMethodGenerator namespace Sample { internal partial class MethodGeneratorSample { public void Panic() => throw new System.Exception(); } } ``` ## Self-Emit Generator Here is target-less, self-emitting generator example. It is useful to generate static database that cannot be generated on Unity runtime. For example, build asset GUIDs database using `UnityEditor.AssetDatabase`, resource integrity tables, etc. ```csharp using System.Text; using SatorImaging.UnitySourceGenerator; [UnitySourceGenerator(OverwriteIfFileExists = false)] class MinimalGenerator { static string OutputFileName() => "Test.cs"; // -> Test..g.cs static bool Emit(USGContext context, StringBuilder sb) { // write content into passed StringBuilder. sb.AppendLine($"Asset Path: {context.AssetPath}"); sb.AppendLine($"Hello World from {typeof(MinimalGenerator)}"); // you can modify output path. initial file name is that USG updated. // NOTE: USG doesn't care the modified path is valid or not. context.OutputPath += "_MyFirstTest.txt"; // return true to tell USG to write content into OutputPath. false to do nothing. return true; } } ``` ### Result ```csharp // MinimalGenerator Asset Path: Assets/Scripts/MinimalGenerator.cs Hello World from Sample.MinimalGenerator ``` Output Directory and File Name ============================== Source Generator creates `USG.g` folder next to target script and append class names to file name. Resulting file path will be: - Assets/Scripts/USG.g/Test.MinimalGenerator.g.cs - Assets/Scripts/USG.g/PanicMethod.MethodGeneratorSample.PanicMethodGenerator.g.cs

日本語 / JA

書き出し先は上記の通り。フォルダーとターゲット・ジェネレータークラス名が付与されます。

> NOTE: In above example, output path is modified so that resulting file name is `Test.MinimalGenerator.g.cs_MyFirstTest.txt` Coding Goodies ============== There are utility methods for coding source generator more efficient and readable. - `StringBuilder` Extentions - `IndentLine` / `IndentAppend` - `IndentBegin` / `IndentEnd` - `IndentLevel` / `IndentChar` / `IndentSize` - `USGFullNameOf` - `usg` - `USGReflection` - `GetAllPublicInstanceFieldAndProperty` - `TryGetFieldOrPropertyType` - `GetEnumNamesAndValuesAsDictionary` - `GetEnumNamesAndValuesAsTuple` `usg` is a special utility that is designed for refactoring-ready source generator more readable, script template import it as a static library by default.

日本語 / JA

`System.Reflection` 系のユーティリティーと `StringBuilder` の拡張メソッド群。 `usg` は特殊で、クラス名やら何やらのリファクタリングに強いジェネレーターにすると読みづらくなってしまうのを緩和するためのモノ。 `{typeof(MyClass).FullName}.{nameof(MyClass.Property)}` どんどん長くなるだけなら良いけどクラス内クラスとか構造体の名前が + 付きの不正な状態で出てくる。その他にもジェネリッククラスへの対応とかなんとか、結局何かが必要になる。それならばと可能な限り短く書けるようにした。インデント系はトリッキーだけど開発機での実行なのでまあ良し。

```csharp // indent utility sb.IndentChar(' '); // default sb.IndentSize(4); // default sb.IndentLevel(3); // template default sb.IndentBegin("void MethodName() {"); { // cast int value to enum sb.IndentLine($"MyObject.EnumValue = ({usg()})intValue"); // --- or --- string CAST_MY_ENUM = "(" + usg(targetTypeVar) + ")"; sb.IndentLine($"MyObject.EnumValue = {CAST_MY_ENUM}intValue"); } sb.IndentEnd("}"); ``` ```csharp using static SatorImaging.UnitySourceGenerator.USGFullNameOf; // usg() to work // usg() allows to write refactoring-ready code with auto completion sb.Append($"public static {usg>()} MyDict = new() {{ init... }};"); // usg{params string[]) to generate full name with specified member name. usg("NestedStruct.MyField"); // -> global::Full.Namespace.To.MyClass.MyStruct.MyField // most strict refactoring-ready code usg(nameof(MyClass.NestedStruct), nameof(MyClass.NestedStruct.MyField)); // usg(object valueOrType, bool isFullName) to retrieve full type definition literal static class MyClass { Dictionary[]>> Complex = new(0); // usg() throws when null } usg(MyClass.Complex); // -> global::...Dictionary[]>> ``` Utility Functions for Build Event ================================= There are utility functions to perform source code generation on build event.

日本語 / JA

`IPostprocessBuildWithReport` も実装しようかと思ったものの、ビルドイベントに勝手に処理追加するのはなんか訳わからんが動かんの原因だし、BuildReport として渡される全てのファイル名を走査する処理は効率も良くない。ということで。

```csharp // perform code generation by class name if you don't know where it is. USGUtility.ForceGenerateByName(nameof(MinimalGenerator)); // perform code generation by known path. USGEngine.ProcessFile(assetPath, true, true); // force re-generate all related files ``` Technical Notes =============== As of C# 9.0, it doesn't allow to define `abstract static` methods in interface, USG reports error when source generator class doesn't implement required static methods.

日本語 / JA

理想はアトリビュートとインターフェイスによるフィルタリングですが、Unity 2021 は C# 9.0 で `abstract static` を含んだインターフェイスが使えません。しょうがないのでメソッドのシグネチャを確認して存在しなければエラーをコンソールに出します。

![](https://camo.githubusercontent.com/684e8904c733bf00da2d5c29ef728b910f791e4fb13ea7c72d76299aaca3f69b/68747470733a2f2f646c2e64726f70626f782e636f6d2f732f6b7374626166626e796335346b326c2f5553475f496e7465666163654572726f722e6a7067) ## Naming Convention - Generator class name and filename must be matched. - Class name must be unique in whole project. - Classes are ignored if defined in assembly which name starts with: - `Unity` (no trailing dot) - `System.` - `Mono.`

日本語 / JA

- ジェネレータークラスの名前はファイル名と一致 - ジェネレータクラスの名前はプロジェクト内で一意 - クラスが以下で始まる名前のアセンブリで宣言されている場合は対象としない - `Unity` (末尾ドット無し) - `System.` - `Mono.`

## `` Tag USG automatically adds document tag at the beginning of generated file. You can remove this document tag by `sb.Clear()` in `Emit()` method.

日本語 / JA

渡される `StringBuilder` の冒頭にはドキュメントタグが入ってます。不要なら `sb.Clear()` してください。

Unity Editor Integration ======================== ## Installation Use the following git URL in Unity Package Manager (UPM). - Latest: https://github.com/sator-imaging/Unity-AltSourceGenerator.git - v2.0.1: https://github.com/sator-imaging/Unity-AltSourceGenerator.git#v2.0.1 ## USG Control Panel & Window - `Main Menu > Edit > Project Settings > Alternative Source Generator` ![](https://camo.githubusercontent.com/85cf73a959252b89cb60c26d5c95391379ea1f3df496b2433c5a5b9e785ada7f/68747470733a2f2f646c2e64726f70626f782e636f6d2f73636c2f66692f6a696a636c6e6172727275786474353930767373312f5553475f50616e656c2e706e673f726c6b65793d6b34346c633973776b306d6d7569383439636b37746170706b26646c3d30) - **On** - Include generator in auto run sequence. - **Run** - Run generator on demand. Note that `OverwriteIfFileExists` setting on attribute is ignored. - **Link** - Click name to unveil generator script file in project window. - Down arrow icon (▼) will show referencing emitters below. - Linked chain icon (🔗) to unveil emitted file in `USG.g` folder. - 🗑️ - Delete *emitted* file from `USG.g` folder. - `Main Menu > Tools > Alternative Source Generator` - open as a window. ![](https://camo.githubusercontent.com/cca493f7a2894628db7690dbe8aa6d6c1dd9441bded5e5a25058a60381beec3a/68747470733a2f2f646c2e64726f70626f782e636f6d2f73636c2f66692f6465646233303639396164687373387a71776674352f5553475f57696e646f772e706e673f726c6b65793d313367713234797063697730306f39746b686963647078706526646c3d30) ## Context Menu

日本語 / JA

手動でソースコード生成イベントの発火も可能です。「ジェネレーターのスクリプトファイル」か「生成されたファイル」を選択して、Project ウインドウで `Reimport` か `Unity Source Generator` 以下のメニューを実行します。ジェネレーターとして参照されているファイルを Reimport した場合は、関連するクラスすべてが再生成されます。`Force Generate...` はクラスアトリビュートの設定に関わらず強制的に上書き生成します。

There is an ability to invoke source code generation by hand. With generator script file or generated file selected in Project window: - `Reimport` - This command respects `OverwriteIfFileExists` setting by generator class attribute. - Classes referencing selected generator will also be re-generated. - `Unity Source Generator > Force Generate` - This command will force re-generate source code even if overwrite setting is disabled. ![](https://camo.githubusercontent.com/1130c5b5e046b5bdf6d6e26890901b4e007ebea543b0518b71aeebe949dc7f93/68747470733a2f2f646c2e64726f70626f782e636f6d2f732f736b7161366d77683933326c7372672f5553475f466972654576656e742e6a7067) Troubleshooting =============== #### Generator script update is not applied to generated file. Usually, this problem happens when Unity automatically reloads updated scripts WITHOUT Editor window getting focus. To solve the problem: 1. Close Unity and Visual Studio. 1. Restart Unity. 1. Launch Visual Studio by double clicking `.cs` script in Unity Editor. > *NOTE*: There is experimental feature to suspend auto reloading while Unity Editor in background (doesn't get focused). Open `Edit > Project Settings > Alternative Source Generator` to enable it. Copyright ========= Copyright © 2023 Sator Imaging, all rights reserved. License =======

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

```text MIT License Copyright (c) 2023 Sator Imaging Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ```

# Devnote ## TODO Clarify terminology of generator types, especially in source code comments. currently, referenced/referencing generator, or just generator, confusing! - Generator class: - Class has `Emit()` method to generate code. And does NOT have `UnitySourceGenerator` attribute. - current -> "referenced" generator, "referenced only" generator, etc. - Emitter class: (or Target, Source, Client, Igniter, Invoker, Caller?) - Class has `UnitySourceGenerator` attribute to invoke code generation. And does NOT have `Emit()` method. - current -> "referencing" class, just generator, etc. - Self-Emit class: - Class has both `Emit()` method and `UnitySourceGenerator` attribute. Works only a file. No dependencies.