Ritual Apotheosis

Ritual Apotheosis

An in-depth ritual system for Vintage Story.

Some knowledge is not taught. It is pieced together from scraps - a rotted scroll on a forgotten altar, a chipped inscription deep in a mine, a whisper remembered only by the dying. The old rites did not survive in libraries. They survived in fragments, scattered across a world that has mostly forgotten them.

You will not be shown what the rituals are. You will find them.

Created by DoctorProfessor and co-author Grembellena, with support from artists "Kyokui Arvarus", "Viscarrion", & "Toryū".

---

What this mod adds

Ritual Apotheosis weaves mystery-driven ritual arcs into Vintage Story, making attempts to integrate naturally with the existing setting. Instead of a tech tree or a recipe list, ancient rites are re-assembled from fragmentary clues that you will organically uncover through normal play. Each clue holds a piece of the puzzle ... put together, they describe an act of power.

You will not open a menu to begin a ritual. The world itself is the interface. Rituals are performed as physical acts. You must determine the conditions, locations, and reagents on your own. Gather information, fulfill the conditions, and begin the rites - on your own, or with friends!

What a rite ultimately produces may be as varied as the rites themselves - lasting objects left behind in the world, zones of altered reality, knowledge the world did not previously contain. Some rituals ask to be repeated. Some must not be.

At a glance, the mod adds:

1. A clue discovery system - fragmentary, cryptic knowledge that surfaces through normal play and decodes as you live with it (see The arc of a ritual below).
2. Rituals - physical, world-as-interface rites with real conditions, real stakes, and lasting rewards (see The arc of a ritual, and the worked example in the spoiler section).
3. Fully customizable, fully walkable boats - chisel a hull into any shape you can imagine and live aboard it at sea (see Ships: Awakening as a Shipwright).
4. Spirit Journeys and Battle Totems - five totem spirits earned through solo pilgrimages, planted and spent at your side in combat, or while hard at work (see Battle Totems: the Spirit Journeys).
5. A constellation system - real stars in the real night sky, revealed in answer to deeds and watched for mastery (see The Night Sky: Astral Communion). (Note: this creates incompatibility with mods which replace the vanilla skybox entirely).
6. A multiblock sculpting framework - the craft beneath it all: build, customize, and interact with full working structures (even large ones) in the world, carved voxel by voxel. The idols, fixtures, and yards every system above incorporates.

... AND A NEW DISCORD SERVER! COME ON DOWN!

https://discord.gg/xNre4Zpw7

 

New and now fully achieveable without dev commands as of version 0.1.12: the mod's second great ritual arc - the Shipwright's Sanctification, whose reward is the largest thing a rite has ever produced, an entire ship - can now be carried from first clue to launched vessel entirely through discovery. Alongside it, two new frontiers have opened: the first Battle Totems have entered playtesting, and the night sky itself has begun to answer (see The Night Sky: Astral Communion below). Versions 0.1.10 through 0.1.12 also folded in two months of bug reports, crash fixes, and a major Grimoire usability overhaul.

The arc of a ritual

Every ritual in Ritual Apotheosis follows the same six-stage arc. Encountering an arc for the first time is part of the experience, so the descriptions below are deliberately vague.

1. Discovery. A fragment crosses your path. You read it. You have learned something. What, exactly, is not yet clear.
2. Understanding. Cryptic hints deepen as you live with the fragment and chase further clues. Over time and with the right experiences, the purpose of the rite becomes legible.
3. Preparation. The rite names what it needs - materials, conditions, a setting. Some are easy. Some are not.
4. The Place and Time. Not every location or time can host every rite. Not every hour, day, or season is right. You will never understand a ritual if you don't know where and when it will answer.
5. The Rite. The rite is performed. If every condition holds, the world changes. If not, it does not - and sometimes it punishes the attempt.
6. Something Gained. The temporal dimension may reward intrepid truth-seekers in myriad ways. Tools, skills, treasured knowledge ... and perhaps a combination of all three.

Of the Hours: a sky that keeps time

New in the latest build: rituals care about when, and the Grimoire now teaches you the sky's schedule. Playtesters kept asking the fairest question in the mod - "when exactly is dusk?" - and the answer is a new Of the Hours page, open to everyone from the first minute they find their first clue. Consult it and it records the hour of your visit (the book does not tick - it remembers when you last asked), lays out today's sky as a schedule - dawn, day, dusk, nightfall, and the sun's touch on the horizon, as clock times for your latitude - tracks the turning of the year (the darkest day, the equinox, the brightest), and follows the Evening Sister through her phases, counting the nights until she stands full or dark. A short glossary explains the mod's words for time, watch by watch.

Alongside it, every timed window in every rite has been through a fairness pass I'm calling the six-hour rule: whatever a rite demands of the clock, there are now at least six contiguous hours a day that satisfy it - at any latitude, in any season. Finding the right hour is meant to be a discovery, not a sprint; far-northern and equatorial players alike get a fair night's work.

Ships: Awakening as a Shipwright

The "Ships On The Horizon" arc (begun in 0.1.9) introduced the mod's second ritual arc - and its most ambitious reward to date. Most rites leave behind an idol, a ward, or a piece of knowledge. The Shipwright's Sanctification leaves behind a ship: a real, voxel-built, fully walkable vessel that you design block by block and sail on the open water, crewed through the unlocked ritualistic secrets of the Wheel, the Sails, and the Oars.

True to the rest of the mod, you do not start with a ship, and there is no "build boat" button. The Shipwright is earned the same way every rite is earned - through discovery. Scattered clues teach you to sculpt new kinds of idols; one type, placed at the corners of a rectangle on the water, raises a shipyard; inside it you chisel your hull into any shape you can imagine; and after mounting the Wheel, Sails, and Oars, a final consecration performed on the water brings the finished hull to life and sets it adrift for good. The exact clues, the conditions, and the rite itself are yours to uncover - I won't spoil them here. As of 0.1.12, this whole arc - including discovering and awakening the ship's working fixtures - is completable organically, with no shortcuts or operator help required: the placeholder-fixtures era and its wall of debug output are behind us.

Once your hull is afloat, it is a place you can live:

• Build it your way. Carve the hull voxel by voxel out of chiseled blocks - cabins, decks, holds, masts, prows, whatever you can picture. Shape is not just cosmetic: a voxel-accurate buoyancy and collision system means weight, balance, and hull form all matter. Pack the hold heavy and you sit lower in the water; build wide and stable and you ride flat.
• Walk the deck. The deck carries you - and your crew - as the ship moves, climbs swells, rolls under load, and rocks against the waves. No teleporting between fixed seats; you simply stand and walk where you like, underway.
• Live aboard. Place chests, doors, trapdoors, ladders, beds, anchors, lanterns, signs, planters, and almost any other block directly onto the moving hull, and they stay put. Open doors, chop wood, mine, chisel, fight, sleep, cook, and craft - all at sea. Rain stops at your roof, a firepit warms your cabin, and low crawl-spaces let you tuck under tight ceilings.
• Take the helm. Steering wheels, oars, and sails are functional fixtures you mount on the deck. Sit at the wheel to steer, raise the sails to catch the wind, or man the oars from seats the ship hands out as you build. These fixtures are discovered and "awakened" through rites of their own - and they grow stronger the farther you sail: a wheel turns harder, sails catch more wind, and oars pull deeper as the miles add up.
• Power at sea. Mechanical blocks work afloat. Windmills, helve hammers, querns, and the rest render and operate correctly on a pitching deck, so a working workshop can sail with you.
• Bring friends. The whole system is multiplayer-ready - crew a single ship together, each player walking the same moving deck.

Since 0.1.9, the ship systems have been through two solid months of sea trials and hardening. Highlights from 0.1.10-0.1.12: fixture visuals now fit your carving (the placeholder sailcloth, for example, reads the actual voxels of the mast you chiseled and hangs itself on your yard, however you shaped or rotated it); a helm-view segment guide was added to the Idol Guide dialog to make multiblock sculpting far less painful; and a family of nasty persistence bugs was hunted down - including the memorable "ghost ship" bug, where deleted or long-gone ships stayed baked into players' cached world maps and left hull-shaped dents in the water. Ships now clean up after themselves properly, and server operators got tools to heal any old scars (see the server administrators section below).

This is the foundation, not the finished story. Combat, naval boarding, and deeper ritual integration are on the way. Ships are brand-new and have a great many moving parts, so if something feels off at sea, please report it - feedback here is enormously valuable right now. I'm not gonna say it's held together with just duct tape, but it IS a very complicated set of machinery and I'd love your help!

Battle Totems: the Spirit Journeys

The mod's third ritual family is now real, and playtesting has begun. Where ward idols protect a place, battle totems fight beside a person: deployable, chargeable combat companions in the spirit of the classic shaman fantasy. Each of the five totem spirits is found and earned alone, through a Spirit Journey - a long, personal pilgrimage that asks you to do certain things in certain places, far from home. No two spirits are courted the same way.

A totem is not a permanent fixture. It is planted for the fight in front of you, it spends itself in your service, and it must be ritually renewed. Lean on many totems at once and you will find the spirits share a single well - drawing deep from it has consequences.

As with everything else in this mod, the journeys, the altar, and the rites are meant to be discovered. If you want the specifics anyway, they're behind the curtain:

Want the specifics anyway? They live with the rest of the spoilers: Battle Totems in detail.

The Night Sky: Astral Communion

Begun in 0.1.10 and growing every release since: the night sky is now part of the mod's canvas. Vintage Story's stars are real - the game ships an 8,000+ star catalog - and Ritual Apotheosis draws its constellations from those actual stars, rotating with the actual sky, visible from the latitudes and in the seasons that real geometry allows.

You will not see them at first. Constellations reveal themselves in answer to deeds - and sometimes, rarely, as an unasked-for gift. When the sky has something to show you, you will know to look up. What you do with what you see - and what watching faithfully earns you - is yours to find out. This system is young and deliberately quiet for now; it will braid into the ritual arcs more tightly over the coming releases.

The specifics, for those who want them: how Astral Communion works.

Multiplayer

Ritual clues are designed to be shareable. Two or more players who have found different clues can combine what they know and perform the rite together. Some rites explicitly require more than one participant (configurable). The mod never locks clues to a single player - everyone can gain complete mastery over secrets of a rite, with enough effort. Secrets may be passed to others, and live in the telling.

A note on play style

The "Discovery Arc" of Ritual Apotheosis rewards patience, observation, and conversation with other players more than it rewards optimization. If the first clue frustrates you because it does not tell you what to do - that is intended. Keep playing. Keep dying. Keep going deeper. The right fragments will find the right hands. And with time, the knowledge WILL eventually become clear to you, regardless of what you do.

Current status

Version 0.1.12 - active development, targeting Vintage Story 1.22.2+ and audited clean against 1.22.4 (I started building on 1.19.0, and have done several codebase updates since - most major systems stayed functional as far back as 1.19.0 when last confirmed, but recent VS API changes mean current builds assume 1.22.x. I can look into a legacy build for 1.19.0-1.21.7 if there is a lot of demand.)

The mod now spans four systems at different levels of maturity. Madness Consecration was the first complete ritual arc: a fully working end-to-end implementation - discovery, decoding, performance, a persistent reward, and an associated crafting/progression system. The Shipwright's Sanctification is the second, and the single largest feature in the mod - a full chiseled-ship engine reached through its own discovery arc (see Ships: The Shipwright above); as of 0.1.12 the arc is completable end-to-end through normal play, and the last two releases have been devoted to hardening it against everything the playtesters threw at it. Battle Totems (see above) are implemented and in active playtesting. Astral Communion (see above) is live in its early, quiet form. Versions 0.1.10-0.1.12 also brought a substantial Grimoire usability overhaul (proper scrolling everywhere, readable icons, per-pool constellation browsing, one-image-per-pattern pages - and, newest of all, the Of the Hours timekeeping page and the six-hour-rule fairness pass on every timed rite, both described above), fixes for several crash-to-desktop bugs (including a thread race in weather particles, a phantom-block crash, and a crash triggered by combining map-icon mods with waypoint editing), and a large purge of log spam. Additional rituals and polish are in progress and will keep coming - all the bones are in place to develop further content more rapidly, and I'm excited to keep at it!

DISCLAIMER: I am a solo developer with zero art skill. This is an extremely ambitious mod with many moving parts, and I'm not really interested in building up my arts skills. As such - while many of the assets I've used come from in-game screenshots or existing in-game assets, about 15 AI genenated images remain. I've founds several artists (and will happily welcome more volunteers) to assist me in replacing them, and continuing to add assets. I do not claim ownership over any art asset seen in this mod.

• Report bugs / suggest rites: please open an issue on the project repository - or better yet, join the new Ritual Apotheosis Discord ([DISCORD-INVITE-LINK]), where playtest coordination and bug triage now live.
• Suggest ideas! I want to hear your own ideas for rituals! I confess - I want full creative control over this project - but I'm more than happy to integrate your coolest ideas (and I promise I'll give you credit if I use your idea :D)
• Playtesters are very welcome. I've taken quite a lot of time to test the many features this mod includes, but there is a lot of surface area and there are bound to be things I missed. In addition, any feedback on clue pacing and "ritual feel" is especially valuable at this early stage. I am also interested on your opinions on the rewards schema I have in place. There is now an organized playtest program running through the Discord - onboarding docs, step-by-step test manuals, and known-issue lists are ready for anyone who wants to help shake down the ships, the totems, or the sky.
• I have internally debated whether this mod should be split into several. If you think that just one aspect of the mod is of primary interest to you, pitch the idea to me - I might consider breaking out these aspects and making them accessible together, or as standalone features. Honestly, there are a lot of systems in here.

Installation

Drop the compiled mod zip into your server's Mods/ folder (or your client's Mods/ folder for singleplayer). The server is authoritative for all ritual logic; clients only render and send input. All connected clients must have the same version installed.

Requires Vintage Story 1.22.2+ (developed and tested through 1.22.4). No hard dependencies on other mods - though there is a dependency on Harmony patches. Please see .../docs/VERSION_SURFACE.md for more information about version maintenance.

I took a look at some of the most popular mods out there and I don't think Ritual Apotheosis will conflict with them - but please let me know if you identify conflicts. If I'm able to reach the creators, I'll ask about what I can do to resolve them. Since 0.1.9 this has gone well beyond a "look": two full playtester mod-packs (hundreds of mods, decompiled and scanned against every Harmony patch and engine seam this mod touches) have been through a structured compatibility audit, and the mod now ships defensive measures for the conflicts that audit surfaced. If you run a heavily modded server and hit something strange, report it; the audit machinery exists and I will use it.

The full ledger - which mods were decompiled and checked, what was found, and every verdict - is public and kept current: Mod Compatibility Ledger.

Localization

Every player-facing string is a lang key in assets/ritualapotheosis/lang/en.json - to translate the mod, copy that file, rename it to your locale code (e.g. de.json), and translate the values; no code changes needed. If you hit untranslatable hardcoded text anywhere, leave a comment here and I'll extract it into a key.

Credits

Created by DoctorProfessor and co-author Grembellina, with support from artists Kyokui Arvarus, Viscarrion, & Toryū - thank you for your hard work! Thank you also to The Coalition & Crown (looking at you Renee) + Pandorica for occasional server stress testing.

Built on the Vintage Story modding API.

Special thanks to the Vintage Story team for an engine that rewards this kind of world-as-interface design, and to any players and playtesters who exercise patience with me as I've embarked on my VS mod-making journey!

---

SPOILERS! INCLUDES A SEMI-SPOILER AND FULL SPOILER SECTIONS:

SEMI-SPOILER: For server administrators.

Spoiler level: Architectural - the shape of the mod, not its secrets. If you run a server, this is for you; if you also want to PLAY fresh, finish a ritual first.

Open the Server Administrator's Guide - where settings live, the config knobs you'll reach for, hosting notes, the /ra operator command tour, and emergency unsticking. (Hosted off-page: the ModDB description has a size limit.)

FULL SPOILER: Design philosophy, architecture, and collaborator notes

Spoiler level: Everything - design reasoning, architecture, and the full worked example of the first ritual. If you have not yet performed your first ritual, I strongly encourage you not to follow the link below!!!

Design, Architecture & Full-Spoiler Notes - the five design pillars, the complete worked example of the first ritual (heavy spoilers), the idol-system internals, the codebase tour, the documentation index, Future Plans, and how to contribute.