Documentación

ForgeaX es un estudio de desarrollo de juegos nativo de IA. Describes el juego en lenguaje sencillo; un líder de IA llamadoFragua lo planifica, lo diseña y lo escribe en el código del juego en ejecución., recargando en caliente el resultado en tu navegador: lo que dices es lo que juegas.

Debajo se encuentran dos cimientos internos: unMotor rediseñado para el punto de vista de la IA.(verPor qué un motor nativo de IA) y unbucle de desarrollo que converge características en un resultado correcto(verCómo la IA consigue una función correctamente).

Se adapta2D / 2.5D / 3Djuegos web. Ya existen FPS jugables, ARPG estilo Diablo, supervivencia de dos niveles y demostraciones de disparos (consulte elescaparate); El motor cubre renderizado PBR / IBL / SSAO, física 2D/3D, animación esquelética y RHI dual (consulte "Capacidades del motor" en la parte inferior de la página).escaparate).

Todo se ejecuta en el navegador (WebGPU), la web y el escritorio en una sola pila; código abierto bajo licencia Apache 2.0 (consulte lalicencia).

Requisitos previos: git,bollo≥ 1,3,nodo≥ 22,rizo. (En un host limpio,configuración de efectos de bollotambién puede iniciar bun/node 22+/pnpm/la cadena de herramientas Rust+wasm: aviso cero de forma predeterminada;--interactivopregunta por herramienta,--skip-bootstrapse lo salta.)

git clone --recurse-submódulos \
  https://github.com/ForgeaX-Games/forgeax-studio.git
cd forgeax-studio
configuración bun fx # configuración única
inicio de bun fx # → http://localhost:18920

Quéconfiguración de efectos de bollohace:verifica los requisitos previos → inicia sus submódulos → construye los paquetes del motor → ejecutainstalar bolloen cada subrepositorio → crea los complementos del mercado → andamios$RAÍZ/.envde.env.ejemplo. Con--interactivotambién solicitaANTROPIC_API_KEY; de lo contrario avisa y editas.envmás tarde.

inicio de bun fxarranca tres servicios: servidor(:18900, el núcleo del tiempo de ejecución: chat/backends/sesiones),interfaz(:18920, la interfaz de usuario de Studio con vite HMR), ymotor(: 15173, el renderizador). Anular puertos en.enva través deFORGEAX_{SERVIDOR,INTERFAZ,MOTOR}_PORT. Luego abrehttp://localhost:18920.

Comandos cotidianos (una entrada,bollo fx):correrconfiguración de efectos de bollouna vez para preparar el ambiente; luego extraiga actualizaciones conactualización de bun fx(actualiza el repositorio raíz + sincroniza los submódulos, no es necesario reinstalar/reconstruir);inicio de bun fx/aplicación de inicio bun fxiniciar web/escritorio;parada de pan fxyreiniciar bun fxdetener/reiniciar;estado de bun fxydoctor bun fxdiagnosticar su configuración;aplicación de compilación bun fxempaqueta la aplicación de escritorio. Correrbollo fxsin argumentos para enumerar cada comando.

Aplicación de escritorio: aplicación de inicio bun fxabre una ventana nativa en la fuente en vivo (primero ejecuta las instalaciones automáticas e inicia la pila; al cerrarla se detiene la pila);aplicación de compilación bun fxempaqueta un autocontenido.aplicación/.dmg. VerEjecutar y obtener vista previapara todos los modos.

Soporte de plataforma (macOS / Linux / Windows, primera clase):instalar y ejecutar son un conjunto descripts Bun multiplataforma, por lo que los tres sistemas ejecutan elmismobollo fxcomandoscon comportamiento idéntico - yWindows ya no necesita Git-Bash(el viejo dual.sh/.murciélago/.ps1los guiones fueron eliminados). Específicamente:desarrollador web(inicio de bun fx) ydesarrollador de escritorio(aplicación de inicio bun fx, una ventana nativa de Tauri en fuente en vivo) funcionan en macOS/Linux/Windows;empaquetar un juego en un formato en el que se puede hacer doble clic.aplicación/.dmg(aplicación de compilación bun fx) se realiza actualmente en macOS. Los problemas comunes específicos de Windows (vista previa en negro, una ventana de consola por turno, procesos que no se cierran limpiamente, el código auxiliar de Python del sistema) están todos solucionados; consulteRegistro de cambios · 2026-06-28.

¿Prefieres no hacerlo a mano? Deje que su CLI de codificación de IA la clone y ejecútela; consulteHaga que su AI CLI clone y ejecútelo; luego construye tu primer juego conInicio rápido. Para claves API, consulteAvanzado · Cambiar/configurar el backend de IA.

La interfaz consta de tres partes: una barra superior, el chat a la izquierda y la vista previa/banco de trabajo a la derecha.

• barra superior- el⊕nuevo menú, unconmutador de proyectos(moverse entre juegos: lo que es un "proyecto" se trata enConceptos centrales), y unconmutador de sesión(revisar/cambiar conversaciones pasadas).
• Izquierda · chat (ChatPanel)— una barra de equipo (Forge y los subagentes), un flujo de mensajes (tarjetas de subagentes, pensamiento de Forge y llamadas a herramientas) y un compositor en la parte inferior con uninterruptor de fondoen la parte inferior derecha (verAvanzado).
• Derecha · área principal (MainArea)— alterna entre elavance(tu juego vive en un iframe) y elbanco de trabajo(edición de archivos/documentos de diseño); verEscenas y editor.

Se abre el engranaje superior derechoAjustes: Claves API, elección de modelo, backend CLI y gestión de complementos. La aplicación de escritorio también muestra una superposición de primera ejecución que solicita la clave la primera vez que la abre.

En ForgeaX,"proyecto" y "juego" son lo mismo- un juego es unojuegos//carpeta. La carpeta de un juego real suele tener este aspecto:

• forge.json — el manifiesto del juego. Mínimo tres campos:identificación,nombre, yentrada(señalando el código de entrada, p. ej.src/main.ts).
• FORGE.md — el propio archivo Léame/descripción general del juego (controles, mecánicas, ritmos de la historia).
• src/ — el código del juego. además delprincipal.tsentrada, generalmente se divide en módulos por preocupación (p. ej.jugador.ts,enemigos/,efectos.ts,configuración.ts).
• design/ · assets/ — documentos de diseño y recursos de arte/audio.
• package.json · tsconfig.json — archivos de proyecto TS estándar.

Elprincipal.tsLa entrada importa capacidades del motor desde@forgeax/motor-runtime/ecs del motor/aplicación de motory exporta unEntrada de juego— el contrato mediante el cual el motor carga un juego. Para conocer el conjunto completo de capacidades, consulte "Capacidades del motor" en la páginaescaparate.

Múltiples juegos = múltiples proyectos, conmutados en el selector de proyectos de la barra superior. Para saber cómo se organizan las escenas/niveles, consulteEscenas y editor.

Forge (el agente principal)es el único que escribe el código del juego directamente: escribejuegos//src/main.ts, la vista previarecargas en calientey ve el resultado de la ejecución para decidir el siguiente paso. Ese bucle editar → ver → editar tiene que quedarse con quien pueda ver la vista previa, es decir, Forge (verConstruye chateando).

Subagentes(por ejemplo, jugabilidad de Iori, diseño de Suzu, narrativa de Kotone, arte de Iro, construcción de Tsumugi) solo planificar/diseñar/crear recursos/escribir documentos ynunca toquessrc/– no tienen comentarios de vista previa en vivo, por lo que cualquier código que escribieran no tendría nada que guiarlo. Mira el elenco completo en elmercadoyCapítulo 10 · El equipo de agentes.

Cómo funciona el envío:Forge envía un subagente con una llamada de herramienta (con forma desubagente(tipo="iori", tarea="...")); el del servidor/api/subagentestream conecta su salida con la conversación principal en tiempo real: esa es la tarjeta de subagente integrada que se ve en el flujo de mensajes. Los documentos de diseño de un subagente se archivan en su propia sección en el banco de trabajo (consulteEscenas y editor).

Asesiónes la memoria de un agente, unasolo agregarflujo de eventos (cada uno es un mensaje de usuario/mensaje de asistente/pensamiento/llamada de herramienta/resultado de herramienta). Forge (principal) y cada subagente mantienen el suyo.

La interfaz de usuario divide los eventos según quién los emitió en el hilo principal y los subagentes, lo que representa la porción de cada subagente como una tarjeta incrustada. Entonces, en una pantalla ves tanto el hilo principal de Forge como lo que realmente hicieron los subagentes que envió.

Utilice el selector de sesiones de la barra superior para revisar y cambiar sesiones pasadas.Cambiar una sesión no reinicia nada— la interfaz de usuario simplemente lee el flujo de eventos de un agente diferente.

Cuanto más específico sea, mejor lo logrará Forge al principio con menos rehacer. Un buen mensaje suele cubrir:

• Género y vista— Vista superior / primera persona / desplazamiento lateral 2.5D…
• Bucle central- lo único que el jugador sigue haciendo
• Controles,ganar/perder,enemigos / obstáculos, y elsentir

Comience poco a poco, póngalo en funcionamiento y luego aplique capas de mecánica. Por ejemplo:

Un juego de arriba hacia abajo: un personaje corre por una arena, dispara balas al espacio, los enemigos siguen apareciendo, los golpes los eliminan y suman puntuación.

Para ver el primer juego paso a paso, consulteInicio rápido; para conocer lo que se puede lograr, explore elescaparate. Para diseños más pesados, Forge recurre a subagentes de diseño (consulteConceptos centrales).

Una vez que envía una solicitud, la cadena es:

• Entender + planificar— Forge aclara el requisito y envía subagentes de diseño/juego para trabajos más pesados ​​(verConceptos centrales).
• escribir codigo- Forja escribesí mismoenjuegos//src/main.ts(y sus módulos divididos).
• recarga en caliente— al guardar, el vite del motor detecta el cambio y la vista previareemplaza en caliente el móduloen su lugar: sin recarga completa, la imagen se actualiza casi instantáneamente.
• ver el resultado— Forge ve el resultado en ejecución a través de la vista previa (que también reenvía el resultado del juego).consolaatrás) y decide el siguiente paso.

Todo el proceso es transparente: el flujo de mensajes muestra el pensamiento de Forge, cada llamada a la herramienta y las tarjetas de los subagentes que envió. Para cambiar/controlar la vista previa frente al banco de trabajo, consulteEscenas y editor; Para saber cómo funciona la recarga en caliente, consulteEjecutar y obtener vista previa.

¿No eres feliz? Siga hablando: cada comentario se convierte en otro cambio, visible instantáneamente mediante recarga en caliente:

Balas más rápidas, doble salud del enemigo, fondo nocturno.

La vista previa tienereproducir/pausar/recargarcontroles para realizar pruebas sobre la marcha; Para anclar la vista previa a un juego específico, active el selector de proyectos (consulteAbre el estudio, aprende la interfaz.).

El bucle básico esdescribir → generar → reproducir → describir de nuevo. Ejecútelo sin problemas y pasará de una oración a un juego jugable: la incorporación completa está disponibleInicio rápido.

El área principal de la derecha alterna entre dos vistas:

• Avance— tu juego se ejecuta en vivo en un iframe, con una lectura de FPS y controles de reproducción/pausa/recarga. Cuando Forge escribe código, se recarga aquí instantáneamente (consulteConstruye chateando).
• Banco de trabajo— un explorador de archivos + editor: vea/edite/guarde texto y código, renderice documentos de diseño de rebajas y obtenga una vista previa de imágenes, audio, video y modelos 3D. También muestra la actividad de los archivos y los bloqueos de "quién está editando", para que usted y la IA editen los mismos archivos sin problemas.

Sin ningún archivo abierto, el banco de trabajo muestra entradas para cada banco de trabajo de creación (personaje/animación/3D/escena/UI/música…) — consulteHerramientas de creacióny elmercado. Para crear activos, consulteActivos.

El editor de escenas guarda el contenido de un nivel en unarchivo de datos de escenaen la carpeta del juego (escena.pack.json) - elúnica fuente de verdadpara ese nivel: lo que hay en el disco es lo que se ejecuta en el juego.

Cuando colocas objetos y sales del modo de edición, los cambios sese descargan en el disco y el juego en ejecución los relee, por lo que la vista previa refleja sus ediciones de inmediato: edición → reproducción de ida y vuelta. Por el contrario, cuando Forge cambia el código mediante el chat, sigue la misma ruta de recarga en caliente (consulteConstruye chateandoyEjecutar y obtener vista previa).

Un juego puede tenermúltiples escenas/niveles, cada uno con sus propios datos de escena, intercambiados y reutilizados según sea necesario: la demostración "Cow Survivor" cambia entre un pasto diurno y un cementerio nocturno (consulte laescaparate).

Cómo organizarse:objetosvivir en los datos de la escena, mientrasrecursos de arte/audiovivir en la carpeta del juego (diseño del proyecto enConceptos centrales, generación de activos enActivos). La división por escena permite mantener un juego en crecimiento.

Utilice eleditor de personajes(carácter-wb) para el diseño del concepto de personajes: escribe un resumen de una línea, obtén unretrato + cambio de rumbo. No se necesitan habilidades de dibujo para conseguir un personaje listo para el juego.

Sus resultados (un manifiesto de personaje + retrato/cambio) se almacenan por personaje dentro de tu juego yalimentar directamente al banco de trabajo de animación como entrada descendente— entonces "diseñar el personaje → hacerlo moverse" es un proceso continuo (ver el siguiente elemento).

Cada banco de trabajo es un panel más un conjunto de herramientas; Usted a mano y AI por envío editan el mismo artefacto. Lista completa en elmercadoy eltutorial de bancos de trabajo.

2D:el banco de trabajo de animación (wb-anim) utiliza el retrato del personaje como modelo y lo convierte en movimientos de caminar, de ataque, en cuatro direcciones, incluso en clips cortos.sin deriva facial, por lo que sigue siendo el mismo personaje una vez que se mueve.

3D:el motor soporta de forma nativaanimación esquelética— importe un modelo modificado y modificado más clips de animación de FBX, con fundidos cruzados suaves entre inactivo/caminar/correr/lanzar/muerte. Esta tubería es real y está enviada: así es como se mueve la bruja de fantasía oscura en el escaparate: verel hito de la animación esqueléticay elescaparate (Hellforge).

Más allá de los personajes, hay bancos de trabajo a lo largo de todo el proceso:

La cobertura artículo por artículo está enCapítulo 9 · Herramientas de creación, eltutorial de bancos de trabajo, y elmercado.

Un ejemplo real del motor ForgeaX ejecutándose en vivo en esta página (WebGPU: se recomienda Chrome/Edge). Más demostraciones ejecutables enEjemplosyJuegos.

Abrir pantalla completa ↗

La misma base de código se ejecuta en tres formas:

• desarrollador web—inicio de bun fxarranca tres servicios (servidor/UI/motor); abiertohttp://localhost:18920en un navegador, edita la recarga en caliente en vivo. Funciona en macOS/Linux/Windows. Instalar enAntes de empezar.
• Desarrollador de escritorio—aplicación de inicio bun fxabre una ventana nativa cargando el mismo servidor de desarrollo, con fuente en vivo y HMR idénticos; Primero ejecute las instalaciones automáticas e inicie la pila, al cerrar la ventana se detiene. Disponible en macOS/Linux/Windows.
• Aplicación de escritorio (empaquetada)—aplicación de compilación bun fxproduce un autocontenido.aplicación/.dmgque se ejecuta al hacer doble clic con su propio sidecar (puertos 18810/15273, deliberadamente desplazados del 18900/15173 del desarrollador para que ambos puedan coexistir); su llave vive en~/ForgeaxProjects/.env, con una superposición de primera ejecución. El embalaje está enPublicar y compartir.

Los tres puertos son anulables en.enva través deFORGEAX_{SERVIDOR,INTERFAZ,MOTOR}_PORT. ⚠️ La ventana del escritorio utiliza el sistema WebView, por lo que 3D se ejecuta en la WebGPU de WebKit, un poco más débil que la de Chrome.Para obtener las mejores imágenes, utilice el navegador.

Guarde y surtirá efecto, sin actualización manual:

• Editarcódigo de juego(juegos//src/…) → el motor intercambia en caliente el módulo en su lugar y la vista previa se actualiza instantáneamente (las ediciones de Forge también utilizan esto; consulteConstruye chateando).
• Cambios en eleditor de escenava al disco y fluye de regreso al juego terrestre (verEscenas y editor).

• Vista previa en blanco/error de motor— el motor no está construido; repeticiónconfiguración de efectos de bollo.
• Error de SSL activado:18920— acceso a través dehttp://localhost(WebGPU todavía funciona en localhost).
• Puerto en uso— un puerto ocupado genera un error (no seleccionará otro automáticamente); correrparada de pan fxentoncesinicio de bun fx, o cambiar puertos en.env.
• El chat dice que no hay clave API- colocarANTROPIC_API_KEYen.env(la aplicación de escritorio avisa al ejecutarla por primera vez); La configuración clave está enAvanzado.
• El 3D se ve más débil en el escritorio— una limitación de la WebGPU del sistema WebView; utilice la versión del navegador Chrome para obtener una mejor representación.

aplicación de compilación bun fxempaqueta todo el estudio junto con tu juego en unpaquete de escritorio autónomo(macOS.aplicación/.dmg): un tiempo de ejecución recortado, el servidor, la interfaz de usuario de Studio, el mercado y el contenido del juego están todos dentro, por lo quese ejecuta al hacer doble clic sin configuraciónpara el usuario.

Se ejecuta en un sidecar integrado en sus propios puertos (18810/15273), por lo que nunca choca con su pila de desarrollo (consulteEjecutar y obtener vista previa). El empaquetado debe ejecutarse en macOS; el empaquetado.aplicaciónse abre al hacer doble clic.

un juego es unoautónomojuegos//carpeta(forjar.json+src/+ documentos de diseño + activos, verConceptos centrales). Comparta o confirme esa carpeta y alguien más la abrirá en su estudio para seguir jugando o construyendo: la biblioteca de demostración almacena varios juegos uno al lado del otro (fps, hellforge, cow-survivor, shoot-opt), consulte laescaparate.

Por ahora, la forma más confiable de entregar un juego a los jugadores espaquete de escritorioarriba; Todavía se está trabajando en una opción más fluida para "publicar/reproducir en línea con un solo clic".

Cambiar backends (intercambiar el chip):elija el kernel desde el interruptor backend en la parte inferior derecha del compositor, o debajo delCLIsección de Configuración —Claude Code / Codex / Cursor / Kimi Code / CodeBuddy / DeepSeek Harness / forgeax-cli. La sección CLI muestra cada backendsaludy unPruebabotón. Cambiar un backend también cambia su personaje predeterminado (consulteEl equipo de agentes.); detalles por backend en elmercado.

Claves/modelos:configure la clave API de su modelo (p. ej.ANTROPIC_API_KEY) en Configuración → Teclas:se aplica en vivo, no se reinicia(también puedes editar.envdirectamente); elija el modelo en Configuración → Modelos. La solución de problemas de claves faltantes está disponibleEjecutar y obtener vista previa.

Casi todas las capacidades de ForgeaX son unacomplemento cargado en tiempo de ejecución(resumen en elmercado), para que puedas agregar el tuyo propio.

El camino más rápido hoy:Copie un complemento de Workbench existente y adáptelo., con elautor del complemento(wb-plugin-autor) ayudar; Está en camino un editor visual más completo en la aplicación (árbol de archivos + editor de código, guardar → recarga automática). Una vez construido, habilítelo y reordenelo en elpanel de administración— Los complementos los monta la CLI en tiempo de ejecución. Ver los tipos de banco de trabajo enHerramientas de creación.

Utilice eleditor de personajes(persona-agente-wb): elija un agente de la lista, edite su personaje en un área de texto yguardar → recarga en caliente, sin reiniciar. Puedes darle a un agente un personaje o voz diferente sin tocar ningún código.

Para saber quiénes son los agentes principales y los subagentes y de dónde provienen las personas predeterminadas, consulteConceptos centralesyEl equipo de agentes.; el elenco completo está en elmercado.

Todos estos soncomplementos cargables; el catálogo completo y filtrable está en elmercado, y hay un tutorial tutorial en eltutorial de bancos de trabajo.

Arin · productor— un productor integral que coordina el diseño/código/arte/audio y es dueño de todo el juego.

Reia · directora de carrete— director interactivo de FMV que forja indicaciones, marca QTE y teje ramas y finales, impulsando a wb-reel Reel Studio a convertir una idea en una película de suspenso reproducible y en la que se puede hacer clic.

Estos sonagentes nombradosenviado a pedido por Forge (la relación principal versus subagente está enConceptos centrales); el elenco completo está en elmercado.

Estos especialistassolo plan y diseño: nunca tocan el código del juego(Forge escribe código, verConceptos centrales); su producción aterriza en el banco de trabajo (verEscenas y editor), y los bienes artísticos se producen como enActivos.

También hay un conjunto deagentes especialistas en arte/patrimonio(personajes/animación 2D, 3D low-poly/VFX, director de cine interactivo y más), cada uno conectado a su banco de trabajo de creación correspondiente (verHerramientas de creación).

Cada backend de CLI viene con una persona lista para usar:claudio(Código Claude),Códice,Cursor, yForgeaX(el forgeax-cli autoconstruido).Al cambiar el backend se cambia la persona predeterminada, no se necesita configuración; Cualquiera que sea el kernel que elijas, viene con su personaje predeterminado.

Cómo cambiar de backend y editar personas está enAvanzado; el elenco completo de agentes y los personajes cargables están en elmercado.