You are viewing a potentially older version of this package. View all versions.
Northlight-ValheimLocationRestorer-0.3.0 icon

ValheimLocationRestorer

Restaura masmorras, ruinas e locais abandonados com os dados originais de geracao, protege bases por bandeiras e roda em ciclos de dias.

Date uploaded a day ago
Version 0.3.0
Download link Northlight-ValheimLocationRestorer-0.3.0.zip
Downloads 13
Dependency string Northlight-ValheimLocationRestorer-0.3.0

This mod requires the following mods to function

ValheimModding-Jotunn-2.30.2 icon
ValheimModding-Jotunn

Jötunn (/ˈjɔːtʊn/, 'giant'), the Valheim Library was created with the goal of making the lives of mod developers easier. It enables you to create mods for Valheim using an abstracted API so you can focus on the actual content creation.

Preferred version: 2.30.2
denikson-BepInExPack_Valheim-5.4.2360 icon
denikson-BepInExPack_Valheim

BepInEx pack for Valheim. Preconfigured with the correct entry point for mods and preferred defaults for the community.

Preferred version: 5.4.2360

README

Valheim Location Restorer 0.3.0

Restaura e reinicializa locais gerados naturalmente pelo mundo de Valheim — masmorras, ruínas, cabanas, acampamentos, fortificações, monumentos e estruturas costeiras — manualmente ou em ciclos automáticos, preservando construções de jogadores, respeitando áreas protegidas por bandeiras e com o servidor no controle em multiplayer.

Versão 0.3.0 (mesmo código da 0.2.0/0.2.1). Compilada contra o Valheim 1.0.21, BepInEx 5.4.23 e Jötunn 2.30.2. A restauração, a proteção e a recuperação foram testadas num servidor dedicado com mundos descartáveis (docs/TEST_REPORT.md). Ainda não testadas: o painel F8 num cliente e o multiplayer com clientes conectados. Faça backup do mundo e teste antes numa cópia.

Requisitos

Dependência Versão de referência
Valheim 1.0.21 (testado)
BepInExPack_Valheim (denikson) 5.4.2360
Jötunn (ValheimModding-Jotunn) 2.30.2
BepInEx Configuration Manager opcional (só a interface F1)

Instale no servidor e nos clientes administradores. Jogadores sem o mod conseguem entrar e recebem os avisos na tela (mensagem nativa do jogo), mas não têm o painel.

Instalação

  1. Instale o BepInExPack_Valheim e o Jötunn (r2modman/Thunderstore ou manual).
  2. Copie ValheimLocationRestorer.dll para BepInEx/plugins/Braian-ValheimLocationRestorer/.
  3. Inicie o jogo/servidor uma vez para gerar BepInEx/config/Braian.ValheimLocationRestorer.cfg.
  4. Ajuste as opções (arquivo ou F1). Referência completa: docs/CONFIGURATION.md.

Compilar

  1. Instale o .NET SDK 8 ou superior (compila net472 via Microsoft.NET.Sdk).
  2. Copie Environment.props.example para Environment.props e ajuste VALHEIM_INSTALL, BEPINEX_PATH e JOTUNN_DLL.
  3. dotnet build -c Release (ou ./build.ps1). Com DEPLOY_PATH definido, a DLL é copiada para o BepInEx automaticamente.
  4. Testes da lógica pura: dotnet test tests/ValheimLocationRestorer.Tests.
  5. Pacote Thunderstore: ./package-thunderstore.ps1 (gera o zip em package/build/).
  6. Testes no jogo (servidor dedicado, perfil isolado, mundos novos): ./run-integration-tests.ps1. Nada é copiado para a pasta do jogo.

Caminhos longos: se o projeto estiver numa pasta com caminho muito longo (mais de 260 caracteres somando obj\...), o compilador pode falhar sem mensagem. Use uma pasta curta ou subst X: <pasta>.

Como funciona

Restauração com dados originais

Cada local gerado tem no mundo um objeto de rede LocationProxy com o hash do local, a seed e a rotação de geração. O mod usa exatamente esses dados para chamar a rotina do próprio jogo (ZoneSystem.SpawnLocation). Se esses dados não existirem, o local não é restaurado e aparece como "Sem dados originais" — o mod nunca faz uma reconstrução aproximada.

Sequência de uma restauração:

  1. Validação com dados frescos: exclusão de boss, bandeiras, objetos de jogadores, jogadores presentes, servidor ocupado, intervalo mínimo, categoria e modo habilitados.
  2. O prefab do local é carregado antes de tocar no mundo. Se falhar, nada é alterado.
  3. No interior (a zona do local acima de y = 3000, onde o DungeonGenerator monta as salas) todo o conteúdo gerado é removido em lotes, assim como as criaturas dos spawners do local.
  4. O local é recriado com a seed e a rotação originais, pela mesma rotina da geração do jogo. As salas da masmorra saem idênticas, porque a seed delas vem da seed do mundo e da posição. Numa zona descarregada, o terreno é carregado temporariamente para os objetos assentarem no chão como na geração original.
  5. No exterior, cada objeto antigo só é substituído quando a recriação gera o gêmeo dele (mesmo prefab, mesmo lugar). Vegetação natural com o mesmo prefab não é apagada. Objetos recriados fora do plano, o LocationProxy novo e qualquer objeto recriado igual a um que ficou são descartados. Assim nada é duplicado.
  6. O novo estado vira a referência do local, entra no histórico e o diário de recuperação é limpo.

Modos

Modo O que faz
A — Completa Recria tudo (exterior e interior)
B — Estrutural Só estruturas e portas; baús, criaturas e recursos são preservados
C — Masmorra Só o interior da masmorra: layout de salas, portas, inimigos, baús, recursos
D — Personalizada Você escolhe as classes (estruturas, portas, baús, criaturas, recursos, layout, outros) e as regiões (exterior/interior)

O que nunca é tocado

  • Bosses (regra permanente no código): pedras de invocação, altares, locais de invocação e progressão (Eikthyr, The Elder, Bonemass, Moder, Yagluth, The Queen, Fader, StartTemple, Vegvisirs). O mod verifica por nome e por componente (OfferingBowl, BossStone, Vegvisir, ItemStand com poder de guardião), então locais renomeados ou de outros mods também são pegos. Mercadores e locais de missão (Haldor, Hildir, Bog Witch) também ficam de fora.
  • Objetos de jogadores: qualquer coisa com criador (peças, baús, portais, navios), animais domesticados, lápides e itens soltos dentro de masmorras. Com Protect Player Buildings ligado (padrão), um local com qualquer um desses objetos é ignorado inteiro.
  • Áreas de bandeira: qualquer bandeira do jogo colocada por um jogador protege um raio de 50 m. Se o local encostar no círculo, ele é excluído inteiro: o teste usa a área ocupada pelo local (o raio declarado ou o objeto mais distante, o que for maior), não só o centro. Masmorras são protegidas também pelo interior.
  • Locais não classificados (ex.: meteoritos, ninhos) nunca são restaurados automaticamente.

Ciclo automático (padrão)

  • Dia 1: início do ciclo.
  • Dias 2 a 8: funcionamento normal.
  • Dia 9: aviso a todos os jogadores conectados.
  • Dia 10: depois da virada do dia causada pelo sono, a restauração começa.
  • Dia 11: começa o próximo ciclo.

O mod nunca força o sono. Se ninguém dormir, ele espera a próxima virada válida. Locais com jogadores dentro (masmorras sempre) são adiados e tentados de novo a cada 60 s. Um mesmo local nunca é restaurado duas vezes no mesmo ciclo. Por padrão, a restauração automática só mexe em locais alterados desde a última verificação.

Uso

Painel (F8, somente administradores): lista por categoria, ordenada pela distância até você, com nome, bioma, coordenadas, distância, estado e proteção. Ver marca o local no mapa. Restaurar abre a escolha do modo e depois Confirmar. Também há a aba Histórico.

Console (F5):

vlr status
vlr list [Dungeons|Ruins|...|all] [página] [free] [texto]
vlr view <id>
vlr restore <id> [complete|structural|dungeon|custom:structures+doors[:exterior|interior|both]] [force]
vlr history [página]
vlr rescan [id|all]
vlr banners
vlr ui

Restaurar e rescan exigem estar no adminlist.txt do servidor, verificado pela conexão do jogador, que não pode ser forjada. force ignora só o intervalo mínimo por local e nunca as regras de segurança.

Arquivos que o mod cria (no servidor)

BepInEx/config/Braian.ValheimLocationRestorer.cfg
BepInEx/config/Braian.ValheimLocationRestorer.categories.txt   (regras de categoria opcionais)
BepInEx/config/Braian.ValheimLocationRestorer/worlds/<mundo>_<uid>/
    state.json     ciclo, bandeiras registradas, referências por local
    history.json   histórico de operações
    journal.json   diário de recuperação da operação em andamento

Todas as gravações são atômicas e mantêm um .bak.

Limitações conhecidas

Veja docs/IMPLEMENTATION_REPORT.md (seção Limitações). As principais:

  • Alterações de terreno (escavação/aplainamento) não são revertidas.
  • A detecção de "local alterado" usa uma impressão digital dos objetos. Criaturas não entram nela, então matar inimigos de uma masmorra sem mexer em baús, portas ou estruturas não a marca como alterada. Use o modo manual ou desligue Only Restore Modified Locations.
  • Sem os dados originais (LocationProxy), o local não é restaurado.

Faça backup do mundo antes de usar. O Valheim guarda backups em worlds_local.

Dependências e créditos

Este mod requer as seguintes dependências, declaradas no manifest.json e instaladas pelo gerenciador de mods:

  • BepInExPack Valheim — framework de plugins.
  • Jötunn — biblioteca de modding para Valheim.

Créditos: BepInEx, Jötunn e equipe NorthLight.

CHANGELOG

Changelog

0.3.0 — 17/11/2026

  • Nova versão de publicação no Thunderstore (a 0.2.1 já existia com o mesmo namespace/nome/versão).
  • Nenhuma alteração de código ou de comportamento em relação à 0.2.1.
  • Servidor e clientes precisam usar a 0.3.0 juntos: a verificação de versão do Jötunn compara major.minor.

0.2.1 — 17/11/2026

  • Atualização de versão para publicação, com novo ícone e créditos no README.
  • Nenhuma alteração de comportamento do mod em relação à 0.2.0.

0.2.0 — 17/11/2026

Correções feitas contra a API real do Valheim 1.0.21 (assembly descompilado), compiladas e validadas em testes de integração num servidor dedicado (veja docs/TEST_REPORT.md). A versão sobe para 0.2.0 porque o protocolo de rede mudou: servidor e clientes administradores precisam da mesma versão.

Erros que impediam o mod de funcionar

  • Não compilava: ZoneLocation.m_hash não existe (é ZoneLocation.Hash); ZRoutedRpc.GetServerPeerID é privado; NetworkManager ambíguo com o do Jötunn; faltava a referência SoftReferenceableAssets.dll.
  • Zonas Vector2s: o jogo usa Vector2s (antes Vector2i). O catálogo lia m_locationInstances como Dictionary<Vector2i, …> e ficava sempre vazio.
  • Busca de objetos só no setor central: FindSectorObjects recebia um SimulationDistance vazio. Objetos fora do setor central não eram removidos, não entravam na checagem de duplicatas e não contavam para a proteção.
  • Catálogo vazio em mundo novo: o catálogo era montado antes de o jogo terminar de posicionar os locais. Agora espera ZoneSystem.LocationsGenerated.
  • Persistência perdida no servidor dedicado: JsonUtility gravava {} para ciclo, bandeiras, estado dos locais, histórico e diário de recuperação. Foi trocado pelo MiniJson (testado; lê os arquivos da 0.1.x).
  • Rotação original perdida após reiniciar: ao salvar o mundo, o jogo trunca a rotação dos ZDOs para 0,5° (ZPackage.WriteSmallRotation). Depois de um reinício, a masmorra era recriada ~9 cm deslocada e com outras salas, porque a seed do DungeonGenerator vem da posição. Agora a rotação de geração exata (passos de 22,5°) é recuperada do proxy (Logic/RotationMath, testado).
  • Restauração de zona descarregada com altura errada: SnapToGround mede a altura por raycast no terreno. Agora o terreno da zona é instanciado temporariamente, como na geração vanilla.

Masmorras

  • O interior agora é a zona do próprio local acima de y = 3000 (Character.InInterior). Antes era um raio em volta da entrada, a partir de 4000 m, que perdia objetos e falhava nas masmorras com interior deslocado (Mistlands). As salas são recriadas de forma determinística pelo DungeonGenerator. Os testes confirmaram os dados de salas idênticos byte a byte.
  • Captura exata de tudo o que a recriação gera (postfix em ZDOMan.CreateNewZDO), inclusive portas e objetos das salas.

Segurança e preservação

  • Exterior por substituição: um objeto antigo só é removido quando a recriação gera o gêmeo dele no mesmo lugar. Árvores e pedras naturais com o mesmo prefab do local deixaram de ser apagadas.
  • Itens soltos, lápides (componente TombStone) e prefabs desconhecidos nunca são apagados, inclusive no exterior.
  • Pedras rúnicas que revelam locais no mapa entram nas exclusões permanentes de progressão.
  • Duplicatas comparadas na horizontal (35 cm, tolerância vertical de 2,5 m; 2 m para itens soltos).
  • Recuperação: na retomada, remove o LocationProxy extra e as cópias deixadas por uma execução interrompida.

Multiplayer

  • Pedidos chegam pela conexão do próprio jogador (ZRpc). Antes vinham por ZRoutedRpc, cujo remetente pode ser forjado pelo cliente. A verificação de admin usa ZNet.IsAdmin(host).
  • Restaurar e forçar varredura sempre exigem administrador. Validate Server Permissions agora controla só a leitura.
  • Os comandos vlr list e vlr history voltam a imprimir no console. Antes a resposta ia só para o painel, mesmo fechado.

Ciclo

  • A espera pelo sono passou a valer a manhã alcançada pelo sono (EnvMan.SkipToMorning concluído). A janela de 180 s falhava quando os jogadores dormiam depois da meia-noite. O mod continua sem nunca forçar o sono.

0.1.0 — 14/11/2026

Primeira versão (não compilada nem testada no jogo).