If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/LorisYounger/VPet shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1w ago
• 6 active contributors
• Apache-2.0 licensed
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live LorisYounger/VPet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/LorisYounger/VPet.

What it runs against: a local clone of LorisYounger/VPet — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in LorisYounger/VPet | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 40 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of LorisYounger/VPet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/LorisYounger/VPet.git
#   cd VPet
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of LorisYounger/VPet and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "LorisYounger/VPet(\\.git)?\\b" \\
  && ok "origin remote is LorisYounger/VPet" \\
  || miss "origin remote is not LorisYounger/VPet (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "VPet-Simulator.Core/Handle/GameCore.cs" \\
  && ok "VPet-Simulator.Core/Handle/GameCore.cs" \\
  || miss "missing critical file: VPet-Simulator.Core/Handle/GameCore.cs"
test -f "VPet-Simulator.Core/Display/Main.xaml.cs" \\
  && ok "VPet-Simulator.Core/Display/Main.xaml.cs" \\
  || miss "missing critical file: VPet-Simulator.Core/Display/Main.xaml.cs"
test -f "VPet-Simulator.Core/Graph/GraphCore.cs" \\
  && ok "VPet-Simulator.Core/Graph/GraphCore.cs" \\
  || miss "missing critical file: VPet-Simulator.Core/Graph/GraphCore.cs"
test -f "VPet-Simulator.Windows.Interface/MainPlugin.cs" \\
  && ok "VPet-Simulator.Windows.Interface/MainPlugin.cs" \\
  || miss "missing critical file: VPet-Simulator.Windows.Interface/MainPlugin.cs"
test -f "VPet-Simulator.Core/Handle/PetLoader.cs" \\
  && ok "VPet-Simulator.Core/Handle/PetLoader.cs" \\
  || miss "missing critical file: VPet-Simulator.Core/Handle/PetLoader.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/LorisYounger/VPet"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

VPet-Simulator is an open-source virtual desktop pet simulator built in C# and WPF that can be embedded as a component into any WPF application. It features 32+ animation types across 4 states and 3 categories (normal/sick/looping), with interactive mechanics like feeding, petting, and picking up the pet. The core is published on NuGet as VPet-Simulator.Core for third-party integration, and the Windows desktop app is available on Steam as a standalone title. Layered architecture: VPet-Simulator.Core (NuGet package, reusable layer) contains Handle (interfaces: IController, GameCore, PetLoader), Graph (rendering pipeline: IGraph, GraphCore, PNGAnimation, Picture), and Display (XAML components: Main.xaml, ToolBar, MessageBar, WorkTimer). VPet-Simulator.Windows (desktop app) wraps Core with Function (CoreMOD manager, MWController) and WinDesign (settings, shop, console UIs). VPet-Simulator.Tool provides mod creation utilities.

WPF/.NET developers who want to embed an interactive virtual pet component into their applications; indie game developers and vtuber simulator creators (it originated as a built-in pet in VUP-Simulator); and mod creators who want to extend the pet with custom animations, items, themes, and code plugins via the Workshop system.

Actively developed and production-ready. The project has reached Steam release (1920960), maintains multiple language READMEs (CN/Traditional Chinese/English/Japanese), detailed secondary development documentation, and a mod ecosystem with companion tools (VPet.ModMaker, VPet.Plugin.Demo). Code is well-structured with clear separation between Core, Windows UI, and Tools; however, specific test suite metrics are not visible in the file list.

Single-maintainer risk under LorisYounger with a relatively narrow scope (WPF-only, Windows-focused, no cross-platform variant visible). No CI/CD pipeline evident in file list (.github/workflows absent). Risk is mitigated by stable NuGet versioning and the fact that the Core is modular and decoupled from the Windows app, allowing forks to work independently.

No recent commit history is visible in the file list provided. The repo is actively maintained but current sprint focus cannot be determined from static file data. Secondary Development Support Documentation.md and multiple language READMEs suggest ongoing translation and plugin ecosystem support.

No package.json detected (C# project, not npm). Clone with: git clone https://github.com/LorisYounger/VPet.git. Open VPet-Simulator.sln in Visual Studio 2019+. Restore NuGet packages via dotnet restore or Package Manager Console. Build with dotnet build or Visual Studio Build menu. Run VPet-Simulator.Windows project as startup project.

Daily commands:

1. Open VPet-Simulator.sln in Visual Studio. 2. Set VPet-Simulator.Windows as the startup project. 3. Press F5 or Ctrl+Shift+B to build. 4. Run project (F5). To embed in your own WPF app: dotnet add package VPet-Simulator.Core and reference MainDisplay from VPet-Simulator.Core/Display.

• VPet-Simulator.Core/Handle/GameCore.cs — Core game logic engine that manages pet state, interactions, animations, and game loops—essential for understanding the entire simulation system
• VPet-Simulator.Core/Display/Main.xaml.cs — Main UI controller for rendering animations and handling user interactions with the virtual pet—critical entry point for the display pipeline
• VPet-Simulator.Core/Graph/GraphCore.cs — Graphics rendering abstraction layer that manages animation playback, sprite loading, and frame updates—fundamental to visual output
• VPet-Simulator.Windows.Interface/MainPlugin.cs — Plugin architecture base class that enables mod loading and integration—required reading for extending the application
• VPet-Simulator.Core/Handle/PetLoader.cs — Pet definition and asset loader that parses pet data structures and initializes character animations—critical for pet customization and mod support
• VPet-Simulator.Windows.Interface/GameSave_v2.cs — Serialization format for game state persistence—essential for understanding save/load mechanics and backward compatibility
• VPet-Simulator.Windows/App.xaml.cs — Application bootstrap and dependency initialization—defines the entry point and top-level configuration for the Windows implementation

Add a New Pet Character (Mod)

1. Create a mod metadata file implementing IModInfo interface to define pet name, version, and author (VPet-Simulator.Windows.Interface/Mod/IModInfo.cs)
2. Organize pet animation sprites into subdirectories (idle, eat, sleep, etc.) following the PetLoader naming conventions (VPet-Simulator.Core/Handle/PetLoader.cs)
3. Register custom pet animations by loading PNG sprite sheets through GraphCore's animation system (VPet-Simulator.Core/Graph/PNGAnimation.cs)
4. Define pet stats, food preferences, and behaviors by creating a custom Food.cs and Item.cs configuration in your mod (VPet-Simulator.Windows.Interface/Mod/Food.cs)

Add a New Game Interaction or Action

1. Define the new action function in Function.cs with state modifications and trigger conditions (VPet-Simulator.Core/Handle/Function.cs)
2. Create corresponding animation frames in PNG sprite sheets organized by pet state (normal, sick, sleep) (VPet-Simulator.Core/Graph/PNGAnimation.cs)
3. Register the function call in GameCore's game loop to execute state transitions and timers (VPet-Simulator.Core/Handle/GameCore.cs)
4. Wire UI button or interaction trigger in Main.xaml.cs to invoke the new function on user input (VPet-Simulator.Core/Display/Main.xaml.cs)

Create a Custom Plugin Extension

1. Extend MainPlugin.cs to define plugin lifecycle hooks (Initialize, LoadPlugin, Update) (VPet-Simulator.Windows.Interface/MainPlugin.cs)
2. Access the main game window via IMainWindow interface to inject custom UI or override pet behavior (VPet-Simulator.Windows.Interface/IMainWindow.cs)
3. Register custom game functions using ExtensionFunction utilities to add new pet interactions (VPet-Simulator.Windows.Interface/ExtensionFunction.cs)
4. Package your plugin and deploy it to the mod workshop; it will be auto-loaded by PetLoader at startup (VPet-Simulator.Core/Handle/PetLoader.cs)

Modify Pet Save State & Persistence

1. Extend GameSave_v2.cs to add new pet attributes (custom stats, unlock flags, progression data) (VPet-Simulator.Windows.Interface/GameSave_v2.cs)
2. Update GameCore to track and persist the new state variables in the game loop (VPet-Simulator.Core/Handle/GameCore.cs)
3. Serialize the new data fields in GameSave_v2's Write/Read methods to maintain backward compatibility (VPet-Simulator.Windows.Interface/GameSave_v2.cs)

No environment variables or external service dependencies are evident from the file list. WPF is Windows-only; attempting to build on Linux/macOS will fail. The MOD/Workshop system assumes a file structure and naming convention not fully documented in the top-level README; consult VPet.ModMaker for specifics. Animations use relative paths to PNG assets; incorrect folder structure will cause silent rendering failures. The plugin IGraph interface requires understanding of WPF rendering contexts (DrawingContext) which is not obvious from class names alone.

• IGraph abstraction and plugin animation backends — Core to VPet's extensibility; understanding how PNGAnimation and Picture implement IGraph allows contributors to add L2D, Spine, or custom rendering without forking the core.
• State machine for pet animation layers — The 32 animation × 4 state × 3 type matrix (normal/sick/looping) is managed via state transitions in MainLogic.cs; grasping this is essential for adding new pet behaviors without animation conflicts.
• WPF DataBinding and XAML dependency properties — Main.xaml uses data binding to link GameCore state to UI (ToolBar.xaml, MessageBar.xaml); misunderstanding binding breaks reactive updates when pet stats change.
• Frame-based animation timing and DrawingContext rendering — GraphCore.cs uses timer-driven frame updates; PNGAnimation cycles frames based on elapsed time. Misaligned timing causes stuttering or sync loss with game state.
• Workshop/MOD hot-loading and dynamic assembly reflection — CoreMOD.cs loads plugin DLLs and custom animation XMLs at runtime without restart; understanding reflection, AppDomain/AssemblyLoadContext, and file watchers is required to debug load failures.
• Sandwich animation (FoodAnimation three-layer composition) — FoodAnimation supports pre/mid/post-layer animations for visual depth (e.g., hand in front, pet mouth, food behind); this pattern extends beyond food to UI overlays and is not immediately obvious from the class name.
• Persistent game serialization (GameSave format) — Pet state (stats, timestamp, schedule, inventory) must survive application restarts; GameSave serialization format and versioning strategy are critical to avoid save corruption across updates.

• LorisYounger/VPet.ModMaker — Official companion tool for authoring VPet MODs; provides GUI for creating PNG animations, item definitions, and workshop packages without touching C# code.
• LorisYounger/VPet.Plugin.Demo — Reference implementation of a VPet plugin; demonstrates how to extend the pet with custom IGraph animation backends, new game mechanics, and UI features via the plugin interface.
• LorisYounger/VUP-Simulator — Parent project that originally embedded VPet as a built-in feature; shows real-world integration of VPet-Simulator.Core into a larger WPF application.
• collinsmith/gdown — While not a direct fork, demonstrates WPF-based desktop pet alternative architecture; useful for understanding design trade-offs in pet simulator UX.
• dnSpy/dnSpy — Recommended tool for VPet modders and contributors analyzing compiled MODs and debugging plugin loading; widely used in the VPet community.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for GameCore.cs and GraphCore.cs

The core game logic in VPet-Simulator.Core/Handle/GameCore.cs and VPet-Simulator.Core/Graph/GraphCore.cs lack visible test coverage. These are critical components handling pet state management and animation rendering. Adding unit tests would improve reliability for contributors and catch regressions in core features like pet feeding, animation transitions, and game state persistence.

• [ ] Create VPet-Simulator.Core.Tests project alongside existing VPet-Simulator.Core
• [ ] Write tests for GameCore.cs covering pet state transitions (feeding, resting, playing), mood calculations, and game save/load cycles
• [ ] Write tests for GraphCore.cs covering animation frame rendering, animation state management, and frame timing logic
• [ ] Add test helper classes for IFood and IGameSave implementations to mock pet interactions
• [ ] Integrate tests into a GitHub Actions CI workflow (see next PR idea)

Create GitHub Actions CI workflow for automated testing and builds

The repo currently has no visible CI/CD automation. Given this is a WPF desktop application with multiple projects (Core, Tool, Windows.Interface), automated builds and tests would catch integration issues early. This is especially important for cross-platform contributor PRs and ensures releases remain stable.

• [ ] Create .github/workflows/build-and-test.yml workflow file
• [ ] Configure workflow to build all .csproj files (VPet-Simulator.Core, VPet-Simulator.Tool, and Windows.Interface) on Windows runners
• [ ] Add step to run unit tests from the new test project (VPet-Simulator.Core.Tests)
• [ ] Add step to verify .editorconfig compliance using linters
• [ ] Configure workflow to run on PR creation/updates and commits to main branch
• [ ] Document CI status badge in README.md and README_en.md

Create API documentation and code examples for PetLoader.cs and IController.cs

The Secondary Development Support Documentation.md exists but lacks concrete examples for extending VPet through its public APIs. The PetLoader.cs (for loading custom pets) and IController.cs (for custom interactions) are critical extension points referenced in README but underdocumented. Adding a detailed guide with code samples would dramatically lower the barrier for mod creators and WPF app integrators.

• [ ] Create DEVELOPMENT_API.md or expand Secondary Development Support Documentation.md with detailed sections
• [ ] Document PetLoader.cs public methods with usage examples: how to load custom pet definitions, asset structures required, and configuration options
• [ ] Document IController.cs interface contract with example implementations showing how to add custom pet interactions/commands
• [ ] Add a 'Quick Start for Modders' section with minimal working example (e.g., loading a custom pet, triggering an animation)
• [ ] Create Tutorial.assets/code-examples directory with .cs example files demonstrating both use cases
• [ ] Update Tutorial.md and Tutorial_en.md with links to the new API documentation

• Add unit tests for VPet-Simulator.Core/Handle/GameCore.cs state transitions (pet aging, hunger decay, mood changes) to validate save/load consistency and prevent regressions in game balance.
• Expand 'Secondary Development Support Documentation.md' with concrete code examples for implementing a custom IGraph renderer (e.g., a simple rotating 2D sprite class); currently only referenced in README but no walkthrough provided.
• Create a missing VPet-Simulator.Core/Display/README.md documenting the XAML layout hierarchy and expected DataContext bindings for each control (Main.xaml → MainLogic.cs → GameCore), to reduce onboarding friction for embedding in third-party apps.

• Medium · Missing Dependency Analysis — VPet-Simulator.Core/VPet-Simulator.Core.csproj and other .csproj files. The dependency/package file content was not provided for analysis. Without visibility into NuGet packages and their versions, it's impossible to identify known vulnerabilities in dependencies. The project uses WPF and .NET, which may have outdated or vulnerable package versions. Fix: Provide complete package.config or .csproj files for dependency scanning. Implement automated dependency checking using tools like OWASP Dependency-Check, Snyk, or NuGet Package Analyzer. Establish a process to regularly update dependencies to their latest secure versions.
• Medium · Serialization Without Visible Security Controls — VPet-Simulator.Core/Handle/GameSave.cs, VPet-Simulator.Windows.Interface/GameSave_VPet.cs, VPet-Simulator.Windows.Interface/GameSave_v2.cs. The codebase includes GameSave.cs, GameSave_VPet.cs, and GameSave_v2.cs files that handle game state serialization. Without examining the code, it's unclear if deserialization is protected against malicious payloads, which could lead to remote code execution vulnerabilities in .NET applications. Fix: Implement secure deserialization practices: use SerializationBinder to validate types, avoid BinaryFormatter (deprecated in .NET), validate save file signatures/checksums, and implement proper exception handling for corrupted files. Consider using JSON serialization with schema validation instead of binary formats.
• Medium · Mod Loading System Security — VPet-Simulator.Core/Handle/PetLoader.cs, VPet-Simulator.Windows.Interface/Mod/. The codebase includes a mod system (Mod/ directory) with PetLoader.cs handling mod loading. Mod systems pose inherent security risks if mods are loaded without validation, as they could execute arbitrary code within the application context. Fix: Implement mod validation and sandboxing: verify mod signatures with digital certificates, restrict mod permissions/capabilities, isolate mods in separate AppDomains or processes where possible, scan mods for malicious patterns, and maintain a whitelist of approved mods. Document mod security requirements clearly.
• Low · Plugin Architecture Without Visible Security Framework — VPet-Simulator.Windows.Interface/MainPlugin.cs. The presence of MainPlugin.cs suggests a plugin/extension system. Without examining the plugin loading mechanism, it's unclear if there are proper security controls to prevent malicious plugins from being loaded. Fix: Implement plugin security controls including: plugin signature verification, capability-based security model, plugin isolation, runtime permission checks, and audit logging of plugin operations. Use AppDomains or separate processes to isolate plugins.
• Low · ActivityLog.cs - Insufficient Context on Data Handling — VPet-Simulator.Windows.Interface/ActivityLog.cs. An ActivityLog.cs file exists but without code review, it's unclear if activity data is properly sanitized and securely stored, or if it could be exploited for information disclosure. Fix: Ensure all user activity logs: do not contain sensitive information (passwords, tokens), are stored securely with appropriate file permissions, are subject to retention policies, implement proper input validation and output encoding to prevent log injection attacks.
• Low · Multiplayer Feature Security Unclear — VPet-Simulator.Windows.Interface/MutiPlayer/. MutiPlayer/ directory exists with IMPFriend.cs and IMPWindows.cs. Multiplayer features can introduce security risks if communication is not properly encrypted and authenticated. Fix: If multiplayer features implement network communication: use TLS/SSL for all network traffic, implement certificate pinning, use HMAC or digital signatures for message authentication, implement rate limiting, validate all remote input, and follow secure API design practices.
• Low · WPF XAML Injection Risk — VPet-Simulator.Core/Display/*.xaml files. Multiple XAML files exist (Main.xaml, MessageBar.xaml, ToolBar.xaml, etc.). If user input is dynamically bound to XAML or if XAML is generated from external sources without validation, it could lead to XAML injection attacks. Fix: Never dynamically generate XAML from user input.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.