3dMVP/blobit-cli-skill-pack

Blobit CLI

Use blobit como o backend de ativos e como o backend de cena/publicação quando o jogo deve consumir uma cena Blobit hospedada.

• Use blobit para:
  • criar projetos
  • enviar imagens
  • gerar ou reutilizar ativos 3D
  • inspecionar metadados de posicionamento
  • compor e validar cenas
  • publicar manifestos
• Para jogos no navegador, use ferramentas de código normais para planejar, estruturar, implementar, executar e verificar visualmente o jogo jogável.
• Em projetos de jogos, o Blobit é o responsável pela geração de ativos em tempo de execução. O código do jogo, interface, entrada, câmera, física e estado do jogo permanecem na base de código do jogo.
• Para jogos no navegador, o modo de manifesto publicado é o caminho padrão de entrega de ativos: use a manifest_url retornada por blobit publish create e carregue-a com @blobit/sdk.

Quando usar

Use esta habilidade quando o usuário pedir para:

• criar ou gerenciar projetos e ativos Blobit
• gerar modelos 3D a partir de imagens
• criar o layout de uma cena usando comandos semânticos de posicionamento
• publicar uma cena Blobit para consumo no navegador
• integrar conteúdo Blobit publicado em um jogo web com o SDK
• criar ou atualizar um jogo no navegador onde o Blobit deve gerar ou fornecer os ativos em tempo de execução

Regras

• Prefira blobit --json quando a saída do comando precisar ser analisada.
• Prefira comandos semânticos de cena em vez de editar manualmente transformações brutas.
• Para novos ativos, prefira geração de imagem Blobit, upload de imagem ou upload de imagem local seguido de geração de modelo/mundo, a menos que o usuário forneça explicitamente um modelo existente para reutilizar.
• Para comandos de geração de modelo e mundo, prefira o provedor padrão armazenado, a menos que a tarefa precise de uma substituição única via --provider.
• Prefira blobit config set-provider <provider> em vez de dizer ao usuário para editar arquivos de configuração do Blobit manualmente.
• Não use o apelido de provedor legado --endpoint-type em novos comandos; use --provider.
• Inspecione metadados de posicionamento antes de organizar ou enquadrar quando a origem, pegada ou contato com o chão de um ativo não estiver claro.
• Execute scene analyze antes e depois de grandes mudanças no layout.
• Execute scene validate antes da publicação.
• Quando uma tarefa altera a geometria visível da cena e uma pré-visualização local ou visualizador estiver disponível, capture uma captura de tela e inspecione para problemas visuais óbvios.
• Para jogos no navegador, evite baixar ativos e carregue o manifesto Blobit publicado em tempo de execução.
• Use blobit assets download apenas quando o usuário pedir explicitamente por ativos empacotados, offline, estáticos ou de arquivo local.
• Não pergunte nem relate um orçamento de ativos em dólares. O Blobit CLI atual não retorna gastos com geração de ativos; pergunte pelo escopo do ativo, quantidade de ativos e prioridade.
• Para jogos de alto polimento, use o modo com revisão por padrão: faça perguntas breves, gere um alvo visual, escreva PLAN.md, gere ou atribua ativos Blobit, construa um primeiro jogável, capture evidências e então itere com base no feedback.
• Antes de planejar a implementação do jogo, pergunte ou registre a escolha de arquitetura para colisão/física: colisão arcade personalizada, física Babylon/Havok ou híbrida.
• Não use fornecedores ou scripts de geração de ativos que não sejam Blobit quando a tarefa pedir por ativos feitos com Blobit.
• Trate o Blobit apenas como o backend de ativos e cenas; use as ferramentas de código normais do repositório para construir a lógica e renderização do jogo.
• Para conteúdo publicado em tempo de execução, use a manifest_url retornada por blobit publish create e carregue-a com @blobit/sdk.

O que produz

• um project_id do Blobit
• IDs de ativos de imagem fonte enviados ou IDs de ativos fonte reutilizados
• IDs de ativos de modelo gerados e, quando aplicável, IDs de trabalhos concluídos
• uma cena persistida com modelos colocados, estado da câmera e operações semânticas de layout aplicadas
• resultados de scene analyze e scene validate
• uma manifest_url publicada mais metadados de publicação relacionados, como publish_id e viewer_url
• o ponto de integração em tempo de execução no aplicativo web onde @blobit/sdk carrega o manifesto publicado
• para tarefas de jogo, PLAN.md, STRUCTURE.md, ASSETS.md e evidência visual do jogo no navegador em execução quando o workflow do projeto as suportar

Pipeline

1. Inspecione ou crie o projeto Blobit.
2. Envie uma imagem fonte e gere um modelo, ou reutilize um ativo existente explícito.
3. Inspecione o ativo gerado ou reutilizado, especialmente metadados de posicionamento, antes das decisões de layout da cena.
4. Adicione o modelo à cena.
5. Aplique operações semânticas de posicionamento como drop-to-floor, place-near, arrange, align, avoid-overlap, distribute, snap e frame-camera.
6. Execute scene analyze, revise sobreposições, limites e avisos, e ajuste a cena se necessário.
7. Execute scene validate antes de publicar e trate avisos de validação como um problema bloqueante a menos que o usuário os aceite explicitamente.
8. Publique e capture a manifest_url e quaisquer metadados de visualizador ou publicação relacionados.
9. No cliente do jogo, carregue o manifesto através de @blobit/sdk.
10. Construa ou atualize a lógica e renderização reais do jogo com a pilha normal do projeto.

Para jogos jogáveis no navegador, leia references/game-workflow.md antes de planejar ou codificar. Ele define um loop de planejamento e implementação adaptado para ativos exclusivamente Blobit. Para a lógica derivada do Godogen por trás desse workflow de jogo, leia references/godogen-patterns.md apenas ao atualizar a habilidade ou reconciliar decisões de workflow.

Validação em tempo de execução

• Após grandes mudanças de layout ou câmera, execute o jogo local, pré-visualização ou visualizador Blobit quando disponível.
• Capture uma captura de tela quando a geometria renderizada importa e inspecione por modelos flutuantes, clipping, escala errada, orientação errada, enquadramento de câmera errado e sobreposições que verificações semânticas podem perder.
• Trate a revisão de captura de tela como um complemento para scene analyze e scene validate, não um substituto.
• Se nenhuma pré-visualização em tempo de execução estiver disponível, confie na validação CLI e anote explicitamente que a validação visual foi pulada.

Notas de cena

• Use drop-to-floor quando um objeto deve descansar visivelmente no palco ou plano do chão.
• Use frame-camera após adicionar, remover ou reorganizar modelos, ou quando a câmera atual pode não mais enquadrar o assunto.
• Inspecione metadados de posicionamento do ativo antes de arrange ou place-near quando a origem, superfície de suporte ou pegada do objeto não estiver clara.
• Prefira operações semânticas de cena em vez de edições diretas de transformação; use transformações diretas apenas para ajustes finais precisos ou solicitações explícitas do usuário.
• Execute scene analyze após passagens de organização em massa ou resolução de sobreposição para confirmar que a cena corresponde às expectativas.

Saídas esperadas / Handoff

• os principais IDs e URLs: project_id, IDs de ativos relevantes, IDs de trabalhos, publish_id, manifest_url e viewer_url quando aplicável
• um breve resumo das operações de cena aplicadas e o estado de validação resultante
• o ponto exato de integração em tempo de execução onde o aplicativo carrega o manifesto publicado através de @blobit/sdk
• uma nota sobre se a validação por captura de tela em tempo de execução foi realizada e o que encontrou
• quaisquer limitações de layout, validação ou runtime não resolvidas que ainda precisam de acompanhamento

Comandos principais

• blobit --json projects list
• blobit --json projects create --name ...
• blobit --json assets generate-image ...
• blobit --json assets upload-image ...
• blobit --json jobs model-from-image ... --wait
• blobit --json jobs model-from-prompt ... --wait
• blobit --json jobs world-from-prompt ... --wait
• blobit --json assets inspect <asset_id>
• blobit --json assets download <asset_id> --out ...
• blobit --json scene add-model <project_id> <asset_id>
• blobit --json scene add-world <project_id> <asset_id>
• blobit --json scene analyze <project_id>
• blobit --json scene place-near ...
• blobit --json scene arrange ...
• blobit --json scene validate <project_id>
• blobit --json publish create <project_id> --allowed-origin ...

Leia references/workflows.md para receitas de comandos de ponta a ponta. Leia references/game-workflow.md para orientação sobre planejamento, implementação, manifesto de ativos e evidência visual de jogos no navegador.