Roslynを使用してゲームコンテンツを編集する

Chatterには価値がありません。 コードを見せてください。
-ライナス・トーバルズ

みなさんこんにちは！ 私は小さな（しかし誇りに思う）gamedevオフィスでプログラマーとして働いています。 過去数年間、同社はmatch3ジャンルのモバイルゲーム用のカジュアルゲームをリリースしてきました。 私たちはC＃（これは喜ばせざるを得ない）で記述し、Unityを使用しません（まあ、ほとんど）。 私の責任の主な領域は、ゲームプレイとUIです。 C＃とそのエコシステムにも夢中です。 今日は、ゲームコンテンツの編集にRoslynコード分​​析および変更ツールをどのように使用したかを説明します。 誰が気にする-私は猫をお願いします。

ご注意 実装方法を理解し、コード例を提供するセクションには、見出しの[技術セクション]が付いています。 そのレベルの詳細に飛び込みたくない場合は、スキップしてください。 これは、アイデアの一般的な理解には影響しません。

バックグラウンド。 1つのMatch3でいっぱいになることはありません

match3ジャンルの多くのゲームには、ゲームの世界を表す別のエンティティがあります。 これをカードと呼びます。 カードの機能は異なる場合があります。非常に単純な（ゲームの進行状況のインジケーター）から本格的なアクションシーン（独自の内部ストーリー、プロット、キャラクターなど）までです。

私が取り組んでいるプロジェクトの1つでは、プロットとマップに特別な注意が払われています。 十分な要件があります：大量のコンテンツ、多様性、魅力、よく整理されたカットシーンなど。 また、これらはすべて簡単に編集および展開できる必要があります。 今まで、私たちのスタジオのゲームプロジェクトにはこのようなものはありませんでした。 プロットシステムとそのツールの両方をゼロから開発する必要がありました。

プロットアーキテクチャ[技術セクション]

プロット全体を別々の間隔-クエストに分割します。 クエストは一連のステージ（状態）であり、それぞれに独自のロジックがあります。 スタブクエストのコードを見てみましょう。

enum StubQuestState { Initial, } class Stub : SectorComponent<StubQuestState> {} class StubQuest : SectorBehaviour<Stub, StubQuestState> { [State(StubQuestState.Initial)] private IEnumerator<object> InitialState() { yield break; } } 

だから私たちは見る：

• 列挙型StubQuestState-クエストのステータス。
• クラススタブ-クエストのコンポーネント。状態とオプションのデータを保存します。
• StubQuestクラス-クエストロジック。 クエストの各状態は、イテレータを返すメソッドに対応する必要があります（メソッドはState属性を介して接続され、この状態で直接実行されるアクションを決定します）。

また、各クエストにはアクティベーション条件があります-起動する必要がある場合（コードではFuncとして表示され、名前はReachedConditionになります）。


クエストは、セクター（SectorNなどの名前の静的クラス）の用語で、場所によって分割されています。 各セクターには、マップ（ここではグラフィック、アニメーションを意味する）、チュートリアル（一部はクエストを通じて実装されず、独立したエンティティです）、およびクエスト自体を初期化するInitializeメソッドがあります。 初期化コードの例を次に示します。

 var fixSubmarineQuest = new FixSubmarineQuest { ReachedCondition = () => plot.Levels.Completed > 3, }; var removeSeaweedQuest = new RemoveSeaweedQuest { ReachedCondition = () => fixSubmarineQuest.Component.IsFinished, }; var fixGateStatuesQuest = new FixGateStatuesQuest { ReachedCondition = () => removeSeaweedQuest.Component.IsFinished && fixSubmarineQuest.Component.IsFinished, }; 

クエストの接続を視覚化します：



ご覧のように、クエストは非連結の非循環有向グラフを形成します。
クエストのステータスのロジックを分析しましょう。 各状態は、基本的にこの状態で実行する必要がある一連のアクションです。 アクションは完全に異なる場合があります。アニメーションのアクティブ化、シーン内でのカメラの移動、ゲームレベルの起動、カットシーンの起動と管理など。 例：

 yield return WaitForMapScreenOnTop(); MapScreen.HideUi(); yield return MapScreen.ScrollToMapNodeTask( MapScreen.Map._Sector02._RadioTower.It, zooming: MapZooming.Minimal, screenPivot: new Vector2(0.5f, 0.4f) ); yield return MapScreen.Map._Sector02._RadioTower.RunAnimationFixTower(); yield return MapScreen.Map._Sector02._RadioTower.RunAnimationCommunicate(); var dialog = new CutScene(CharacterEmotion.Playfulness); dialog.AddBubble("Bla-bla-bla"); yield return Task.WaitWhile(() => !dialog.IsNearlyHidden); MapScreen.ShowUiWithDelay(); SetState(FixCommunicationCrystalQuestState.Final); 

この例では、次のことを行います。

1. マップが一番上のダイアログとして表示されるまで待ちます。
2. UIを非表示にして、カメラを移動します。
3. プロットアニメーションを順次起動します。
4. 「Bla-bla-bla」という幸せなキャラクターのカットシーンを紹介します。
5. UIを表示して、次の状態に進みます。

ロズリンとコンテンツ

ご存じのように、gamedevはソフトウェア開発のかなり極端な分野です。 ゲームはシステムとコンポーネントの「寄せ集め」であるだけでなく、それらの間の関係は電光石火の速度によって変化します（場合によっては、振り子の原理によっても：削除、返却​​、半分の削除...）。 活発な開発の段階で、プロットは絶えず変化しています。 これは、記述されたアーキテクチャのすべてのレベルに影響します：クエスト間の関係（それらの順序）、クエストのセクターへの分割、そして直接クエストロジック（状態とアクション）。 私は正直なところ、すべてを手で書く（またはCtrl + C、Ctrl + Vを行ってから名前を変更するなど）のにうんざりしているため、最初にWinFormsで小さなアプリケーションを作成して、指定された名前とステータスのStubQuestを生成しました。 そして、Roslynについて思い出し、プロット編集ツールを作成することにしました。

上で説明したように、プロット全体はコードによって設定されます。 プログラミングスキルがなければ編集できません。 上記のすべてのコンポーネント（クエスト、順序、ロジック、アクション）を他の人（プロデューサー、ゲームデザイナー）に変更する機能を提供し、何倍も速く作業するために、Roslynが重要な役割を担うエディターが作成されました。 その仕事の原理：

1. Roslyn（特に、Microsoft.CodeAnalysis.CSharp）を使用して、ゲームコードが分析され、論理モデルが構築されます。
2. 論理モデルが図に表示されます。
3. ダイアグラムへの変更がモデルに表示され、その後（再びRoslynを介して、ただしAPIを使用してコードを生成および変更して）コードベースに戻ります。

概略的には、これは次のように表現できます。



論理表現自体は非常に単純です-ゲームエンティティを表すクラス/構造のセット、それらを記述/補足できるさまざまなデータ、およびこれらのエンティティ間の関係。 論理モデルのおかげで、振る舞いの正確さを簡単に確認できます（たとえば、グラフ内のサイクルの存在や、カットシーンの後にUIを表示する開発者の忘れやすさ）。 コード分​​析と論理構造の構築について詳しく説明します。

コード分​​析とモデル構築[技術セクション]。

コードとは何ですか？ 手始めに、それは単なるテキストです。 次に、 構文解析段階で、AST（ Abstract Syntax Tree ）が取得されます。 セマンティック分析の後、シンボルテーブルが表示されます。 Roslynを使用して、必要なデータ構造を取得することは難しくありません（例をここから取ります ）。

 var tree = CSharpSyntaxTree.ParseText(@" public class MyClass { int MyMethod() { return 0; } }" ); var Mscorlib = MetadataReference.CreateFromFile(typeof(object).Assembly.Location); var compilation = CSharpCompilation.Create( "MyCompilation", syntaxTrees: new[] { tree }, references: new[] { Mscorlib } ); //Note that we must specify the tree for which we want the model. //Each tree has its own semantic model var model = compilation.GetSemanticModel(tree); 

そのため、分析に便利な形式のコードがあります。 これをプロットの論理構造とリンクすることは残っています。 プロジェクトのファイル構造と上記のアーキテクチャは、次の点で役立ちます。

 public void LoadSectorCode(string dirPath) { var sectorFile = Directory.EnumerateFiles(dirPath) .FirstOrDefault(p => new FileInfo(p).Name.StartsWith("Sector")); if (sectorFile == null) { throw new SectorFileNotFoundException(); } code.ReadFromFile(Path.Combine(dirPath, sectorFile), CodeBulkType.Sector); var questsDir = Path.Combine(dirPath, "Quests"); if (Directory.Exists(questsDir)) { var files = Directory.EnumerateFiles(questsDir); foreach (var filePath in files) { code.ReadFromFile(filePath, CodeBulkType.Quest); } } } 

コードベースの各ファイルは、タイプ（enum CodeBulkType）に関連付けられています：クエスト、セクター、構成ファイルなど。 タイプがわかれば、より高いレベルの分析を行うことができます。 たとえば、クエストデータを読み取ります。

 class QuestReader : CodeReader { public override CodeBulkType[] AcceptedTypes => new[] { CodeBulkType.Quest, }; public override void Read(CodeBulk codeBulk, Code code, ref Flow flow) { var quest = FromCodeTransformer.ReadQuest(codeBulk.Tree); //... sector.Quests.Add(quest); //... } } 

構文ツリーの分析と編集には、 Visitorパターン（ LINQ ）が積極的に使用されます。 後者は非常に不便で、非常に単純な分析に適しています。 プロジェクトコードでは、 SyntaxVisitor 、 SyntaxWalkerおよびSyntaxRewriterクラスを積極的に使用しました 。 最初の2つのユースケース-構文ツリーの分析。 たとえば、クエストをプロットに追加したり、静かに横になって誰にも触れないようにすることができます。 この特性を判断するには、クエストコンストラクターがどこかで呼び出されるかどうかを確認する必要があります。 Roslynを使用すると、これは非常に簡単です。SyntaxWalkerから継承し、すべてのObjectCreationExpressionを「訪問」します。

 // SyntaxWalker -  CSharpSyntaxWalker'a  .  private class QuestInitializationFinder : SyntaxWalker { //... public override void VisitObjectCreationExpression(ObjectCreationExpressionSyntax node) { base.VisitObjectCreationExpression(node); var model = Code.Compilation.GetSemanticModel(node.SyntaxTree); if (model.GetTypeInfo(node).Type == questTypeToFind) { //…. } } //... } 

構築されたモデルの表示。

そこで、モデルを作成しました。 それを表示したままにして、編集方法を学びます。

モデルマッピングは、 NShapeオープンライブラリを使用して実装されました。 このプロジェクトは習得が最も簡単で、機能が豊富であることが判明しました（ただし、拡張の機会がもっと必要な場合もあります...）。 クエストグラフの頂点を配置するために、 Microsoft Automatic Graph LayoutライブラリのSugiyamaアルゴリズムを使用しました。また、いくつかのヒューリスティックを作成する必要がありました。

最初のセクターでのクエストの例を挙げます。



初期化コードよりもはるかにユーザーフレンドリーに見えますよね？ （これはまだ非常に単純な例で、クエストはほとんどなく、線形の順序で初期化されています。）そして、ここにクエストロジックの表示があります（「プログラマー用」モードはコードを表示するためです。

モデルの編集[技術セクション]。

NShapeライブラリは 、ダイアグラムを作成および編集するように設計されています。 論理構造を図形式で表示したので、その（構造）視覚的編集の可能性があります。 主なことは、変更を正しく解釈し、無効な変更を禁止することです。

ダイアグラム上のアクションの論理アクションへの変換は、NShapeライブラリのツールの特別なラッパーで行われます（このコードを書くのはまだ喜びでした）。 論理モデルのコンテキストで何らかの意味を持つアクションのみが変換されます（たとえば、クエストを示す形状の回転は、表示方法の構造的な変更を意味しません）。 すべてのアクションはCommandタイプのオブジェクトにカプセル化され（ パターンを認識しましたか？）、元に戻すことができます。

 delegate void DoneHandler(bool firstTime); delegate void UndoneHandler(); interface ICommand { DoneHandler Done { get; set; } UndoneHandler Undone { get; set; } void Do(); void Undo(); } 

このインターフェイス（およびそれを実装する抽象クラス）は、論理モデルとコードの変更を担当します。 視覚的なプレゼンテーションは、Done / Undoneデリゲートへのサブスクリプションを通じて更新されます。


構文ツリーの編集には、上記のようにCSharpSyntaxRewriterクラスの拡張が使用されます（手法については、 こちらで詳しく説明されています ）。 クエストを無効にする例（コンストラクター呼び出しを削除する）：

 class DeactivateQuestCommand : Command { //… public override void Do() { var classDecls = codeBulk.Tree.GetRoot().DescendantNodes().OfType<ClassDeclarationSyntax>(); foreach (var classDecl in classDecls) { var typeRemover = new ClassConstructorCallRemover( Context.CodeEditor.GetSymbolFor(classDecl, codeBulk), Context.Code ); Context.CodeEditor.ApplySyntaxRewriter(typeRemover); } //... } //... } class ClassConstructorCallRemover : SyntaxRewriter { //… public override SyntaxNode VisitExpressionStatement(ExpressionStatementSyntax node) { var model = Compilation.GetSemanticModel(node.SyntaxTree); var expr = node.Expression; if (expr is ObjectCreationExpressionSyntax oces) { if (ReferenceEquals(model.GetTypeInfo(expr).Type, typeToRemove)) { return null; } } return base.VisitExpressionStatement(node); } public override SyntaxNode VisitLocalDeclarationStatement(LocalDeclarationStatementSyntax node) { if (node.Declaration.Variables.Count == 1) { var model = Compilation.GetSemanticModel(node.SyntaxTree); var type = model.GetTypeInfo(node.Declaration.Variables.First().Initializer.Value).Type; if (ReferenceEquals(type, typeToRemove)) { return null; } } return base.VisitLocalDeclarationStatement(node); } //... } 

Roslynには、すぐに使用できる編集機能がいくつか用意されています。 顕著な例は、名前の変更（ Renamer ）およびスペースのフォーマット（ Formatter ）です。 そして、それは人生を大いに簡素化します。
現時点では、既存のコードを削除/変更したという事実のみを扱いました。 そして、新しい世代はどうですか？ これは、 SyntaxFactory .Parse *およびノー​​ド変更関数を介して簡単に実行されます。

 var linkExprText = $"ReachedCondition = {newLinkText}"; var newInitializer = node.Initializer.AddExpressions(SyntaxFactory.ParseExpression(linkExprText)); 

お気づきかもしれませんが（2行目を注意深く見ると）、AddExpressions関数は新しいノードを返します。 一般に、Roslyn全体はアーキテクチャの機能的アプローチに従います。何かを変更する場合は、必要なパラメーターを使用して新しいものを作成します。 最初は不便ですが、それからあなたはそれを愛し始めます。


このようなコードを作成するには、文法（確認/編集/作成する必要がある構文単位の種類）とRoslyn APIの十分な知識が必要です。 しかし、必要なものがすべて揃った後、Roslynを使用したプログラミングは楽しいものになります（特にアーキテクチャの点で、私は美しいコードと機能の大ファンです）。

エディターの機能とトレードオフ。 実用的な例。

これまで、エディターとその機能についてはほとんど言及されていませんでした。 状況を修正しましょう：最後に、正確に編集できる内容、機能の豊富さと複雑さのバランスをとるためにどのような妥協が必要かを議論し、実際の実践からの例を検討します（多少簡略化されていますが）。

そこで、コードを編集することにしました。 言葉遣いは非常に怖いことを認めています。 ここでは、人々はいつも本来のように書くとは限りませんが、他のコードを分析して変更 するプログラムを書く必要があります。 そして、それは必ずしも私たちによって書かれているわけではありません。 制限なしではできません。

私が最初に説明したいのは、解釈方法がわからないコードを見つけた場合のエディターの動作です：プログラマーの内部の問題、ハッキング、プロジェクトに入るかどうかを正確に言うことができない新機能など。 。 この状況は非常に慎重に「解決」する必要があります。 そうしないと、ツールは良いことよりも害になります。

この問題をどのように解決しましたか？ あなたが理解していないことで遊ばないでください。 理解するということは、コードの論理的な意味に関するプログラムの知識を意味します。 抽象的すぎる？ 以下に例をいくつか示します。

最初の例。 クエストは、次のレベルだけでなく、3つのレベルが完了した後にもアクティブにする必要があります。 または5。 そして、ユーザーが毎日の報酬を与えられた後でも。 一般的に、いくつかの追加条件があります。 一般的なケースでは、エディターからそのような条件を指定することはできません。プログラマーの介入が必要です。 さて、プログラマーはついに自分自身を解放し、コードに数行を追加しました。 次は？ まず、エディターはこれを図に表示します。



ユーザーは、このクエストではそれほど簡単ではないことがすぐにわかります。 第二に、未知の（エディターによってソートされていない）条件を編集することは禁止されています。 できることの最大は、ソースコードとそこに残されたコメントを読むことです（便利な機能-プログラマーがコードの意味を未経験者に説明できるようにします）。 第三に、 新しい条件の追加のみが許可されます（そしてもちろん、それらの編集と削除）。 すなわち 条件がより厳しくなり、エディターが許可する範囲内になる可能性があります。

2番目の例。 クエストのロジック（アクション）の再構築されていないコード。 おそらく最も一般的な状況。 ここでの哲学は同じです：編集を許可せず、銘板に目立たない警告を表示します （一般に、アセンブルされていないコードを非表示/表示するチェックマークがあります）。

2番目に議論することは、実行スレッドの編集です。 たとえば、クエストの1つにはロジックの一部があり、それ自体はオプションであり、特定の不可分な条件によってのみ起動されます。 編集を完全に禁止するのは愚かなことです。 したがって、この可能性をユーザーに任せることが決定されましたが、いくつかの注意事項があります：開始条件（if、whileの条件）の編集は許可されず、一般的なケースではブロック全体を移動します（はい、苦い真実-移動はコンパイルを中断するかさらに悪いことに、ロジックを変更することは明らかではありません）。 ロジックを移動する必要がありますか？ 2つのオプション：ユニットをオフにして適切な場所に新しいユニットを作成するか、プログラマにタスクを与えます。

次に、簡単な例を示して説明します。 ゲームデザイナーは、FindKeyクエストとOpenTheDoorクエストの間にTalkToLeeroyクエストを挿入します。 クエストでは、カットシーンを表示し、クエストの直接通過を待ってから、2番目のカットシーンを表示して、クエストを完了します。 ゲームデザイナーのアクションのアルゴリズム（彼に代わって）：

1. 新しいクエストを挿入する必要があるクエストを見つけます：
   
2. 目的の名前で新しいクエストを追加し、接続をスローします。
   
3. クエスト編集ウィンドウを開き、必要な状態を追加します。
   
4. 次に、各状態に必要なアクションを入力します。 たとえば、初期状態のタスクは、最初のカットシーンを表示することです。
   
5. 類推により、残りの状態が満たされます。
6. エラーが突然検出された場合（たとえば、インターフェイスを隠して表示するのを忘れた場合）、これについて視覚的に警告されます（図に特別なマークが表示されます）。 エラーを修正します。
7. ゲームを開始し、すべてが意図したとおりに機能することを確認します。

だから、タスクは完了し、うれしそうなデザイナーは静かにテストのために彼女を送り、お茶を飲むために去ります。

エディターの目的は、コンテンツのプロトタイプをすばやく作成して入力することでした。最終的には、ゲームのロジック（仮想世界の小さな王と神）に対する絶対的な力を持つのはプログラマだけです。ツールを大幅に複雑化するのではなく、ゲームの機能を洗練/改良するタスクを彼に与える方が安価です（したがって、より適切です）。そして、それはそのような状況にそれほど近くありません：

おわりに

私はすべてとはほど遠いことを述べてきました。いくつかの点（エラーの分析と視覚化、セクターの操作など）を省略しなければなりませんでした。興味があれば、コメントを書いて、おそらく別の記事を書くでしょう。これの目的は、ゲーム開発にあまり関係がないと思われるそのようなツールでさえ、実際にうまく適用できることを示すことでした。
最終的に行われたもの：

1. 時には仕事を加速
2. ゲームの構造とアーキテクチャの改善
3. 著者はRoslynを研究し、C＃の知識を深め、設計スキルを向上させました。

Roslynを学習と使用に推奨しますか？ もちろん。 辛抱強く行きましょう。