SharpCompanion

An AI companion app built with Godot 4.7 (C#): pick a VRM avatar, drop it into a 3D stage with a background of your choice, and chat with it through a local or remote LLM. The companion can react with its own animations/expressions while it talks, picked by the model itself based on the situation.

This is an attempt to make an all-in-one and ready to use, but still customizable, AI Companion app. SharpCompanion can run as it is: no other stuff to install, no external dependecies. Just start the app, download the model, and enjoy.

This is a personal/hobby project, expect rough edges. Contributions and issue reports are welcome.

Features

• VRM avatar viewer — load any .vrm file, position/rotate/scale it in the 3D stage, and pick a 2D background image behind it.
• Multiple AI backends, switchable from the setup wizard:
  • LLamaSharp — runs a local .gguf model fully on-device (CPU, or CUDA/Vulkan on desktop), no account or server needed. Comes with an in-app downloader for a small catalog of models, and supports multimodal (image-aware) models via a paired mmproj file.
  • Ollama — point it at a local or remote Ollama server.
  • Any OpenAI-compatible endpoint — custom URL, model name, optional API key.
• Character cards — optional Character Card V3 character card support (via CharacterCardV3Sharp) to give the companion a personality, greeting, and system prompt.
• Expression & animation system — the model can trigger the avatar's own animations as an "emotion" through a real Semantic Kernel function call (native tool-calling on Ollama/OpenAI-compatible; a lightweight tag-based fallback on LLamaSharp, since llama.cpp models generally can't do native tool-calling yet).
• Chat history — multiple saved conversations per character, editable/deletable messages, streaming or non-streaming replies.
• Context-window safety — automatic history truncation (ChatHistoryTruncationReducer) so long conversations don't overflow the model's context.
• Responsive UI — same project targets desktop and mobile: layout, control sizing, and the on-screen-keyboard-aware chat input all adapt to portrait/landscape and screen size.
• 9 languages out of the box: English, Italian, French, German, Spanish, Portuguese, Japanese, Chinese (simplified), Korean — selectable in-app, independent of the OS locale. NOTE: Translations are AI-Generated, they may be innacutate. Please, report any error you may encounter

Planned Features

• Handle multiple greetings for Character v3 cards
• Autonomous mode - make the companion send a message automatically from time to time
• Image recognition - only on supported models, Mmproj file loading for local models
• Text-To-Speech engine - to give a voice to your companion
• Speech-To-Text engine - to be able to talk to your companion
• Screen Share feature - Make the model see and comment another window of screen
• Animated Backgrounds

Platforms

• Windows (x64 / arm64)
• Linux (x64 / arm64)
• MacOS (*)
• Android

(*) I currently don't have a paid apple developer account, this means the app is currently signed using and ad-hoc signature and will be blocked by MacOs's Gatekeep.

The app can in theory run on iOS too, but it isn't currently supported by llamasharp (the library i use for local LLMs), so i'm not distributing any app for iOS at the moment

GPU Support for local AI (LlamaSharp)

On Windows and Linux, you should be able to use Cuda 12 or 11 on Nvida GPUs. As a fallback, you should be able to use the Vulkan backend on every GPU which supports the Vulkan API.

On MacOs, you should be able to use the GPU trough the Metal API.

Finally, on Android there's currently no GPU support, at the moment.

Getting started

Requirements - Desktop

CPU

Windows: x86_64 CPU with SSE4.2 support, ARMv8 CPU

    Example: Intel Core 2 Duo E8200, AMD FX-4100, Snapdragon X Elite

macOS: x86_64 or ARM CPU (Apple Silicon)

    Example: Intel Core 2 Duo SU9400, Apple M1

Linux: x86_64 CPU with SSE4.2 support, ARMv8 CPU

    Example: Intel Core 2 Duo E8200, AMD FX-4100, Raspberry Pi 4

GPU

Integrated graphics with full Vulkan 1.0 support, Metal 3 support (macOS) or Direct3D 12 (12_0 feature level) support (Windows)

    Example: Intel HD Graphics 510 (Skylake), AMD Radeon R5 Graphics (Kaveri)

RAM

Min. 2 GB

(see Additional Requirements for local AI below)

Storage

~1.3GB for CUDA, ~500 MB without CUDA

(see Additional Requirements for local AI below)

Operating system

Windows 10, macOS 11.0, any Linux distribution released after 2018

Note: Metal support for GPU rendering and local AI need macOS 13.0 or newer

Requirements - Mobile Devices

CPU

Android: SoC with any 32-bit or 64-bit ARM or x86 CPU

    Example: Qualcomm Snapdragon 430, Samsung Exynos 5 Octa 5430

GPU

SoC featuring GPU with full Vulkan 1.0 support

    Example: Qualcomm Adreno 505, Mali-G71 MP2

RAM

Min 2 GB

(see Additional Requirements for local AI below)

Storage

~1.3GB for CUDA, ~500 MB without CUDA

(see Additional Requirements for local AI below)

Operating system

Android 9.0

Additional Requirements for local AI

Running an AI model on your machine could be more or less demanding depending on wich model you choose to run.

Fisrt of all, you need to have enough disk space for downloading the model into the work folder, you can either paste a .gguf model into the chat_model folder, or downloading it using the built-in downloader.

Then, you need enough VRAM/RAM to load the model. In the ideal situation, youur GPU should have enough VRAM for the GGUF model (and eventually the mmproj model if using a multimodal model) and ~1-2 GB extra for the KV Cache. If your VRAM isn't enough, the software should try to use as many vram as possible, and then load the remaning data into the RAM. This will result in slower response time than loading the whole model into the video card's VRAM.

Running it

1. Go to the Release section and dowload the package for your OS. Cuda packages are intended for nvidia users, if you don't have a nvidia gpu or don't plan to use CUDA, download the no-cuda package instead, which is smaller.
2. Run the project. On first launch you'll be asked to:
   • pick a working folder (this is where avatars, backgrounds, character cards, chat models, and saved chats live — kept separate from the install/repo so it survives updates and reinstalls);
   • optionally, pick an avatar and a background;
   • pick an AI provider. For using AI in your pc, you can pick one of the proposed models from the built-in downloader, or you can download a LLM model in the GGUF format from sites such as HuggingFace and put it into the working folder's chat_models/ subfolder. NOTE: some newer models may not be supported yet

Building / exporting

Build Requirements

• Godot 4.7.1 with .NET/Mono support (the "Godot .NET" build, not the standard one)
• .NET SDK matching the project's target framework (net10.0)

Export presets are already configured for Linux, Windows, MacOS and Android (export_presets.cfg).

Ecluding CUDA from the build

Files for CUDA can increase dramatically the release size, so i made possible to exclude that from the build, for those cases when isn't needed.

Directory.Build.targets reads an IncludeCuda MSBuild property (env var or -p:IncludeCuda=false) to skip the CUDA backend packages entirely. In the root folder you can find two scripts: export.sh (for Linux) and export.sh (For Windows). Those scripts wraps that instrinction into ready-made profiles:

Linux

./export.sh linux
./export.sh linux --no-cuda
./export.sh windows
./export.sh windows --no-cuda

Windows

.\export.ps1 linux
.\export.ps1 linux -NoCuda
.\export.ps1 windows
.\export.ps1 windows -NoCuda

Project structure

Scripts/
  App/      -- app shell, config load/save, responsive layout
  Ai/       -- ChatService, KernelFactory (provider wiring), chat history, expression/animation plugins
  Scene/    -- 3D avatar stage, background handling
  UI/       -- setup wizard panels, chat panel, settings
  Vrm/      -- working-folder scaffolding, bundled-asset copying
  Models/   -- .gguf catalog + downloader
Scenes/     -- the .tscn counterpart of each UI panel
Translations/ -- ui_strings.csv (source of truth) + generated .translation files
addons/     -- third-party Godot addons (see Third-party components below)

Third-party components

Component	Used for	License
godot-vrm (addons/vrm)	VRM 0.x/1.0 import	MIT
Godot-MToon-Shader (addons/Godot-MToon-Shader)	VRM's MToon (anime-style) shader	MIT
Godot Icons Fonts (addons/icons-fonts)	Material Design icon glyphs in the UI	MIT
Rakugo Nodes	misc. custom nodes	MIT
LLamaSharp	local GGUF inference	MIT
Microsoft Semantic Kernel	provider-agnostic chat orchestration, function calling	MIT
CharacterCardV3Sharp	character card parsing	MIT

Bundled sample assets

vrm_samples/, character_cards/, and backgrounds/ ship with a couple of sample avatars/character cards/images so the app is usable out of the box.

• Sample VRM avatars (Moonlight.vrm, Sunshine.vrm) — created by the author in VRoid Studio, distributed under the VRM Public License 1.0 (bundled in vrm_samples/).
• Sample backgrounds (backgrounds/) — AI-generated images created by the author; no specific license restrictions apply.
• Sample animations (animations/) — adapted from Mixamo character animations.

License

This project is licensed under the MIT License. Bundled sample assets follow their own terms — see Bundled sample assets above — and the third-party addons/packages keep their own licenses, listed in the table above.