Primeiros passos

Documentação · English

Para jogar localmente, use o instalador de Windows, Linux ou macOS. Ele reaproveita ferramentas compatíveis, prepara as ausentes e as dependências Python/npm fixadas, compila o frontend e salva configurações. O Gravewright Runner gerado inicia a aplicação preparada em uma etapa separada. O fluxo de terminal abaixo usa o código-fonte com configuração administrada manualmente.

Extraia antes o projeto completo para uma pasta gravável. A instalação pode baixar ferramentas e pacotes; a inicialização usa o ambiente preparado. Mantenha o terminal do Runner aberto e pressione Ctrl+C para encerrar. O endereço padrão é http://127.0.0.1:3000. Downloads privados Linux exigem glibc; consulte no guia as famílias de distribuição reconhecidas e os limites de Alpine/musl.

O pacote 0.2.1 atualizado em 13 de outubro de 2026 inclui esses instaladores Linux/macOS junto do Windows. Hosts que já usam 0.2.1 precisam baixar manualmente o ZIP atualizado e seu checksum; o atualizador automático não oferece novamente a mesma versão. Pare o Runner, faça backup de .env, banco/mídias configurados e estado de recuperação, preserve-os ao substituir os arquivos da aplicação na pasta existente e execute o instalador. Consulte as instruções completas.

Requisitos

Use Python 3.14 ou superior, conforme pyproject.toml. O código usa sintaxe do Python 3.14; interpretadores antigos não são suportados. Instale uv pelas instruções oficiais. Execute os comandos na pasta que contém manage.py.

uv sync --locked
cp -n .env.example .env
uv run --locked python manage.py migrate
uv run --locked python main.py

uv sync inclui o grupo de dependências de desenvolvimento. O lock file fornece as versões reproduzíveis. Esse fluxo de terminal serve os recursos JavaScript e CSS existentes. Para recompilá-los, use o projeto npm em gravewright/maps/frontend, conforme frontend; os instaladores de cada plataforma fazem essa preparação automaticamente. No CMD do Windows, substitua a cópia por if not exist .env copy .env.example .env.

Primeiro acesso

Abra http://127.0.0.1:3000. Antes de existir um proprietário, /setup cria essa conta e inicia a sessão. Escolha nome, e-mail e senha com pelo menos 12 caracteres. Depois da configuração, /register cria participantes e /login autentica contas existentes.

O proprietário pode criar campanhas em /inside, convidar jogadores e entrar na mesa. O vínculo com a campanha define permissões de mestre/jogador. Veja o guia de uso.

Para acessar a administração separada do Django em /admin/:

uv run --locked python manage.py createsuperuser

Isso cria uma conta administrativa, não o proprietário do VTT. Não substitui /setup.

Arquivos e configuração

O .env é opcional e carregado automaticamente. Variáveis exportadas no processo têm prioridade; ${NAME} no .env permanece literal. Reinicie o servidor após alterar valores. Consulte a referência de configuração.

O Runner gerado usa o .env do projeto e seus caminhos de banco/mídia, impondo seu perfil local de rede. Todo armazenamento padrão fica na pasta descompactada do projeto no Windows, Linux e macOS: data/ para estado, logs e assets coletados, e data/runner/ para ferramentas gerenciadas, ambientes e caches. O estado não é compartilhado pelo perfil do usuário do sistema operacional. --data-dir muda estado/logs/assets coletados; altere o .env para mudar o banco ou uploads. Antes de atualizar, faça backup conjunto do banco configurado, mídias e .env.

Se alterar os caminhos do banco ou dos arquivos, crie as pastas necessárias e conceda escrita à conta do serviço. O desenvolvimento local usa um processo ASGI e Channels em memória. Hospedagem pública e múltiplos processos precisam de configuração adicional; veja implantação.

Problemas comuns

Para verificações de desenvolvimento e preparo do navegador, continue em testes.