Documentation
Tout ce dont vous avez besoin pour obtenir votre premier rapport de bugs.
Vue d'ensemble
Phantom Z est un agent QA autonome pour jeux vidéo. Il joue votre jeu, détecte les bugs, et génère un rapport structuré avec vidéos, logs et étapes de reproduction.
Il existe deux façons d'utiliser Phantom Z :
- Web (recommandé pour les studios indés) — Soumettez une URL, payez par rapport, recevez le résultat par email. Aucune installation requise.
- CLI — Installez le package Python pour des sessions locales, intégration CI ou des tests instrumentés avec sidecar.
Soumettre via le web
Le flux web est la façon la plus rapide d'obtenir un rapport :
- Achetez un rapport sur la page tarifs ($49.99 par rapport, ou $199 pour un pack de 5).
- Après paiement, rendez-vous sur /submit et collez l'URL de téléchargement de votre jeu (itch.io, Google Drive, lien .exe direct).
- Entrez votre email, le nom du jeu et le genre.
- Phantom Z télécharge et joue votre jeu de façon autonome (1–4 heures).
- Vous recevez un rapport de bugs avec clips vidéo par email et un lien partageable permanent.
Anatomie du rapport
Chaque rapport contient les éléments suivants :
| Champ | Description |
|---|---|
bug_type | Crash / soft-lock / progression / logique / visuel |
severity | Critical · High · Medium · Low |
summary | Description courte du bug en langage naturel |
probable_cause | Hypothèse IA sur la cause racine |
repro_steps | Séquence d'actions pour reproduire |
evidence_timeline | Événements horodatés traçant l'origine du bug |
video_clip | Clip MP4 centré sur l'événement déclencheur |
affected_system | Composant du jeu concerné (physique, UI, sauvegarde…) |
confidence | Score de confiance de l'agent (0–1) |
active_agent_trace | Historique des personas utilisés (utile en mode auto) |
Le rapport est disponible en HTML (navigateur) et JSON (intégration CI). Chaque rapport a également un lien partageable permanent.
CLI — démarrage rapide
Une fois l'accès accordé, vous pouvez lancer votre première session en quelques minutes :
# Run with mock mode (no game needed — great for testing the pipeline)
phantom-z run --mode mock --duration 120
# Run against a real game binary
phantom-z run --mode blackbox --game-binary ./MyGame.exe --duration 300
# Use a specific agent persona
phantom-z run --mode blackbox --game-binary ./MyGame.exe --agent chaos_monkeyVotre premier rapport sera dans runs/<run_id>/report.html.
Agents QA
Choisissez un agent avec --agent:
| Agent | Stratégie | Idéal pour |
|---|---|---|
auto | Change de persona selon les signaux de stagnation et soft-lock. | Usage général |
explorer | Exploration axée couverture — sonde les zones non visitées. | Menus morts, flux inaccessibles |
chaos_monkey | Entrées aléatoires haute entropie. Le plus rapide pour les crashes. | Crashes, corruption d'état |
speedrunner | Toujours l'action la plus probable vers l'objectif suivant. | Blocages de progression, chemin critique |
completionist | Suit chaque élément UI visité. Maximise la couverture d'états. | Cas limites de dialogues, zones UI mortes |
Modes d'exécution
| Mode | Description | Prérequis |
|---|---|---|
mock | Tourne contre un sidecar simulé. Aucun binaire de jeu requis. Idéal pour tester le pipeline. | Rien |
blackbox | Tourne contre un exécutable externe sans intégration sidecar. | Binaire .exe / .app |
instrumented | Tourne avec le sidecar gRPC intégré pour une télémétrie enrichie. | Sidecar Unity installé |
Sidecar Unity
Le sidecar expose une interface gRPC depuis votre build Unity, donnant à Phantom Z accès à la télémétrie interne du jeu.
# 1. Copy the sidecar into your Unity project
cp -r phantomz/sidecar/ Assets/PhantomZ/
# 2. Build your game as usual in Unity
# 3. Run in instrumented mode
phantom-z run --mode instrumented --game-binary ./MyGame.exeRéférence CLI
| Commande | Description |
|---|---|
phantom-z run | Lance une session QA locale |
phantom-z swarm | Lance un swarm parallèle sur Modal (Studio) |
phantom-z audit | Audite un répertoire de run existant |
phantom-z doctor | Vérifie l'environnement et les dépendances |
Options de phantom-z run
phantom-z run \
--mode {mock,instrumented,blackbox} \
--agent {auto,explorer,completionist,speedrunner,chaos_monkey} \
--game-binary ./MyGame.exe # path to executable
--duration 120 # seconds (default: 120)
--action-budget 12 # max actions per step
--stagnation-window 12 # steps before persona switch
--switch-policy {round_robin,prefer_chaos_on_stagnation} \
--file-bugs # file to GitHub Issues (needs GITHUB_TOKEN)Variables d'environnement
| Variable | Description | Requis |
|---|---|---|
GEMINI_API_KEY | Requis pour l'analyse IA des captures d'écran. | Oui |
PINECONE_API_KEY | Mémoire cloud pour la régression cross-build. | Non |
GITHUB_TOKEN | Active --file-bugs vers GitHub Issues. | Non |
STRIPE_SECRET_KEY | Requis pour le checkout web (déploiement du frontend). | Non (web seulement) |
FAQ
Quel format de jeu est supporté ?
Tout exécutable Windows (.exe) et macOS (.app). Envoyez le build standalone — pas besoin de Steam ou d'un launcher externe. Les builds Unity et Unreal sont testés et fonctionnent.
Combien de temps prend une session ?
Les rapports web prennent entre 1 et 4 heures selon la durée de session choisie. Les sessions CLI mock/blackbox peuvent commencer en moins de 5 minutes.
Est-ce que ça fonctionne avec Unreal Engine ?
Le mode blackbox fonctionne avec n'importe quel moteur. Le mode instrumenté avec sidecar est actuellement Unity uniquement. Un sidecar Unreal est prévu.
Puis-je tester un jeu multijoueur ?
Phantom Z teste le comportement côté client — ce que le joueur voit et contrôle. Pour les titres multijoueurs, nous nous concentrons sur l'expérience client locale et la cohérence UI.
Est-ce que les rapports sont permanents ?
Oui. Chaque rapport a un lien partageable permanent. Vos artifacts de session sont toujours les vôtres.