OpenScaleOrg/aseprite-live

Trabajar en vivo en la ventana de Aseprite del usuario

El servidor MCP de Aseprite tiene dos modos, elegidos por llamada:

• En vivo: Aseprite se está ejecutando con la extensión Aseprite MCP Live, que se conecta al servidor. Cada herramienta ejecuta su script dentro de esa ventana, sobre el sprite abierto, y el lienzo se redibuja de inmediato.
• Por lotes: no hay ventana conectada. Cada herramienta inicia un Aseprite oculto, edita el archivo en disco y sale. Una ventana abierta no mostrará el cambio hasta que se vuelva a abrir el archivo.

Iniciar cada sesión con live_status

Resultado	Qué hacer
connected; active tab: <ruta> + saved	Usar esa ruta como filename para cada herramienta.
... UNSAVED	Preguntar dónde guardarlo, luego save_active_sprite("<dir>/<nombre>.aseprite") y usar esa ruta.
connected; no sprite is open	create_canvas abre una nueva pestaña en la ventana.
Aseprite is not connected ...	Informar al usuario. Trabajar en modo por lotes solo si él acepta.

Dibujar siempre en el archivo que el usuario tiene abierto (estricto)

Cada dibujo va a la pestaña abierta del usuario: el sprite activo reportado por live_status. Nunca colocar el trabajo en un archivo separado.

• Nunca crear un segundo sprite. No llamar a create_canvas, ni nunca usar Sprite(w, h) en run_lua_script, mientras el usuario tenga una pestaña abierta. Usar create_canvas solo cuando live_status indique que no hay sprite abierto. En Lua, editar app.activeSprite.
• Si el lienzo es demasiado pequeño, redimensionar ese mismo archivo. Por ejemplo, si la pestaña abierta es de 64×64 y la escena necesita 160×112, llamar a resize_canvas(<archivo abierto>, 160, 112) sobre él y luego dibujar. Hacer lo mismo para el número de fotogramas: agregar fotogramas a ese archivo con add_frames.
• Un lienzo que ya tiene obra de arte debe consultarse primero. resize_canvas escala los píxeles existentes, así que en una pestaña en blanco simplemente redimensionarlo; cuando la pestaña ya tiene arte, preguntar al usuario antes de redimensionar.
• Si la pestaña no está guardada, guardarla con save_active_sprite (preguntar dónde), luego seguir trabajando en ese archivo. Guardarlo no es motivo para iniciar otro.
• Si el modo en vivo no está conectado, detenerse e informar al usuario. No recurrir a un nuevo archivo en disco a menos que el usuario lo solicite explícitamente.

La extensión se instala en Aseprite la primera vez que se inicia el servidor. Luego, Aseprite debe reiniciarse una vez, y en el primer uso pregunta si el script puede conectarse a la red o escribir archivos. El usuario debe permitir esto en Aseprite. Nunca hacer clic en estas solicitudes en su nombre.

Mientras se dibuja en vivo

• Una llamada de herramienta es un paso deshacible. El usuario puede presionar Ctrl+Z para deshacer exactamente uno de tus pasos, así que decírselo cuando sea útil.
• Trabajar en pases visibles (silueta, luego colores planos, sombreado, detalles, animación) para que el usuario vea cómo se construye la pieza, y decir qué hace cada pase.
• Una cosa pequeña por llamada. La ventana solo se redibuja cuando una llamada regresa, por lo que un script que pinte toda la escena aparece de golpe. Cada llamada debe añadir un objeto, una capa, un pase de sombreado o un fotograma. Escribir un script, ejecutarlo, luego escribir el siguiente. Nunca escribir todos los scripts primero y ejecutarlos al final.
  • Preferir las herramientas dedicadas (draw_rows, draw_rectangle_at, draw_ellipse_at, fill_area_at, ...). Cada una de ellas es un único paso visible.
  • En modo en vivo, run_lua_script rechaza scripts de más de 40 líneas de código. Mantener las funciones auxiliares cortas, ya que cada script debe redefinir las suyas propias.
  • Una escena de 64×64 normalmente requiere de 10 a 25 llamadas. Eso es esperable: el usuario está viendo cómo se construye.
• Cada paso se guarda en el archivo, lo que mantiene sincronizados view_sprite y las herramientas de exportación. Estas aún leen el archivo guardado a través de un Aseprite oculto.
• El usuario también puede editar. Verificar con view_sprite o read_rows antes de redibujar un área, y no sobrescribir sus cambios sin preguntar.
• No cambiar su vista. Evitar cambiar de pestañas, fotogramas o capas en la ventana a menos que la tarea lo requiera.

Solución de problemas

• Una herramienta agota el tiempo de espera con "A dialog may be open". Aseprite está esperando una solicitud, como un permiso. Pedir al usuario que la responda.
• Los cambios no aparecen en la ventana. Ejecutar live_status. Cada llamada primero reclama el enlace en vivo de cualquier otra sesión de Claude que lo tenga, así que si aún dice no conectado, Aseprite se abrió antes de instalar la extensión y necesita un reinicio. Detenerse e informar al usuario; no seguir dibujando en el archivo en disco.
• Nunca iniciar Aseprite por tu cuenta. No abrir el archivo en una nueva ventana con un comando de shell. Dos ventanas sobre el mismo archivo se desincronizan, y los scripts solo van a la ventana que se conectó al final. Si la pestaña abierta está desactualizada, pedir al usuario que use Archivo → Revertir.
• Aparecen y se cierran pestañas con títulos similares al sprite. Eso es esperable: algunas herramientas de análisis trabajan con una copia temporal que se cierra después.