### Wait for Model Setup with Progress Callback in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Demonstrates how to wait for the LLM model setup while also receiving progress updates. This allows for displaying download progress to the user, enhancing the user experience during model loading.

```csharp
await LLM.WaitUntilModelSetup(SetProgress);

void SetProgress(float progress){
  string progressPercent = ((int)(progress * 100)).ToString() + "% flexibility";
  Debug.Log($"Download progress: {progressPercent}");
}
```

--------------------------------

### Set Up Pre-commit Hooks

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/CONTRIBUTING.md

Installs pre-commit hooks for the LLMUnity project by executing a setup script. This helps ensure code quality before commits.

```shell
sh ./.github/setup.sh
```

--------------------------------

### Wait for Model Setup on Mobile in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Illustrates how to wait for the LLM model to be fully set up, particularly relevant for mobile applications where models might be downloaded on the first launch. This ensures the model is ready before interaction.

```csharp
await LLM.WaitUntilModelSetup();
```

--------------------------------

### Pure Text Completion in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Provides an example of using the `Complete` method for pure text completion. This method takes a message and callback functions for handling the reply and completion.

```csharp
void Game(){
    // your game function
    ...
    string message = "The cat is away";
    _ = llmCharacter.Complete(message, HandleReply, ReplyCompleted);
    ...
  }
```

--------------------------------

### Unity C# Mod System Setup with MEReceiver

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

This script sets up the MEReceiver and MEReplacer in Unity to dynamically inject custom animator controllers and MonoBehaviour components into VRM models at runtime. It requires the Unity Engine namespace and System.Collections.Generic. It takes default and custom VRM models as input and configures replacement entries for animators and custom scripts.

```csharp
using UnityEngine;
using System.Collections.Generic;

// Setup receiver on the avatar parent
public class ModSystemSetup : MonoBehaviour
{
    public GameObject defaultVRMModel;
    public GameObject customVRMModel;

    void Start()
    {
        // Create receiver on Model parent
        GameObject modelParent = new GameObject("Model");
        var receiver = modelParent.AddComponent<MEReceiver>();

        receiver.VRMModel = defaultVRMModel;
        receiver.CustomVRM = customVRMModel;

        // Create mod replacer
        GameObject modObject = new GameObject("CustomAnimMod");
        var replacer = modObject.AddComponent<MEReplacer>();

        // Setup source object with custom animator controller
        GameObject sourceObject = new GameObject("AnimationSource");
        var sourceAnimator = sourceObject.AddComponent<Animator>();
        sourceAnimator.runtimeAnimatorController =
            Resources.Load<RuntimeAnimatorController>("Custom/MyAnimController");

        // Add custom component to override
        var customScript = sourceObject.AddComponent<CustomBehavior>();
        customScript.speed = 2.5f;
        customScript.enabled = true;

        // Configure replacement
        replacer.replacements = new List<MEReplacer.ReplacementEntry>
        {
            new MEReplacer.ReplacementEntry
            {
                sourceObject = sourceObject
            }
        };

        Debug.Log("Mod system configured");
        Debug.Log("When VRM loads, it will receive:");
        Debug.Log("- Custom animator controller");
        Debug.Log("- CustomBehavior component with speed=2.5");
    }
}

public class CustomBehavior : MonoBehaviour
{
    public float speed = 1.0f;
    public string customText = "Modified";

    void Update()
    {
        transform.Rotate(Vector3.up, speed * Time.deltaTime);
    }
}

// Runtime behavior:
// 1. MEReplacer detects when receiver.VRMModel or receiver.CustomVRM changes
// 2. Copies RuntimeAnimatorController from source to target
// 3. For each MonoBehaviour on source:
//    - Finds or adds same component type on target
//    - Copies all serialized fields/properties
//    - Skips null/empty/default values
// 4. Disables source components
// 5. Hides source GameObject

```

--------------------------------

### Save and Load RAG State

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Provides code examples for saving the current state of the RAG system to a file and subsequently loading it back. This is useful for persistence and avoiding re-computation of embeddings.

```csharp
rag.Save("rag.zip");
await rag.Load("rag.zip");
```

--------------------------------

### Radial Menu System Setup

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

Sets up a radial menu system in Unity that includes movement blocking, bone-following UI, and customizable menu entries. It allows for configuration of menu prefabs, input keys, and visual tracking behavior. The system can block player movement and other interactions when menus are active.

```csharp
using UnityEngine;
using System.Collections.Generic;

public class RadialMenuSetup : MonoBehaviour
{
    public GameObject settingsMenu;
    public GameObject radialMenuPrefab;

    void Start()
    {
        var menuActions = gameObject.AddComponent<MenuActions>();

        // Register settings menu
        menuActions.menuEntries = new List<MenuEntry>
        {
            new MenuEntry
            {
                menu = settingsMenu,
                blockMovement = true,      // Prevent dragging when open
                blockHandTracking = false,
                blockReaction = false,
                blockChibiMode = false
            }
        };

        // Configure radial menu
        menuActions.radialMenuObject = Instantiate(radialMenuPrefab);
        menuActions.radialMenuKey = KeyCode.F1;
        menuActions.radialDraggingBlocks = true;
        menuActions.radialBlockMovement = true;

        // Bone following configuration
        menuActions.followBone = true;
        menuActions.targetBone = HumanBodyBones.Head;
        menuActions.followSmoothness = 0.15f;  // Lower = smoother

        Debug.Log("Radial menu: Press F1 to toggle");
    }

    // Check if movement is blocked
    void Update()
    {
        if (MenuActions.IsMovementBlocked())
        {
            Debug.Log("Movement blocked by open menu");
        }

        if (Input.GetMouseButtonDown(0))
        {
            // Example: Only allow dragging if not blocked
            if (!MenuActions.IsMovementBlocked())
            {
                // Start drag operation
            }
        }
    }
}

// Expected output when F1 pressed:
// - Radial menu appears at head bone position
// - Menu follows head smoothly as character moves
// - Movement/interaction blocked based on settings
// - Plays menu open/close sounds

```

--------------------------------

### Manipulate JSON with LINQ to JSON using Json.NET

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/Packages/Newtonsoft.Json.13.0.3/README.md

Illustrates using LINQ to JSON with Json.NET to create and manipulate JSON structures programmatically. This example shows creating a JArray and a JObject, then converting them to a JSON string.

```csharp
JArray array = new JArray();
array.Add("Manual text");
array.Add(new DateTime(2000, 5, 23));

JObject o = new JObject();
o["MyArray"] = array;

string json = o.ToString();
// { 
//   "MyArray": [ 
//     "Manual text",
//     "2000-05-23T00:00:00"
//   ]
// }
```

--------------------------------

### RAG Integration for LLM Prompting

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Demonstrates how to use the RAG system to retrieve relevant data based on a user's query and then incorporate that data into a prompt for an LLM. This enhances the LLM's ability to provide contextually accurate responses.

```csharp
string message = "How is the weather?";
(string[] similarPhrases, float[] distances) = await rag.Search(message, 3);

string prompt = "Answer the user query based on the provided data.\n\n";
prompt += $"User query: {message}\n\n";
prompt += $"Data:\n";
foreach (string similarPhrase in similarPhrases) prompt += $"\n- {similarPhrase}";

_ = llmCharacter.Chat(prompt, HandleReply, ReplyCompleted);
```

--------------------------------

### Serialization and Serving Index from Disk

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

Demonstrates how to serialize and deserialize USearch indexes to and from disk files. It covers saving, loading, and restoring indexes, as well as creating a view of an index from a file.

```python
index.save("index.usearch")

loaded_copy = index.load("index.usearch")
view = Index.restore("index.usearch", view=True)

other_view = Index(ndim=..., metric=...)
other_view.view("index.usearch")
```

--------------------------------

### Initialize RAG Script in Unity

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Initializes the RAG component with specified search and chunking methods, and the LLM instance. This is the programmatic way to set up RAG in your Unity project.

```csharp
RAG rag = gameObject.AddComponent<RAG>();
rag.Init(SearchMethods.DBSearch, ChunkingMethods.SentenceSplitter, llm);
```

--------------------------------

### Create Outfit Menu UI with Buttons - C#

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

This script sets up a UI outfit menu dynamically at runtime. It instantiates a canvas, panel, and up to 8 outfit buttons, assigning them to an AvatarClothesHandler. Button labels are configured using TextMeshProUGUI. The script also initializes animation parameters for the buttons.

```csharp
using UnityEngine;
using UnityEngine.UI;
using TMPro;

public class OutfitMenuSetup : MonoBehaviour
{
    public GameObject menuPanelPrefab;

    void Start()
    {
        // Create outfit menu UI
        GameObject menuCanvas = new GameObject("OutfitMenuCanvas");
        var canvas = menuCanvas.AddComponent<Canvas>();
        canvas.renderMode = RenderMode.ScreenSpaceOverlay;
        menuCanvas.AddComponent<CanvasScaler>();
        menuCanvas.AddComponent<GraphicRaycaster>();

        GameObject panel = Instantiate(menuPanelPrefab, menuCanvas.transform);
        panel.SetActive(false);

        // Setup handler
        var handler = gameObject.AddComponent<AvatarClothesHandler>();
        handler.menuPanel = panel;

        // Create 8 outfit buttons
        handler.outfitButtons = new Button[8];
        handler.buttonLabels = new TextMeshProUGUI[8];

        for (int i = 0; i < 8; i++)
        {
            GameObject buttonObj = new GameObject($"OutfitButton{i}");
            buttonObj.transform.SetParent(panel.transform);

            var rectTransform = buttonObj.AddComponent<RectTransform>();
            rectTransform.sizeDelta = new Vector2(200, 50);
            rectTransform.anchoredPosition = new Vector2(0, -60 * i);

            var button = buttonObj.AddComponent<Button>();
            handler.outfitButtons[i] = button;

            GameObject textObj = new GameObject("Label");
            textObj.transform.SetParent(buttonObj.transform);
            var text = textObj.AddComponent<TextMeshProUGUI>();
            text.alignment = TextAlignmentOptions.Center;
            handler.buttonLabels[i] = text;

            buttonObj.SetActive(false);
        }

        // Configure animation
        handler.floatSpeedX = 1f;
        handler.floatSpeedY = 1.5f;
        handler.floatAmplitudeX = 5f;
        handler.floatAmplitudeY = 5f;

        Debug.Log("Outfit menu created with 8 button slots");
    }

    void Update()
    {
        // Open outfit menu
        if (Input.GetKeyDown(KeyCode.O))
        {
            var handler = GetComponent<AvatarClothesHandler>();
            handler.menuPanel.SetActive(!handler.menuPanel.activeSelf);

            // Auto-refresh buttons when opened
            // - Searches for MEClothes component on active avatars
            // - Creates buttons for each outfit entry
            // - Buttons show outfit name and trigger ActivateOutfit()
            // - Buttons animate with sine/cosine wave motion
        }

        // Check menu state
        if (AvatarClothesHandler.IsMenuOpen)
        {
            Debug.Log("Outfit menu is currently open");
        }
    }
}

```

--------------------------------

### Add and Search Text Inputs with RAG

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Demonstrates how to add multiple text inputs to the RAG system and then perform a semantic search for similar inputs. It also shows how to retrieve chunks instead of full inputs by enabling `ReturnChunks`.

```csharp
using LLMUnity;

public class MyScript : MonoBehaviour
{
  RAG rag;

  async void Game(){
    ...
    string[] inputs = new string[]{
      "Hi! I'm a search system.",
      "the weather is nice. I like it.",
      "I'm a RAG system"
    };
    // add the inputs to the RAG
    foreach (string input in inputs) await rag.Add(input);
    // get the 2 most similar inputs and their distance (dissimilarity) to the search query
    (string[] results, float[] distances) = await rag.Search("hello!", 2);
    // to get the most similar text parts (chnuks) you can enable the returnChunks option
    rag.ReturnChunks(true);
    (results, distances) = await rag.Search("hello!", 2);
    ...
  }
}
```

--------------------------------

### Warmup LLM for Faster Initial Processing in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Shows how to use the `Warmup` method of an LLMCharacter to pre-process prompts, reducing initial response times. The `WarmupCompleted` callback function is executed upon completion.

```csharp
void WarmupCompleted(){
    // do something when the warmup is complete
    Debug.Log("The AI is nice and ready");
  }

  void Game(){
    // your game function
    ...
    _ = llmCharacter.Warmup(WarmupCompleted);
    ...
  }
```

--------------------------------

### Multi-Index Lookups with USearch Indexes

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

Shows how to set up and use the `Indexes` class for parallel multi-index lookups, which is beneficial for handling very large datasets (billions or trillions of vectors).

```python
from usearch.index import Indexes

multi_index = Indexes(
    indexes: Iterable[usearch.index.Index] = [...],
    paths: Iterable[os.PathLike] = [...],
    view: bool = False,
    threads: int = 0,
)
multi_index.search(...)
```

--------------------------------

### Check Hardware Acceleration for USearch Index (Python)

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

This snippet demonstrates how to check for hardware acceleration support in USearch for different data types and metrics. It initializes an Index object with specified dimensions, metric, and data type, then prints the detected hardware acceleration features. This is useful for optimizing performance by leveraging available hardware instructions.

```python
from usearch.index import Index
print(Index(ndim=768, metric="cos", dtype="f16").hardware_acceleration)
```

```python
from usearch.index import Index
print(Index(ndim=166, metric="tanimoto").hardware_acceleration)
```

--------------------------------

### Exact and Approximate Search with USearch

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

Illustrates how to perform both exact and approximate searches using the USearch library. It shows searching a single vector against many and many vectors against many, utilizing SIMD optimizations for performance.

```python
from usearch.index import search, MetricKind, Matches, BatchMatches
import numpy as np

# Generate 10'000 random vectors with 1024 dimensions
vectors = np.random.rand(10_000, 1024).astype(np.float32)
vector = np.random.rand(1024).astype(np.float32)

one_in_many: Matches = search(vectors, vector, 50, MetricKind.L2sq, exact=True)
many_in_many: BatchMatches = search(vectors, vectors, 50, MetricKind.L2sq, exact=True)
```

--------------------------------

### Configure UniVRM Packages in manifest.json

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/MATE ENGINE - Packages/VRM/README.md

Configuration for adding UniVRM and VRMShaders packages to a Unity project by directly editing the Packages/manifest.json file. This is an alternative to using the Package Manager GUI and specifies the git URLs for the packages.

```json
{
  "dependencies": {
    "com.vrmc.vrmshaders": "https://github.com/vrm-c/UniVRM.git?path=/Assets/VRMShaders",
    "com.vrmc.univrm": "https://github.com/vrm-c/UniVRM.git?path=/Assets/VRM"
  }
}
```

--------------------------------

### C# Unity Outfit Management with MEClothes

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

This C# script demonstrates how to initialize and use the MEClothes component in Unity for managing outfits on a VRM avatar. It sets up different outfit entries with tags for exclusivity and shows how to activate them via key presses. The script assumes the presence of the MEClothes component and specific GameObjects within the scene hierarchy.

```csharp
using UnityEngine;

public class OutfitSystemExample : MonoBehaviour
{
    void Start()
    {
        // Setup on VRM avatar
        var clothes = gameObject.AddComponent<MEClothes>();

        // Configure outfit entries (max 8)
        clothes.entries = new MEClothes.OutfitEntry[8];

        // Entry 0: Hat accessory
        clothes.entries[0] = new MEClothes.OutfitEntry
        {
            name = "Witch Hat",
            tag = "headwear",  // Only one headwear active at a time
            gameObjects = new GameObject[]
            {
                transform.Find("Armature/Head/WitchHat").gameObject
            }
        };

        // Entry 1: Alternative hat
        clothes.entries[1] = new MEClothes.OutfitEntry
        {
            name = "Cat Ears",
            tag = "headwear",  // Same tag as above
            gameObjects = new GameObject[]
            {
                transform.Find("Armature/Head/CatEars").gameObject
            }
        };

        // Entry 2: Jacket (no tag = independent toggle)
        clothes.entries[2] = new MEClothes.OutfitEntry
        {
            name = "Jacket",
            tag = "",
            gameObjects = new GameObject[]
            {
                transform.Find("Armature/Spine/Chest/Jacket").gameObject,
                transform.Find("Armature/LeftArm/JacketSleeve").gameObject,
                transform.Find("Armature/RightArm/JacketSleeve").gameObject
            }
        };

        // Entry 3: Backpack
        clothes.entries[3] = new MEClothes.OutfitEntry
        {
            name = "Backpack",
            tag = "back",
            gameObjects = new GameObject[]
            {
                transform.Find("Armature/Spine/Backpack").gameObject
            }
        };

        // Initialize - hide all outfits
        foreach (var entry in clothes.entries)
        {
            if (entry != null && entry.gameObjects != null)
            {
                foreach (var obj in entry.gameObjects)
                {
                    if (obj != null) obj.SetActive(false);
                }
            }
        }
    }

    void Update()
    {
        var clothes = GetComponent<MEClothes>();

        // Activate outfit 0 (Witch Hat)
        if (Input.GetKeyDown(KeyCode.Alpha1))
        {
            clothes.ActivateOutfit(0);
            // Result: Witch Hat ON, Cat Ears OFF (same tag)
        }

        // Activate outfit 1 (Cat Ears)
        if (Input.GetKeyDown(KeyCode.Alpha2))
        {
            clothes.ActivateOutfit(1);
            // Result: Cat Ears ON, Witch Hat OFF (same tag)
        }

        // Toggle jacket (independent)
        if (Input.GetKeyDown(KeyCode.Alpha3))
        {
            clothes.ActivateOutfit(2);
            // Result: Jacket toggles ON/OFF, doesn't affect other items
        }

        // Toggle backpack
        if (Input.GetKeyDown(KeyCode.Alpha4))
        {
            clothes.ActivateOutfit(3);
            // Result: Backpack toggles ON/OFF
        }
    }
}

```

--------------------------------

### Set Up LLMUnity Symbolic Link

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/CONTRIBUTING.md

Creates a symbolic link for the LLMUnity package within a Unity project's Assets directory. This is a prerequisite for adding the package to the project's manifest.

```bash
cd Assets && ln -s ./LLMUnity/Samples~ ./Samples 
```

--------------------------------

### Basic Vector Indexing and Search with USearch (Python)

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

Demonstrates the fundamental usage of USearch for adding vectors to an index and performing a nearest neighbor search. It requires numpy and usearch libraries. The output includes the key of the found match and its distance, and verifies the retrieved vector.

```python
$ pip install numpy usearch

import numpy as np
from usearch.index import Index

index = Index(ndim=3)

vector = np.array([0.2, 0.6, 0.4])
index.add(42, vector)

matches = index.search(vector, 10)

assert matches[0].key == 42
assert matches[0].distance <= 0.001
assert np.allclose(index[42], vector)
```

--------------------------------

### Bug Report Template

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/MATE ENGINE - Shaders/jp.lilxyzw.liltoon-1.8.5/README.md

A template for reporting bugs encountered while using lilToon shaders. It includes essential fields for bug description, reproduction steps, and optional but helpful information such as Unity version, VRChat World details, screenshots, and console logs.

```markdown
Bug: 
Reproduction method: 

# Optional
Unity version: 
VRChat World: 
Screenshots: 
Console logs: 
```

--------------------------------

### Python: Multi-Modal Semantic Search with USearch, UCall, and UForm

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

This Python code demonstrates building a text-to-image search platform using USearch for indexing and searching image vectors, UForm for encoding images and text, and UCall as a web-programming framework. It defines server functions to add image-key pairs and search for images based on text queries.

```python
import ucall
import uform
import usearch

import numpy as np
import PIL as pil

server = ucall.Server()
model = uform.get_model('unum-cloud/uform-vl-multilingual')
index = usearch.index.Index(ndim=256)

@server
def add(key: int, photo: pil.Image.Image):
    image = model.preprocess_image(photo)
    vector = model.encode_image(image).detach().numpy()
    index.add(key, vector.flatten(), copy=True)

@server
def search(query: str) -> np.ndarray:
    tokens = model.preprocess_text(query)
    vector = model.encode_text(tokens).detach().numpy()
    matches = index.search(vector.flatten(), 3)
    return matches.keys

server.run()
```

--------------------------------

### Fuzzy Joins with USearch

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

Illustrates how to implement fuzzy joins between two USearch indexes. This functionality enables sub-quadratic complexity approximate and semantic joins, useful for fuzzy-matching tasks in databases.

```python
men = Index(...)
women = Index(...)
pairs: dict = men.join(women, max_proposals=0, exact=False)
```

--------------------------------

### Asynchronous Chat Reply Handling with Async/Await in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Demonstrates using `async`/`await` to wait for an AI reply before proceeding with subsequent code. The `Chat` method is awaited, and the reply is logged to the console.

```csharp
async void Game(){
    // your game function
    ...
    string message = "Hello bot!";
    string reply = await llmCharacter.Chat(message, HandleReply, ReplyCompleted);
    Debug.Log(reply);
    ...
  }
```

--------------------------------

### Programmatically Add LLM and LLMCharacter Components in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Shows how to dynamically add and configure `LLM` and `LLMCharacter` components to a GameObject in Unity. This includes setting the model, LoRA weights, chat template, and character prompts.

```csharp
using UnityEngine;
using LLMUnity;

public class MyScript : MonoBehaviour
{
    LLM llm;
    LLMCharacter llmCharacter;

    async void Start()
    {
        // disable gameObject so that theAwake is not called immediately
        gameObject.SetActive(false);

        // Add an LLM object
        llm = gameObject.AddComponent<LLM>();
        // set the model using the filename of the model.
        // The model needs to be added to the LLM model manager (see LLM model management) by loading or downloading it.
        // Otherwise the model file can be copied directly inside the StreamingAssets folder.
        llm.SetModel("Phi-3-mini-4k-instruct-q4.gguf");
        // optional: you can also set loras in a similar fashion and set their weights (if needed)
        llm.AddLora("my-lora.gguf");
        llm.SetLoraWeight(0.5f);
        // optional: you can set the chat template of the model if it is not correctly identified
        // You can find a list of chat templates in the ChatTemplate.templates.Keys
        llm.SetTemplate("phi-3");
        // optional: set number of threads
        llm.numThreads = -1;
        // optional: enable GPU by setting the number of model layers to offload to it
        llm.numGPULayers = 10;

        // Add an LLMCharacter object
        llmCharacter = gameObject.AddComponent<LLMCharacter>();
        // set the LLM object that handles the model
        llmCharacter.llm = llm;
        // set the character prompt
        llmCharacter.SetPrompt("A chat between a curious human and an artificial intelligence assistant.");
        // set the AI and player name
        llmCharacter.AIName = "AI";
        llmCharacter.playerName = "Human";
        // optional: set streaming to false to get the complete result in one go
        // llmCharacter.stream = true;
        // optional: set a save path
        // llmCharacter.save = "AICharacter1";
        // optional: enable the save cache to avoid recomputation when loading a save file (requires ~100 MB)
        // llmCharacter.saveCache = true;
        // optional: set a grammar
        // await llmCharacter.SetGrammar("json.gbnf");

        // re-enable gameObject
        gameObject.SetActive(true);
    }
}
```

--------------------------------

### Export Custom Model as ME Bundle (Unity C#)

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

This script defines a Unity Editor menu item to export the selected GameObject as a .me asset bundle. It interacts with the MEModelExporter window to set the prefab and bundle name, then logs instructions for manual export. The process includes gathering dependencies, compression, and saving the bundle.

```csharp
using UnityEditor;
using UnityEngine;

// Usage: Window → MateEngine → ME Model Exporter
public class ExportCustomModel
{
    [MenuItem("Assets/Export as ME Model")]
    static void ExportSelected()
    {
        GameObject selectedObject = Selection.activeGameObject;
        if (selectedObject == null)
        {
            Debug.LogError("No GameObject selected");
            return;
        }

        // Get the MEModelExporter window
        var window = EditorWindow.GetWindow<MEModelExporter>();

        // Use reflection to set private fields
        var prefabField = typeof(MEModelExporter).GetField("prefabToExport",
            System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);
        var nameField = typeof(MEModelExporter).GetField("bundleName",
            System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance);

        prefabField.SetValue(window, selectedObject);
        nameField.SetValue(window, selectedObject.name.ToLower());

        Debug.Log($"Ready to export: {selectedObject.name}");
        Debug.Log("Click 'Export' button in ME Model Exporter window");

        // Manual export process:
        // 1. Opens "ME Model Exporter" window
        // 2. Automatically gathers all dependencies (textures, materials, animations)
        // 3. Includes VideoPlayer external files
        // 4. Builds asset bundle with ChunkBasedCompression
        // 5. Saves to Assets/ExportedModel/[name].me
        // 6. Opens folder in file explorer

        // File structure:
        // Assets/ExportedModel/
        //   └── custommodel.me  (asset bundle)
        //   └── video.mp4       (external video files if any)
    }
}

// .me file loading at runtime (user-side):
/*
AssetBundle bundle = AssetBundle.LoadFromFile("path/to/custommodel.me");
GameObject model = bundle.LoadAsset<GameObject>("ModelName");
Instantiate(model);
bundle.Unload(false);
*/
```

--------------------------------

### Clustering with USearch

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

Demonstrates the clustering capabilities of USearch, which allows for K-Nearest Neighbors Clustering and dimensionality reduction. It covers generating clusters, analyzing their properties, and sub-clustering.

```python
clustering = index.cluster(
    min_count=10, # Optional
    max_count=15, # Optional
    threads=..., # Optional
)

# Get the clusters and their sizes
centroid_keys, sizes = clustering.centroids_popularity

# Use Matplotlib to draw a histogram
clustering.plot_centroids_popularity()

# Export a NetworkX graph of the clusters
g = clustering.network

# Get members of a specific cluster
first_members = clustering.members_of(centroid_keys[0])

# Deepen into that cluster, splitting it into more parts, all the same arguments supported
sub_clustering = clustering.subcluster(min_count=..., max_count=...)
```

--------------------------------

### Enable Fullscreen Avatar View with AvatarBigScreenHandler

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

This C# script demonstrates how to initialize and toggle the AvatarBigScreenHandler to enter and exit fullscreen avatar viewing mode. It configures camera settings, fade animations, and movement blocking, and can be triggered via user input.

```csharp
using UnityEngine;

public class BigScreenModeExample : MonoBehaviour
{
    public Camera mainCamera;

    void Start()
    {
        var animator = GetComponent<Animator>();
        var bigScreen = gameObject.AddComponent<AvatarBigScreenHandler>();

        // Configure
        bigScreen.avatarAnimator = animator;
        bigScreen.MainCamera = mainCamera;
        bigScreen.attachBone = HumanBodyBones.Head;

        // Camera settings
        bigScreen.TargetZoom = 0f;        // 0 = auto-calculate
        bigScreen.ZoomMoveSpeed = 10f;    // Camera movement speed
        bigScreen.YOffset = 0.08f;        // 8cm above head bone

        // Fade animation
        bigScreen.FadeYOffset = 0.5f;     // Fade in from 50cm above
        bigScreen.FadeInDuration = 0.5f;
        bigScreen.FadeOutDuration = 0.5f;

        // Movement blocking
        bigScreen.moveCanvas = GameObject.Find("MoveCanvas");
    }

    void Update()
    {
        var bigScreen = GetComponent<AvatarBigScreenHandler>();

        // Toggle big screen mode with B key
        if (Input.GetKeyDown(KeyCode.B))
        {
            bigScreen.ToggleBigScreenFromUI();

            // When activating:
            // 1. Stores original window position/size
            // 2. Finds largest monitor
            // 3. Moves window to cover entire monitor
            // 4. Stores original camera position/rotation/FOV
            // 5. Animates camera to head bone position
            // 6. Hides movement canvas
            // 7. Avatar fades in from above

            // When deactivating:
            // 1. Fades out avatar
            // 2. Restores camera position/rotation/FOV
            // 3. Restores window position/size
            // 4. Shows movement canvas

            Debug.Log("Big Screen mode toggled");
        }
    }
}

// Windows API calls used internally:
// - EnumDisplayMonitors: Find all connected monitors
// - GetWindowRect: Get current window bounds
// - MoveWindow: Reposition/resize application window

```

--------------------------------

### Send Chat Message with Callback in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Demonstrates how to send a message to an LLMCharacter and handle the reply using a callback function. This is the basic method for interacting with the AI. It requires an LLMCharacter instance and a handler function for the response.

```csharp
using LLMUnity;

public class MyScript {
  public LLMCharacter llmCharacter;
  
  void HandleReply(string reply){
    // do something with the reply from the model
    Debug.Log(reply);
  }
  
  void Game(){
    // your game function
    ...
    string message = "Hello bot!";
    _ = llmCharacter.Chat(message, HandleReply);
    ...
  }
}
```

--------------------------------

### Configuring USearch Index Parameters (Python)

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

Illustrates how to configure various parameters when initializing a USearch Index. This includes setting the number of dimensions, distance metric, data type, and optional parameters for controlling recall and search quality. The default metric is 'ip' (inner product).

```python
index = Index(
    ndim=3, # Define the number of dimensions in input vectors
    metric='cos', # Choose 'l2sq', 'haversine' or other metric, default = 'ip'
    dtype='f32', # Quantize to 'f16' or 'i8' if needed, default = 'f32'
    connectivity=16, # Optional: Limit number of neighbors per graph node
    expansion_add=128, # Optional: Control the recall of indexing
    expansion_search=64, # Optional: Control the quality of the search
    multi=False, # Optional: Allow multiple vectors per key, default = False
)
```

--------------------------------

### Python: Molecular Search with USearch and RDKit

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/Runtime/RAG/usearch/README.md

This Python snippet illustrates performing molecular structure search using USearch and RDKit. It generates binary fingerprints from SMILES strings using RDKit's RDKitFPGenerator and then uses USearch with the Tanimoto metric to index and search these fingerprints, finding similar molecular structures.

```python
from usearch.index import Index, MetricKind
from rdkit import Chem
from rdkit.Chem import AllChem

import numpy as np

molecules = [Chem.MolFromSmiles('CCOC'), Chem.MolFromSmiles('CCO')]
encoder = AllChem.GetRDKitFPGenerator()

fingerprints = np.vstack([encoder.GetFingerprint(x) for x in molecules])
fingerprints = np.packbits(fingerprints, axis=1)

index = Index(ndim=2048, metric=MetricKind.Tanimoto)
keys = np.arange(len(molecules))

index.add(keys, fingerprints)
matches = index.search(fingerprints, 10)
```

--------------------------------

### Add UniVRM Packages via Unity Package Manager

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/MATE ENGINE - Packages/VRM/README.md

Instructions for importing VRMShaders and UniVRM packages into a Unity project using the Package Manager. This method requires Unity version 2019.3.4f1 or later. VRMShaders is a dependency for UniVRM.

```text
Window -> Package Manager -> Add package from git URL
https://github.com/vrm-c/UniVRM.git?path=/Assets/VRMShaders
https://github.com/vrm-c/UniVRM.git?path=/Assets/VRM
```

--------------------------------

### Grouped Data Add and Search in RAG

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Shows how to add and search text inputs associated with specific groups (e.g., characters or scenes). This allows for context-specific retrieval of information within the RAG system.

```csharp
// add the inputs to the RAG for a group of data e.g. an orc character
foreach (string input in inputs) await rag.Add(input, "orc");
// get the 2 most similar inputs for the group of data e.g. the orc character
(string[] results, float[] distances) = await rag.Search("how do you feel?", 2, "orc");
...
```

--------------------------------

### Serialize .NET Object to JSON using Json.NET

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/Packages/Newtonsoft.Json.13.0.3/README.md

Demonstrates how to serialize a .NET object (Product) into a JSON string using the JsonConvert.SerializeObject method from the Json.NET library. This is useful for sending data across networks or storing it in a JSON format.

```csharp
Product product = new Product();
product.Name = "Apple";
product.Expiry = new DateTime(2008, 12, 28);
product.Sizes = new string[] { "Small" };

string json = JsonConvert.SerializeObject(product);
// { 
//   "Name": "Apple",
//   "Expiry": "2008-12-28T00:00:00",
//   "Sizes": [ 
//     "Small"
//   ]
// }
```

--------------------------------

### Set LLM Character Grammar via Code in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Shows how to programmatically set the grammar for an LLMCharacter, either using a GBNF string or a JSON schema string. This allows for runtime control over the AI's output format, such as restricting it to JSON.

```csharp
// GBNF grammar
llmCharacter.grammarString = "your GBNF grammar here";

// or JSON schema grammar
llmCharacter.grammarJSONString = "your JSON schema grammar here";
```

--------------------------------

### Configure VRM Avatar Mouse Tracking in Unity C#

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

This C# script sets up real-time mouse tracking for a humanoid VRM avatar in Unity. It allows for configurable head, spine, and eye rotations that follow the user's cursor, with options for smoothness, rotation limits, and blend influence. It also includes a system for managing tracking permissions based on animation states or parameters.

```csharp
using UnityEngine;
using System.Collections.Generic;

// Add to any Animator-equipped VRM model
public class SetupMouseTracking : MonoBehaviour
{
    void Start()
    {
        var animator = GetComponent<Animator>();
        if (animator == null || !animator.isHuman)
        {
            Debug.LogError("Requires humanoid Animator");
            return;
        }

        // Add mouse tracking component
        var tracking = gameObject.AddComponent<AvatarMouseTracking>();

        // Configure head tracking
        tracking.enableMouseTracking = true;
        tracking.headYawLimit = 45f;        // ±45° horizontal
        tracking.headPitchLimit = 30f;      // ±30° vertical
        tracking.headSmoothness = 10f;      // Higher = smoother
        tracking.headBlend = 1f;            // 100% tracking influence

        // Configure spine tracking
        tracking.spineMinRotation = -15f;
        tracking.spineMaxRotation = 15f;
        tracking.spineSmoothness = 25f;
        tracking.spineBlend = 1f;

        // Configure eye tracking
        tracking.eyeYawLimit = 12f;
        tracking.eyePitchLimit = 12f;
        tracking.eyeSmoothness = 10f;
        tracking.eyeBlend = 1f;

        // Set up state-based permissions
        var permission = new TrackingPermission
        {
            stateOrParameterName = "Idle",  // Animation state name
            isParameter = false,             // false = state, true = bool parameter
            allowHead = true,
            allowSpine = true,
            allowEye = true
        };
        tracking.trackingPermissions = new List<TrackingPermission> { permission };

        Debug.Log("Mouse tracking configured for " + gameObject.name);
    }
}

// Expected behavior:
// - Head rotates toward cursor within ±45° yaw, ±30° pitch
// - Spine follows horizontal cursor position
// - Eyes track cursor independently within ±12° limits
// - All movements smoothly interpolated

```

--------------------------------

### Save and Load Chat History in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Demonstrates how to manually save and load chat history for an LLMCharacter instance. This involves calling `Save` and `Load` methods with a specified filename. The data is saved to Unity's persistent data path.

```csharp
llmCharacter.Save("filename");
llmCharacter.Load("filename");
```

--------------------------------

### Compute Embeddings using LLMCharacter in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Demonstrates how to use the Embeddings function of the LLMCharacter script to obtain phrase embeddings. This requires an initialized LLMCharacter instance connected to a running LLM server. The function returns a list of floats representing the embedding vector.

```csharp
List<float> embeddings = await llmCharacter.Embeddings("hi, how are you?");
```

--------------------------------

### Send Chat Message with Completion Callback in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Shows how to send a message to an LLMCharacter and specify a separate function to be called when the model's reply is fully completed. This is useful for streaming responses or performing actions after the AI finishes generating output.

```csharp
  void ReplyCompleted(){
    // do something when the reply from the model is complete
    Debug.Log("The AI replied");
  }
  
  void Game(){
    // your game function
    ...
    string message = "Hello bot!";
    _ = llmCharacter.Chat(message, HandleReply, ReplyCompleted);
    ...
  }
```

--------------------------------

### Add LLMUnity Package to Unity Manifest

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/CONTRIBUTING.md

Specifies how to add the LLMUnity package to a Unity project's manifest.json file, enabling its use in the project.

```json
{
  "dependencies": {
    "ai.undream.llm": "file:path/to/project/Assets/LLMUnity"
  }
}
```

--------------------------------

### Parse TOML to Model and Generate TOML String in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/Packages/Tomlyn.0.19.0/readme.md

This snippet demonstrates how to parse a TOML string into a default runtime model (TomlTable) and then generate a TOML string back from that model. It highlights the ability to preserve comments during the round-trip process. Dependencies include the Tomlyn library.

```csharp
var toml = @"global = \"this is a string\"
# This is a comment of a table
[my_table]
key = 1 # Comment a key
value = true
list = [4, 5, 6]
";

// Parse the TOML string to the default runtime model `TomlTable`
var model = Toml.ToModel(toml);
// Fetch the string
var global = (string)model["global"]!;
// Prints: found global = "this is a string"
Console.WriteLine($"found global = \"{global}\"");
// Generates a TOML string from the model
var tomlOut = Toml.FromModel(model);
// Output the generated TOML
Console.WriteLine(tomlOut);
```

--------------------------------

### Deserialize JSON to .NET Object using Json.NET

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/Packages/Newtonsoft.Json.13.0.3/README.md

Shows how to deserialize a JSON string into a .NET object (Movie) using JsonConvert.DeserializeObject<T> from Json.NET. This is essential for consuming JSON data received from APIs or files.

```csharp
string json = @"{ 
  'Name': 'Bad Boys',
  'ReleaseDate': '1995-4-7T00:00:00',
  'Genres': [ 
    'Action',
    'Comedy'
  ]
}";

Movie m = JsonConvert.DeserializeObject<Movie>(json);

string name = m.Name;
// Bad Boys
```

--------------------------------

### Chibi Mode Transformation

Source: https://context7.com/bbkuan/my-mate-engine/llms.txt

Implements a chibi (super-deformed) character transformation by scaling specific body parts. It requires Unity's Animator component and handles audio and particle effects for entering/exiting the mode. The script configures armature, head, and leg scales, along with sound effects and particle durations. It can be toggled using a specified key input.

```csharp
using UnityEngine;
using System.Collections.Generic;

public class ChibiModeExample : MonoBehaviour
{
    void Start()
    {
        // Setup chibi toggle on VRM avatar
        var animator = GetComponent<Animator>();
        var chibi = gameObject.AddComponent<ChibiToggle>();

        // Configure chibi proportions
        chibi.chibiArmatureScale = new Vector3(0.3f, 0.3f, 0.3f);  // 30% body size
        chibi.chibiHeadScale = new Vector3(2.7f, 2.7f, 2.7f);      // 270% head size
        chibi.chibiUpperLegScale = new Vector3(0.6f, 0.6f, 0.6f);  // 60% leg length

        // Setup audio source
        chibi.audioSource = gameObject.AddComponent<AudioSource>();

        // Load sound effects from Resources
        chibi.chibiEnterSounds = new List<AudioClip>
        {
            Resources.Load<AudioClip>("Sounds/chibi_enter_1"),
            Resources.Load<AudioClip>("Sounds/chibi_enter_2")
        };
        chibi.chibiExitSounds = new List<AudioClip>
        {
            Resources.Load<AudioClip>("Sounds/chibi_exit_1")
        };

        // Setup particle effect
        GameObject particles = new GameObject("ChibiParticles");
        particles.transform.SetParent(transform);
        particles.AddComponent<ParticleSystem>();
        particles.SetActive(false);
        chibi.particleEffectObject = particles;
        chibi.particleDuration = 4f;
    }

    void Update()
    {
        // Toggle chibi mode with C key
        if (Input.GetKeyDown(KeyCode.C))
        {
            var chibi = GetComponent<ChibiToggle>();
            chibi.ToggleChibiMode();

            // Output:
            // - Plays random sound from appropriate list
            // - Activates particles for 4 seconds
            // - Scales armature to 30%, head to 270%
            // - Automatically adjusts Y position to keep feet on ground
        }
    }
}
```

--------------------------------

### Control Message History Inclusion in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Explains how to control whether a message is added to the chat/prompt history by setting the last argument of the `Chat` function. A value of `false` prevents the message from being added.

```csharp
void Game(){
    // your game function
    ...
    string message = "Hello bot!";
    _ = llmCharacter.Chat(message, HandleReply, ReplyCompleted, false);
    ...
  }
```

--------------------------------

### Cancel LLM Chat Requests in C#

Source: https://github.com/bbkuan/my-mate-engine/blob/main/Assets/LLMUnity/README.md

Provides the code to immediately stop any ongoing chat requests with the LLMCharacter. This is useful for interrupting the AI's response or clearing pending operations.

```csharp
    llmCharacter.CancelRequests();
```