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/xenia-project/xenia 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 — Mixed signals — read the receipts

• Last commit 3mo ago
• 10 active contributors
• Other licensed
• Tests present
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows 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 xenia-project/xenia repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xenia-project/xenia.

What it runs against: a local clone of xenia-project/xenia — 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 xenia-project/xenia | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 110 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xenia-project/xenia. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xenia-project/xenia.git
#   cd xenia
#
# 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 xenia-project/xenia and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "docs/building.md" \\
  && ok "docs/building.md" \\
  || miss "missing critical file: docs/building.md"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.md"
test -f "android/android_studio_project/app/build.gradle" \\
  && ok "android/android_studio_project/app/build.gradle" \\
  || miss "missing critical file: android/android_studio_project/app/build.gradle"
test -f ".appveyor.yml" \\
  && ok ".appveyor.yml" \\
  || miss "missing critical file: .appveyor.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 110 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~80d)"
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/xenia-project/xenia"
  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).

Xenia is an experimental Xbox 360 emulator written in C++ that executes Xbox 360 game binaries on modern hardware (Windows, Linux, Android) by translating PowerPC instructions and emulating the Xenon CPU architecture, GPU via Vulkan, and system calls. It's a research project focused on reverse-engineering and emulating a complex modern console rather than a production-grade commercial emulator. Monolithic C++ codebase with cross-platform build via Premake/xb (Starlark config in .drone.star, batch/shell scripts in root). Core emulation in src/ (inferred), Android bindings in android/android_studio_project/ using NDK, GPU tracing in GpuTraceViewerActivity.java. Build artifacts use AppVeyor for Windows and Drone for Linux; clang-format enforces style uniformly.

Reverse-engineering enthusiasts, emulation researchers, game preservation hobbyists, and Xbox 360 game developers who want to understand or run legacy games on modern platforms. Contributors are expected to have advanced C++ knowledge and interest in low-level systems programming.

Actively developed but experimental: the repo shows regular CI builds (AppVeyor, Drone), Android integration with NDK 25, and structured build tooling via Premake/xb scripts. However, the README explicitly states 'Quite a few real games run. Quite a few don't,' indicating incomplete compatibility. This is a research project, not production-ready emulation software.

Moderate-to-high risk for external use: this is a volunteer-run research project with no guaranteed support timeline. The legal disclaimer explicitly warns about reverse-engineering activity, and game compatibility is highly variable (tracked in a separate repo). Single-maintainer risk is real; community coordination happens primarily via Discord. Binary format compatibility breaks are likely as research progresses.

Active cross-platform development: recent focus on Android support (compileSdkVersion 33, NDK 25.0.8775105, arm64-v8a + x86_64 ABI filters), GPU trace viewer improvements, and game compatibility expansion. CI/CD is configured via .appveyor.yml and .drone.star, indicating continuous integration testing.

Clone: git clone https://github.com/xenia-project/xenia.git && cd xenia. Install per docs/building.md (requires Premake, LLVM, Vulkan SDK). Build: run xb script in the repo root (Python-based build tool). Run: xb build then launch the compiled executable or APK on Android.

Daily commands: Windows: xb build && xb run <game_iso>. Linux: same via Drone CI or local build. Android: cd android/android_studio_project && gradle build && gradle installDebug (builds via NDK, targets arm64-v8a and x86_64). Game files must be legally owned Xbox 360 discs.

• README.md — Entry point documenting project vision, status, build instructions, and community guidelines for all contributors.
• docs/building.md — Essential build system and environment setup documentation that every contributor must follow to work locally.
• .github/CONTRIBUTING.md — Contribution guidelines defining coding standards, PR process, and development workflow for the project.
• android/android_studio_project/app/build.gradle — Android build configuration that defines NDK integration, SDK versions, and native compilation for cross-platform support.
• .appveyor.yml — CI/CD pipeline definition for Windows builds and automated testing on every commit.
• .clang-format — Code style and formatting standards enforced across the C++ codebase for consistency.
• .gitmodules — Declares external dependencies and submodule versions required for building the emulator.

• LauncherActivity / WindowedAppActivity (Java, Android Framework, JNI) — Android lifecycle, game selection, settings, and JNI initialization bridge to native emulator.
  • Failure mode: App crash → user loses game state; critical for UX stability on mobile.

Add a New Android Activity/Screen

1. Create Java activity class extending Android Activity in android/android_studio_project/app/src/main/java/jp/xenia/emulator/ (android/android_studio_project/app/src/main/java/jp/xenia/emulator/NewFeatureActivity.java)
2. Define UI layout XML in android/android_studio_project/app/src/main/res/layout/ (android/android_studio_project/app/src/main/res/layout/activity_new_feature.xml)
3. Register activity in AndroidManifest.xml with intent-filters (android/android_studio_project/app/src/main/AndroidManifest.xml)
4. Hook JNI calls to native emulator code following WindowedAppActivity pattern (android/android_studio_project/app/src/main/java/jp/xenia/emulator/WindowedAppActivity.java)

Add a New Documentation Page for CPU/GPU Feature

1. Create markdown file in docs/ following convention (e.g., docs/instruction_tracing.md) (docs/new_feature.md)
2. Reference it in the main README with link to GitHub wiki or docs/ (README.md)
3. Include architecture diagrams (stored in docs/images/) and code examples (docs/images/new_architecture.png)

Update CI/CD Pipeline for New Platform

1. Add new build job in .appveyor.yml for Windows or .drone.star for other platforms (.appveyor.yml)
2. If Android build, update NDK arguments in build.gradle with new platform target (android/android_studio_project/app/build.gradle)
3. Update docs/building.md with new platform setup instructions (docs/building.md)

• PPC CPU JIT Compiler — Xbox 360 used PowerPC processors; JIT translates to native x86/ARM for performance on emulation host.
• Vulkan Graphics API — Cross-platform low-level GPU access for high-performance graphics on Windows, Linux, Android, and macOS.
• Android NDK + Java JNI — Bridges high-performance native C++ emulator core with Android UI framework for mobile deployment.
• Premake Build System — Generates platform-specific build files (Visual Studio, Make, Xcode) from single Lua-based configuration.
• AppVeyor & Drone CI — Automates builds and testing across Windows and Linux to catch regressions early.

• JIT over interpretation

  • Why: JIT compilation has startup overhead but achieves near-native execution speed for long-running games.
  • Consequence: First 1-5 seconds slower, but sustained 60fps playable performance. Trade memory for speed.

• Vulkan over Direct3D/OpenGL

  • Why: Vulkan is cross-platform, low-overhead, and matches Xbox 360's console-level GPU abstraction.
  • Consequence: Steeper learning curve than OpenGL, but better multi-platform support and driver efficiency.

• Monolithic native core with JNI bridge

  • Why: Keeps performance-critical CPU/GPU code in optimized C++ while Android app provides UI.
  • Consequence: JNI boundary overhead (~microseconds) but isolation keeps Android crashes from killing emulator.

• Submodules for dependencies

  • Why: Decouples project versions of CPU, GPU, utilities to allow parallel development.
  • Consequence: Complex dependency management and higher clone size; requires git submodule update --init.

• Does not target consoles other than Xbox 360 (e.g., Xbox One, PlayStation).
• Does not provide ROM distribution or game licensing (research-only, users supply own copies).
• Does not support online multiplayer or Xbox Live integration.
• Does not run on 32-bit systems or ARM32 Android (minSdkVersion 24 = Android 7.0, NDK ARM64 only).
• Not a debugger/profiler for game development—primarily for emulation research and preservation.

PowerPC ISA knowledge required: emulator targets Xbox 360's Xenon CPU (3-core PowerPC), not x86; contributor must understand CPU architecture to modify instruction handling. Vulkan mandatory for GPU: no fallback to OpenGL; requires modern GPU drivers. Reverse-engineering legal gray area: project explicitly disclaims enabling piracy; contributors must use legally purchased titles only. Game compatibility is per-title: a fix for one game may break another; comprehensive testing suite appears absent from file list.

• PowerPC JIT Compilation — Xenia translates Xbox 360 PowerPC machine code to native x86/ARM at runtime; you must understand how JIT works to debug CPU emulation or optimize instruction handling
• Xenon GPU Architecture (GCN-derived Radeon) — Xbox 360 GPU is a custom ATI Radeon; Xenia translates GPU commands to Vulkan, requiring knowledge of GPU command buffers and tile-based deferred rendering
• Memory-Mapped I/O — Xbox 360 hardware (GPU, sound, network) is accessed via memory-mapped registers; emulator must trap memory accesses and dispatch to hardware handlers
• System Call Emulation (Syscall Hooking) — Games invoke Xbox 360 kernel APIs via syscalls; Xenia intercepts these calls and reimplements them in software, similar to QEMU user-mode emulation
• Vulkan Graphics API — GPU backend is Vulkan, not DirectX; understanding command buffer recording, synchronization, and shader translation is essential for graphics debugging
• Cross-Platform Native Build Abstraction (Premake) — Xenia uses Premake to generate Visual Studio, Make, and NDK build files from a single config; modifying build targets or compiler flags requires understanding Premake Lua DSL
• JNI (Java Native Interface) for Android Integration — Android port bridges Java UI layer (LauncherActivity, WindowedAppActivity) to C++ emulator core via JNI; required to add Android-specific features

• xenia-project/game-compatibility — Official companion repo tracking which games run, their status, and known issues; essential reference for validating emulator improvements
• xenia-project/release-builds-windows — Automated Windows release binary pipeline; shows how CI artifacts are published for end-users
• dolphin-emu/dolphin — Similar GameCube/Wii emulator (C++, Vulkan GPU backend, JIT CPU); mature reference for cross-platform emulation architecture and game compatibility tooling
• RPCS3/rpcs3 — PlayStation 3 emulator with nearly identical tech stack (C++, Vulkan, JIT PowerPC via LLVM); shares reverse-engineering philosophy and syscall emulation patterns
• llvm/llvm-project — Dependency for Xenia's JIT compiler; understanding LLVM IR generation is critical for optimizing CPU instruction translation

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 GitHub Actions CI workflow for Android builds

The repo has .appveyor.yml and .drone.star for CI, but no GitHub Actions workflow for the Android build pipeline. Given the Android Studio project structure and NDK build configuration in android/android_studio_project/app/build.gradle, adding a GitHub Actions workflow would enable automated builds on PRs, catch Android-specific regressions early, and reduce manual testing burden on maintainers.

• [ ] Create .github/workflows/android-build.yml with jobs for arm64-v8a and x86_64 ABI targets
• [ ] Configure NDK version 25.0.8775105 and SDK 33 matching the gradle config
• [ ] Add build step using ndk-build with xenia-app target for both Debug and Release configurations
• [ ] Set up artifact upload for successful APK builds
• [ ] Test on a sample PR to verify Android builds complete without regression

Add unit tests for Android JNI bridge components

The Android app has multiple JNI-exposed activities (LauncherActivity.java, WindowedAppActivity.java, GpuTraceViewerActivity.java) and a custom exception class (XeniaRuntimeException.java), but there are no visible test files in the Android project structure. Adding unit/integration tests for these components would ensure the JNI layer remains stable across native code changes.

• [ ] Create android/android_studio_project/app/src/test/java/jp/xenia/emulator/ directory structure
• [ ] Write unit tests for XeniaRuntimeException behavior and error handling
• [ ] Add instrumented tests (androidTest) for WindowSurfaceView.java lifecycle and renderer initialization
• [ ] Create mock tests for LauncherActivity to verify intent routing and app launch logic
• [ ] Update build.gradle to include androidx.test:runner and junit dependencies

Document Android build setup and troubleshooting in CONTRIBUTING.md

While CONTRIBUTING.md exists, it appears minimal based on the file listing. The Android build has complex NDK dependencies, specific API level requirements (minSdkVersion 24 for Vulkan), and ndk-build workarounds (e.g., --output-sync=none for Windows). New contributors attempting Android builds will struggle without explicit setup instructions and common issue resolutions.

• [ ] Add 'Android Development Setup' section to .github/CONTRIBUTING.md covering NDK 25.0.8775105 installation
• [ ] Document minSdkVersion 24 requirement and Vulkan support implications
• [ ] Include step-by-step Android Studio project import and gradle sync instructions
• [ ] List common build failures (Bad file descriptor on Windows, gradle sync issues) and their workarounds
• [ ] Add instructions for building with ndk-build directly for non-app targets mentioned in build.gradle comments

• Add cross-platform logging tests: src/ likely lacks unit tests for trace/debug output paths; create test fixtures for GPU trace viewer (GpuTraceViewerActivity.java) serialization
• Document kernel syscall mappings: src/kernel/ system call implementations likely lack inline docs; create a syscall reference table in docs/ with real Xbox 360 ABI offsets
• Extend Android build matrix: app/build.gradle targets arm64-v8a and x86_64; add armeabi-v7a support with conditional NEON optimization flags for older devices

The Xenia Xbox 360 emulator Android build configuration has a reasonable security posture but includes several areas for improvement. The main concerns are: (1) Outdated NDK version without the latest security patches, (2) Lower minimum SDK version expanding the vulnerable device base, (3) Inconsistent code obfuscation across build variants, and (4) Potential unreviewed secrets in gradle.properties. No critical vulnerabilities were identified in the visible configuration, but the project should prioritize updating build tools and dependencies, increasing the minimum SDK version, and ensuring consistent security controls across all build variants. The codebase appears to follow standard Android development practices with appropriate build configurations for debug and release variants.

• Medium · Outdated Android NDK Version — android/android_studio_project/app/build.gradle. The build.gradle specifies ndkVersion '25.0.8775105', which is an older NDK version. Newer NDK versions include security patches and compiler improvements. Consider updating to the latest stable NDK version. Fix: Update ndkVersion to the latest stable release (currently 26.x or higher). Regularly check for NDK updates to ensure security patches are applied.
• Medium · Minification Only in Release Builds — android/android_studio_project/app/build.gradle. ProGuard minification is only enabled for release builds. Debug builds have minifyEnabled implicitly false, which could expose code structure and make reverse engineering easier during testing phases. Fix: Consider enabling minification for debug builds as well, or use a separate obfuscation strategy for non-release builds to prevent information disclosure.
• Medium · Lower Minimum SDK Version — android/android_studio_project/app/build.gradle. The minSdkVersion is set to 24 (Android 7.0), which is older and may not receive regular security updates. This exposes the application to vulnerabilities present in older Android versions. Fix: Evaluate increasing minSdkVersion to at least 26-28 (Android 8.0+) to reduce the attack surface and ensure users have access to more recent security patches.
• Low · Build Configuration Output Sync Workaround — android/android_studio_project/app/build.gradle. The build uses '--output-sync=none' as a workaround for 'Bad file descriptor' issues on Windows with NDK r22+. This may mask underlying build system issues. Fix: Investigate if this workaround is still necessary with the current NDK version. Document the rationale and consider upgrading the build toolchain to eliminate the need for this workaround.
• Low · Missing Security-Related Gradle Properties — android/android_studio_project/gradle.properties. The gradle.properties file is present but not shown. Ensure it doesn't contain hardcoded sensitive information like API keys, signing credentials, or authentication tokens. Fix: Review gradle.properties to ensure no secrets are stored in plain text. Use Android Keystore or secure credential management systems for sensitive data.
• Low · Debug Flag Enabled in Debug Build — android/android_studio_project/app/build.gradle. The debug build variant has debuggable=true, which is expected but increases attack surface. Ensure this is never set to true in release builds. Fix: Verify that debuggable is set to false in release builds. Add build-time checks to prevent accidental release builds with debugging enabled.

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.