HeimForgeExample

A modular Valheim mod-suite repository generated by HeimForge.

This is an unofficial community project and is not affiliated with or endorsed by Iron Gate or Coffee Stain.

The repository provides standalone build, test, deployment, metadata, and packaging workflows. Static validation does not replace runtime testing against the actual Valheim client and server.

Quick start

Use WSL/Linux as the primary development environment and keep the repository in the Linux filesystem rather than under /mnt/c.

Copy the local configuration templates:

cp Environment.props.example Environment.props
cp .valheim/dev.json.example .valheim/dev.json

Then run a portable repository-only check:

./scripts/preflight.sh --portable

For full local validation after configuring a development Valheim installation:

./scripts/preflight.sh
./scripts/bootstrap.sh

See docs/development.md for local setup, server deployment, and dependency/reference maintenance.

Modules

This project was generated with the following modules:

• HeimForgeExample.ServerCore: server-only gameplay and administration features.
• HeimForgeExample.Shared.Diagnostics: independent two-sided module with its own compatibility requirements.
• HeimForgeExample.Client: client-only UI, visual, input, and convenience features.
• HeimForgeExample.Common: shared pure code and protocol primitives.

Compatibility boundaries:

• ServerCore: NotEnforced / None
• Client: NotEnforced / None
• Shared.Diagnostics: VersionCheckOnly / Minor

Common is a shared library rather than a BepInEx runtime plugin; at least one of the three must be enabled -- a generation request disabling all three is rejected before this repository is created.

suite.config.json and the solution file are the current structural authority.

Development environment

The canonical workflow is:

WSL repository + dotnet
        |
        +-- build/test/package in WSL
        +-- inspect Windows Valheim files through /mnt/c/...
        +-- deploy client DLLs to Windows Valheim through /mnt/c/...
        +-- deploy server DLLs to the configured local or remote server

Windows remains the real Valheim client runtime.

Common commands

Validate project metadata:

python3 scripts/suite_metadata.py check

Synchronize supported metadata changes:

python3 scripts/suite_metadata.py sync

Run tests:

./scripts/test.sh

Build:

./scripts/build.sh Debug

Inspect the configured Valheim/Jötunn/BepInEx development stack:

python3 scripts/update-game-stack.py check

Refresh game references after a Valheim binary/reference update:

python3 scripts/update-game-stack.py refresh

Create deterministic Release packages:

./scripts/package.sh

See docs/development.md, docs/dependencies.md, and docs/testing.md for details.

Deployment

Deployment is explicit and metadata-driven:

./scripts/deploy-client.sh Debug
./scripts/deploy-server.sh Debug

Client receives Common + Client + Shared.Diagnostics. Server receives Common + ServerCore + Shared.Diagnostics.

Server deployment is not tied to Docker. Local filesystem destinations and remote POSIX or Windows servers over SSH are supported. Docker is an optional lifecycle integration for restart, status, and log operations.

Managed hosts that expose only FTP/SFTP or a control-panel file manager require manual deployment through the provider's tools because automated remote deployment requires an SSH command channel.

Server deployment does not restart the server unless explicitly requested.

See docs/development.md for local and SSH deployment configuration, transaction guarantees, and server lifecycle behavior.

Metadata

suite.config.json is the editable source of truth for supported mutable project metadata, including:

• version and publication metadata
• dependency pins
• project scopes and target frameworks
• client/server package membership

suiteName and rootNamespace are generation-time identity and are locked in suite.identity.lock.json.

Use scripts/suite_metadata.py rather than hand-editing generated metadata files.

Licensing

HeimForge does not select a project-level license for generated repositories.

LICENSES/MIT-0.txt covers the HeimForge scaffold material. Before public distribution:

1. choose a project license
2. add it as the root LICENSE
3. remove LICENSE.todo
4. run:

python3 scripts/suite_metadata.py check --release

See docs/release.md for the complete release checklist.

Runtime validation

Repository checks can prove structural consistency, build behavior, packaging, and deployment rules, but some behavior still requires the user's actual Valheim environment:

• full Jötunn/Valheim plugin compilation
• dedicated-server plugin load
• actual multiplayer compatibility behavior
• Shared Diagnostics RPC runtime proof
• any implemented feature's game-internal behavior, once a feature is chosen and built

Documentation

• docs/development.md — local environment, build, deployment, and server workflows
• docs/dependencies.md — dependency purposes and version maintenance
• docs/module-catalog.md — generated module topology
• docs/networking.md — networking conventions
• docs/patch-ledger.md — Harmony patch tracking
• docs/release.md — packaging and public-release checklist
• docs/testing.md — validation and test workflow