Metadata-Version: 2.5
Name: open-sprite
Version: 0.1.1
Summary: Engine privada de criação de arte para o EternityME: um núcleo, três superfícies
Requires-Python: >=3.13
Requires-Dist: av>=12.0
Requires-Dist: fal-client>=0.5
Requires-Dist: fastapi>=0.115
Requires-Dist: mcp>=1.12
Requires-Dist: numpy>=2.1
Requires-Dist: pillow>=11.0
Requires-Dist: pydantic-settings>=2.6
Requires-Dist: pydantic>=2.9
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# open-sprite

Uma engine de criação de recursos para jogo 2D — sprite, animação, tilemap e ícone.
Um núcleo em Python exposto por três superfícies: um CLI, uma API REST e um servidor
MCP. Um editor web acompanha o pacote, já construído, e nele gerar arte e colocá-la no
mapa acontecem na mesma tela.

## Instalar

```bash
pip install open-sprite
```

Node não entra em caminho de instalação nenhum: a página do editor viaja pronta dentro
do pacote.

## Começar

Tudo tem o projeto por escopo — o diretório que contém `.open_sprite.json`, achado
subindo a partir de onde o comando foi digitado. Não há modo sem projeto, e os comandos
recusam quando não encontram um, dizendo qual critério falhou.

```bash
mkdir meu-jogo && cd meu-jogo
open-sprite init
```

Os estágios que geram arte compram de um modelo, e isso custa dinheiro. A credencial
sai do ambiente ou do próprio `.open_sprite.json`:

```bash
export FAL_KEY=...
```

`.open_sprite.json` carrega uma credencial e nunca deve ser comitado. `open-sprite init`
avisa quando não há `.gitignore` que o cubra, e diz o comando a rodar quando o git já o
está rastreando.

## Os três comandos que sobem alguma coisa

```bash
open-sprite serve          # a API REST e a página do editor
open-sprite editor         # o mesmo, e abre o navegador nele
open-sprite mcp start      # o servidor MCP, na porta dele
```

São dois processos e duas portas, de propósito: o editor sobe e derruba o MCP, o que
seria impossível se fosse esse mesmo servidor que o servisse. Um agente fala com o MCP
sem o editor estar aberto; uma pessoa abre o editor sem o MCP estar no ar. O que os dois
veem é o mesmo disco, então um rascunho aberto pelo agente chega ao editor como qualquer
outra mudança.

## Antes de gastar

```bash
open-sprite preview ...    # no que a chamada seria composta, antes de fazê-la
open-sprite cost           # o que este projeto já gastou, por tipo
open-sprite status         # o que ele guarda, por tipo
```

Todo estágio que gasta diz isso no próprio `--help`, e a chamada é registrada antes dos
arquivos que ela escreve. `open-sprite --help` lista os estágios todos.

## Os números do jogo não estão aqui

Tamanho de célula, grade da folha, faixa de ids da arte própria e as faixas medidas do
mundo são um perfil declarado em `.open_sprite.json`. O núcleo não guarda nenhum deles:
um literal desses no código é defeito, não atalho.

Um perfil neutro acompanha a ferramenta, e é o que faz um projeto novo funcionar sem
configurar nada. Ele não conhece o seu jogo. `open-sprite measure` lê a arte que você já
tem e escreve o perfil dela — é esse passo que faz um relatório de medição significar
alguma coisa em vez de comparar o seu sprite com uma média de ninguém.

## Versões

Toda execução de um estágio é uma versão, guardada inteira, nunca sobrescrita e nunca
apagada por uma troca. Um nome canônico resolve para a versão corrente, e `apply` é o
que move essa resolução; a escolhida nunca segue a mais nova sozinha. `uses` responde o
que aponta para um nome antes de você promover outra coisa para ele.
