If you’ve been following this series, you’ll know we’ve been incrementally building out the Iron Mind AI personal trainer agent.

We’ve added function tools, agents as function tools, human-in-the-loop checkpoints, contextual memory, background responses, MCP tool support, and email marketing capabilities.

In this post, we take a different direction and look at how to give your AI agent access to your own documents using Retrieval Augmented Generation (RAG).

Instead of relying solely on the LLM’s training data, the agent searches a vector store before each response and grounds its answers in your content.

~

Why RAG Matters for AI Agents

LLMs are powerful but they have a fundamental limitation, they only know what they were trained on.

They can’t access your internal documentation, product guides, company policies, or domain-specific knowledge.

RAG solves this by retrieving relevant documents at runtime and injecting them into the model’s context. The result is an agent that answers questions using your data, not generic knowledge.

This is useful when you want your agent to:

• Answer questions grounded in specific documentation
• Cite sources so users can verify information
• Avoid hallucination by constraining responses to known content

RAG also helps your agent stay current without retraining the underlying model

~

How It Works

The Microsoft Agent Framework provides a TextSearchProvider that hooks into the agent’s execution pipeline. Before each model invocation, it runs a vector search against your document store and injects the matching results into the conversation as additional context messages.

The flow works like this:

1. User asks a question
2. TextSearchProvider converts the question into an embedding
3. The embedding is compared against document embeddings in the vector store
4. The top matching documents are injected into the model context
5. The LLM generates a response grounded in the retrieved documents

For this example, we use the InMemoryVectorStore from the Microsoft.SemanticKernel.Connectors.InMemory NuGet package.

We’re using this because at the time of writing, the Microsoft Agent Framework doesn’t ship with its own vector store connector.

Instead, the Microsoft Agent Framework delegates storage to the Microsoft.Extensions.VectorData abstractions.

These define the interfaces but contain no implementations.  The Semantic Kernel connector packages ship with standard implementations for this interface.

Note: We’re not using the Semantic Kernel framework itself, just this one connector package for its in-memory vector store implementation.

In a production scenario, you could swap this out for any vector store that implements these same abstractions, such as Azure AI Search, Qdrant, or Pinecone.

~

Project Structure

The project follows the same structure we’ve used throughout this series, with an Agents/ folder to keep agent logic separate from the entry point:

├── Agent-Framework-9-Basic-RAG.csproj
├── Program.cs
├── Agents/
│   └── IronMindRagAgent.cs
├── TextSearchStore.cs
└── TextSearchDocument.cs

• Program.cs is lean and handles only the OpenAI client setup and the chat loop
• IronMindRagAgent.cs encapsulates the vector store setup, search logic, and agent configuration
• TextSearchStore.cs wraps the in-memory vector store with a clean API for upserting documents and running searches
• TextSearchDocument.cs defines the document model

With an overview of the project structure, lets look at the project definition.

~

Setting Up the Project

The project targets .NET 8.0 and uses the following NuGet packages:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <RootNamespace>Agent_Framework_9_Basic_RAG</RootNamespace>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>


  <ItemGroup>
   <PackageReference Include="Microsoft.Agents.AI" Version="1.0.0-preview.260205.1" />
    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-preview.260205.1" />
    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="10.2.0-preview.1.26063.2" />
    <PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
    <PackageReference Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.66.0-preview" />
    <PackageReference Include="OpenAI" Version="2.8.0" />
    <PackageReference Include="System.ClientModel" Version="1.8.1" />
  </ItemGroup>
</Project>

Some key packages to note include:

• Microsoft.Agents.AI provides the TextSearchProvider, AIAgent, and ChatClientAgentOptions
• Microsoft.Agents.AI.OpenAI provides the .AsAIAgent() extension method for OpenAI’s ChatClient
• Microsoft.Extensions.AI.OpenAI provides .AsIEmbeddingGenerator() to convert OpenAI’s embedding client into the standard IEmbeddingGenerator interface
• Microsoft.Extensions.VectorData.Abstractions defines the vector store abstractions (VectorStoreCollection, etc.)
• Microsoft.SemanticKernel.Connectors.InMemory provides the InMemoryVectorStore implementation

Now let’s dig into the required models.

~

Defining the Document Model

First, we need a simple model to represent the documents we want to store and search:

public class TextSearchDocument
{
    public string SourceId { get; set; } = string.Empty;
    public string SourceName { get; set; } = string.Empty;
    public string SourceLink { get; set; } = string.Empty;
    public string Text { get; set; } = string.Empty;
}

Each document has an identifier, a human-readable source name, a link for citation purposes, and the actual text content.

~

Building the TextSearchStore

The TextSearchStore wraps the in-memory vector store and provides a clean API for upserting documents and running searches:

using Microsoft.Extensions.VectorData;
using Microsoft.SemanticKernel.Connectors.InMemory;
namespace Agent_Framework_9_Basic_RAG;

public class TextSearchStore
{
    private readonly VectorStoreCollection<string, TextSearchRecord> _collection;


    public TextSearchStore(InMemoryVectorStore vectorStore, string collectionName, int dimensions)
    {
        var definition = new VectorStoreCollectionDefinition
        {
            Properties =
            [
                new VectorStoreKeyProperty("SourceId", typeof(string)),
                new VectorStoreDataProperty("SourceName", typeof(string)),
                new VectorStoreDataProperty("SourceLink", typeof(string)),
                new VectorStoreDataProperty("Text", typeof(string)),
                new VectorStoreVectorProperty("Embedding", typeof(string), dimensions),
            ]
        };
        _collection = vectorStore.GetCollection<string, TextSearchRecord>(collectionName, definition);
    }


    public async Task UpsertDocumentsAsync(IEnumerable<TextSearchDocument> documents)
    {
        await _collection.EnsureCollectionExistsAsync();


        foreach (var doc in documents)
        {
            var record = new TextSearchRecord
            {
                SourceId = doc.SourceId,
                SourceName = doc.SourceName,
                SourceLink = doc.SourceLink,
                Text = doc.Text,
                Embedding = doc.Text
            };
            await _collection.UpsertAsync(record);
        }
    }


    public async Task<IEnumerable<TextSearchDocument>> SearchAsync(
        string query, int topK, CancellationToken cancellationToken = default)
    {
        var results = _collection.SearchAsync(query, topK, cancellationToken: cancellationToken);


        var documents = new List<TextSearchDocument>();
        await foreach (var result in results)
        {
            documents.Add(new TextSearchDocument
            {
                SourceId = result.Record.SourceId,
                SourceName = result.Record.SourceName,
                SourceLink = result.Record.SourceLink,
                Text = result.Record.Text
            });
        }

        return documents;
    }
}

A few important things to note here:

• The VectorStoreCollectionDefinition defines the schema for the collection, including the vector property with its dimensions (3072 for text-embedding-3-large)
• The Embedding property is typed as string, not ReadOnlyMemory<float>. This is important. When you set the Embedding to the document text and the vector store has an EmbeddingGenerator configured, it automatically converts the text to a vector embedding during upsert. The same happens during search when you pass a string query. If you use ReadOnlyMemory<float> instead, the embeddings won’t be generated and you’ll get a dimension mismatch error at search time
• The TextSearchRecord is an internal model that includes the Embedding property, while TextSearchDocument is the public-facing model

The internal record type:

public class TextSearchRecord
{
    public string SourceId { get; set; } = string.Empty;
    public string SourceName { get; set; } = string.Empty;
    public string SourceLink { get; set; } = string.Empty;
    public string Text { get; set; } = string.Empty;
    public string Embedding { get; set; } = string.Empty;
}

This is used to represent vectorised content.

~

Creating the Sample Documents

For this example, we use three Iron Mind AI personal trainer documents covering beginner training, nutrition, and recovery. These are defined as a static method on TextSearchStore:

public static IEnumerable<TextSearchDocument> GetSampleDocuments()
{
    yield return new TextSearchDocument
    {
        SourceId = "beginner-strength-001",
        SourceName = "Iron Mind AI - Beginner Strength Training Guide",
        SourceLink = "https://ironmindai.com/tips/beginner-strength",
        Text = "For beginners, focus on compound movements like squats, deadlifts, bench press, " +
               "and overhead press. Train 3-4 days per week with at least one rest day between " +
               "sessions. Start with a weight you can control for 8-12 reps with good form. " +
               "Progressive overload is key - aim to gradually increase weight, reps, or sets " +
               "over time. Consistency beats intensity in the early stages."
    };
    yield return new TextSearchDocument
    {
        SourceId = "nutrition-basics-001",
        SourceName = "Iron Mind AI - Nutrition for Muscle Growth",
        SourceLink = "https://ironmindai.com/tips/nutrition-muscle-growth",
        Text = "To support muscle growth, aim for 1.6 to 2.2 grams of protein per kilogram of " +
               "body weight per day. Spread protein intake across 3-5 meals for optimal muscle " +
               "protein synthesis. Prioritize whole food sources like chicken, fish, eggs, Greek " +
               "yogurt, and legumes. Don't neglect carbohydrates - they fuel your workouts and " +
               "aid recovery. A slight caloric surplus of 200-300 calories above maintenance is " +
               "ideal for lean muscle gain."
    };
    yield return new TextSearchDocument
    {
        SourceId = "recovery-sleep-001",
        SourceName = "Iron Mind AI - Recovery and Sleep Guide",
        SourceLink = "https://ironmindai.com/tips/recovery-sleep",
        Text = "Sleep is when your body repairs and builds muscle tissue. Aim for 7-9 hours of " +
               "quality sleep per night. Poor sleep increases cortisol levels, which can impair " +
               "muscle recovery and promote fat storage. Establish a consistent sleep schedule, " +
               "limit screen time before bed, and keep your room cool and dark. Active recovery " +
               "on rest days - such as walking, stretching, or light yoga - also helps reduce " +
               "soreness and improve circulation."
    };
}

In a real-world scenario, these documents would come from a database, CMS, file system, or an external API.

~

The IronMindRagAgent

This is where the RAG logic lives. The IronMindRagAgent class encapsulates the vector store setup, the search adapter, and the agent configuration.

This keeps Program.cs clean and follows the same Agents/ folder convention used across the other projects in this series.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.SemanticKernel.Connectors.InMemory;
using OpenAI;
using OpenAI.Chat;


namespace Agent_Framework_9_Basic_RAG.Agents;

public class IronMindRagAgent
{
    private const int EmbeddingDimensions = 3072;
    private const string CollectionName = "iron-mind-ai-tips";

    private readonly TextSearchStore _textSearchStore;

    public IronMindRagAgent(OpenAIClient openAIClient, string embeddingModel)
    {
        var vectorStore = new InMemoryVectorStore(new()
        {
            EmbeddingGenerator = openAIClient.GetEmbeddingClient(embeddingModel).AsIEmbeddingGenerator()
        });

        _textSearchStore = new TextSearchStore(vectorStore, CollectionName, EmbeddingDimensions);
    }


    public async Task<AIAgent> CreateAgentAsync(OpenAIClient openAIClient, string model)
    {
        await _textSearchStore.UpsertDocumentsAsync(TextSearchStore.GetSampleDocuments());

        var textSearchOptions = new TextSearchProviderOptions
        {
            SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
            CitationsPrompt = "Always cite sources at the end of your response using the format: " +
                              "**Source:** [SourceName](SourceLink)",
        };


        return openAIClient
            .GetChatClient(model)
            .AsAIAgent(new ChatClientAgentOptions
            {
                ChatOptions = new()
                {
                    Instructions = "You are Iron Mind AI, a knowledgeable personal trainer. " +
                                   "You MUST base your answers on the provided context documents. " +
                                   "Always cite your sources by name and link at the end of your response. " +
                                   "If the context does not contain relevant information, say so."
                },

                AIContextProviderFactory = (ctx, ct) => new ValueTask<AIContextProvider>(
                    new TextSearchProvider(SearchAsync, ctx.SerializedState,
                                          ctx.JsonSerializerOptions, textSearchOptions)),
                ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
                    new InMemoryChatHistoryProvider().WithAIContextProviderMessageRemoval()),
            });
    }


    private async Task<IEnumerable<TextSearchProvider.TextSearchResult>> SearchAsync(
        string text, CancellationToken ct)
    {
        var searchResults = await _textSearchStore.SearchAsync(text, 2, ct);
        return searchResults.Select(r => new TextSearchProvider.TextSearchResult
        {
            SourceName = r.SourceName,
            SourceLink = r.SourceLink,
            Text = r.Text,
            RawRepresentation = r
        });

    }
}

Let’s walk through the key parts.

~

The Constructor

The constructor takes the OpenAIClient and the embedding model name. It creates the in-memory vector store with the OpenAI embedding generator and initialises the TextSearchStore:

public IronMindRagAgent(OpenAIClient openAIClient, string embeddingModel)
{
    var vectorStore = new InMemoryVectorStore(new()
    {
        EmbeddingGenerator = openAIClient.GetEmbeddingClient(embeddingModel).AsIEmbeddingGenerator()
    });

    _textSearchStore = new TextSearchStore(vectorStore, CollectionName, EmbeddingDimensions);
}

The .AsIEmbeddingGenerator() extension converts OpenAI’s embedding client into the standard IEmbeddingGenerator interface from Microsoft.Extensions.AI.

This embedding generator is used automatically during both upsert (to convert document text into vectors) and search (to convert the query into a vector).

~

CreateAgentAsync

This method loads the sample documents into the vector store, configures the TextSearchProvider, and builds the agent:

public async Task<AIAgent> CreateAgentAsync(OpenAIClient openAIClient, string model)
{
    await _textSearchStore.UpsertDocumentsAsync(TextSearchStore.GetSampleDocuments());

    var textSearchOptions = new TextSearchProviderOptions
    {
        SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
        CitationsPrompt = "Always cite sources at the end of your response using the format: " +
                          "**Source:** [SourceName](SourceLink)",
    };


    return openAIClient
        .GetChatClient(model)
        .AsAIAgent(new ChatClientAgentOptions { ... });
}

Two options control the RAG behaviour:

• SearchTime = BeforeAIInvoke tells the provider to automatically run a search before every model invocation and inject the results as context messages
• CitationsPrompt provides explicit instructions to the model on how to format source citations

An alternative to BeforeAIInvoke is OnDemandFunctionCalling, which exposes the search as a function tool that the model can choose to invoke when it decides it needs more information.

~

The Agent Configuration

The AIContextProviderFactory creates a new TextSearchProvider instance for each session. The SearchAsync method is passed as a method group reference rather than an inline delegate, keeping the code clean and readable.

The ctx.SerializedState and ctx.JsonSerializerOptions parameters support session serialisation, allowing the provider’s state to be persisted and restored.

The ChatHistoryProviderFactory creates an InMemoryChatHistoryProvider with .WithAIContextProviderMessageRemoval().

This is important because without it, every search result message would accumulate in the chat history, bloating the context window over a multi-turn conversation.

Notice the system instructions explicitly tell the model to base answers on the provided context and cite sources.

Without strong instructions, the model may fall back to its general training data and ignore the injected documents.

~

The Search Adapter

The TextSearchProvider doesn’t talk to the vector store directly. Instead, it calls the SearchAsync method that you provide.

This gives you full control over how searches are executed:

private async Task<IEnumerable<TextSearchProvider.TextSearchResult>> SearchAsync( string text, CancellationToken ct)
{
    var searchResults = await _textSearchStore.SearchAsync(text, 2, ct);
    return searchResults.Select(r => new TextSearchProvider.TextSearchResult
    {
        SourceName = r.SourceName,
        SourceLink = r.SourceLink,
        Text = r.Text,
        RawRepresentation = r
    });
}

We return the top 2 results per query. You can adjust this based on how much context you want to provide to the model.

~

Program.cs

With all the RAG logic encapsulated in the agent class, Program.cs is minimal:

using Agent_Framework_9_Basic_RAG.Agents;
using OpenAI;


string apiKey = "your-openai-api-key";
string model = "gpt-4o-mini";
string embeddingModel = "text-embedding-3-large";

OpenAIClient openAIClient = new(apiKey);

var ironMind = new IronMindRagAgent(openAIClient, embeddingModel);
var agent = await ironMind.CreateAgentAsync(openAIClient, model);
var session = await agent.CreateSessionAsync();

Console.WriteLine("Iron Mind AI - Personal Trainer");
Console.WriteLine("Ask me anything about training, nutrition, or recovery. Type 'exit' to quit.\n");

while (true)
{
    Console.Write("You: ");
    string? input = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
        break;


    Console.WriteLine();
    Console.WriteLine(await agent.RunAsync(input, session));
    Console.WriteLine();
}

Three lines to set up the agent. The rest is the chat loop. All vector store configuration, document loading, search logic, and prompt engineering lives inside IronMindRagAgent.

~

Example Output

Here’s what a conversation with the RAG-enabled agent looks like in action:

An example from the console output:

Iron Mind AI - Personal Trainer

Ask me anything about training, nutrition, or recovery. Type 'exit' to quit.


You: as a beginner, what can i do?


As a beginner in strength training, here are some key steps you can follow:


**Focus on Compound Movements**: Start with exercises like squats, deadlifts,

   bench presses, and overhead presses. These movements engage multiple muscle groups,

   which is great for building strength effectively.


**Training Frequency**: Aim to train 3-4 days per week. Ensure you have at least

   one rest day between sessions to allow your muscles to recover.


**Start with Manageable Weights**: Choose a weight that you can control for 8-12

   repetitions while maintaining good form.


**Progressive Overload**: Gradually increase the weight, number of repetitions,

   or sets over time.


**Consistency Over Intensity**: In the beginning, it's better to focus on being

   consistent with your workouts rather than pushing yourself too hard.


**Prioritize Recovery and Sleep**: Aim for 7-9 hours of quality sleep per night,

   as this is when your body repairs and builds muscle tissue.


**Source:** [Iron Mind AI - Beginner Strength Training Guide](https://ironmindai.com/tips/beginner-strength),

[Iron Mind AI - Recovery and Sleep Guide](https://ironmindai.com/tips/recovery-sleep)

The agent pulls from the relevant documents, synthesises a coherent answer, and cites the sources at the end. This is the key benefit of RAG: the response is grounded in your content, not hallucinated from general training data.

~

Demo

In the following demo, we can see the “RAG-fied” Iron Mind AI personal trainer agent in action:

~

Wrapping Up

In this post we looked at how to add RAG capabilities to a Microsoft Agent Framework agent using TextSearchProvider and an in-memory vector store. The key takeaways:

• TextSearchProvider integrates directly into the agent pipeline, running searches before each model invocation
• In-Memory Vector Store with an EmbeddingGenerator handles embedding generation automatically during both upsert and search
• The vector property should be typed as string (not ReadOnlyMemory<float>) to enable automatic embedding generation
• Strong system instructions are essential to ensure the model uses the provided context rather than falling back to general knowledge
• CitationsPrompt on TextSearchProviderOptions tells the model how to format source citations
• WithAIContextProviderMessageRemoval() prevents search result messages from bloating the chat history
• Encapsulating the RAG logic in a dedicated agent class keeps Program.cs lean and followsgood separation of concerns

The in-memory vector store used here is great for prototyping and demos.

For production workloads, you would swap it for a persistent vector store such as Azure AI Search, Qdrant, Weaviate, or Pinecone.

The Microsoft.Extensions.VectorData abstractions make this a straightforward change.

If you have any questions, feel free to reach out.

~

Enjoy what you’ve read, have questions about this content, or would like to see another topic?

Drop me a note below.

You can schedule a call using my Calendly link to discuss consulting and development services.

I was today years old when I realized that:

• Code and code comments ideally should be wrapped to a different column.
• For comments, the width should be relative to the start of the comment.

It’s a good idea to limit line length to about 100 columns. This is a physical limit, the width at which you can still comfortably fit two editors side by side (see Size Matters). Note an apparent contradiction: the optimal width for readable prose is usually taken to be narrower, 60–70 columns. The contradiction is resolved by noticing that, for code, indentation eats into usable space. Typically, code is much less typographically dense than prose.

Still, I find comment blocks easier to read when they are wrapped narrower than the surrounding code. I want lines to be wrapped at 100, and content of comments to be wrapped at 70 (unless that pushes overall line to be longer than 100). That is, I want layout like this (using 20/30 rulers instead of 70/100, for illustrative purposes):

// Top level comments
// can be this wide.
const S = struct {
    // Nested comments are
    // also this wide, but
    // are shifted right.
    fn f() void {
        switch (value) {
            0 => {
                // But there is
                // a hard limit.
            }
        }
    }
}

This feels obvious in retrospect, but notably isn’t be well-supported by the tools? The VS Code extension I use allows configuring dedicated fill column for comments, but doesn’t make it relative, so indented comment blocks are always narrower than top-level ones. Emacs M-q also doesn’t do relative wrapping out of the box!

Aside on hard-wrapping: should we bother with wrapping comments at all? Can’t we rely on our editor to implement soft-wrapping? The problem with soft-wrapping is that you can’t soft-wrap text correctly without understanding its meaning. Consider a markdown list:

A list:
  * item one,
  * item two.

If the first item is long enough to necessitate wrapping, the wrapped line should also be indented, which requires parsing the text as markdown first:

A list:
  * item one which is long enough
    necessitate wrapping,
  * item two.

How many times have you rewritten the same systems across different Unity projects? Or copied entire folders from an old project, only to spend hours fixing references, renaming namespaces, and adapting the code to fit a slightly different architecture?

That repetition doesn’t just waste time – it slows down your development and creates maintenance headaches across projects.

This guide walks you through a set of reusable, modular Unity packages you can drop into any project to speed up development. You’ll build them once as packages and install them via Git wherever you need them, instead of reimplementing the same systems every time.

The article covers four core packages:

1. com.core.initializer – Finds and initializes your game controllers at runtime (MVC-style) so startup and dependencies centralized.

2. com.core.data – Handles local (and optionally cloud) save data using MemoryPack binary serialization and a provider abstraction so you can switch or extend storage backends.

3. com.core.ui – Manages popups and full-screen UIs in a consistent way so you can show dialogs, panels, and screens without duplicating logic.

4. com.core.dotween – Wraps the DoTween tween engine as a Unity package so com.core.ui (and other packages) can reference it for animations.

In this tutorial, we’ll build all four packages step by step. The Initializer, Data, UI, and DoTween packages are all documented so you can easily follow along. All packages are also upload to github which you can find the links at the end.

Table of Contents

• What You Will Learn

• Prerequisites

• Set Up Your Development Project

• Package 1: The Initializer Package

• Package 2: The Data Package

• Package 3: The DoTween Package

• Package 4: The UI Package

• Summary

What You Will Learn

• How to create a Unity package with the Package Manager

• How to set up the package structure

• How to built a centralized initialization flow for your packages

• How to use UniTask for async initialization on Unity's main thread

• How the Data package uses IDataProvider and MemoryPack for local save/load

• How the UI package uses popups (stack) and screens (single active) with DoTween animations

Prerequisites

Before you start, make sure you have:

• Unity installed (any Long Term Support version compatible with the packages. The referenced packages target Unity 6000.3)

• Git installed

• Jetbrains Rider or Visual Studio Community installed

• Know how to use Unity game engine

• Know C# and async/await structures

You will use the Unity Package Manager to create packages, then upload and install them via Git in other projects.

Set Up Your Development Project

Create a new Unity project if you don’t already have one. We’ll use it as a playground to build and test your packages. This project (and not the packages themselves) is your development environment.

Package 1: The Initializer

The first package is com.core.initializer. It finds all your controllers, runs their async initialization before the first scene loads, and lets the rest of the game access them via a single handler.

What com.core.initializer Does

• Early initialization: Runs at RuntimeInitializeLoadType.BeforeSceneLoad, so all controllers exist and are initialized before the first scene loads.

• Central access: Stores each controller by its type and exposes them through a type-safe getter.

• Completion signaling: Exposes a static event (ControllersInitialized) and a UniTaskCompletionSource (InitializationCompleted) so you can run code only after all controllers have finished initializing.

Create the Initializer Package

To start, open Window → Package Manager (under Package Management). Then click the + button and choose Create package.

Name the package com.core.initializer (or your preferred name).

Unity creates the essential package files for you.

You can edit package.json and the assembly definition (asmdef) names to match your naming. The full set of changes is not listed here. The final package is available on GitHub (linked at the end).

Add the UniTask Dependency

Unity runs on the main thread, and C# Tasks can be problematic in that context. They don’t know about the Unity Editor's play state and keep running after exiting play mode for example. So you’ll need to handle these cases manually. For these reasons, this package uses UniTask instead of C# Tasks for async operations.

Git-based dependencies are supported at the project level but not at the package level. Add UniTask via OpenUPM by following the manual installation steps.

Add UniTask as a dependency in package.json of initializer package:

"dependencies": {
  "com.cysharp.unitask": "2.5.10"
}

Also reference UniTask in the asmdef file.

You’ll need to follow this dependency flow for the rest of the packages you create.

Implement the Package Structure

The initializer uses an MVC-like architecture. Controllers handle both initialization and game logic. You could later split initialization into services and keep business logic in controllers (for example, an MVCS-style setup). This tutorial keeps things simple and uses only controllers.

Target layout:

• Runtime/Interface/ – IController

• Runtime/Helper/ – Creator (reflection-based instance creation)

• Runtime/ – ControllerHandler (orchestrates initialization)

All controllers implement the IController interface. The Initialize method returns a UniTask so initialization can be async on the main thread.

using Cysharp.Threading.Tasks;

namespace com.core.initializer
{
    public interface IController
    {
        bool IsInitialized { get; }

        UniTask Initialize();
    }
}

Create the Creator Helper

You’ll need to find all types that implement IController, create instances of them at runtime, and also find MonoBehaviours that implement IController (since those cannot be created via reflection). The Creator class does both.

using System;
using System.Collections.Generic;
using System.Linq;
using UnityEngine;

namespace com.core.initializer
{
    public static class Creator
    {
        /// <summary>
        /// Creates instances of every type which inherits from T interface.
        /// </summary>
        public static IEnumerable<T> CreateInstancesOfType<T>(params Type[] exceptTypes)
        {
            var interfaceType = typeof(T);

            var result = AppDomain.CurrentDomain.GetAssemblies().SelectMany(x => x.GetTypes()).Where
                (
                 x => interfaceType.IsAssignableFrom(x) &&
                      !x.IsInterface                    &&
                      !x.IsAbstract                     &&
                      exceptTypes.All(type => !x.IsSubclassOf(type) && x != type)
                ).Select(Activator.CreateInstance);

            return result.Cast<T>();
        }

        public static IEnumerable<T> GetMonoControllers<T>() => UnityEngine.Object.FindObjectsByType<MonoBehaviour>(FindObjectsInactive.Include, FindObjectsSortMode.None).OfType<T>();
    }
}

Using reflection at runtime has some overhead. You can optimize this later with baking the reflection in editor and using it at runtime. For MonoBehaviours, FindObjectsByType is used here for simplicity. In a larger project, you might use a dependency injection solution such as VContainer or Reflex.

Implement the ControllerHandler

The ControllerHandler uses Creator to gather all IController instances (both reflection-created and MonoBehaviours), initializes them in order, and exposes an event and a UniTaskCompletionSource so the rest of the game can wait for startup to finish.

using System;
using System.Collections.Generic;
using System.Linq;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.initializer
{
    public class ControllerHandler
    {
        public static readonly UniTaskCompletionSource InitializationCompleted = new();

        public static event Action ControllersInitialized;

        private static Dictionary<Type, IController> _controllers = new();

        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
        public static async void Initialize()
        {
            var controllers = Creator.CreateInstancesOfType<IController>(typeof(MonoBehaviour)).ToList();
            controllers.AddRange(Creator.GetMonoControllers<IController>());

            Debug.Log("Initializing controller");

            foreach (var controller in controllers)
            {
                Debug.Log($"<color=yellow>Initializing {controller.GetType().Name}</color>");
                await controller.Initialize();
                _controllers.Add(controller.GetType(), controller);
                Debug.Log($"<color=green>Initialized {controller.GetType().Name}</color>");
            }

            Debug.Log("<color=green>All controllers are initialized</color>");
            ControllersInitialized?.Invoke();
            InitializationCompleted?.TrySetResult();
        }

        public static T GetController<T>() where T : class, IController => _controllers[typeof(T)] as T;
    }
}

How to Test the Initializer

1. Create a class that implements IController (or a MonoBehaviour that implements it).

2. Implement Initialize() with your setup logic (you can use await and UniTask).

3. After initialization, access the controller with:
   var myController = ControllerHandler.GetController<MyController>();

You can also subscribe to ControllerHandler.ControllersInitialized or await ControllerHandler.InitializationCompleted.Task to run code after all controllers are ready.

There are some limitations here. First, it can be hard to handle dependencies between different controllers. Second, it’s easy to run into circular dependencies.

When you check the GitHub repo, a DI framework may already be implemented to address these limitations. Make sure to open an issue if you want this feature.

Package 2: The Data Package

com.core.data handles local saving with a binary serializer. The package uses MemoryPack for fast, binary serialization and defines an IDataProvider interface so you can plug in different providers (local, cloud, or hybrid).

Package dependency: com.cysharp.memorypack (version 1.10.0). Add it to your project via OpenUPM and add it to package.json and the asmdef for com.core.data.

Create a new package and name it com.core.data. Use a structure such as:

• Runtime/Interface/ – IDataProvider

• Runtime/Providers/ – LocalDataProvider

• Runtime/ – optional sample DataController (in your game assembly) that implements IController and uses an IDataProvider

All data providers use the IDataProvider interface.

using Cysharp.Threading.Tasks;

namespace com.core.data
{
    public interface IDataProvider
    {
        bool     IsInitialized { get; }
        void     Save<T>(string key, T data);
        T        Load<T>(string key, T defaultValue = default);
        bool     HasKey(string  key);
        string[] GetKeys();
        UniTask  Delete(string key);
        UniTask  DeleteAll();
    }
}

You will use UniTask in the data package as well. Add com.cysharp.unitask to package.json since both IController and IDataProvider uses it.

Here’s the DataController:

using System;
using System.Collections.Generic;
using System.Text;
using com.core.data;
using com.core.initializer;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.data
{
    public class DataController : IController
    {
        private const string PLAYER_VERSION_KEY = "player-version-key";

        private IDataProvider _provider;

        public bool IsInitialized { get; private set; }

        public UniTask Initialize()
        {
            _provider = new LocalDataProvider();
            SaveUserVersion();
            IsInitialized = true;
            return UniTask.CompletedTask;
        }

        private void SaveUserVersion()
        {
            var versionHistory = Load(PLAYER_VERSION_KEY, new List<string>());
            var sb             = new StringBuilder();
            versionHistory.ForEach(vh => sb.Append(vh + Environment.NewLine));
            Debug.Log($"[DataController] Player version history: {sb}");

            if (!versionHistory.Contains(Application.version))
            {
                Debug.Log($"[DataController] Player's current version: {Application.version}");
                versionHistory.Add(Application.version);
                Save(PLAYER_VERSION_KEY, versionHistory);
            }
        }

        public void Save<T>(string key, T data) => _provider.Save(key, data);

        public T Load<T>(string key, T defaultValue = default) => _provider.Load(key, defaultValue);

        public bool         HasKey(string key)  => _provider.HasKey(key);
        public string[]     GetKeys()           => _provider.GetKeys();
        public UniTask      Delete(string key)  => _provider.Delete(key);
        public UniTask      DeleteAll()         => _provider.DeleteAll();
        public List<string> GetVersionHistory() => Load(PLAYER_VERSION_KEY, new List<string>());
    }
}

The controller delegates all logic to LocalDataProvider, which uses MemoryPack to serialize and write bytes to a "Data" folder under Application.persistentDataPath. The controller also keeps the user's app version history, which is useful for upgrade prompts or blocking old versions.

Here’s the full implementation:

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using Cysharp.Threading.Tasks;
using MemoryPack;
using UnityEngine;

namespace com.core.data
{
    public class LocalDataProvider : IDataProvider
    {
        private const    string StorageFolderName = "Data";
        private readonly string _storagePath;

        private static readonly UTF8Encoding KeyEncoding = new(false);

        public bool IsInitialized => true;

        public LocalDataProvider()
        {
            _storagePath = Path.Combine(Application.persistentDataPath, StorageFolderName);
            EnsureStorageDirectoryExists();
        }

        public void Save<T>(string key, T data)
        {
            if (string.IsNullOrEmpty(key)) { Debug.LogWarning("[LocalDataProvider] Save called with null or empty key."); return; }
            if (data == null) { Debug.LogWarning("[LocalDataProvider] Save called with null data."); Delete(key).Forget(); return; }
            try
            {
                byte[] bin = MemoryPackSerializer.Serialize(data);
                WriteBytes(key, bin);
            }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Save failed for key '{key}': {ex.Message}"); throw; }
        }

        public T Load<T>(string key, T defaultValue = default)
        {
            if (string.IsNullOrEmpty(key)) { Debug.LogWarning("[LocalDataProvider] Load called with null or empty key."); return defaultValue; }
            if (!ReadBytes(key, out byte[] bin)) return defaultValue;
            try { return MemoryPackSerializer.Deserialize<T>(bin) ?? defaultValue; }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Load failed for key '{key}': {ex.Message}"); return defaultValue; }
        }

        public bool HasKey(string key) => !string.IsNullOrEmpty(key) && File.Exists(GetFilePath(key));

        public UniTask Delete(string key)
        {
            if (string.IsNullOrEmpty(key)) return UniTask.CompletedTask;
            try { var filePath = GetFilePath(key); if (File.Exists(filePath)) File.Delete(filePath); }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] Delete failed for key '{key}': {ex.Message}"); }
            return UniTask.CompletedTask;
        }

        public UniTask DeleteAll()
        {
            try
            {
                if (!Directory.Exists(_storagePath)) return UniTask.CompletedTask;
                foreach (string file in Directory.GetFiles(_storagePath))
                {
                    try { File.Delete(file); }
                    catch (Exception ex) { Debug.LogWarning($"[LocalDataProvider] Could not delete file '{file}': {ex.Message}"); }
                }
            }
            catch (Exception ex) { Debug.LogError($"[LocalDataProvider] DeleteAll failed: {ex.Message}"); }
            return UniTask.CompletedTask;
        }

        public string[] GetKeys()
        {
            if (!Directory.Exists(_storagePath)) return Array.Empty<string>();
            var keys = new List<string>();
            foreach (string file in Directory.GetFiles(_storagePath))
            {
                try { string key = DecodeKeyFromFileName(Path.GetFileName(file)); if (key != null) keys.Add(key); }
                catch { Debug.LogWarning($"[LocalDataProvider] Could not read file '{file}'."); }
            }
            return keys.ToArray();
        }

        private void EnsureStorageDirectoryExists() { if (!Directory.Exists(_storagePath)) Directory.CreateDirectory(_storagePath); }
        private void WriteBytes(string key, byte[] bin) { EnsureStorageDirectoryExists(); File.WriteAllBytes(GetFilePath(key), bin); }
        private bool ReadBytes(string key, out byte[] bin) { string filePath = GetFilePath(key); if (!File.Exists(filePath)) { bin = null; return false; } bin = File.ReadAllBytes(filePath); return true; }
        private string GetFilePath(string key) => Path.Combine(_storagePath, EncodeKeyToFileName(key));
        private static string EncodeKeyToFileName(string key) { byte[] bytes = KeyEncoding.GetBytes(key); string base64 = Convert.ToBase64String(bytes); return base64.Replace('+', '-').Replace('/', '_'); }
        private static string DecodeKeyFromFileName(string fileName) { try { string base64 = fileName.Replace('-', '+').Replace('_', '/'); return KeyEncoding.GetString(Convert.FromBase64String(base64)); } catch { return null; } }
    }
}

You can implement another IDataProvider (for example JSON via Newtonsoft or PlayerPrefs) and swap it in your DataController.

In production, you might use a local and a cloud provider and sync data based on the player's online status. The com.core.data GitHub repo may be updated with cloud saving and syncing. You can open an issue if you need that feature.

Package 3: com.core.dotween

com.core.dotween is a Unity package wrapper around DOTween (Demigiant). DoTween is a widely used, production-ready tween engine. The UI package uses it for popup show/hide animations.

DOTween is not available on OpenUPM, so you’ll typically need to download it from the Unity Asset Store and import it into your project (for example, under Assets/Plugins).

Then you’ll run the DOTween setup window(it should pop automatically after importing) and click Create ASMDEF so assembly definition files are generated and you can reference them from other packages.

Next, create a new package (for example, com.core.dotween) and move the Demigiant folder from Assets/Plugins into the package folder so that com.core.ui (or any other package) can depend on com.core.dotween via Package Manager or Git.

After that, reference com.core.dotween in com.core.ui's asmdef(You will create the UI package right after this) so you can use DG.Tweening namespace in BasePopup and other UI scripts.

com.core.dotween has no external dependencies – it only wraps the DOTween asset.

Package 4: The UI Package

com.core.ui centralizes how you show popups and full-screen UIs. It contains:

• Popups – Modal or non-modal dialogs (confirm/cancel, alerts, forms) with a consistent API so you don’t duplicate panel logic in every screen. Popups are stacked – the top one is closed first.

• Screens – Full-screen panels (for example, loading, main menu). Only one screen is active at a time, and switching a screen hides the current one and shows the new one.

Create a new package named com.core.ui with a structure such as:

• Runtime/Interface/ – IUI

• Runtime/UIs/ – BasePopup, BaseScreen

• Runtime/ – UIController, UIParent

• Runtime/Resources/UIPrefabs/ – UIParent prefab, and subfolders Popups and Screens

Add com.core.dotween, com.core.initializer, and com.cysharp.unitask as dependencies in package.json and asmdef.

Popups work like a stack: each popup is shown on top of the previous one and closed from top to bottom. Screens are single-active: only one screen is visible at a time. UIController hides the current one when you show another. UIController is the single point of contact for both screens and popups and handles stacking, caching, and background placement.

IUI Interface

Both BasePopup and BaseScreen implement IUI:

using System;
using Cysharp.Threading.Tasks;

namespace com.core.ui
{
    public interface IUI
    {
        event Action<IUI> Showed;
        event Action<IUI> Hidden;

        UniTask ShowAsync();
        UniTask HideAsync();
    }
}

IUI is a very basic interface with 2 async Show/Hide methods and 2 events to be fired upon completion of those methods.

BasePopup

BasePopup uses DoTween to animate scale on show/hide and exposes events and overridable animation methods:

using System;
using Cysharp.Threading.Tasks;
using DG.Tweening;
using UnityEngine;

namespace com.core.ui
{
    public abstract class BasePopup : MonoBehaviour, IUI
    {
        public event Action<IUI> StartedShowing;
        public event Action<IUI> Showed;
        public event Action<IUI> Hidden;

        [SerializeField] private float   openingTime  = 0.35f;
        [SerializeField] private float   closingTime  = 0.25f;
        [SerializeField] private Vector3 initialScale = new(0.75f, 0.75f, 0.75f);
        [SerializeField] private Ease   openingEase  = Ease.OutBack;
        [SerializeField] private Ease   closingEase  = Ease.InBack;

        protected virtual Tweener PlayShowAnimation(Action completedCallback) => transform.DOScale(Vector3.one, openingTime).SetEase(openingEase).SetUpdate(true).OnComplete(() => completedCallback?.Invoke());
        protected virtual Tweener PlayHideAnimation(Action completedCallback) => transform.DOScale(initialScale, closingTime).SetEase(closingEase).SetUpdate(true).OnComplete(() => completedCallback?.Invoke());

        public UniTask ShowAsync()
        {
            StartedShowing?.Invoke(this);
            transform.SetAsLastSibling();
            var utcs = new UniTaskCompletionSource();
            transform.localScale = initialScale;
            gameObject.SetActive(true);

            PlayShowAnimation(() => OnAnimationShowed(utcs));
            return utcs.Task;
        }

        public void Show() => ShowAsync().Forget();

        public UniTask HideAsync()
        {
            var utcs = new UniTaskCompletionSource();
            PlayHideAnimation(() => OnAnimationCompleted(utcs));
            return utcs.Task;
        }

        private void OnAnimationShowed(UniTaskCompletionSource utcs)
        {
            Showed?.Invoke(this);
            utcs.TrySetResult();
        }

        private void OnAnimationCompleted(UniTaskCompletionSource utcs)
        {
            transform.SetAsFirstSibling();
            gameObject.SetActive(false);
            Hidden?.Invoke(this);
            utcs.TrySetResult();
        }

        public void Hide() => HideAsync().Forget();
    }
}

You can see that DoTween is the core component in this class and a lot of parameters are configurable like opening/closing times and easings. Notice how DoTween completion callbacks are utilized to fire Showed and Hidden events.

Another important thing here is the usage of SetUpdate(true) for animations. This makes animations to ignore timescale. I found that most of the time it's best to ignore the timescale for animations but if you don't want this then feel free to change it.

BaseScreen

BaseScreen only enables/disables the GameObject and raises events. There’s no animation:

using System;
using Cysharp.Threading.Tasks;
using UnityEngine;

namespace com.core.ui
{
    public abstract class BaseScreen : MonoBehaviour, IUI
    {
        public event Action<IUI> Showed;
        public event Action<IUI> Hidden;

        public virtual UniTask ShowAsync()
        {
            gameObject.SetActive(true);
            Showed?.Invoke(this);
            return UniTask.CompletedTask;
        }

        public UniTask HideAsync()
        {
            gameObject.SetActive(false);
            Hidden?.Invoke(this);
            return UniTask.CompletedTask;
        }
    }
}

You will notice that BaseScreen doesn't need UniTask since it is not performing any async operations but it is still beneficial to have this since it doesn't cause any overheads and if we ever need an animation for any of our screens like popups, we have it ready.

UIController

UIController implements IController, instantiates UIParent from Resources, and provides APIs to push/pop popups and show/hide screens. It caches popup and screen instances by type and loads prefabs from Resources:

• UIParent: Resources/UIPrefabs/UIParent

• Popups: Resources/UIPrefabs/Popups/<TypeName>.prefab

• Screens: Resources/UIPrefabs/Screens/<TypeName>.prefab

using System;
using System.Collections.Generic;
using com.core.initializer;
using Cysharp.Threading.Tasks;
using UnityEngine;
using Object = UnityEngine.Object;

namespace com.core.ui
{
    public class UIController : IController
    {
        private const string UI_PARENT_PATH    = "UIPrefabs/UIParent";
        private const string POPUPS_RESOURCES  = "UIPrefabs/Popups";
        private const string SCREENS_RESOURCES = "UIPrefabs/Screens";

        private readonly Stack<BasePopup>             _popupStack  = new();
        private readonly Dictionary<Type, BasePopup>  _popupCache  = new();
        private readonly Dictionary<Type, BaseScreen> _ScreenCache = new();

        private BaseScreen _currentScreen;
        private UIParent   _uiParent;

        public bool IsInitialized { get; private set; }

        public UniTask Initialize()
        {
            var uiParentPrefab = Resources.Load<UIParent>(UI_PARENT_PATH);
            if (uiParentPrefab == null)
            {
                Debug.LogError($"[UIController] UIParent prefab not found at {UI_PARENT_PATH}. Ensure it exists in a Resources folder.");
                return UniTask.CompletedTask;
            }

            _uiParent      = Object.Instantiate(uiParentPrefab);
            _uiParent.name = "UIParent";

            Object.DontDestroyOnLoad(_uiParent.gameObject);

            IsInitialized = true;
            return UniTask.CompletedTask;
        }

        public async UniTask<TPopup> PushPopupAsync<TPopup>() where TPopup : BasePopup
        {
            var popup = GetOrCreatePopup<TPopup>();
            _popupStack.Push(popup);
            var popupTask = popup.ShowAsync();
            UpdateBackgroundForTopPopup();
            await popupTask;
            return popup;
        }

        public void PushPopup<TPopup>() where TPopup : BasePopup => PushPopupAsync<TPopup>().Forget();

        public async UniTask PopPopupAsync()
        {
            if (_popupStack.Count == 0)
            {
                Debug.LogWarning("[UIController] PopPopup called but popup stack is empty.");
                return;
            }

            var top = _popupStack.Pop();
            await top.HideAsync();
            UpdateBackgroundForTopPopup();
        }

        public void PopPopup() => PopPopupAsync().Forget();

        public BasePopup PeekPopup() => _popupStack.Count > 0 ? _popupStack.Peek() : null;

        public async UniTask<TScreen> ShowScreenAsync<TScreen>() where TScreen : BaseScreen
        {
            var screen = GetOrCreateScreen<TScreen>();

            if (_currentScreen == screen && screen.gameObject.activeSelf) return screen;
            if (_currentScreen != null   && _currentScreen != screen && _currentScreen.gameObject.activeSelf) await _currentScreen.HideAsync();

            _currentScreen = screen;
            await screen.ShowAsync();
            return screen;
        }

        public async UniTask HideScreenAsync<TScreen>() where TScreen : BaseScreen
        {
            var type = typeof(TScreen);
            if (!_ScreenCache.TryGetValue(type, out var screen))
            {
                Debug.LogWarning($"[UIController] HideScreenAsync<{type.Name}> called but Screen was never shown (not in cache).");
                return;
            }

            await screen.HideAsync();

            if (_currentScreen == screen) _currentScreen = null;
        }

        public void ShowScreen<TScreen>() where TScreen : BaseScreen => ShowScreenAsync<TScreen>().Forget();
        public void HideScreen<TScreen>() where TScreen : BaseScreen => HideScreenAsync<TScreen>().Forget();

        private TPopup GetOrCreatePopup<TPopup>() where TPopup : BasePopup
        {
            var type = typeof(TPopup);
            if (_popupCache.TryGetValue(type, out var cached) && cached != null) return (TPopup)cached;

            var prefab = LoadPopupPrefab<TPopup>();
            if (prefab == null)
            {
                Debug.LogError($"[UIController] Popup prefab for {type.Name} not found at {POPUPS_RESOURCES}/{type.Name}. Ensure the prefab exists in a Resources folder.");
                return null;
            }

            var instance = UnityEngine.Object.Instantiate(prefab, _uiParent.PopupParent);
            instance.gameObject.SetActive(false);

            var popup = instance.GetComponent<TPopup>();
            _popupCache[type] = popup;

            return popup;
        }

        private TScreen GetOrCreateScreen<TScreen>() where TScreen : BaseScreen
        {
            var type = typeof(TScreen);
            if (_ScreenCache.TryGetValue(type, out var cached) && cached != null) return (TScreen)cached;

            var prefab = LoadScreenPrefab<TScreen>();
            if (prefab == null)
            {
                Debug.LogError($"[UIController] Screen prefab for {type.Name} not found at {SCREENS_RESOURCES}/{type.Name}. Ensure the prefab exists in a Resources folder.");
                return null;
            }

            var instance = UnityEngine.Object.Instantiate(prefab, _uiParent.ScreenParent);
            instance.gameObject.SetActive(false);

            var screen = instance.GetComponent<TScreen>();
            _ScreenCache[type] = screen;

            return screen;
        }

        private TPopup  LoadPopupPrefab<TPopup>() where TPopup : BasePopup     => LoadViewPrefab<TPopup>(POPUPS_RESOURCES);
        private TScreen LoadScreenPrefab<TScreen>() where TScreen : BaseScreen => LoadViewPrefab<TScreen>(SCREENS_RESOURCES);

        private static T LoadViewPrefab<T>(string resourcesPath) where T : MonoBehaviour
        {
            var type = typeof(T);
            var path = $"{resourcesPath}/{type.Name}";
            var go   = Resources.Load<GameObject>(path);
            return go != null ? go.GetComponent<T>() : null;
        }

        private void UpdateBackgroundForTopPopup()
        {
            var backgroundGO = _uiParent.BackgroundGO;
            if (backgroundGO == null) return;

            if (_popupStack.Count > 0)
            {
                var topPopup = _popupStack.Peek();
                if (topPopup != null && topPopup.gameObject.activeSelf)
                {
                    // Position background one step behind the top popup
                    var topPopupIndex = topPopup.transform.GetSiblingIndex();
                    backgroundGO.SetActive(true);
                    backgroundGO.transform.SetSiblingIndex(Mathf.Max(0, topPopupIndex - 1));
                }
                else
                {
                    // Top popup is inactive, hide background
                    backgroundGO.SetActive(false);
                }
            }
            else
            {
                // No popups in stack, hide background
                backgroundGO.SetActive(false);
            }
        }
    }
}

Usage:

var ui = ControllerHandler.GetController<UIController>();
await ui.PushPopupAsync<MyPopup>();
await ui.PopPopupAsync();
await ui.ShowScreenAsync<MainMenuScreen>();
await ui.HideScreenAsync<LoadingScreen>();

UIController also updates the background GameObject so it indexes behind the top popup.

It uses GetOrCreatePopup<TPopup>() / GetOrCreateScreen<TScreen>() to load and cache prefabs from Resources/UIPrefabs/Popups/<TypeName> and Resources/UIPrefabs/Screens/<TypeName>, pushes popups onto a stack, and shows/hides screens with async methods.

UIParent is a MonoBehaviour that holds references to ScreenParent, PopupParent, and BackgroundGO:

using UnityEngine;

namespace com.core.ui
{
    public class UIParent : MonoBehaviour
    {
        [SerializeField] private Transform  screensParent;
        [SerializeField] private Transform  popupsParent;
        [SerializeField] private GameObject backgroundGO;

        public Transform  ScreenParent => screensParent;
        public Transform  PopupParent  => popupsParent;
        public GameObject BackgroundGO => backgroundGO;
    }
}

UIParent prefab has a canvas and UIParent script attached:

There are a couple limitations here as well. First, popups and screens must live under Resources/UIPrefabs/Popups and Resources/UIPrefabs/Screens. Second, prefab name must match the script/type name (for example, TestPopup prefab name for a script named TestPopup).

Summary

In this article, you set up a Unity project and walked through creating four reusable packages:

• com.core.initializer – You created the package, added UniTask, defined IController, used the Creator helper to find and create controllers (including MonoBehaviours), and implemented ControllerHandler to run initialization at BeforeSceneLoad and expose controllers via GetController<T>().

• com.core.data – You use IDataProvider and LocalDataProvider with MemoryPack for binary local save/load, and the DataController that implements IController and tracks version history.

• com.core.dotween – You wrap the DoTween asset as a package so other packages (like com.core.ui) can reference it for animations.

• com.core.ui – You created a modular UI package that you can use in your games to handle popups and full size screens. You can also extend this to add other UI types in the future.

Building these as separate packages keeps your code modular and speeds up development across projects. You can install each package via Git into any Unity project.

Example manifest.json file to implement these packages:

{
  "dependencies"    : {
	"com.core.data"       : "https://github.com/TalhaCagatay/com.core.data.git#v0.1.0",
	"com.core.initializer": "https://github.com/TalhaCagatay/com.core.initializer.git#v0.1.0",
	"com.core.dotween"    : "https://github.com/TalhaCagatay/com.core.dotween.git#v0.1.0",
	"com.core.ui"         : "https://github.com/TalhaCagatay/com.core.ui.git#v0.1.0"
  },
  "scopedRegistries": [
	{
	  "name"  : "package.openupm.com",
	  "url"   : "https://package.openupm.com",
	  "scopes": [
		"com.cysharp.unitask",
		"com.cysharp.memorypack"
	  ]
	}
  ]
}

Resources:

• com.core.initializer on GitHub

• com.core.data on GitHub

• com.core.dotween on Github

• com.core.ui on Github

• Example game that I developed and used many modular systems like the ones you built in this article.

NET 11 Preview 1 is released, featuring Runtime Async as the headline change, moving async method handling from the compiler into the runtime itself. The preview also brings CoreCLR WebAssembly work, native Zstandard compression, C# 15 collection expression arguments, and MAUI improvements. Community reaction has been mixed, with praise for async changes but debate over language complexity.

PayPal disclosed a software error in its Working Capital platform that exposed sensitive customer data, including Social Security numbers, for months in 2025.

The post PayPal Flaw Exposed Email Addresses, Social Security Numbers for 6 Months appeared first on TechRepublic.