Ai-Chan Companion

An intelligent companion for REPO. Ai-Chan follows the team, accepts light items (can change in configs), brings objects to the cart, can carry tumbled players, and includes chat commands, interactive physics, and Steam-powered multiplayer synchronization.

Plugin GUID: com.neko3004.aichancompanion

Overview

First of all, if you are seeing this mod on Thunderstore or any other modding platform, it means I decided the mod is good enough and not something broken that doesn't work properly. The initial idea and production for this mod began on August 6, 2026, at the end of my vacation and after I had finished creating my first simple mod to fix another mod (I didn't imagine it would be so difficult... I don't plan on making another mod anytime soon.) Since there have been many changes to the mod and each major change requires testing to be done from scratch, some parts of this readme might be outdated, though most of it should still be accurate.

Ai-Chan Companion adds one pet companion to the game. She spawns automatically at the start of each level and in the shop, appears near a player, and chooses an owner to follow.

She uses advanced NavMesh navigation and Ghost Probing to move intelligently around obstacles, pathfinds toward her owner, can open doors natively, and includes recovery systems to prevent her from getting stuck. Players can grab and throw her as a physics object; after landing, she recovers and resumes following her owner.

In multiplayer, the host/Master Client is authoritative for the AI. Other players receive synchronized position, rotation, state, owner, and interaction events.

Features

• Automatic Ai-Chan spawn in levels and in the shop.
• Floating Ai-Chan name tag above the character.
• Minimap Tracker: Ai-Chan appears as a distinct pink/magenta circle marker on the dirt finder minimap.
• Automatic owner following with configurable distance.
• Automatic owner switching in multiplayer.
• Manual owner switching by the current owner.
• Chat commands to call, send away, jump, play dead, change to preset sizes, or set a custom size.
• Petting system with animation, sound, and heart particles (heart particles not working properly yet).
• Can be grabbed, carried, and thrown by players.
• Falling physics, knockdown impact resistance, and recovery after being released or hit by fast-moving objects.
• No physical collision with players, preventing unwanted blocking and pushing.
• Advanced NavMesh movement with Ghost Probing to avoid tables/walls, automatic jumps when stuck, try door opening, and an emergency safety teleport when stuck.
• Accepts objects held by players based on configurable mass limits.
• Carried Item Scaling(opcional): Items can optionally inherit her scale while she carries them (host only config).
• Carries accepted items to the cart/delivery objective when a valid target is available. If two carts or more are present, she chooses the nearest; if no carts are present, she will go to the active extractor.
• Can carry players in a tumble state.
• Audio feedback for commands and interactions.
• Network Profiler for tracking the mod steam data usage.
• Explosion!! :3

Installation

Thunderstore Mod Manager

1. Install GenshinImpactOverhaul_REPO by GoblinKingShmee. (If you want Aino but don't want the GenshinImpactOverhaul_REPO mod to replace the enemies, simply disable the replacement in the GenshinImpactOverhaul_REPO mod settings; my mod should still work.)
2. Install REPO_SteamNetworking_Lib by Rune580.
3. Install Ai-Chan Companion in the same profile.
4. Install MenuLib by nickklmao.
5. Launch the game through Thunderstore Mod Manager or another compatible mod manager.

Important: Ai-Chan uses the Aino prefab supplied by GenshinImpactOverhaul_REPO. The companion visual cannot be created without that dependency. REPO_SteamNetworking_Lib is necessary for multiplayer.

Multiplayer

Multiplayer should already work for now...at least for what I tested with my friend (Woolfy), which I'm grateful for spending hours with me compiling, opening the game, testing, failing, fixing, compiling, opening, etc. <3

For a consistent multiplayer experience, every player in the lobby should use:

• Ai-Chan Companion on the same version
• GenshinImpactOverhaul_REPO
• REPO_SteamNetworking_Lib
• MenuLib

The mod requires strict compatibility with the Steam networking library. Using different versions can prevent loading or correct synchronization.

How it works

Spawning and ownership

• In single-player, Ai-Chan is created locally at the beginning of a level or in the shop.
• In multiplayer, only the Master Client/host creates the authoritative pet instance.
• When joining an active room, a client requests synchronization after the Steam handshake; the host replies with the pet position and ViewID so that client can recreate the same pet locally.
• On startup, Ai-Chan selects the nearest player as her owner and starts following them.
• In multiplayer, ownership can automatically change every 3 minutes by default. The selection prioritizes players who have not yet been selected during that level.
• Only the current owner can request a manual ownership switch.

Movement and recovery

Ai-Chan follows her owner through the NavMesh and stops near them according to the configured follow distances. With the new Ghost Probing system, she anticipates walls and obstacles to navigate. She can also open closed doors (or at least try) in her path.

If she encounters an obstacle or a partial path, she may perform an automatic jump. If she remains far above her owner for several seconds or falls into the void, the safety system teleports her to a navigable position near the owner.

She can be grabbed and thrown. While held or falling, her navigation is paused. When she touches the ground — or after the recovery timeout — she stands up, finds the NavMesh again, and returns to the following state. Fast-moving heavy objects hitting her will also knock her down based on the configured impact resistance.

Pathfinding & Movement Overhaul (The "Jitter" Fix)

After extensive debugging, a critical issue causing severe jittering, stuttering, and velocity drops (especially when carrying the player/items to the cart) has been completely resolved on August 24, 2026. (10+ hours just on it...I almost gave up on fixing it, it was soo exhausting).

The Core Problems (Suspects):

1. NavMeshObstacle Carving Conflict: The PhysGrabCart actively carves a dynamic hole in the NavMesh. The Unity NavMeshAgent's native obstacle avoidance would detect this hole and force the agent to violently brake (dropping speed from 3.5m/s to ~1.5m/s) to prevent "falling off" the NavMesh.
2. Procedural Floor Interpolation Tug-of-War: In procedural levels (like Factories/Mines), the floor has micro-seams. The NavMeshAgent forced the position to snap to these seams, while the Rigidbody interpolation tried to smooth it out. This created a 60-frames-per-second mathematical conflict, resulting in visual "500ms ping" stutters.
3. Ragdoll Drag: When carrying a player, only the main PlayerTumble colliders were disabled. The rest of the player's body (arms/legs) remained solid, dragging on the floor and applying a massive -15m/s physics drag against the pet.
4. Update vs LateUpdate Desync: Calculating carrying positions in Update while the camera renders in LateUpdate created a 1-frame visual desynchronization.

The Solution (The "Decoupled Agent" Architecture):

• Brain/Body Decoupling: Disabled agent.updatePosition and agent.updateRotation. The NavMeshAgent (the brain) now silently calculates the perfect mathematical path, while the physical 3D model (the body) uses a smooth Vector3.Lerp to follow it. This entirely absorbs any procedural floor bumps.
• Native Evasion Disabled: Disabled autoBraking and set ObstacleAvoidanceType.NoObstacleAvoidance so the pet confidently maintains a constant 3.5m/s speed without fearing the cart's carved hole.
• Total Ragdoll Suppression: Implemented a root-level collider scan that temporarily ignores collision for every single limb of the carried player, eliminating all physics friction.
• Unified LateUpdate Kinematics: All physical transportation of items and players is now strictly enforced inside LateUpdate with forced isKinematic = true, ensuring 1:1 frame-perfect synchronization with the player's camera.

Items and rescue

1. Hold a physics item (She will not pick up carts, monsters, doors, or dead players [dead player carrying may be supported in the future]).
2. Stand near Ai-Chan.
3. Press the give-item key, R by default.
4. She picks up the object and attempts to bring it to the available cart/delivery destination.
5. If two or more players are holding the item, she will not carry it to prevent sync errors.
6. If she is grabbed or falls during the delivery, the item will drop on the ground near her.

The same interaction can be used with a player in a downed/tumble state. Hold a downed teammate and press R, or, if your own character is downed, press R while holding no item. Ai-Chan will attempt to carry that player.

The accepted maximum item mass is configurable and defaults to 3. The internal item-give distance defaults to 4.5 m. Carried items can optionally scale to match Ai-Chan's current size by enabling the Inherit Pet Scale On Carry setting.

Shop extractor behavior

In the shop, Ai-Chan can deliver items to the Extraction Point (the shop's "cart" equivalent). For this to work correctly:

• The extraction point must be unlocked and active.
• If the extraction point is locked, Ai-Chan will instantly drop the item or player at her feet instead of attempting delivery.
• This prevents the pet from getting stuck trying to deliver to an unavailable objective.
• She will not pick up carts.

When a valid extraction point is available, Ai-Chan approaches it and drops the item at a randomized position within the "In Cart" collider to avoid stacking items exactly on top of each other.

Controls

All three keys can be changed in the configuration.

Chat commands

To recognize a command, the chat message must include a pet keyword: aino, ai-chan, aichan, or pet.

It works with the SoloChat mod, so it doesn't necessarily need to be a hosted online room.

The mod matches keywords in sentences, so typing "become small aino" will still trigger the small size command (0.5x). Commands that change the AI are processed by the Master Client. This prevents different clients from controlling the same pet at the same time. Chat messages are read locally only to trigger pet commands and are not hosted, stored, or sent to any external server. Why not just a keybind? Aside from there being so many commands, I thought it would be cool to hear commands from friends, since the game has a chat-reading system. Supports English and Portuguese aliases

Configuration

After launching the game once, open the in‑game ModMenu configuration UI to adjust Ai‑Chan settings.

For now, only the host apparently defines the configuration for everyone; I'll change that to allow some settings for the client as well, such as Follow Range, Stopping Distance, Audio...but there is no expectation for me to do it for now. Don't be afraid to change these movement, interaction, and physics settings, as they may not be balanced or fit your play style.

I'm from Brazil, so don't be surprised if I forgot to translate some of the logs into English, oops :3

Multiplayer networking

Ai-Chan Companion combines the game's Photon room infrastructure with REPO SteamNetworking Lib to send custom pet packets through Steam.

REPO SteamNetworking Lib is an API for mod developers to offload mod networking from REPO’s Photon servers, helping the REPO devs save bandwidth. Ai‑Chan Companion uses it to send pet packets over Steam networking.

Authority

The Master Client is responsible for:

• creating Ai-Chan in online sessions;
• running navigation, AI, door interactions, and relevant physics;
• processing item-give and player-carry requests;
• switching the owner;

Remote clients do not run pet navigation or physics. They reproduce the received position, rotation, state, and owner, while keeping the Rigidbody kinematic to avoid physics divergence.

State updates

The host sends a snapshot every 0.05 seconds, up to 20 updates per second, containing:

• PetViewID to identify the instance;
• OwnerViewID to identify the current owner;
• pet state;
• sequence number;
• position;
• rotation.

On clients, short movement corrections are smoothed through interpolation. If the position difference exceeds 3.0 m, the pet is moved directly to the received position to correct visible desynchronization.

Synchronized events

In addition to continuous state, Steam networking sends dedicated packets for:

• pet spawning and synchronization for late-joining players;
• synchronization requests to the host;
• item delivery;
• player-carry requests;
• picking up and dropping an item or player (including scale inheritance);
• petting;
• manual owner switching.
• explosion trigger and countdown;

Item delivery, player carrying, and owner-switch events are sent to the host. The host resolves the referenced objects through their PhotonView, executes the authoritative action, and sends the necessary visual results to the other players.

Troubleshooting

Ai-Chan does not spawn

• Confirm that GenshinImpactOverhaul_REPO is installed and loads before this mod.
• Confirm that REPO_SteamNetworking_Lib is installed.
• Check the BepInEx console for errors and keep Enable Debug Logs = true while diagnosing the issue.

A client cannot see the pet

• Make sure the host and clients have the mod and all dependencies installed.
• Make sure every player uses compatible versions.
• Rejoin the room if the Steam handshake fails; a client requests pet reconstruction about 2 seconds after joining.

Ai-Chan does not accept an item

• Stay within the configured interaction distance.
• Hold a valid physics item that does not exceed Max Carried Mass.
• Make sure the pet isn't already carrying something.

Ai-Chan appears stuck

• Give the automatic jump or safety teleport a few seconds to activate.
• The new Ghost Probing system will attempt to navigate around most objects automatically.
• Avoid leaving her in areas without NavMesh.
• Adjust Auto Jump Stuck Delay, Speed, and Ghost Probe Rays settings if needed.

Compatibility and notes

• This mod is made for REPO and relies on game-provided classes, physics layers, NavMesh, and networking.
• The mod uses the Aino visual/prefab supplied by GenshinImpactOverhaul_REPO.
• In multiplayer, the host should maintain a stable connection because it is authoritative for the AI.
• Mods that heavily alter Photon, PhysGrabObject physics, carts, NavMesh, or the Aino prefab may cause incompatibilities.

Credits

• Ai-Chan Companion: mod development.
• BepInEx: plugin loader.
• Harmony: runtime patching.
• GenshinImpactOverhaul_REPO: Insert Aino prefab/visual into the game, by GoblinKingShmee.
• REPO_SteamNetworking_Lib: Steam-based packets and multiplayer synchronization by Rune580.
• MenuLib (nickklmao): in‑game configuration UI library.
• REPO: base game, physics, navigation, Photon, and interaction systems.

Thanks

A big thank you to GoblinKingShmee. I asked him via Discord, and he gave me permission to use his mod to load the model it adds to the game into my own mod. Again, a huge thank you to my friend(Woolfy) for spending countless hours with me compiling, opening the game, testing, failing, fixing, and testing again. implementing multiplayer simply wouldn't have been possible without him <3 (So, be grateful to him too :<)

Legal / Asset notice

• The Aino character model and related assets are the property of HoYoverse. This mod does not claim ownership of, nor distribute, HoYoverse assets.

AI assistance disclaimer

This mod was developed with the assistance of AI tools for code generation and refactoring. Since I don't know C#, I heavily relied on AI to write the code while I tested, provided feedback, compiled, and rewrote parts the way I wanted. All gameplay logic, system design, implementation requirements, test plans, and iterative feedback were authored and directed by me through multiple review cycles (I gained over 50 hours of playtime just testing the mod -_-)

AI was used as a productivity aid, not as the designer of the mod's behavior or features. Most of the time, the AI would break a mechanic that was working perfectly (like grab, animations, or pathfinding/following) and couldn't fix it. When this happened, I was forced to roll back to an earlier save, losing progress. Sometimes, realizing my approach wasn't going to work, I had to start over from scratch.

For example, I was suggested to use an in-game item as a grab mechanism for Ai-Chan by inserting the item invisibly inside the model. It kind of worked—or so I thought—but it was never going to truly work because of collision issues. If the item broke, it disappeared along with its value, mechanics, and the model of Ai-Chan. It just didn't work! :)

A lot was fixed through this back-and-forth process. Many hours were spent on this mod, which I created with a lot of care~

Known issues? Not sure because I fixed a lot of things...

• Sometimes she won't find the path to the cart if it is too far away or if the map has dead-ends on the way back.
• Her pathfinding is kinda experimental, so she might get lost if no one is in her direct line of sight.
• When spawning, she sometimes won't attach to the NavMesh properly and won't move (or moves very slowly). Just grab her and release; she will correct it.
• For the multiplayer client, its rotation might appear jittery or stuck.

Mod architecture (Just for curiosity, line counts might be outdated)

What about the other models in GenshinImpactOverhaul_REPO?

ya..I briefly tested making a "general" version; I might even make it available later (without posting it because it's kind of terrible and it's way behind compared to what this mod does). Some models have specific peculiarities while others are easier, so I focused only on Aino, which is what initially motivated me to make this mod. But in theory, it would be possible to extend this in the future... or maybe load custom models without dependency. I don't know how imports work... hence the dependency on the GenshinImpactOverhaul_REPO mod.

Don't expect many updates, since I'm busy with a lot of things... nya~

Anyway, I hope you have fun and give Aino lots of headpats!~

Contact

You can contact me at discord: nekomimiowo Or at the github of this mod: https://github.com/NekomimiOwO