Divine Ascension

Deity-driven religion and faction systems for Vintage Story: create and manage religions, earn player Favor and Religion Prestige, unlock blessing trees, and organize multi‑religion civilizations. This repository contains the mod/library and an extensive xUnit test suite.

Status: Active development (last updated 2026-01-21). New to Divine Ascension? Read the Player Guide!

Feature Summary

• Religions and Deities
  • Create, browse, join/leave player‑run religions associated with a deity; server‑authoritative managers and command support.
• Dual progression: Favor and Religion Prestige
  • Player Favor and Religion Prestige ranks with thresholds; rewards from activities and PvP; configurable death penalties; passive Favor accumulation with multipliers.
• Blessing trees and effects
  • Unlockable blessing nodes with prerequisites and categories; server‑validated unlocks; effects applied via the Buff system; in‑game tree layout and icon rendering.
• Civilizations (multi‑religion alliances)
  • Create, browse, and manage civilizations; invite/accept/kick/disband flows; UI tabs and server commands; religion‑level membership; milestone-driven rank progression (Nascent → Eternal) with permanent stat bonuses.
• PvP integration
  • Kill rewards and death penalties integrated with Favor/Prestige.
• Networking and persistence
  • Protobuf‑net packets for religion, player, blessing, and civilization data; server→client sync on join and on state changes.
• UI
  • Blessing dialog with tooltips, tree layout, and civilization management views; consistent color palette and icon utilities.
• Test suite
  • Large xUnit v3 test project covering systems, GUI utilities, networking, and models.
• Holy Sites and Prayer
  • Land claim-based holy site creation with tiered bonuses; altar prayer mechanics with 1-hour cooldowns; offering system for bonus favor rewards; automatic holy site creation/removal on altar placement/destruction.
• Localization
  • Multi-language support with translation files; server and client-side localization service.
• Content Moderation
  • Configurable profanity filter for religion/civilization names and descriptions; L33t speak detection; per-world enable/disable.

Build and Configuration

• Toolchain: .NET SDK 8.0 (C# 12)
• Solution: DivineAscension.sln
• Projects:
  • DivineAscension — main mod/library targeting the Vintage Story API
  • DivineAscension.Tests — xUnit v3 test project
  • CakeBuild — C# Cake bootstrapper used by build.sh/build.ps1

Vintage Story dependency

Tests and (optionally) the main project reference Vintage Story game libraries via the VINTAGE_STORY environment variable. Point it to a local Vintage Story install that contains at minimum:

• VintagestoryAPI.dll
• Lib/0Harmony.dll, Lib/cairo-sharp.dll, Lib/Newtonsoft.Json.dll, Lib/protobuf-net.dll
• Mods/VSEssentials.dll, Mods/VSSurvivalMod.dll

Examples:

Windows PowerShell

$env:VINTAGE_STORY = "C:\\Games\\Vintagestory"

Linux/macOS

export VINTAGE_STORY="$HOME/.local/share/Vintagestory"

Quick build

• Full Cake build (packaging):

  • Linux/macOS: ./build.sh
  • Windows: ./build.ps1

• Direct solution build:

  • dotnet build DivineAscension.sln -c Debug

Artifacts are placed under Releases/ when using the Cake build. See the Releases/ folder for example outputs.

Testing

• Framework: xUnit v3 with Microsoft.NET.Test.Sdk 17.13 and xunit.runner.visualstudio 3.1.5
• Run all tests:
  • dotnet test (from repo root), or
  • dotnet test DivineAscension.Tests/DivineAscension.Tests.csproj
• Target a subset by fully qualified name (preferred):
  • dotnet test --filter FullyQualifiedName~DivineAscension.Tests.GUI.UI.Utilities.DeityHelperTests
• Coverage:
  • ./generate-coverage.sh (auto-installs ReportGenerator and opens HTML report)
  • Manual: dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings

Notes

• If VINTAGE_STORY is not set correctly, the test project will fail to build. See the dependency section above.
• The main project exposes internals to tests via [assembly: InternalsVisibleTo("DivineAscension.Tests")].

Documentation

• Documentation index: docs/README.md
• Common entry points:
  • Reference: docs/topics/reference/ (deities, blessings, favor)
  • Implementation guides: docs/topics/implementation/
  • UI design: docs/topics/ui-design/
  • Testing: docs/topics/testing/

Project structure (top-level)

DivineAscension/
├── DivineAscension/         # Main mod project
├── DivineAscension.Tests/   # Tests
├── CakeBuild/               # Build bootstrapper
├── docs/                    # Documentation
├── Releases/                # Example release artifacts
├── build.sh / build.ps1     # Convenience build scripts
└── DivineAscension.sln

Troubleshooting

• Build errors about missing Vintage Story DLLs → verify VINTAGE_STORY and directory layout; restart your shell so dotnet inherits the env var.
• Coverage script doesn’t open the report → open coverage-report/index.html manually.
• Intermittent test failures tied to time/randomness → prefer injecting clocks and random sources.

Commit Message Linting

This project uses commitlint to enforce Conventional Commits format. A git hook automatically validates your commit messages on commit.

First-time setup:

# Restore .NET tools (includes Husky.Net)
dotnet tool restore

# Install Node.js dependencies (commitlint)
npm install

The commit-msg hook will now run automatically on every commit and reject messages that don't follow the format:

<type>: <subject>

[optional body]

Rules:

• type must be lowercase and one of: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
• subject must be lowercase (no sentence-case, start-case, pascal-case, or upper-case)
• subject must not end with a period
• header (type + subject) max 100 characters
• body lines max 100 characters (wrap long lines)

Examples:

# ✅ Good
git commit -m "feat: add prayer cooldown system"
git commit -m "fix: resolve territory multiplier calculation"

# ❌ Bad
git commit -m "Feat: Add Prayer System"  # type must be lowercase
git commit -m "feat: Add Prayer System"  # subject must be lowercase
git commit -m "add prayer system"        # missing type

Contributing

v1.0 is now in beta testing! We're looking for:

• Testers: Try the mod and report bugs or balance issues
• Feedback: Which special effects should be prioritized in patches?
• Balance Data: How do the stat modifiers feel in actual gameplay?
• Feature Requests: What would make the religion system more engaging?

Contributions, suggestions, and feedback are welcome! Please open an issue or discussion on the repository.

Code Contributions

• Match the existing C# style (C# 12, ImplicitUsings, Nullable enabled).
• Keep types internal when appropriate; tests already have access via InternalsVisibleTo.
• Place new tests under DivineAscension.Tests/<Area>/ and align namespaces with folder structure.

License

This project is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material for any purpose, even commercially

Under the following terms:

• Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made

See the LICENSE file for full details.

Credits

• Built using the official Vintage Story Mod Template
• Heavily inspired by mods:
  • Karma System mod
  • xSkills Gilded
  • xSkills
• Assets used from:
  • Game-icons.net