OpenScaleOrg/aseprite-live

Trabalhando ao vivo na janela do Aseprite do usuário

O servidor MCP do Aseprite tem dois modos, escolhidos por chamada:

• Ao vivo (Live): O Aseprite está em execução com a extensão Aseprite MCP Live, que se conecta ao servidor. Cada ferramenta executa seu script dentro dessa janela, no sprite aberto, e o canvas é redesenhado imediatamente.
• Batch: nenhuma janela conectada. Cada ferramenta inicia um Aseprite oculto, edita o arquivo em disco e sai. Uma janela aberta não mostrará a alteração até que o arquivo seja reaberto.

Inicie toda sessão com live_status

Resultado	O que fazer
connected; active tab: <caminho> + saved	Use esse caminho como filename para todas as ferramentas.
... UNSAVED	Pergunte onde salvá-lo, então save_active_sprite("<dir>/<nome>.aseprite") e use esse caminho.
connected; no sprite is open	create_canvas abre uma nova aba na janela.
Aseprite is not connected ...	Avise o usuário. Trabalhe no modo batch apenas se ele concordar.

Sempre desenhe no arquivo que o usuário tem aberto (estrito)

Todo desenho vai para a aba aberta do usuário: o sprite ativo informado por live_status. Nunca coloque o trabalho em um arquivo separado.

• Nunca crie um segundo sprite. Não chame create_canvas, e nunca chame Sprite(w, h) em run_lua_script, enquanto o usuário tiver uma aba aberta. Use create_canvas apenas quando live_status disser que não há sprite aberto. Em Lua, edite app.activeSprite.
• Se o canvas for muito pequeno, redimensione o mesmo arquivo. Por exemplo, se a aba aberta é 64×64 e a cena precisa de 160×112, chame resize_canvas(<arquivo aberto>, 160, 112) nela e então desenhe. Faça o mesmo para a contagem de quadros: adicione quadros a esse arquivo com add_frames.
• Um canvas que já tem arte deve ser perguntado primeiro. resize_canvas escala os pixels existentes, então em uma aba em branco apenas redimensione; quando a aba já tiver arte, pergunte ao usuário antes de redimensionar.
• Se a aba não estiver salva, salve-a com save_active_sprite (pergunte onde), então continue trabalhando nesse arquivo. Salvá-lo não é motivo para iniciar outro.
• Se o modo ao vivo não estiver conectado, pare e avise o usuário. Não recorra a um novo arquivo em disco a menos que o usuário diga explicitamente.

A extensão se instala no Aseprite na primeira vez que o servidor inicia. O Aseprite deve então ser reiniciado uma vez, e no primeiro uso ele pergunta se o script pode se conectar à rede ou escrever arquivos. O usuário precisa permitir isso no Aseprite. Nunca clique nesses prompts em nome dele.

Enquanto desenha ao vivo

• Uma chamada de ferramenta é uma etapa de desfazer. O usuário pode pressionar Ctrl+Z para desfazer exatamente um dos seus passos, então avise-o quando isso ajudar.
• Trabalhe em passes visíveis (silhueta, depois cores chapadas, sombreamento, detalhes, animação) para que o usuário veja a peça se formar, e diga o que cada passagem faz.
• Uma coisa pequena por chamada. A janela só redesenha quando uma chamada retorna, então um script que pinta a cena inteira aparece de uma vez só. Cada chamada deve adicionar um objeto, uma camada, um passe de sombreamento ou um quadro. Escreva um script, execute-o, depois escreva o próximo. Nunca escreva todos os scripts primeiro e execute-os no final.
  • Prefira as ferramentas dedicadas (draw_rows, draw_rectangle_at, draw_ellipse_at, fill_area_at, ...). Cada uma delas é um único passo visível.
  • No modo ao vivo, run_lua_script recusa scripts com mais de 40 linhas de código. Mantenha funções auxiliares curtas, pois cada script tem que redefinir as suas próprias.
  • Uma cena de 64×64 normalmente leva de 10 a 25 chamadas. Isso é esperado: o usuário está vendo a construção.
• Cada etapa é salva no arquivo, o que mantém view_sprite e as ferramentas de exportação sincronizadas. Elas ainda leem o arquivo salvo através de um Aseprite oculto.
• O usuário também pode editar. Verifique com view_sprite ou read_rows antes de redesenhar uma área, e não sobrescreva as alterações dele sem perguntar.
• Não mude a visualização dele. Evite trocar abas, quadros ou camadas na janela a menos que a tarefa precise.

Solução de problemas

• Uma ferramenta excede o tempo limite com "A dialog may be open". O Aseprite está esperando um prompt, como uma solicitação de permissão. Peça ao usuário para responder.
• Alterações não aparecem na janela. Execute live_status. Cada chamada primeiro reivindica o link ao vivo de qualquer outra sessão do Claude que o segure, então se ainda disser não conectado, o Aseprite foi aberto antes da instalação da extensão e precisa ser reiniciado. Pare e avise o usuário; não continue desenhando no arquivo em disco.
• Nunca inicie o Aseprite por conta própria. Não abra o arquivo em uma nova janela com um comando de shell. Duas janelas no mesmo arquivo ficam dessincronizadas, e os scripts só vão para a janela que se conectou por último. Se a aba aberta estiver desatualizada, peça ao usuário para usar Arquivo → Reverter.
• Abas com título semelhante ao sprite aparecem e fecham. Isso é esperado: algumas ferramentas de análise trabalham em uma cópia temporária, que é fechada em seguida.