Documentação

ForgeaX é um estúdio de desenvolvimento de jogos nativo de IA. Você descreve o jogo em linguagem simples; um líder de IA chamadoForja planeja, projeta e grava na execução do próprio código do jogo, recarregando o resultado em seu navegador – o que você diz é o que você toca.

Duas fundações internas ficam embaixo: umamotor redesenhado para o ponto de vista da IA(verPor que um mecanismo nativo de IA) e umciclo de desenvolvimento que converge recursos para um resultado correto(verComo a IA acerta um recurso).

Combina2D/2,5D/3Djogos na web. Já existem FPS jogáveis, ARPG estilo Diablo, sobrevivência em dois níveis e demos de tiro (veja ovitrine); o mecanismo cobre renderização PBR / IBL / SSAO, física 2D/3D, animação esquelética e RHI duplo (consulte "Capacidades do mecanismo" na parte inferior dovitrine).

Tudo roda no navegador (WebGPU), web e desktop em uma pilha; código aberto sob licença Apache 2.0 (veja olicença).

Pré-requisitos: idiota,pão≥ 1,3,nó≥ 22,enrolar. (Em um host limpo,configuração bun fxtambém pode inicializar bun / node 22+ / pnpm / o conjunto de ferramentas Rust + wasm - prompt zero por padrão;--interativopede por ferramenta,--skip-bootstrapignora.)

git clone --recurse-submodules \
  https://github.com/ForgeaX-Games/forgeax-studio.git
cd forgeax-studio
configuração bun fx # configuração única
bun fx start # → http://localhost:18920

O queconfiguração bun fxfaz:verifica pré-requisitos → inicia submódulos → constrói os pacotes do mecanismo → executainstalação de pãoem cada sub-repo → constrói os plugins do mercado → scaffolds$ROOT/.envde.env.exemplo. Com--interativotambém solicitaANTHROPIC_API_KEY; senão ele avisa e você edita.envmais tarde.

coque fx começarinicializa três serviços: servidor(:18900, o núcleo do tempo de execução — chat/backends/sessões),interface(:18920, a UI do Studio com vite HMR) emotor(:15173, o renderizador). Substituir portas em.envatravés deFORGEAX_{SERVIDOR,INTERFACE,ENGINE}_PORT. Então abrahttp://localhost:18920.

Comandos diários (uma entrada,coque fx):correrconfiguração bun fxuma vez para preparar o ambiente; mais tarde, obtenha atualizações comatualização bun fx(atualiza o repositório raiz + sincroniza submódulos, sem reinstalar/reconstruir);coque fx começar/aplicativo bun fx startiniciar web/desktop;parada de bun fxebun fx reiniciarparar/reiniciar;status de coque fxemédico bun fxdiagnosticar sua configuração;aplicativo de construção bun fxempacota o aplicativo de desktop. Corrercoque fxsem argumentos para listar todos os comandos.

Aplicativo de desktop: aplicativo bun fx startabre uma janela nativa na fonte ativa (a primeira execução instala automaticamente e inicia a pilha; fechá-la interrompe a pilha);aplicativo de construção bun fxempacota um autocontido.aplicativo/.dmg. VerExecutar e visualizarpara todos os modos.

Suporte de plataforma (macOS/Linux/Windows, primeira classe):instalar e iniciar são um conjunto descripts Bun multiplataforma, então todos os três sistemas executam omesmocoque fxcomandoscom comportamento idêntico - eO Windows não precisa mais do Git-Bash(o antigo duplo.sh/.bastão/.ps1scripts foram excluídos). Especificamente:desenvolvedor web(coque fx começar) edesenvolvedor de desktop(aplicativo bun fx start, uma janela nativa do Tauri em fonte ao vivo) funciona em macOS/Linux/Windows;empacotar um jogo em um clicável duplo.aplicativo/.dmg(aplicativo de construção bun fx) é feito atualmente no macOS. Problemas comuns específicos do Windows (visualização em preto, uma janela do console por turno, processos que não fecham corretamente, stub Python do sistema) foram todos corrigidos - consulteRegistro de alterações · 28/06/2026.

Prefere não fazer isso manualmente? Deixe sua CLI de codificação de IA clonar e iniciá-la - consulteFaça seu clone AI CLI e inicie-o; então construa seu primeiro jogo comInício rápido. Para chaves de API, consulteAvançado · Alternar/configurar o backend de IA.

A interface é composta por três partes: uma barra superior, o chat à esquerda e a visualização/bancada de trabalho à direita.

• Barra superior- o⊕novo cardápio, umalternador de projeto(mudança entre os jogos - o que é um "projeto" é abordado emConceitos centrais) e umalternador de sessão(revisar/alternar conversas anteriores).
• Esquerda · bate-papo (ChatPanel)- um trilho de equipe (Forge e os subagentes), um fluxo de mensagens (cartões de subagentes, pensamento de Forge e chamadas de ferramentas) e um compositor na parte inferior com uminterruptor de back-endno canto inferior direito (vejaAvançado).
• Direita · área principal (MainArea)— alterna entrevisualização(seu jogo ao vivo em um iframe) e obancada de trabalho(edição de arquivos/documentos de design); verCenas e editor.

A engrenagem superior direita abreConfigurações: Chaves de API, escolha de modelo, backend CLI e gerenciamento de plugins. O aplicativo de desktop também mostra uma sobreposição de primeira execução que solicita a chave na primeira vez que você o abre.

No ForgeaX,“projeto” e “jogo” são a mesma coisa- um jogo é umjogos//pasta. Uma pasta de jogo real geralmente se parece com isto:

• forge.json — o manifesto do jogo. No mínimo três campos:eu ia,nome, eentrada(apontando para o código de entrada, por ex.src/main.ts).
• FORGE.md — o leia-me/visão geral da jogabilidade do próprio jogo (controles, mecânica, batidas da história).
• src/ — o código do jogo. Além doprincipal.tsentrada, geralmente é dividido em módulos por preocupação (por exemplo,jogador.ts,inimigos/,efeitos.ts,configuração.ts).
• design/ · assets/ — documentos de design e ativos de arte/áudio.
• package.json · tsconfig.json — arquivos de projeto TS padrão.

Oprincipal.tsentrada importa recursos do mecanismo de@forgeax/motor-runtime/motor-ecs/aplicativo de mecanismoe exporta umEntrada do jogo— o contrato pelo qual o motor carrega um jogo. Para o conjunto completo de capacidades, consulte "Capacidades do motor" na páginavitrine.

Vários jogos = vários projetos, alternados no alternador de projetos da barra superior. Para saber como as cenas/níveis são organizados, consulteCenas e editor.

Forge (o agente principal)é o único que escreve o código do jogo diretamente – ele escrevegames//src/main.ts, a visualizaçãorecargas a quente, e vê o resultado da execução para decidir a próxima etapa. Esse loop de edição → ver → edição deve ficar com quem pode ver a visualização, ou seja, Forge (vejaConstrua conversando).

Subagentes(por exemplo, jogabilidade Iori, design Suzu, narrativa Kotone, arte Iro, construção Tsumugi) apenas planejar/projetar/criar recursos/escrever documentos enunca toquefonte/- eles não têm feedback de visualização ao vivo, portanto, qualquer código que escrevessem não teria nada para orientá-lo. Veja o elenco completo nomercadoeCapítulo 10 · A equipe de agentes.

Como funciona o despacho:Forge despacha um subagente com uma chamada de ferramenta (em formatosubagente(type="iori", tarefa="…")); o servidor/api/subagentestream conecta sua saída de volta à conversa principal em tempo real — esse é o cartão de subagente incorporado que você vê no fluxo de mensagens. Os documentos de design de um subagente são arquivados em sua própria seção no ambiente de trabalho (consulteCenas e editor).

UMsessãoé a memória de um agente - umapenas anexarfluxo de eventos (cada um é uma mensagem do usuário/mensagem do assistente/pensamento/chamada da ferramenta/resultado da ferramenta). Forge (principal) e cada subagente mantêm o seu próprio.

A IU divide os eventos de acordo com quem os emitiu no thread principal e nos subagentes, renderizando a fatia de cada subagente como um cartão incorporado. Então, em uma tela você vê o thread principal do Forge e o que os subagentes que ele despachou realmente fizeram.

Use o alternador de sessões da barra superior para revisar e alternar sessões anteriores.Alternar uma sessão não reinicia nada— a UI apenas lê o fluxo de eventos de um agente diferente.

Quanto mais específico você for, melhor o Forge acerta primeiro com menos refazer. Um bom prompt geralmente cobre:

• Gênero e visualização- de cima para baixo / primeira pessoa / rolagem lateral 2.5D…
• Loop central- a única coisa que o jogador continua fazendo
• Controles,ganhar/perder,inimigos / obstáculos, e osentir

Comece pequeno, coloque-o em funcionamento e, em seguida, aplique a mecânica. Por exemplo:

Um jogo de cima para baixo: um personagem corre ao redor de uma arena, o espaço dispara balas, os inimigos continuam surgindo, os golpes os removem e adicionam pontuação.

Para um primeiro jogo passo a passo, consulteInício rápido; para saber o que é possível, navegue novitrine. Para projetos mais pesados, o Forge utiliza subagentes de design (consulteConceitos centrais).

Depois de enviar uma solicitação, a cadeia é:

• Entenda + planeje— Forge esclarece o requisito, despachando subagentes de design/jogabilidade para trabalhos mais pesados ​​(vejaConceitos centrais).
• Escreva o código- Forge escreveem siemgames//src/main.ts(e seus módulos divididos).
• Recarregar a quente— ao salvar, o motor do motor detecta a alteração e a visualizaçãosubstitui o módulo a quenteno lugar - sem recarga completa, a imagem é atualizada quase instantaneamente.
• Veja o resultado— Forge vê o resultado da corrida através da pré-visualização (que também encaminha o jogoconsolevoltar) e decide o próximo passo.

Todo o processo é transparente: o fluxo de mensagens mostra o pensamento do Forge, cada chamada de ferramenta e os cartões dos subagentes que ele despachou. Para alternar/controlar a visualização versus o ambiente de trabalho, consulteCenas e editor; para saber como funciona o hot-reload, consulteExecutar e visualizar.

Não está feliz? Continue falando - cada feedback se torna outra mudança, visível instantaneamente por meio de hot-reload:

Balas mais rápidas, saúde dupla do inimigo, fundo noturno.

A prévia temreproduzir / pausar / recarregarcontroles para testar conforme você avança; para fixar a visualização em um jogo específico, alterne o alternador de projetos (vejaAbra o estúdio, aprenda a interface).

O ciclo básico édescrever → gerar → reproduzir → descrever novamente. Execute-o sem problemas e você passará de uma frase a um jogo jogável - a integração completa está emInício rápido.

A área principal à direita alterna entre duas visualizações:

• Visualização— seu jogo é executado ao vivo em um iframe, com leitura de FPS e controles de reprodução/pausa/recarregamento. Quando o Forge escreve código, ele é recarregado aqui instantaneamente (vejaConstrua conversando).
• Bancada de trabalho- um navegador de arquivos + editor: visualize / edite / salve texto e código, renderize documentos de design de markdown e visualize imagens, áudio, vídeo e modelos 3D. Ele também mostra a atividade do arquivo e os bloqueios de “quem está editando”, para que você e a IA editem os mesmos arquivos sem atrapalhar.

Sem nenhum arquivo aberto, o ambiente de trabalho mostra entradas para cada ambiente de criação (personagem/animação/3D/cena/UI/música…) — consulteFerramentas de criaçãoe omercado. Para criar ativos, consulteAtivos.

O editor de cena salva o conteúdo de um nível em umarquivo de dados de cenana pasta do jogo (cena.pack.json) - oúnica fonte de verdadepara esse nível: o que está no disco é o que roda no jogo.

Quando você posiciona objetos e sai do modo de edição, as alterações sãoliberado para o disco e o jogo em execução os relê, para que a visualização reflita suas edições imediatamente - a viagem de ida e volta editar→reproduzir. Por outro lado, quando o Forge altera o código por chat, ele segue o mesmo caminho de recarga a quente (consulteConstrua conversandoeExecutar e visualizar).

Um jogo pode termúltiplas cenas/níveis, cada um com seus próprios dados de cena, trocados e reutilizados conforme necessário - a demo "Cow Survivor" alterna entre um pasto diurno e um cemitério noturno (veja ovitrine).

Como organizar:objetosviver nos dados da cena, enquantorecursos de arte/áudioao vivo na pasta do jogo (layout do projeto emConceitos centrais, geração de ativos emAtivos). A divisão por cena mantém um jogo em crescimento sustentável.

Use oeditor de personagens(caractere wb) para design de conceito de personagem: escreva um resumo de uma linha, obtenha umretrato + reviravolta. Não são necessárias habilidades de desenho para obter um personagem pronto para o jogo.

Suas saídas (um manifesto do personagem + retrato/reviravolta) são armazenadas por personagem dentro do seu jogo ealimente diretamente no ambiente de trabalho de animação como entrada downstream— então “projetar o personagem → fazê-lo se mover” é um pipeline contínuo (veja o próximo item).

Cada bancada é um painel mais um conjunto de ferramentas; você manualmente e a IA por despacho edita o mesmo artefato. Lista completa nomercadoe otutorial de bancadas.

2D:a bancada de animação (wb-anim) usa o retrato do personagem como modelo e o transforma em movimentos de caminhada, ataque, em quatro direções e até mesmo em clipes curtos -sem desvio de rosto, então ele permanece o mesmo personagem quando se move.

3D:o mecanismo suporta nativamenteanimação esquelética- importe um modelo manipulado e com skin, além de clipes de animação do FBX, com crossfades suaves entre inativo / caminhada / corrida / elenco / morte. Esse pipeline é real e enviado – é como a bruxa da fantasia sombria na vitrine se move: vejao marco da animação esqueléticae ovitrine (Hellforge).

Além dos personagens, existem bancadas em todo o pipeline:

A cobertura item por item está emCapítulo 9 · Ferramentas de criação, otutorial de bancadas, e omercado.

Um exemplo real do mecanismo ForgeaX rodando ao vivo nesta página (WebGPU – Chrome / Edge recomendado). Mais demonstrações executáveis ​​emExemploseJogos.

Abrir tela inteira ↗

A mesma base de código é executada em três formas:

• Desenvolvedor Web-coque fx começarinicializa três serviços (servidor/UI/motor); abrirhttp://localhost:18920em um navegador, edita hot-reload ao vivo. Funciona em macOS/Linux/Windows. Instalar emAntes de começar.
• Desenvolvedor de desktop-aplicativo bun fx startabre uma janela nativa carregando o mesmo servidor de desenvolvimento, com fonte ao vivo e HMR idênticos; primeiro execute a instalação automática e inicie a pilha, fechando a janela a interrompe. Disponível em macOS/Linux/Windows.
• Desktop .app (empacotado)-aplicativo de construção bun fxproduz um autocontido.aplicativo/.dmgque roda em clique duplo com seu próprio sidecar (portas 18810/15273, deliberadamente deslocadas das 18900/15173 do desenvolvedor para que ambas possam coexistir); sua chave mora em~/ForgeaxProjects/.env, com uma sobreposição de primeira execução. A embalagem está emPublicar e compartilhar.

Todas as três portas são substituíveis em.envatravés deFORGEAX_{SERVIDOR,INTERFACE,ENGINE}_PORT. ⚠️ A janela da área de trabalho usa o sistema WebView, então o 3D roda no WebGPU do WebKit – um pouco mais fraco que o do Chrome.Para obter os melhores recursos visuais, use o navegador.

Salve e ele entrará em vigor – sem atualização manual:

• Editarcódigo do jogo(jogos//src/…) → o motor troca o módulo no lugar e a visualização é atualizada instantaneamente (as edições do Forge também usam isso - vejaConstrua conversando).
• Mudanças noeditor de cenadescarregar no disco e fluir de volta para o jogo em execução (vejaCenas e editor).

• Visualização em branco/erro de mecanismo— o motor não está construído; executar novamenteconfiguração bun fx.
• Erro SSL ativado:18920- acesso atravéshttp://localhost(WebGPU ainda funciona em localhost).
• Porta em uso— uma porta ocupada apresenta erro (não selecionará outra automaticamente); correrparada de bun fxentãocoque fx começarou altere as portas em.env.
• O bate-papo diz que não há chave de API- definirANTHROPIC_API_KEYem.env(o aplicativo de desktop solicita na primeira execução); a configuração da chave está emAvançado.
• 3D parece mais fraco no desktop— uma limitação do WebGPU do sistema WebView; use a versão do navegador Chrome para melhor renderização.

aplicativo de construção bun fxempacota todo o estúdio junto com seu jogo em umpacote de desktop independente(macOS.aplicativo/.dmg): um tempo de execução reduzido, o servidor, a UI do Studio, o mercado e o conteúdo do jogo estão todos dentro, entãoé executado com clique duplo sem configuraçãopara o usuário.

Ele roda em um sidecar integrado em suas próprias portas (18810/15273), então nunca colide com sua pilha de desenvolvimento (vejaExecutar e visualizar). O empacotamento deve ser executado no macOS; o embalado.aplicativoabre com um clique duplo.

Um jogo é umindependentejogos//pasta(forja.json+fonte/+ documentos de design + ativos, consulteConceitos centrais). Compartilhe ou envie essa pasta e outra pessoa a abrirá em seu estúdio para continuar jogando ou construindo — a biblioteca de demonstração armazena vários jogos lado a lado (fps, hellforge, cow-survivor, shoot-opt), veja ovitrine.

Por enquanto, a maneira mais confiável de entregar um jogo aos jogadores épacote de desktopacima; uma "publicação/reprodução on-line na Web com um clique" mais suave ainda está em andamento.

Alternar backends (trocar o chip):escolha o kernel no switch de back-end no canto inferior direito do compositor ou sob oCLIseção de Configurações —Claude Code / Codex / Cursor / Kimi Code / CodeBuddy / DeepSeek Harness / forgeax-cli. A seção CLI mostra cada back-endsaúdee umTestebotão. Mudar um back-end também troca sua persona padrão (consulteA equipe de agentes); detalhes por back-end nomercado.

Chaves/modelos:defina a chave de API do seu modelo (por exemplo,ANTHROPIC_API_KEY) em Configurações → Chaves —aplica-se ao vivo, sem reinicialização(você também pode editar.envdiretamente); escolha o modelo em Configurações → Modelos. A solução de problemas de chave ausente está emExecutar e visualizar.

Quase todos os recursos do ForgeaX sãoplugin carregado em tempo de execução(visão geral nomercado), para que você possa adicionar o seu próprio.

O caminho mais rápido hoje:copie um plugin de ambiente de trabalho existente e adapte-o, com oautor do plugin(autor do plugin wb) ajudando; um editor visual mais completo no aplicativo (árvore de arquivos + editor de código, salvar → recarregar automaticamente) está a caminho. Uma vez construído, ative e reordene-o nopainel de administração— os plugins são montados pela CLI em tempo de execução. Veja os tipos de bancada emFerramentas de criação.

Use oeditor de personalidade(wb-agente-persona): escolha um agente da lista, edite sua persona em uma área de texto esalvar → recarregar a quente, sem reiniciar. Você pode dar a um agente um personagem ou voz diferente sem tocar em nenhum código.

Para saber quem são os agentes principais e os subagentes e de onde vêm as personas padrão, consulteConceitos centraiseA equipe de agentes; o elenco completo está nomercado.

Todos estes sãoplug-ins carregáveis; o catálogo completo e filtrável está nomercado, e um tutorial passo a passo está notutorial de bancadas.

Arin · produtor— um produtor versátil que coordena design/código/arte/áudio e é dono de todo o jogo.

Reia · diretora do filme- diretor interativo de FMV que forja prompts, acompanha QTEs e tece ramificações e finais, conduzindo o wb-reel Reel Studio para transformar uma ideia em um filme de suspense clicável e jogável.

Estes sãoagentes nomeadosdespachado sob demanda pelo Forge (o relacionamento principal versus subagente está emConceitos centrais); o elenco completo está nomercado.

Esses especialistasapenas planejamento e design – eles nunca tocam no código do jogo(Forge escreve código, vejaConceitos centrais); sua saída chega à bancada (vejaCenas e editor), e os ativos de arte são produzidos como emAtivos.

Há também um conjunto deagentes especializados em arte/ativos(personagem/animação 2D, low-poly/VFX 3D, diretor de filme interativo e muito mais), cada um conectado à sua bancada de criação correspondente (consulteFerramentas de criação).

Cada backend CLI vem com uma persona pronta para uso:Cláudio(Código Claude),Códice,Cursor, eForgeaX(o forgeax-cli desenvolvido internamente).Mudar o back-end troca a persona padrão – nenhuma configuração necessária; qualquer kernel que você escolher vem com sua personalidade padrão.

Como mudar backends e editar personas está emAvançado; o elenco completo do agente e as personas carregáveis ​​​​estão nomercado.