Documentation

ForgeaX est un studio de développement de jeux natif d'IA. Vous décrivez le jeu dans un langage simple ; un responsable de l'IA appeléForge le planifie, le conçoit et l'écrit lui-même dans le code du jeu en cours d'exécution, rechargez à chaud le résultat dans votre navigateur – ce que vous dites est ce que vous jouez.

Deux fondations internes se trouvent en dessous : unmoteur repensé pour le point de vue de l'IA(voirPourquoi un moteur natif d'IA) et unboucle de développement qui fait converger les fonctionnalités vers un résultat correct(voirComment l'IA réussit à créer une fonctionnalité).

Ça convient2D / 2,5D / 3Djeux sur Internet. Des FPS jouables, des ARPG façon Diablo, des démos de survie et de shooter à deux niveaux existent déjà (voir levitrine); le moteur couvre le rendu PBR / IBL / SSAO, la physique 2D/3D, l'animation squelettique et le double RHI (voir "Capacités du moteur" en bas duvitrine).

Tout fonctionne dans le navigateur (WebGPU), sur le Web et sur le bureau sur une seule pile ; open source sous Apache License 2.0 (voir lelicence).

Prérequis : git,chignon≥ 1,3,nœud≥ 22,boucle. (Sur un hôte propre,configuration du chignon fxpeut également amorcer bun / node 22+ / pnpm / la chaîne d'outils Rust+wasm - zéro invite par défaut ;--interactifdemande par outil,--skip-bootstraple saute.)

git clone --recurse-submodules \
  https://github.com/ForgeaX-Games/forgeax-studio.git
cd forgeax-studio
configuration bun fx # configuration unique
chignon fx démarrer # → http://localhost:18920

Quoiconfiguration du chignon fxfait:vérifie les prérequis → initialise ses sous-modules → construit les packages du moteur → s'exécuteinstallation de chignondans chaque sous-dépôt → construit les plugins du marché → échafaudages$RACINE/.envdepuis.env.exemple. Avec--interactifil demande égalementANTHROPIC_API_KEY; sinon il prévient et vous éditez.envplus tard.

chignon fx démarrerdémarre trois services : serveur(:18900, le noyau d'exécution — chat / backends / sessions),interface(:18920, l'interface utilisateur de Studio avec vite HMR), etmoteur(:15173, le moteur de rendu). Remplacer les ports dans.envviaFORGEAX_{SERVEUR,INTERFACE,ENGINE}_PORT. Puis ouvrezhttp://localhost:18920.

Commandes quotidiennes (une entrée,chignon fx) :courirconfiguration du chignon fxune fois pour préparer l'environnement ; plus tard, extrayez les mises à jour avecmise à jour de Bun FX(met à jour le dépôt racine + synchronise les sous-modules, pas de réinstallation/reconstruction) ;chignon fx démarrer/Application de démarrage Bun FXlancer le Web/le bureau ;chignon fx arrêteretredémarrage de Bun FXarrêter/redémarrer ;statut bun fxetchignon fx docteurdiagnostiquer votre configuration ;application de création de bun fxemballe l’application de bureau. Courirchignon fxsans arguments pour lister chaque commande.

Application de bureau : Application de démarrage Bun FXouvre une fenêtre native sur la source en direct (exécutez d'abord les installations automatiques et démarrez la pile ; la fermer arrête la pile );application de création de bun fxpaquets un autonome.app/.dmg. VoirExécuter et prévisualiserpour tous les modes.

Prise en charge de la plate-forme (macOS / Linux / Windows, première classe) :l'installation et le lancement constituent un ensemble descripts Bun multiplateformes, donc les trois systèmes exécutent lemêmechignon fxcommandesavec un comportement identique - etWindows n'a plus besoin de Git-Bash(l'ancien dual.sh/.batte/.ps1les scripts ont été supprimés). Spécifiquement:développement web(chignon fx démarrer) etdéveloppeur de bureau(Application de démarrage Bun FX, une fenêtre Tauri native sur source live) fonctionne sur macOS / Linux / Windows ;emballer un jeu dans un double clic.app/.dmg(application de création de bun fx) est actuellement réalisé sur macOS. Les problèmes courants spécifiques à Windows (aperçu noir, fenêtre de console par tour, processus ne se fermant pas proprement, stub Python du système) sont tous résolus - voirJournal des modifications · 2026-06-28.

Vous préférez ne pas le faire à la main ? Laissez votre CLI de codage IA cloner et lancez-la - voirFaites cloner votre AI CLI et lancez-le; puis construisez votre premier jeu avecDémarrage rapide. Pour les clés API, voirAvancé · Changer/configurer le backend IA.

L'interface est composée de trois parties : une barre supérieure, le chat à gauche et l'aperçu/workbench à droite.

• Barre supérieure- le⊕nouveau menu, unsélecteur de projet(passer d'un jeu à l'autre - ce qu'est un "projet" est couvert dansConcepts de base), et uncommutateur de session(réviser/changer les conversations passées).
• Gauche · chat (ChatPanel)— un rail d'équipe (Forge et les sous-agents), un flux de messages (cartes de sous-agents, réflexions et appels d'outils de Forge), et un compositeur en bas avec uncommutateur principalen bas à droite (voirAvancé).
• Droite · zone principale (MainArea)— bascule entre lesaperçu(votre jeu vit dans une iframe) et leétabli(édition de fichiers / documents de conception) ; voirScènes et éditeur.

Le rouage en haut à droite s'ouvreParamètres: Clés API, choix du modèle, backend CLI et gestion des plugins. L'application de bureau affiche également une superposition de première exécution qui vous demande la clé la première fois que vous l'ouvrez.

Dans ForgeaX,"projet" et "jeu" sont la même chose— un jeu en est unjeux//dossier. Un vrai dossier de jeu ressemble généralement à ceci :

• forge.json — le manifeste du jeu. Au minimum trois champs :identifiant,nom, etentrée(en pointant le code d'entrée, par ex.src/main.ts).
• FORGE.md — le fichier readme/aperçu du gameplay du jeu (commandes, mécanismes, rythmes de l'histoire).
• src/ — le code du jeu. Outre lemain.tsentrée, il est généralement divisé en modules par préoccupation (par ex.joueur.ts,ennemis/,effets.ts,configuration.ts).
• design/ · assets/ — documents de conception et actifs artistiques/audio.
• package.json · tsconfig.json — fichiers de projet TS standard.

Lemain.tsl'entrée importe les capacités du moteur depuis@forgeax/moteur-runtime/moteur-ecs/application moteuret exporte unEntrée de jeu— le contrat par lequel le moteur charge un jeu. Pour connaître l'ensemble complet des fonctionnalités, voir « Capacités du moteur » sur levitrine.

Plusieurs jeux = plusieurs projets, commutés dans le sélecteur de projet de la barre supérieure. Pour savoir comment les scènes/niveaux sont organisés, voirScènes et éditeur.

Forge (l'agent principal)est le seul à écrire directement le code du jeu — il écritjeux//src/main.ts, l'aperçurecharges à chaud, et il voit le résultat en cours pour décider de l'étape suivante. Cette boucle édition → voir → édition doit rester avec quiconque peut voir l'aperçu, c'est-à-dire Forge (voirConstruisez en discutant).

Sous-agents(par exemple, gameplay Iori, conception Suzu, récit Kotone, art Iro, construction Tsumugi) uniquement planifier/concevoir/créer des actifs/écrire des documents etne jamais touchersrc/- ils n'ont pas de retour d'aperçu en direct, donc tout code qu'ils ont écrit n'aurait rien pour le guider. Retrouvez le casting complet dansmarchéetChapitre 10 · L'équipe d'agents.

Comment fonctionne l'expédition :Forge envoie un sous-agent avec un seul appel d'outil (en formesous-agent(type="iori", tâche="…")); celui du serveur/api/sous-agentstream relie sa sortie à la conversation principale en temps réel : il s'agit de la carte de sous-agent intégrée que vous voyez dans le flux de messages. Les documents de conception d'un sous-agent sont classés dans sa propre section dans l'atelier (voirScènes et éditeur).

UNsessionest la mémoire d'un agent - unajout uniquementflux d'événements (chacun est un message utilisateur / un message d'assistant / une réflexion / un appel d'outil / un résultat d'outil). Forge (principal) et chaque sous-agent gardent chacun le sien.

L'interface utilisateur divise les événements selon celui qui les a émis dans le thread principal par rapport aux sous-agents, rendant la tranche de chaque sous-agent sous la forme d'une carte intégrée. Ainsi, sur un écran, vous voyez à la fois le fil principal de Forge et ce que les sous-agents qu'il a envoyés ont réellement fait.

Utilisez le sélecteur de session dans la barre supérieure pour consulter et basculer entre les sessions passées.Changer de session ne redémarre rien- l'interface utilisateur lit simplement le flux d'événements d'un autre agent.

Plus vous êtes précis, plus Forge réussit à essayer en premier avec moins de reprises. Une bonne invite couvre généralement :

• Genre et vue— vue de haut en bas / première personne / défilement latéral 2,5D…
• Boucle centrale- la seule chose que le joueur continue de faire
• Contrôles,gagner/perdre,ennemis / obstacles, et lesentir

Commencez petit, faites-le fonctionner, puis superposez la mécanique. Par exemple:

Un jeu descendant : un personnage court dans une arène, l'espace tire des balles, les ennemis continuent d'apparaître, les frappes les suppriment et ajoutent des points.

Pour un premier jeu étape par étape, voirDémarrage rapide; pour savoir ce qui est réalisable, parcourez levitrine. Pour une conception plus lourde, Forge fait appel à des sous-agents de conception (voirConcepts de base).

Une fois que vous envoyez une demande, la chaîne est :

• Comprendre + planifier— Forge clarifie l'exigence en envoyant des sous-agents de conception/gameplay pour des travaux plus lourds (voirConcepts de base).
• Écrire du code— Forge écritlui-mêmedansjeux//src/main.ts(et ses modules split-out).
• Rechargement à chaud— lors de la sauvegarde, le vite du moteur détecte le changement et l'aperçuremplacement à chaud du moduleen place – pas de rechargement complet, l’image se met à jour presque instantanément.
• Voir le résultat— Forge voit le résultat en cours d'exécution via l'aperçu (qui transmet également leconsoleretour) et décide de l'étape suivante.

L'ensemble du processus est transparent : le flux de messages montre la pensée de Forge, chaque appel d'outil et les cartes des sous-agents qu'il a envoyés. Pour basculer/contrôler l'aperçu par rapport au Workbench, voirScènes et éditeur; pour savoir comment fonctionne le rechargement à chaud, voirExécuter et prévisualiser.

Pas content ? Continuez à parler : chaque élément de retour devient un autre changement, visible instantanément via un rechargement à chaud :

Balles plus rapides, double santé de l'ennemi, fond nocturne.

L'aperçu alecture/pause/rechargementdes contrôles pour tester au fur et à mesure ; pour épingler l'aperçu à un jeu spécifique, activez le sélecteur de projet (voirOuvrez le studio, apprenez l'interface).

La boucle de base estdécrire → générer → jouer → décrire à nouveau. Exécutez-le en douceur et vous passez d'une phrase à un jeu jouable - l'intégration complète est en coursDémarrage rapide.

La zone principale de droite bascule entre deux vues :

• Aperçu— votre jeu s'exécute en direct dans une iframe, avec une lecture FPS et des commandes de lecture/pause/rechargement. Lorsque Forge écrit du code, il se recharge instantanément à chaud (voirConstruisez en discutant).
• Établi— un navigateur de fichiers + un éditeur : affichez/modifiez/enregistrez du texte et du code, restituez des documents de conception markdown et prévisualisez des images, des modèles audio, vidéo et 3D. Il fait également apparaître l'activité des fichiers et les verrous « qui édite », de sorte que vous et l'IA modifiez les mêmes fichiers sans vous encombrer.

En l'absence de fichier ouvert, l'atelier affiche les entrées pour chaque atelier de création (personnage / animation / 3D / scène / UI / musique…) — voirOutils de créationet lemarché. Pour créer des actifs, voirActifs.

L'éditeur de scène enregistre le contenu d'un niveau dans unfichier de données de scènedans le dossier du jeu (scène.pack.json) - lesource unique de véritépour ce niveau : ce qui est sur le disque est ce qui s'exécute dans le jeu.

Lorsque vous placez des objets et quittez le mode édition, les modifications sontvidés sur le disque et le jeu en cours les relit, de sorte que l'aperçu reflète immédiatement vos modifications - l'aller-retour édition → lecture. À l'inverse, lorsque Forge modifie le code par chat, il emprunte le même chemin de rechargement à chaud (voirConstruisez en discutantetExécuter et prévisualiser).

Un jeu peut avoirplusieurs scènes / niveaux, chacun ses propres données de scène, commutées et réutilisées selon les besoins — la démo "Cow Survivor" bascule entre un pâturage de jour et un cimetière de nuit (voir levitrine).

Comment organiser :objetsvivre dans les données de la scène, tandis queressources artistiques/audiolive dans le dossier du jeu (disposition du projet dansConcepts de base, génération d'actifs dansActifs). La division par scène permet de maintenir un jeu en pleine croissance.

Utilisez leéditeur de personnages(caractère wb) pour la conception du concept de personnage : rédigez un brief d'une ligne, obtenez unportrait + retournement. Aucune compétence en dessin n'est nécessaire pour obtenir un personnage prêt à jouer.

Ses sorties (un manifeste de personnage + un portrait/revirement) sont stockées par personnage dans votre jeu etalimenter directement l'atelier d'animation en tant qu'entrée en aval- donc "concevoir le personnage → le faire bouger" est un pipeline continu (voir l'élément suivant).

Chaque établi est un panneau plus un ensemble d'outils ; vous-même et l'IA par expédition modifiez le même artefact. Liste complète dans lemarchéet letutoriel sur les établis.

2D :l'atelier d'animation (wb-anim) utilise le portrait du personnage comme modèle et le transforme en mouvements de marche, d'attaque, dans quatre directions, voire en clips courts -sans dérive du visage, donc il reste le même personnage une fois qu'il bouge.

3D :le moteur prend en charge nativementanimation squelettique- importez un modèle truqué et skinné ainsi que des clips d'animation depuis FBX, avec des fondus enchaînés fluides entre ralenti/marche/course/cast/mort. Ce pipeline est réel et expédié — c'est ainsi que se déplace la sorcière dark-fantasy de la vitrine : voirle jalon de l'animation squelettiqueet levitrine (Hellforge).

Au-delà des personnages, il existe des ateliers tout au long du pipeline :

La couverture article par article est en coursChapitre 9 · Outils de création, letutoriel sur les établis, et lemarché.

Un exemple réel de moteur ForgeaX exécuté en direct sur cette page (WebGPU — Chrome/Edge recommandé). Plus de démos exécutables dansExemplesetJeux.

Ouvrir en plein écran ↗

La même base de code s'exécute sous trois formes :

• Développement Web—chignon fx démarrerdémarre trois services (serveur/interface utilisateur/moteur) ; ouvrirhttp://localhost:18920dans un navigateur, modifie le rechargement à chaud en direct. Fonctionne sur macOS/Linux/Windows. Installer dansAvant de commencer.
• Développeur de bureau—Application de démarrage Bun FXouvre une fenêtre native chargeant le même serveur de développement, avec une source live et un HMR identiques ; exécutez d’abord les installations automatiques et démarrez la pile, la fermeture de la fenêtre l’arrête. Disponible sur macOS/Linux/Windows.
• Desktop .app (emballé)—application de création de bun fxproduit un autonome.app/.dmgqui fonctionne en double-clic avec son propre side-car (ports 18810/15273, délibérément décalés par rapport aux 18900/15173 du développeur afin que les deux puissent coexister) ; sa clé réside dans~/ForgeaxProjects/.env, avec une superposition de première exécution. L'emballage est enPublier et partager.

Les trois ports sont remplaçables dans.envviaFORGEAX_{SERVEUR,INTERFACE,ENGINE}_PORT. ⚠️ La fenêtre du bureau utilise le système WebView, donc la 3D fonctionne sur le WebGPU de WebKit – un peu plus faible que celui de Chrome.Pour les meilleurs visuels, utilisez le navigateur.

Enregistrez et cela prend effet – pas d’actualisation manuelle :

• Modifiercode de jeu(jeux//src/…) → le moteur remplace à chaud le module en place et l'aperçu se met à jour instantanément (les modifications de Forge utilisent également cela - voirConstruisez en discutant).
• Des changements dansmonteur de scènevider sur le disque et revenir dans le jeu en cours (voirScènes et éditeur).

• Aperçu vide / erreur moteur— le moteur n'est pas construit ; rediffusionconfiguration du chignon fx.
• Erreur SSL activée:18920— accès viahttp://localhost(WebGPU fonctionne toujours sur localhost).
• Port utilisé— un port occupé génère une erreur (il n'en sélectionnera pas automatiquement un autre) ; courirchignon fx arrêteralorschignon fx démarrer, ou changez de port dans.env.
• Le chat ne dit pas de clé API- ensembleANTHROPIC_API_KEYdans.env(l'application de bureau vous le demande lors de la première exécution) ; la configuration des clés est en coursAvancé.
• La 3D semble plus faible sur le bureau— une limitation du WebGPU du système WebView ; utilisez la version du navigateur Chrome pour un meilleur rendu.

application de création de bun fxregroupe l'ensemble du studio avec votre jeu dans unensemble de bureau autonome(macOS.app/.dmg) : un runtime réduit, le serveur, l'interface utilisateur du Studio, la place de marché et le contenu de votre jeu sont tous à l'intérieur, donc ils'exécute en double-clic sans configurationpour l'utilisateur.

Il fonctionne sur un side-car intégré sur ses propres ports (18810/15273), de sorte qu'il n'entre jamais en collision avec votre pile de développement (voirExécuter et prévisualiser). Le packaging doit fonctionner sur macOS ; le emballé.apps'ouvre par double-clic.

Un jeu en est unautonomejeux//dossier(forge.json+src/+ documents de conception + ressources, voirConcepts de base). Partagez ou validez ce dossier et quelqu'un d'autre l'ouvrira dans son studio pour continuer à jouer ou à construire - la bibliothèque de démonstration stocke plusieurs jeux côte à côte (fps, hellforge, cow-survivor, shoot-opt), voir levitrine.

Pour l'instant, le moyen le plus fiable de proposer une partie aux joueurs est lepaquet de bureauau-dessus de; une « publication Web/lecture en ligne en un clic » plus fluide est toujours en préparation.

Changer de backend (échanger la puce) :choisissez le noyau à partir du commutateur backend en bas à droite du compositeur ou sous leCLIsection des paramètres -Claude Code / Codex / Cursor / Kimi Code / CodeBuddy / DeepSeek Harness / forgeax-cli. La section CLI montre chaque backendsantéet unTestbouton. Changer de backend permute également son personnage par défaut (voirL'équipe des agents); détails par backend dans lemarché.

Clés / modèles :définissez la clé API de votre modèle (par ex.ANTHROPIC_API_KEY) sous Paramètres → Clés - ils'applique en direct, pas de redémarrage(vous pouvez également modifier.envdirectement); choisissez le modèle sous Paramètres → Modèles. Le dépannage de clé manquante est en coursExécuter et prévisualiser.

Presque toutes les fonctionnalités de ForgeaX sont unplugin chargé à l'exécution(aperçu dans lemarché), afin que vous puissiez ajouter le vôtre.

Le chemin le plus rapide aujourd’hui :copier un plugin workbench existant et l'adapter, avec leauteur du plugin(wb-plugin-auteur) aider ; un éditeur visuel intégré à l'application plus complet (arborescence de fichiers + éditeur de code, sauvegarde → rechargement automatique) est en route. Une fois construit, activez-le et réorganisez-le dans lepanneau d'administration— les plugins sont montés par la CLI au moment de l'exécution. Voir les types d'établis dansOutils de création.

Utilisez leéditeur de personnages(personnage-agent-wb) : choisissez un agent dans la liste, modifiez son personnage dans une zone de texte, etsauvegarder → recharger à chaud, pas de redémarrage. Vous pouvez donner à un agent un personnage ou une voix différente sans toucher à aucun code.

Pour savoir qui sont les agents principaux et les sous-agents et d'où viennent les personnages par défaut, voirConcepts de baseetL'équipe des agents; le casting complet est dans lemarché.

Tous ces éléments sontplugins chargeables; le catalogue complet et filtrable se trouve dans lemarché, et un didacticiel pas à pas se trouve dans letutoriel sur les établis.

Arin · producteur— un producteur polyvalent qui coordonne le design/le code/l'art/l'audio et possède l'ensemble du jeu.

Reia · directeur de bobine- réalisateur FMV interactif qui crée des invites, rythme les QTE et tisse des branches et des fins, conduisant le wb-reel Reel Studio à transformer une idée en un film à suspense cliquable et jouable.

Ce sontagents nommésexpédié à la demande par Forge (la relation principal/sous-agent est enConcepts de base); le casting complet est dans lemarché.

Ces spécialistesseulement le plan et la conception – ils ne touchent jamais au code du jeu(Forge écrit du code, voirConcepts de base); leur sortie atterrit dans l'établi (voirScènes et éditeur), et les actifs artistiques sont produits comme dansActifs.

Il y a aussi un ensemble deagents spécialisés en art/actifs(personnage/animation 2D, low-poly/VFX 3D, réalisateur de film interactif, et plus), chacun étant connecté à son atelier de création correspondant (voirOutils de création).

Chaque backend CLI est livré avec un personnage prêt à l'emploi :Claude(ClaudeCode),Manuscrit,Curseur, etForgeaX(le forgeax-cli auto-construit).Le changement de backend permute le personnage par défaut – aucune configuration nécessaire; quel que soit le noyau que vous choisissez, il est livré avec son personnage par défaut.

Comment changer de backend et modifier les personnages est disponibleAvancé; le casting complet de l'agent et les personnages chargeables sont dans lemarché.