thnbi · Oct 15, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 28, 2026
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -0,0 +1,87 @@
+# shōbu
+
+FPS de sniper PvP no navegador, com servidor autoritativo. Este glossário fixa os nomes que o
+código, os documentos e as conversas usam para as mesmas coisas.
+
+## Partida
+
+**Sala**:
+O grupo de jogadores conectados juntos ao servidor de jogo. Dura várias partidas seguidas, e
+quem chega entra na sala mesmo com uma partida em andamento.
+_Evitar_: room, lobby
+
+**Matchmaking**:
+O pareamento de jogadores pela URL: quem abre o mesmo endereço da sala joga junto. Põe o jogador
+na sala do endereço, cria a sala se ela não existe, ou o põe na fila da sala se ela está cheia.
+Não pareia por habilidade.
+_Evitar_: lobby, alocação de sala
+
+**Endereço da sala**:
+O identificador de uma sala, escrito como um endereço IPv4 fictício no caminho da URL
+(`/203.0.113.7`). Não tem relação com o endereço real de nenhuma máquina. Os gerados evitam as
+faixas privadas e reservadas; um endereço digitado vale em qualquer faixa, e abrir um endereço
+sem sala cria a sala. Cada octeto vai de 0 a 255, sem zeros à esquerda: `10.0.0.07` é a sala
+`10.0.0.7`.
+_Evitar_: código da sala, IP da sala, room id
+
+**Fila da sala**:
+Os jogadores que abriram o endereço de uma sala cheia e esperam vaga nela, por ordem de chegada.
+Quem está na fila joga numa sala provisória até a vaga abrir.
+_Evitar_: lobby, espera
+
+**Sala provisória**:
+Uma sala comum com vaga, onde um jogador da fila joga enquanto espera. A URL mostra o endereço
+dela, não o da sala pedida. Quem espera pela mesma sala pode estar em salas provisórias
+diferentes. Quando abre vaga na sala pedida, o jogador é levado para lá, mesmo no meio de uma
+partida, e a URL muda.
+_Evitar_: sala temporária, overflow
+
+**Partida**:
+Uma rodada de 5 minutos dentro de uma sala. Quem entra na sala durante a partida joga o tempo
+que resta dela.
+_Evitar_: match, round, sala
+
+**Sala de voz**:
+O canal de voz de uma sala. Existe enquanto a sala existe e atravessa as partidas.
+_Evitar_: room de voz
+
+## Simulação
+
+**Tick**:
+A unidade fixa de tempo em que o estado da partida avança, igual no cliente e no servidor.
+_Evitar_: passo, frame, quadro
+
+**Snapshot**:
+O estado completo da partida num tick.
+_Evitar_: estado, frame
+
+**Patch de estado**:
+A diferença entre dois snapshots, que é o que o servidor de jogo envia aos clientes.
+_Evitar_: delta snapshot, update
+
+**Input**:
+O que um jogador comanda num tick: movimento, mira e botões.
+_Evitar_: comando
+
+## Rede
+
+**Servidor de jogo**:
+Única autoridade da partida: simula, valida cada disparo e decide quem está em cada sala.
+_Evitar_: servidor Colyseus, host
+
+**Servidor de mídia**:
+Repassa o áudio de voz entre os jogadores de uma mesma sala, sem entender o jogo.
+_Evitar_: SFU de voz, servidor de voz
+
+**Cliente de jogo**:
+A parte do navegador que troca input e patches de estado com o servidor de jogo.
+
+**Cliente de voz**:
+A parte do navegador que troca sinalização e áudio com o servidor de mídia.
+
+**Sinalização**:
+Troca de controle que abre, mantém e fecha a conexão de voz, separada do áudio.
+
+**Fluxo de áudio**:
+O áudio de um jogador enquanto ele fala. Existe um por jogador falando.
+_Evitar_: locutor
diff --git a/README.md b/README.md
@@ -9,6 +9,7 @@
 ```bash
 npm install
 npm run dev          # vite em http://localhost:5173
+npm run dev --workspace @shobu/server   # servidor de jogo em :2567; reinicia a cada edição, núcleo incluso
 npm test             # vitest headless, sem navegador
 npm run typecheck    # tsc sem emitir, nos dois pacotes
 npm run lint         # biome

diff --git a/config/gameplay.json b/config/gameplay.json
@@ -1,7 +1,7 @@
 {
   "simulation": {
     "tickHz": 60,
-    "snapshotHz": 30,
+    "patchHz": 60,
     "inputSendHz": 60
   },
   "movement": {
@@ -143,5 +143,9 @@
     "airborneErrorDeg": 5,
     "flinchErrorDeg": 4,
     "meleeReactionS": 0.3
+  },
+  "voice": {
+    "fullVolumeRadiusM": 10,
+    "silentRadiusM": 45
   }
 }
diff --git a/docs/adr/0002-transporte-de-rede.md b/docs/adr/0002-transporte-de-rede.md
@@ -1,6 +1,13 @@
 # ADR 0002 — transporte de rede e framework de sincronização
 
-- **status**: aceita
+- **status**: aceita. o transporte foi reavaliado e mantido na [adr 0025](0025-websocket-sem-udp.md),
+  o tamanho de sala foi revisto na [adr 0027](0027-sala-de-quatro.md), a condição de medição
+  foi fixada na [adr 0006](0006-condicao-de-rede-do-aceite.md), e as taxas de rede atuais estão
+  em [docs/rede](../rede/arquitetura-de-rede.md).
+  a versão pinada também foi revista em 2026-09-28: a linha 0.18 virou a estável, e os pacotes do
+  colyseus têm versões independentes, então `0.18.2` em todos não forma um conjunto válido. o
+  pino exato passou a ser `@colyseus/core` 0.18.17, `@colyseus/ws-transport` 0.18.4,
+  `@colyseus/sdk` 0.18.4 e `@colyseus/schema` 5.0.34, sem o meta-pacote `colyseus`.
 - **data**: 2026-08-18
 - **decidem**: renato, nicolas
 

diff --git a/docs/adr/0003-fisica-e-controlador.md b/docs/adr/0003-fisica-e-controlador.md
@@ -60,7 +60,7 @@ controlador de personagem baseado em havok, já pronto na engine.
   com **sub-passo por deslocamento**: quando o movimento no tick passa de uma fração do raio da
   cápsula, o passo é dividido, e o número de sub-passos é o deslocamento dividido por esse
   limite. as mecânicas rápidas (puxão do gancho, queda perto da terminal) caem nesse caso a
-  60 Hz, e é isso, e não tick rate maior, que impede atravessar parede fina.
+  64 Hz, e é isso, e não tick rate maior, que impede atravessar parede fina.
 - **o havok fica reservado** a prop, ragdoll, destroço e qualquer coisa que não afete a
   autoridade nem a predição.
 - **hitscan é raycast no servidor**, contra as cápsulas dos jogadores rebobinadas para o

diff --git a/docs/adr/0006-condicao-de-rede-do-aceite.md b/docs/adr/0006-condicao-de-rede-do-aceite.md
@@ -0,0 +1,24 @@
+# ADR 0006 — condição de rede em que o aceite é medido
+
+- **status**: aceita
+- **data**: 2026-09-28
+- **decide**: renato
+
+o critério de aceite do [nfr.md](../nfr.md), p99 do erro posicional abaixo de 0,10 m, não dizia
+em que rede é medido, e a rede da mesa da equipe é otimista. medimos em três perfis
+emulados no servidor, e o aceite vale no perfil **wi-fi congestionado**. os outros dois são
+relatados junto, para mostrar como o jogo degrada.
+
+| perfil | rtt | perda, por direção |
+|---|---|---|
+| lan ideal | o da rede do estande, sem emulação | a da rede |
+| **wi-fi congestionado** | 10 ± 5 ms | 1%, aleatória |
+| pior caso | 30 ± 10 ms | 3%, em rajadas de 3 pacotes em média |
+
+## consequências
+
+- a emulação roda no servidor, nas duas direções, com `tc netem` na saída e uma interface `ifb`
+  na entrada. os comandos, o modelo de perda em rajada e as grandezas registradas em cada rodada
+  estão em [docs/rede](../rede/arquitetura-de-rede.md).
+- o jitter do netem reordena pacotes. o tcp absorve a reordenação, mas ela pesa na medição, e o
+  relatório declara isso.
diff --git a/docs/adr/0025-websocket-sem-udp.md b/docs/adr/0025-websocket-sem-udp.md
@@ -0,0 +1,28 @@
+# ADR 0025 — websocket mantido, sem udp
+
+- **status**: aceita
+- **data**: 2026-09-22
+- **decide**: renato
+
+a rede da feira bloqueia udp, e no navegador todo transporte com datagrama depende dele:
+webtransport não conecta, e webrtc cai para tcp. reavaliamos a [adr 0002](0002-transporte-de-rede.md)
+e mantemos websocket direto entre cliente de jogo e servidor de jogo, porque sobre tcp é o caminho
+com menos camadas e menos saltos. o ponto fraco do tcp é a perda de pacote, e por isso o estande
+tem rede própria. o detalhe de rede está em [docs/rede](../rede/arquitetura-de-rede.md).
+
+## opções descartadas
+
+- **quic, pelo `@colyseus/h3-transport`**: não conecta sem udp e não cai sozinho para tcp. o
+  próprio colyseus declara esse transporte instável.
+- **webrtc com sfu (livekit)**: sem udp, a mídia vai por ice-tcp e o head-of-line blocking volta,
+  com mais camadas. o sfu não entende o jogo, então o servidor de jogo entra como participante e
+  cada mensagem ganha um salto. e sai do colyseus, com o netcode escrito à mão.
+- **p2p**: ninguém tem autoridade sobre o acerto. um jogador vira host, com vantagem e chance de
+  trapaça, ou o cliente afirma o acerto, que a adr 0002 proíbe.
+- **mqtt**: pub/sub de iot sobre websocket, com um broker no meio e sem sala, estado nem rewind.
+
+## revisão
+
+o transporte fica atrás de uma interface do projeto. se a rede da feira liberar udp, o quic volta
+a ser candidato sem reescrever o jogo. reabrir também se o critério do [nfr.md](../nfr.md) falhar
+com perda de pacote simulada.
diff --git a/docs/adr/0026-chat-de-voz.md b/docs/adr/0026-chat-de-voz.md
@@ -0,0 +1,34 @@
+# ADR 0026 — chat de voz por livekit, ao lado do colyseus
+
+- **status**: aceita
+- **data**: 2026-09-23
+- **decide**: renato
+
+voz precisa de cancelamento de eco, supressão de ruído, codec de voz, jitter buffer e ocultação
+de perda, e aceita atraso e perda que o tiro não aceita. usamos um servidor de mídia livekit na
+rede do estande, ao lado do servidor de jogo. o webrtc do navegador já faz o tratamento de áudio,
+e o livekit só repassa os fluxos de áudio, sem entender o jogo. nenhum dado de jogo passa por
+ele. o detalhe de rede está em [docs/rede](../rede/arquitetura-de-rede.md).
+
+## opções descartadas
+
+- **voz pelo websocket do jogo**: tratamento de áudio escrito à mão, e sobre tcp um pacote
+  perdido congela o áudio em vez de ser disfarçado. o áudio ainda disputaria banda com o jogo.
+- **webrtc p2p em malha**: sinalização e ice escritos à mão, e cada jogador envia uma cópia da
+  voz para cada outro.
+
+## consequências
+
+- o servidor de jogo decide quem está na sala de voz: ele emite o token de acesso quando o
+  jogador entra na sala e o remove quando ele sai.
+- o navegador só libera o microfone em https, então a página e o canal de jogo também passam a
+  exigir tls, com certificado válido na rede do estande.
+- a voz por proximidade é calculada no cliente, com as posições que o servidor de jogo já envia.
+  um cliente adulterado pode ouvir quem está longe. se isso importar, o servidor de jogo passa a
+  decidir quem ouve quem.
+- a voz é o primeiro corte se a data apertar, e o jogo roda inteiro com ela desligada.
+
+## revisão
+
+reabrir se o servidor de mídia não passar pela rede do estande, se o áudio pesar no quadro, ou
+se jogar lado a lado no estande tornar a voz desnecessária.
diff --git a/docs/adr/0027-sala-de-quatro.md b/docs/adr/0027-sala-de-quatro.md
@@ -0,0 +1,18 @@
+# ADR 0027 — sala de quatro jogadores
+
+- **status**: aceita
+- **data**: 2026-09-28
+- **decide**: renato
+
+o [gdd](../gdd.md) previa oito jogadores por sala. reduzimos para quatro. com patches de estado a
+64 hz, cada jogador a mais aumenta o histórico de rewind, a cpu de cada tick e a banda de descida
+de todos os clientes, porque o patch cresce com o número de jogadores. a arquitetura de rede não
+depende desse número: o orçamento em [docs/rede](../rede/arquitetura-de-rede.md) está em função
+de N.
+
+## consequências
+
+- o gdd e o [nfr.md](../nfr.md) mudam de oito para quatro.
+- o item 4 da fila de corte da [adr 0002](0002-transporte-de-rede.md), reduzir para quatro
+  jogadores, deixa de existir porque já foi aplicado.
+- o level design, pensado para oito, precisa ser revisto para o mapa não ficar vazio.
diff --git a/docs/adr/0028-endereco-da-sala.md b/docs/adr/0028-endereco-da-sala.md
@@ -0,0 +1,28 @@
+# ADR 0028 — endereço da sala em formato ipv4, com fila e sala provisória
+
+- **status**: aceita
+- **data**: 2026-09-28
+- **decide**: renato
+
+cada sala é identificada por um endereço ipv4 fictício no caminho da url, como
+`shobu.com/203.0.113.7`. abrir um endereço sem sala cria a sala, e os endereços gerados evitam as
+faixas privadas e reservadas para não se confundir com os ips reais da rede do estande. quem abre
+o endereço de uma sala cheia entra na fila dela e joga numa sala provisória até a vaga abrir. os
+termos estão definidos no [CONTEXT.md](../../CONTEXT.md).
+
+## opções descartadas
+
+- **código curto alfanumérico**: funciona igual, mas perde a identidade de rede do jogo.
+- **esperar vaga parado**: contradiz o pilar 2 ([pillars.md](../pillars.md)), que exige controle
+  do personagem em menos de cinco segundos depois do clique no link.
+- **mandar para outra sala sem fila**: cumpre o pilar, mas separa quem abriu o link de quem o
+  mandou.
+
+## consequências
+
+- o id de sala do colyseus só aceita letras, números, `_` e `-`, então o servidor de jogo mantém
+  um mapa de endereço para sala.
+- um caminho com ponto, como `/203.0.113.7`, costuma ser tratado como arquivo pelo servidor de
+  página. a rota precisa devolver a página para esses caminhos.
+- ir da sala provisória para a pedida é sair e entrar de novo no servidor de jogo e no servidor
+  de mídia, no meio de uma partida.
diff --git a/docs/gdd.md b/docs/gdd.md
@@ -104,7 +104,7 @@ o loop é: nascer, buscar linha de tiro, matar ou morrer, voltar. kill vale 100
 
 cada mapa do catálogo segue a mesma planta: sem paredes em volta — a cidade continua além dele — e cada um tem três camadas: becos embaixo (distância curta), passarelas no meio (rota principal de trânsito, uso mais frequente do gancho), telhados em cima (linhas de tiro longas, jogador exposto). cada camada tem pelo menos duas rotas de subida que não exigem gancho, e toda linha de tiro longa tem cobertura intermediária. oito pontos de spawn distribuídos pelas três camadas. o que delimita a partida é a área de jogo, um retângulo no chão do tamanho do piso da arena: quem sai dela vê na tela o aviso "VOLTE PARA A ARENA" com uma contagem de cinco segundos, e se não voltar a tempo morre e reaparece num spawn. voltar zera a contagem.
 
-o escopo entregável é um catálogo de dois mapas, um personagem, um sniper, uma faca, um gancho e um modo, para até quatro jogadores. os mapas são o Neon-kaidō, rua-cânion cyberpunk de noite e o padrão, e o Ichiban-gai, na hora azul ([adr 0023](adr/0023-catalogo-de-mapas-e-neon-kaido.md)). fora do escopo entregável: voip, times, mapas além desses dois, progressão, loja funcional, matchmaking por habilidade e anti-cheat. voip entra como expansão, depois da base jogável.
+o escopo entregável é um catálogo de dois mapas, um personagem, um sniper, uma faca, um gancho e um modo, para até quatro jogadores. os mapas são o Neon-kaidō, rua-cânion cyberpunk de noite e o padrão, e o Ichiban-gai, na hora azul ([adr 0023](adr/0023-catalogo-de-mapas-e-neon-kaido.md)). a voz por proximidade entre os jogadores da sala também entra, construída depois da base jogável e primeira a ser cortada se a data apertar ([adr 0026](adr/0026-chat-de-voz.md)). fora do escopo entregável: times, mapas além desses dois, progressão, loja funcional, matchmaking por habilidade e anti-cheat.
 
 # What sets this project apart?
   - roda no navegador, sem instalação e sem conta obrigatória
@@ -162,7 +162,7 @@ até quatro jogadores em free-for-all livre de cinco minutos numa arena vertical
   - feedback de tiro: hitmarker no acerto, zunido de bala no quase-acerto.
   - fim de partida ([adr 0022](adr/0022-fim-de-partida-mvp-e-voto.md)): o relógio zera e a arena congela — ninguém anda, atira nem pontua, a luneta fecha —, e o narrador diz o fim por três segundos. depois, dez segundos de tela de mvp: o nome e a skin do melhor jogador da partida (o corpo dele num pódio de neon sobre o mapa, e o retrato no cartão), os números dele — pontos, abates, mortes, melhor sequência e medalhas — e o placar final da sala. o mvp é quem tem mais pontos; o desempate é mais abates, depois menos mortes, depois quem chegou antes aos pontos. no óculos, a mesma tela no visor, com o retrato.
   - voto do próximo mapa: durante os dez segundos da tela de mvp, os mapas do catálogo e aleatório. vota-se pelo número (1, 2, 3), pelas setas e enter, pelo mouse (mexer anda o foco, o clique vota), pelo d-pad e A no controle, ou tocando na opção. os bots votam também, cada um uma vez, da semente da partida, e o voto deles aparece chegando, com o nome. vence a maioria; empate é sorteio da semente entre os empatados; aleatório vencendo sorteia um mapa. o mapa vencedor fica na tela por um segundo e meio, e a partida seguinte começa sozinha: no mesmo mapa, na hora, com placar, relógio, medalhas e spawns zerados; em outro, a página recarrega no mapa novo e um clique (ou enter, ou A) entra direto, com as mesmas regras. esc ou B na tela de mvp voltam ao menu. saída fechando a aba.
-  - fora do escopo entregável: voip, times, modos alternativos, mapas além dos dois do catálogo ([adr 0023](adr/0023-catalogo-de-mapas-e-neon-kaido.md)), progressão, loja funcional, matchmaking por habilidade, anti-cheat.
+  - fora do escopo entregável: times, modos alternativos, mapas além dos dois do catálogo ([adr 0023](adr/0023-catalogo-de-mapas-e-neon-kaido.md)), progressão, loja funcional, matchmaking por habilidade, anti-cheat.
 
 # Assets Needed
 
@@ -224,7 +224,7 @@ a equipe não tem especialista em arte. a maior parte dos assets vem de pacotes
   - Ambient Scripts (Runs in the background)
     - servidor autoritativo: estado da sala, validação de disparo, respawn, cronômetro, placar
     - sincronização de estado entre servidor e clientes
-    - lobby: entrada por link, apelido, alocação em sala de até quatro jogadores
+    - matchmaking: pareamento pelo endereço da sala na url ([adr 0028](adr/0028-endereco-da-sala.md)), nome de perfil, salas de até quatro jogadores
     - killfeed, placar e transição de fim de partida
   - NPC Scripts
     - bots completam a sala quando faltam jogadores ([adr 0016](adr/0016-bots-no-nucleo.md)): andam pelo mapa com a mesma física, atiram com a mesma arma e pontuam pelo mesmo placar. dificuldade em `config/gameplay.json`, seção `bots`. no treino, andam sem atirar.
@@ -259,7 +259,7 @@ a equipe não tem especialista em arte. a maior parte dos assets vem de pacotes
       - implementação do cliente, 13/10
   - expansões e feira
     - Time Scale: 13/10 a 19/11
-      - expansão 1, voip aberto, 20/10 e 27/10
+      - expansão 1, voz por proximidade, 20/10 e 27/10
       - expansão 2, a definir, 03/11 e 10/11
       - integração com a feira de jogos, 17/11
       - feira de jogos, 19/11