Viking Codex

v1.0.0 initial release - multiplayer verification and complete biome classification remain pending.

One Valheim plugin combining a progression-aware Codex with server-wide cooperative material discovery. It shares knowledge through native character registration. It does not add inventory items, change crafting costs, or remove station requirements.

Install when ready

Finish your current game session before installing. Use a separate test profile and backed-up disposable characters/worlds initially.

1. Install BepInExPack_Valheim 5.4.2351 and Jötunn 2.30.2 or compatible versions.
2. Extract the Manual ZIP and copy its VikingCodex folder into your game's or mod profile's BepInEx/plugins/ directory.
3. Install the same Viking Codex version on the server and every client, then start the modded game normally.
4. Press F8 or open inventory and select Codex.

No default configuration changes are needed. The optional installer scripts copy only this plugin and back up an existing VikingCodex.dll. They do not install dependencies. Do not install RuntimeProbe.dll, .references, .tools or .runtime into a play profile.

The Thunderstore-format ZIP declares both dependencies. Local ZIP import, mod-manager installation, and public distribution remain pending actual installation testing. There is no published Viking Codex listing yet.

Implemented features

• Native-styled independent Codex panel, Escape/Close, keyboard navigation, virtualized scrolling, scaling, search, combined biome/category/discovery filters and progression/alphabetical sorting.
• Unknown-name/detail protection with dark icon silhouettes, calculated discovery/recipe completion, crafting and building requirements, alternative recipes and known recipe relationships.
• Asset-backed vanilla registry plus dynamic modded detection. Baseline: 2,369 item/creature/piece asset records and 481 recipe asset records from the installed Valheim 1.0.20 bundle. These are source inventory counts, not displayed in-game totals. Iconless NPC attack items are excluded from Codex pages; actual entries must also be registered in the live game.
• Versioned character-bound sharing protocol, server validation/rate limits, duplicate protection, offline catch-up, bounded per-frame native application, explicit existing-knowledge import, and world-specific atomic/checksummed history with backups.
• Independent Codex/sharing settings, synchronized server options, local UI settings, optional intentional Wiki actions, external metadata, catalog reload/export and diagnostics.

Curated seeds, native spawn-biome flags, explicit biome asset paths and verified recipe/drop/conversion relationships supply progression metadata. Unresolved entries stay Unclassified. Derived ordering and newly added content still need gameplay review; metadata never changes native prerequisites.

Configuration

BepInEx/config/com.vikingcodex.cfg is created on first plugin load. Server defaults enable eligible-material sharing and offline catch-up; existing-knowledge import is off. Client defaults enable Codex, spoiler protection, unknown placeholders and Wiki actions. Inventory-button visibility and offset can be adjusted for UI mods.

See docs/CONFIGURATION.md, docs/USER-GUIDE.md, docs/SERVER.md and docs/TROUBLESHOOTING.md.

Build and verification

Build/API baseline: Valheim 1.0.20, Unity 6000.0.75f1, BepInExPack 5.4.2351 (loader 5.4.23.5), Jötunn 2.30.2, .NET SDK 8.0.426. Game/dependency DLLs are private compilation references and never included in packages.

The plugin compiles and 65 automated checks pass. Multi-client scenarios exercise the same core used by the runtime adapter through the real packet codec, but they are simulations, not actual Valheim multiplayer tests. The user confirmed the earlier build opens in-game; the latest UI changes and actual multiplayer acceptance remain pending. See docs/RELEASE-VERIFICATION.md for remaining acceptance.

Populate .references from your own installation with scripts/collect-references.ps1, then run scripts/build.ps1 (or bash scripts/build.sh with a .NET SDK). Package with python scripts/package.py. Production packaging is blocked until all 24 runtime acceptance criteria have evidence and release metadata is finalized.

1.0.0 features and known limitations

Item and recipe rows are combined. Biome selectors show progress. Recipe details flag missing materials and station requirements. Session discoveries are marked NEW until viewed. All peers must have the same plugin version, including when sharing is disabled.

The static asset audit found no missing metadata IDs or enabled recipes without visible output items. 843 visible asset records remain Unclassified; full gameplay coverage and biome correctness are not verified. See docs/CATALOG-AUDIT.md.

AI disclosure

Code and documentation were generated with assistance from OpenAI Codex under the project owner's direction. Select the AI Generated category when publishing this package.

1.0.8

• Finalized the stable full release README with complete feature coverage and consistent JustQOL branding.

• Finalize the stable-release README, feature descriptions, installation instructions, dependency information, and support details.

• Clarify session-only contributions, joining-player catch-up, base-game scope, and preserved crafting restrictions.

• Record successful dedicated-server operation reported by the author.

• Correct outdated version and Unclassified-filter wording. No gameplay changes from 1.0.7.

1.0.7

• Give packaged files a deterministic, release-specific timestamp instead of reusing one timestamp across every release. This prevents different releases having identical packaged DLL timestamps.
• Correct outdated README version instructions and document safe upgrades.
• Clean-profile upgrade behavior still requires in-game verification.

1.0.6 candidate

• Remove bulk character-knowledge import, including when legacy configs enable it.
• Observe repeated native item registrations so already-known item encounters can contribute to the server.
• Expand vanilla eligibility to collectible item entries with native icons; retain metadata denial and modded opt-in.
• Add packet/application counters to status and log malformed packets plus durable server commits.
• Preserve existing server history and normal crafting requirements.
• Dedicated-server gameplay verification remains pending. Not installed or published automatically.

1.0.5

• Add a native Viking Codex main-menu button above Viking Revival and Viking Meals.
• Add a main-menu guide to controls, discovery clues and biome checklists.
• Keep the existing in-game Codex and sharing behavior.

1.0.4

• Give hidden entries discovery clues in the list and detail panel; 165 verified base-game entries have specific clues, with gameplay-type clues for the rest.
• Search discovery clues while keeping undiscovered names and recipe details hidden.
• Show a biome checklist percentage and remaining count that stay stable while searching or filtering categories. Empty biomes do not claim 100% completion.
• Include base-game identities only, even when old configs enabled modded detection. Keep discovery sharing behavior unchanged for eligible base-game materials.
• Expose Unclassified entries separately and clarify that catalog and biome coverage still need review.
• Add the permanent JustQOL Valheim Mods Discord support invite.
• Build and automated verification completed; graphical and live multiplayer acceptance of this update remain pending.

1.0.3

• Replace Unity catalog JSON loading with the game-provided Newtonsoft.Json parser and reject empty embedded catalogs.
• Show All followed by named biomes, without Unclassified or progress text in the selector.
• Runtime verification of catalog loading fix remains pending.

1.0.2

• Enable existing eligible material knowledge import by default. Existing server configs retain their saved value; set ImportExistingDiscoveries=true to enable import after upgrading.
• Update the README to describe automatic existing-knowledge import.

1.0.1

• Enable import of existing eligible character material knowledge by default. Existing configs retain their saved setting.

• Rewrite the README with feature descriptions, usage instructions, dependencies, dedicated-server testing feedback, and Discord support contact.

• Combine the Astra credit and AI disclosure; remove text artwork.

1.0.0 initial release

• Label hidden creature entries as ??? - Creature instead of showing a generic placeholder icon.

• Triple wheel scroll speed; place discovered entries first in All view.

• Provide a generic codex-page icon when native icons are missing.

• Keep selected biome progress on one line; diagnostic exports report icon availability.

• Fix oversized scrollbar handle by clearing the default Unity RectTransform dimensions. Scrolling behavior unchanged.

• In-game visual verification of this fix remains pending.

• Updated plugin and package version to 1.0.0.

• Includes combined item/recipe rows, biome progress, silhouettes and scrolling improvements.

• Build and 65 automated checks pass. Actual multiplayer acceptance remains pending.

• 843 visible asset records remain Unclassified.

0.2.2 development

• Merge item/recipe rows; preserve recipe filtering and separate knowledge states.
• Show progress for the selected biome.
• Add missing-resource and station requirement guidance.
• Mark discoveries made during the current session NEW until viewed.
• Add reproducible read-only asset catalog coverage audit.
• Actual two-player gameplay verification remains pending.

0.2.1 development

• Add a draggable list scrollbar and consistent wheel scrolling.
• Fit detail scrolling to actual text height.
• Label biome/category controls and distinguish item, recipe, and building rows.
• Show dark icon silhouettes for unknown entries while hiding names and details.
• Game validation of these UI changes remains pending.

Changelog

0.2.0 — 2026-10-19 (development)

• Character-bound protocol v2 with batched atomic commits, explicit rejection acknowledgements, per-frame catch-up and testable authority/receiver cores.
• Read-only installed-asset catalog baseline, native spawn-biome metadata, progression relationships and exclusion of iconless NPC attack entries.
• Transactional registry rebuilds, alternative recipes, building requirements, known relationships, external text/icon/discovery policies and reload/export/status commands.
• Native key-based material identity fallback with ambiguity rejection; length validation before transport payload allocation.
• UI keyboard navigation, configurable inventory-button placement, preserved scroll position, coalesced refreshes, loading/error recovery and throttled warnings.
• 65 automated checks. Actual game/multiplayer/platform/installation acceptance remains pending.

Protocol v2 requires this same plugin version on every peer. World history schema 1 is unchanged. Earlier 0.1.0 archives remain available locally for rollback.

0.1.0 — 2026-10-19 (development)

Initial plugin foundation, Codex UI/data, native discovery sharing, checksummed sidecar storage, configuration, test probe and package automation. Initial automated checks passed; an isolated startup smoke test loaded the earlier DLL, but world entry was blocked by the game backend.

1.0.0 — unreleased

Reserved until approved specification 1.2 has passed actual game, multiplayer, platform and installation acceptance.