Criar um módulo: da pesquisa à publicação
O procedimento completo para criar um módulo de jogo confiável: pesquisa, testes com o servidor real, runtimes portáteis, o isolamento, os modos de console e testes em um PC real.
Criar um módulo: da pesquisa à publicação
O guia de desenvolvimento de módulos explica o que um módulo contém. Esta página explica como criar um módulo que funciona em um PC real.
Um módulo que passa em todos os testes unitários ainda pode falhar em um servidor real. O módulo do Terraria é um exemplo. Ele passou em todos os testes unitários e em todas as verificações de conformidade. Em um servidor real, ele tinha nove defeitos. Esta página mostra o procedimento que encontra esses defeitos antes de uma publicação.
1. Regras de projeto
Estas regras valem para todos os módulos.
- O daemon faz o trabalho. Um módulo só descreve um jogo. Não contorne o contrato do daemon. Se falta ao contrato uma função que você precisa, adicione primeiro um ponto de extensão geral no daemon.
- Não ramifique pelo nome do jogo. O daemon e os utilitários compartilhados não têm nomes de jogos. Use chaves do
module.toml, hooks e slots. - O mesmo ambiente de execução em todo lugar. Não use um runtime instalado no PC. O módulo baixa uma versão fixa do runtime e a coloca na pasta do servidor (seção 5).
- Cada valor em um só lugar. O valor padrão de uma configuração vem de um arquivo: o que o jogo cria, ou o arquivo de exemplo do download.
- Todo texto para usuários fica em
locales/.en.jsoné o arquivo de referência.
2. Pesquisar o jogo
Antes de escrever código, crie uma tabela de pesquisa em <game>/RESEARCH.md. Escreva a fonte de cada item. Escreva também se a fonte é um documento ou uma medição. Se não encontrar uma fonte, deixe o item vazio e escreva "não verificado". Não adivinhe valores.
| Item | Onde encontrar |
|---|---|
| Executável do servidor, argumentos de inicialização, portas padrão | Documentos oficiais, a ajuda do servidor, os scripts de inicialização do download |
| Todos os comandos e seus argumentos | Documentos oficiais de comandos e a saída do comando help do servidor. Compare os dois linha por linha |
| Todas as configurações (chave, formato, faixa, padrão) | O arquivo de configuração padrão que o servidor cria. Se ele não cria um, use o arquivo de exemplo do download |
| Sintaxe e codificação do arquivo de configuração | Os bytes originais desse arquivo |
| Mundos salvos e as cópias que o jogo cria | A lista de arquivos depois de iniciar o servidor e salvar o mundo |
| Mensagens de pronto, parada, entrada e saída | A saída original do console. Veja também se a configuração de idioma do servidor traduz essas mensagens |
| Método de instalação e verificação de arquivos | O endereço oficial de download e o checksum oficial. Se não houver checksum, escreva "nenhum" e a fonte |
| Requisitos de execução | As referências do executável do servidor e os documentos oficiais. Procure o que o download não inclui |
| Arquivos fora da pasta da instância | Mudanças na pasta pessoal e na pasta Documentos depois de rodar o servidor |
Uma wiki pode descrever uma versão antiga. A wiki do Terraria cita um comando death. O servidor Terraria 1.4.5.8 responde "Invalid command." a ele.
3. Examinar os arquivos reais
Se você pode baixar o servidor, examine os arquivos você mesmo.
- Mostre todas as entradas do arquivo compactado. Veja se há uma pasta por sistema operacional e se o mesmo nome de executável está em mais de uma pasta. O arquivo do Terraria tem
TerrariaServer.exena pastaLinux/e na pastaWindows/. - Leia os arquivos padrão byte a byte. Identifique a codificação (UTF-8, BOM, cp1252), as quebras de linha (LF, CRLF), as chaves de exemplo comentadas e as linhas que não são comentários.
- Adicione as chaves de exemplo comentadas à lista de configurações. Uma linha que não é comentário dá o valor padrão.
4. Rodar o servidor real
Inicie o servidor do mesmo jeito que o daemon: ligue stdin e stdout por pipes. Registre a saída original. Se o seu ambiente de build só consegue rodar uma versão do servidor para outro sistema operacional, rode essa versão. Comandos, mensagens e o comportamento de salvamento são iguais quando o código do jogo é o mesmo.
Registre o seguinte:
- A linha de pronto, a linha depois do comando de parada e o tempo de um salvamento.
- A saída de
help. Envie cada comando que só um documento cita e anote a resposta. - O prompt do console. Alguns servidores o escrevem sem quebra de linha, e a linha seguinte começa com o prompt. O Terraria escreve
: Server started. - A resposta a um comando enviado pelo pipe. Se o servidor não responder, teste de novo com um pseudoconsole (seção 7).
- As mensagens de pronto e parada em cada idioma do servidor.
- Os arquivos que o servidor cria ao iniciar e ao salvar. O Terraria cria
world.wld.bakeworld.wld.bak2.
Alguns itens precisam de um cliente do jogo, por exemplo mensagens de entrada e um alvo para expulsar. Deixe esses itens vazios e escreva "não medido".
5. Requisitos de execução: portáteis e fixos
Alguns servidores precisam de um runtime que o download não inclui, por exemplo Java, XNA Framework ou o runtime do Visual C++. Não use um runtime instalado no PC. A versão dele pode ser diferente em cada PC.
Siga este procedimento:
- Escreva o endereço, o tamanho, a assinatura e o SHA-256 do arquivo oficial na tabela de pesquisa.
- Encontre o menor conjunto de arquivos de que o servidor precisa. Inicie o servidor só com esses arquivos para confirmar. No Terraria, são os quatro assemblies do XNA (
Microsoft.Xna.Framework,.Game,.Graphics,.Xact),XnaNative.dll,msvcr100.dllemsvcp100.dll. - Em
install_server, baixe a versão fixa. Compare o arquivo com o checksum oficial. Se não houver checksum oficial, compare com um SHA-256 que você registrou de um arquivo com assinatura de editor válida. - Coloque só os arquivos necessários na pasta do servidor ou da instância. Inicie o servidor com esse caminho.
- Em
validate, procure esses arquivos. Se faltar algum, devolva um problema comseverity: "critical"e umcodepróprio. Peça ao usuário para instalar o servidor de novo.
Não use direitos de administrador, instalação no sistema todo nem um serviço do Windows.
Limite: o .NET Framework carrega primeiro um assembly do cache global de assemblies (GAC) quando ele tem o mesmo nome e versão. As DLLs nativas são carregadas primeiro da pasta do servidor.
6. O isolamento
No Windows, um módulo que não vem do catálogo assinado do Saba-chan roda em um AppContainer do Windows. Todo módulo novo roda nesse isolamento. Teste seu módulo no isolamento antes de abrir um pull request.
O isolamento bloqueia o seguinte:
| Bloqueado | Use em vez disso |
|---|---|
| Conexões loopback (a API do daemon, a API REST do servidor do jogo) | daemon_stdin_command, daemon_rest, loopback_http, loopback_exchange. O daemon repassa a solicitação |
Windows Installer (msiexec falha com o erro 1601) e outros serviços | Leia o arquivo de instalação (MSI, CAB) com Python |
Uma pasta que tempfile.mkdtemp cria na pasta da instância | tempfile.mkstemp, ou uma pasta criada com os.mkdir. A partir do Python 3.13, mkdtemp dá acesso só ao usuário atual, e a conta isolada não consegue gravar nessa pasta |
| Gravações fora das pastas permitidas | As pastas da instância, de trabalho e de instalação, e as pastas de data_roots |
Se um utilitário compartilhado falhar no isolamento, não contorne a falha no módulo. Informe a falha como um problema do daemon.
7. Modos de console
Por padrão, o daemon liga stdin e stdout do servidor por pipes ([launch] console = "pipe"). Alguns servidores funcionam de outro jeito quando stdin é um pipe:
- O Palworld guarda a saída até parar.
- O servidor do Terraria para Windows não lê entrada de um pipe. Ele não respondeu a comandos nem a
exit. O daemon o encerrou à força depois de 60 segundos, sem salvar.
Para esses servidores, defina [launch] console = "pty". O daemon então inicia o servidor em um pseudoconsole (Windows ConPTY, pty do Unix).
Um pseudoconsole mostra cada comando enviado. As quebras de linha também podem mudar. Em um pseudoconsole, o Terraria escreve o prompt : e Server started em linhas diferentes. Escreva seus padrões para os dois casos.
8. Padrões de console
Escreva os padrões de pronto, entrada, saída e parada só a partir de saída medida.
- Coloque os padrões de pronto, entrada e saída em
[extensions.saba-core](ready_patterns,player_join_patterns,player_leave_patterns). Coloque o padrão de parada em[detection] graceful_exit_patterns. - Ancore cada padrão no início e no fim da linha. Uma linha de chat com as mesmas palavras não pode combinar, por exemplo
<Server> Server started. - Se um prompt pode vir antes da mensagem, aceite-o com
^(?:<prompt>)?. - Se a configuração de idioma do servidor traduz uma mensagem, adicione a mensagem medida de cada idioma. Se você adicionar só o inglês, o daemon não vê o estado de pronto de um servidor configurado em outro idioma.
- Adicione um teste. As linhas medidas devem combinar com e sem o prompt. Uma linha de chat não deve combinar.
9. Instalação e arquivos de configuração
Instalação:
- Se o arquivo compactado tem uma pasta por sistema operacional, escolha a pasta pelo nome do sistema operacional. Não escolha pelo nome do executável, pelo tamanho do caminho nem pela primeira entrada. Se não encontrar nenhuma pasta ou encontrar mais de uma, devolva uma falha.
- Não substitua configurações nem mundos existentes. Extraia o arquivo de configuração de exemplo só quando não existir nenhum arquivo de configuração.
- Verifique cada arquivo baixado. Use o checksum oficial de cada binário. Se não houver checksum oficial, use HTTPS para um host oficial fixo, o CRC do arquivo compactado e a presença do executável esperado. Escreva "sem checksum oficial" e a fonte na tabela de pesquisa. Não invente um checksum e não use um checksum de fonte da comunidade.
Arquivos de configuração:
- Leia e grave o arquivo com a sintaxe oficial do formato. Por exemplo, arquivos Java
.propertiestêm os escapes\:e\=, e um\no fim da linha continua a linha. - Não suponha uma codificação. Leia o arquivo com a codificação real e grave-o de novo com a mesma codificação e as mesmas quebras de linha. O
serverconfig.txtdo Terraria para Windows usa cp1252 e tem o byte 0x92 em um comentário. Um módulo que só lê UTF-8 não consegue iniciar esse servidor, nem salvar ou importar as configurações. - Mude só as chaves que mudaram. Mantenha as outras chaves, os comentários e a ordem.
- Se não conseguir ler o arquivo, não o grave. Arquivo ausente, arquivo ilegível e arquivo que não pode ser interpretado são três casos diferentes.
10. Testes
Os testes unitários e o kit de conformidade rodam sem isolamento e com arquivos de exemplo. Eles não encontram problemas que só aparecem com o download real, no isolamento, em um modo de console ou no Windows. Faça os três níveis de testes.
10.1 Testes unitários
- Escreva em
test_lifecycle.pyum teste para cada função antes de escrever a função. - Rode o teste e confirme que ele falha.
- Escreva a função.
- Rode estas verificações:
saba-core module validate mygame
saba-core module audit mygame
pytest conformance --module path/to/mygame --shared-libs path/to/saba-chan/modules
10.2 Testes com o servidor real (antes de um pull request)
Depois da seção 4, chame as funções do módulo em uma pasta de servidor real.
- Rode
install_servercom o download real. Confirme que só os arquivos deste sistema operacional estão na pasta. - Inicie o servidor com o comando de
get_launch_command. Confirme que o padrão de pronto combina. - Envie cada modelo de comando. Confirme que o servidor o aceita.
- Envie o comando de parada. Confirme que o servidor salva e para.
- Compare os caminhos de
backup_pathsereset_servercom os arquivos que o servidor criou.
10.3 Testes em um PC real
Use a instalação normal do Saba-chan em um PC com Windows. Um módulo novo roda no isolamento, então este teste também encontra problemas de isolamento.
- Copie a pasta do módulo para
modules\<nome>\na pasta de dados do Saba-chan. - Rode
saba-chan-cli module refresh. - Rode
saba-chan-cli server add <servidor> -m <módulo>. - Inicie o servidor. Confirme que o Saba-chan mostra o estado de pronto.
- Envie comandos com
saba-chan-cli run <servidor> <comando>. Leia as respostas comsaba-chan-cli server console <servidor> --print. - Mude uma configuração e reinicie o servidor. Confirme que o servidor usa o novo valor.
- Crie um backup com
saba-chan-cli backup create <servidor>. Examine os arquivos do backup. - Pare o servidor. Confirme que o Saba-chan registra uma parada normal e que o mundo salvo está lá.
- Redefina o mundo. Veja quais arquivos foram apagados e quais ficaram.
Se [module.dependencies] saba-core pede uma versão ainda não publicada, a instalação normal não carrega o módulo. Faça o teste no PC depois que essa versão for publicada. Não diminua a versão da dependência.
11. Checklist antes de um pull request
-
RESEARCH.mdtem uma fonte para cada item, e cada fonte indica "documento" ou "medição". - Você examinou as entradas do arquivo compactado e os bytes originais dos arquivos padrão.
- Você rodou o servidor real e registrou a saída original, a saída de
helpe os arquivos depois de salvar. - Cada comando declarado está na saída de
help. - O servidor responde a comandos. Se não responder,
[launch] console = "pty"está definido. - Cada padrão de console vem de saída medida e aceita o prompt e cada tradução.
- Cada runtime é uma versão portátil fixa, e o módulo verifica os arquivos baixados.
- A instalação extrai só a pasta deste sistema operacional.
- O arquivo de configuração mantém a codificação e as quebras de linha.
- A redefinição do mundo apaga só os arquivos que o servidor criou, inclusive os backups dele.
- O módulo não usa
msiexec, um serviço do Windows, uma pasta demkdtempnem uma conexão loopback direta. - Você fez os testes com o servidor real e em um PC real, ou anotou cada teste que não pôde fazer.