Sagas PT

Sagas

As Sagas são uma extensão opcional que dá vida ao site com o que acontece dentro do jogo. Ela acrescenta quatro páginas: o mapa (/mapa/), as histórias (/historias/), a Armaria (/armaria/) e os rankings (/rankings/). A página inicial também passa a mostrar os momentos e feitos mais recentes. Os links dessas páginas ficam no menu do site, que você organiza em Layout Editor → Menu.

A captura usa dados de exemplo.

Como funciona

São duas peças que conversam:

• A ponte (HeimdallSagas.Bridge.dll) roda no servidor. Ela recebe o que os jogadores compartilham e calcula o mapa do mundo.
• O cliente (HeimdallSagas.Client.dll) roda no jogo de cada jogador. Ele envia só o que o próprio jogador autorizou.

Ninguém aparece no site sem ter escolhido aparecer. Esse é o princípio da extensão inteira.

Instalação

1. Instale primeiro o Heimdall Nexus e o BepInEx no servidor.

2. Na pasta do repositório, instale a ponte que vem com esta versão:

   cd ~/Heimdall-Nexus
   git switch main
   git pull --ff-only origin main
   sudo ./deploy/update.sh
   sudo ./deploy/install-sagas-extension.sh "$PWD/dist/sagas/HeimdallSagas.Bridge.dll"

   No Windows, use o PowerShell como administrador e o Valheim desligado:

   cd C:\HeimdallNexus-src
   & "$env:ProgramFiles\HeimdallNexus\venv\Scripts\python.exe" deploy\windows\install-sagas.py dist\sagas\HeimdallSagas.Bridge.dll

3. Reinicie o Valheim em Jarl → Console para carregar a ponte. O instalador não reinicia o jogo por conta própria.

4. Cada jogador que quiser participar baixa o cliente 0.2.1 e extrai o .zip na pasta do jogo. O arquivo deve ficar em BepInEx/plugins/HeimdallSagas/HeimdallSagas.Client.dll. Não misture: a ponte fica só no servidor, e o cliente, só no jogo do jogador.

5. Abra Jarl → Sagas e siga os cartões Para funcionar. Eles dizem o que falta em cada recurso. Ligue só o que você quiser; a coleta e as histórias têm opções separadas.

Privacidade dos jogadores

Cada jogador decide o que compartilhar na configuração do cliente, na seção Privacy. Tudo começa desligado.

Opção	O que o jogador autoriza
ShareProfile	Nome, presença e equipamento aparecendo no site. É a base das outras.
ShareMap	O bioma e o local dos momentos. Só aparece no site junto com ShareProfile.
SharePosition	A posição ao vivo no mapa, desde que o mapa público do próprio Valheim também esteja ligado.
ShareStories	Usar os fatos compartilhados para escrever capítulos. Exige ShareProfile.

Voltar atrás apaga de verdade. Desligar ShareProfile apaga os eventos guardados daquele viking; desligar ShareMap apaga as coordenadas e os biomas; desligar ShareStories apaga os capítulos que citam o viking. E a página pública confere o consentimento atual a cada leitura, então nada fica "preso" no site depois que o jogador muda de ideia.

Mapa

O mapa usa o estilo Birds Eye, desenhado a partir de camadas que a ponte calcula do mundo, com os tiles servidos pelo seu próprio servidor. Você escolhe quanto revelar:

• Terras conhecidas: mostra o terreno num raio de 700 m dos lugares que os jogadores compartilharam. O mapa vai se abrindo conforme eles exploram.
• Mundo inteiro: mostra tudo de uma vez. É bonito, mas estraga a surpresa da exploração.

A névoa individual do mapa de cada jogador ainda não é capturada. Enquanto ninguém tiver compartilhado nada, as páginas mostram um aviso explicando por que estão vazias, mesmo com tudo instalado.

Armaria

A Armaria é o perfil de cada viking, como uma ficha de personagem: um retrato 3D, o equipamento vestido com os ícones do próprio jogo (itens de mods incluídos), qualidade, durabilidade, atributos, efeitos e engastes de gemas, a barra de atalhos e os atributos vitais.

O cliente tira o retrato quando o viking está de pé no mundo, de novo quando a aparência ou o equipamento mudam, e sempre que o jogador aperta F9. Como tudo na Armaria, o retrato exige ShareProfile. Quem quiser ajustar a foto mexe na seção [Portrait] da configuração do cliente:

Opção	Padrão	O que faz
Enabled	ligado	Envia ou não o retrato.
RefreshKey	F9	Tira o retrato de novo na hora.
Ambient, KeyLight, FillLight	.62, .8, .35	Luz suave geral, luz principal e luz de preenchimento.
Reflection	.65	Brilho nas armaduras de metal.
FieldOfView	12	A lente da câmera; quanto menor, mais achatado.
CameraAngle	.2	O giro da câmera em volta do viking; 0 é de frente.

As imagens são conferidas e limpas no servidor antes de aparecer, e só ficam visíveis enquanto o jogador compartilha o perfil. Se preferir, você pode esconder o equipamento de todo mundo em Jarl → Sagas.

O fundo da página é a imagem /assets/armaria-bg.webp. Quer um fundo para cada bioma? Coloque imagens com os nomes /assets/armaria-<bioma>.webp, usando prados, floresta-negra, pantano, montanha, planicies, terras-nebulosas, terras-de-cinzas, extremo-norte ou oceano. A página usa o bioma do último momento que o viking compartilhou (isso depende do ShareMap); sem imagem para aquele bioma, fica o fundo padrão.

Rankings

Por enquanto, os rankings são um recorte dos últimos 100 momentos públicos: chefes derrotados, descobertas e abates. As regras da pontuação estão escritas na própria página. Rankings completos por período e troféus ainda estão nos planos.

Histórias com IA

Em Jarl → Sagas → Histórias, ligue o recurso, escolha o provedor (OpenRouter, OpenAI, Anthropic ou Gemini), guarde a chave da API e defina um limite diário. O botão Gerar história faz um teste com os fatos que já existem. Se você ligar a escrita automática, cada grande feito novo (um chefe derrotado, uma descoberta) pode virar um capítulo.

Um detalhe que confunde muita gente: a assinatura do site ou do app de um provedor normalmente não inclui crédito de API. A API tem cobrança e limites próprios, então confira na conta do provedor.

O Nexus envia ao provedor só os fatos selecionados e autorizados. A chave fica no servidor, nunca vai para o navegador nem para os logs. Todo capítulo público vem marcado como ficção criada por IA e mostra os registros reais que o inspiraram. Se faltar fato ou consentimento, o cartão Para funcionar diz qual é o próximo passo.

Atualizações e limites

As atualizações do Nexus, em Jarl → Sobre e atualizações, trocam sozinhas uma ponte já instalada; reinicie o Valheim depois para ela valer. O cliente, por outro lado, não se atualiza sozinho no computador dos jogadores: quando sair uma versão nova, cada um precisa baixar de novo.

Ainda estão na devroad: login individual, a névoa real de exploração, o replay da jornada, troféus e integrações mais profundas com mods. O número 1.0.0 é a versão do Nexus; as DLLs das Sagas têm versões próprias (ponte e cliente estão na 0.2.1).