Mods / Manifold

Tags:
Worldgen Library Travel & Exploration Teleport
Author:
Pixnop
Side:
Both
Created:
May 20th at 8:42 PM
Last modified:
Jun 12th at 9:20 PM
Downloads:
1343
Latest release (for Vintage Story 1.21.0-pre.1 - 1.22.3, potentially outdated):
Manifold-0.4.1.zip  1-click install

Manifold is a library mod for Vintage Story 1.21+ that lets other mods create and manage their own custom dimensions. It adds no content of its own - install it only because another mod depends on it.

Vintage Story 1.21+ Universal Zero Harmony NuGet API MIT

For players

Manifold is a dependency. If a mod you use requires Manifold, install this alongside it. It is safe on both client and server (Universal). On its own, it does nothing visible.

For mod developers

Manifold exposes a clean public API to declare and run custom dimensions:

  • Custom dimensions - persistent or ephemeral, registered at boot or at runtime, identified by an AssetLocation code.
  • Active worldgen - implement IWorldgenStrategy; Manifold pre-generates a chunk region around the arrival point before the player enters (bounded mode, configurable radius). Dimensions can also opt into streaming generation via .Streaming(loadRadius), which generates chunks on demand as players move with no fixed edge. The streaming radius is extended to the server view distance so generated terrain always reaches as far as players can see, and the relight band height is configurable per dimension via WithRelightHeight.
  • Player transit - one call, TeleportPlayer, moves a player between dimensions, with cancellable lifecycle events and opt-in helpers (a portal-block base class and a chat-command builder).
  • Non-player entity transit (0.3.0) - TeleportEntity moves items and other non-player entities between dimensions; the destination region is generated on demand before the entity is re-homed.
  • Block transit (0.4.0) - TeleportBlock(source, targetDim, targetLocal) moves a single block plus its BlockEntity state (inventory, attributes, BE-behaviors) between dimensions, completing the Player / Entity / Block triplet.
  • Travel policy per dimension - pick the landing position (SameCoordinates, DimensionSpawn, or LastVisited) and optionally force a game mode.
  • Per-dimension player inventory (0.3.0, opt-in) - WithSeparateInventory(Hotbar | Backpack | Character) gives a dimension its own player inventory; profiles are stored in player moddata, saved together with the physical inventory, so they survive logout and server restarts with no item loss.
  • Per-dimension metadata (0.4.0) - WithMetadata(key, value) attaches typed registration-time hints (display name, category, opt-in flags) readable by any consumer via IDimension.GetMetadata<T>(key). Supports primitives, string, enum, byte[].
  • Per-dimension streaming budget (0.4.0) - WithStreamingBudget(maxColumnsPerTick) (range 1..64) caps streaming generation per dim per tick. Budgets are independent across dimensions so a busy dim cannot starve a quiet one.
  • Transit events (0.4.0) - PlayerEntering (cancellable, pre-generation), PlayerArriving (cancellable, post-generation, pre-teleport), PlayerLeft / PlayerEntered (post-teleport), and EntityChangedDimension (post TeleportEntity).
  • Persistence - dimensions, generated chunks and per-player positions survive restarts. A dimension whose owning mod is removed is quarantined: its chunks are kept and transit is refused, never corrupted.
  • Zero Harmony patches - built entirely on the public VintagestoryAPI.

Quickstart

Add Manifold as a dependency in your modinfo.json:

"dependencies": { "manifold": "" }

Reference the API at compile time from the NuGet package Pixnop.Manifold:

dotnet add package Pixnop.Manifold

Then register a dimension from your mod system:

var manifold = sapi.GetManifoldServer(this);
manifold.Registry
    .Define(new AssetLocation("mymod", "void"))
    .Persistent()
    .WithWorldgen(new BasicVoidWorldgenStrategy())
    .RegisterStatic();

Full guide and API reference: pixnop.github.io/Manifold

Demo

Manifold Sample logo

Manifold Sample demo and template
Shows void, flat, streaming and vault dimensions with the /voiddim, /flatdim, /streamdim, /vaultdim and /overworlddim commands, plus /sendtestitem (entity transit) and /sendtestblock (block transit, 0.4.0). MIT licensed - reuse the code freely.

Companion mods

Chart logo

Chart 0.2.0 alpha
A separate companion mod that makes the in-game world map dimension-aware: each Manifold dimension keeps its own tile cache and the map swaps on transit. Client-side only, requires Manifold.

Mods built on Manifold

Personal Pocket Dimension logo

Personal Pocket Dimension first third-party mod
By LilianaXolkiyr and Zachurai - craft a device that opens a door to a private dimension, with a visual room builder, a temporal energy economy and a full crafting progression.

VS Backrooms logo

VS Backrooms third-party mod
By LilianaXolkiyr - noclip through reality into a liminal Backrooms dimension, an unsettling yellow maze of rooms and corridors under fluorescent light. Early access.

Secure Shelter logo

Spaturno and Trini's Secure Shelter third-party mod
By Spaturno and Trini - cast Leomund's Secure Shelter through a painting and step into a cozy interdimensional cottage shared by the whole server: no damage, no hostile spawns, self-replenishing supplies and an Unseen Servant to manage your stored goods.

Building something on Manifold? Tell me on the issue tracker or in the comments and I will list it here.

Why the name "Manifold"

In mathematics, a manifold is a space made of many local pieces glued into one coherent whole, and its structure is described by an atlas of charts (maps). The word also just means "many and various". That is exactly what this project does: it manages many dimensions as one system. It is also a nod to a mechanical manifold, the part that routes a single flow out to several outlets, like routing players out to several worlds.

Compatibility & source

Mod Version Mod IdentifierFor Game version Downloads Released Changelog Download 1-click mod install*
0.4.1 manifold
1.21.0-pre.1 - 1.22.3
1134 Jun 12th at 9:20 PM Manifold-0.4.1.zip 1-click install

Ephemeral dimensions now fire Destroyed on server shutdown.

  • Previously an ephemeral dimension simply vanished from the manifest at the next boot without ever firing its Destroyed event on a graceful stop. The registry now removes every ephemeral dimension during server shutdown, so companions and consumer mods subscribed to IDimensionRegistry.Destroyed (or the client mirror's IManifoldClient.Destroyed) get a chance to clean up per-dimension state (cached files, UI, trackers) before the server exits. Saved-game data is unchanged.
  • The Manifold Sample gains /createtempdim and /destroytempdim commands demonstrating the runtime ephemeral lifecycle (Define().Ephemeral().Create() and Registry.TryRemove).
  • Ships together with Chart 0.2.0, which uses this signal for its per-dimension map cache cleanup and fixes a major lag issue inside custom dimensions.

For Vintage Story 1.21+.

0.4.0 manifold
1.21.0-pre.1 - 1.22.3
90 May 30th at 8:46 PM Manifold-0.4.0.zip 1-click install

Block transit, per-dimension metadata, per-dimension streaming budget, and two new transit events.

  • Block transit - ITransitionService.TeleportBlock(source, targetDim, targetLocal) moves a single block plus its BlockEntity state (inventory, attributes, BE-behaviors) between dimensions, completing the Player / Entity / Block triplet. The destination region is generated on demand; the BlockEntity is round-tripped through ToTreeAttributes / FromTreeAttributes with the embedded position re-stamped so interactions (e.g. opening a chest) route correctly to the new location. Source slot is cleared after a successful move.
  • Per-dimension metadata - IDimensionBuilder.WithMetadata(key, value) attaches typed registration-time hints to a dimension; consumers read them via IDimension.Metadata or the typed GetMetadata<T> extension. Useful for hub / menu mods that enumerate dimensions with a friendly name or category. Supports primitives, string, enum, byte[], and null.
  • Per-dimension streaming budget - WithStreamingBudget(maxColumnsPerTick) (range 1..64) caps how many columns the streaming driver may ensure for the dimension per tick. Budgets are independent across dimensions: a busy dim cannot starve a quiet one.
  • PlayerArriving event - cancellable hook on TeleportPlayer fired after region generation and before the actual teleport. Right place for setup work that needs the destination chunks loaded (place a welcome block, attach server-side state, log arrival metadata).
  • EntityChangedDimension event - server-side event fired after TeleportEntity re-homes a non-player entity. Mirrors the engine's PlayerDimensionChanged for everything that is not an EntityPlayer.

For Vintage Story 1.21+.

0.3.1 manifold
1.21.0-pre.1 - 1.22.2
38 May 23rd at 3:02 PM Manifold-0.3.1.zip 1-click install

Crash fix for Vintage Story 1.22.x.

  • VS 1.22 refactored Entity.Pos from a public field into a public property; the 0.3.0 binary was built against the 1.21 API and threw MissingFieldException at world generation on 1.22.x. Manifold now resolves Entity.Pos through a small reflection-cached helper, so the same binary keeps working on every 1.21.x and 1.22.x release.
  • CI / NuGet / release / package / docs workflows now build against VS 1.22.2 (latest stable). The shipped binary still runs on 1.21.x.
  • The Manifold Sample now declares manifold >= 0.3.0 in its modinfo, since it uses the 0.3.0 TeleportEntity and WithSeparateInventory APIs.

For Vintage Story 1.21+.

0.3.0 manifold
1.21.0-pre.1 - 1.22.2
26 May 23rd at 9:53 AM Manifold-0.3.0.zip 1-click install

Per-dimension player inventory and non-player entity transit.

  • Per-dimension player inventory - opt-in via WithSeparateInventory(Hotbar | Backpack | Character). Entering swaps the chosen categories to that dimension's set (empty on the first visit); leaving restores the previous one. Profiles live in player moddata, saved together with the physical inventory, so they survive logout and server restarts with no item loss.
  • Non-player entity transit - TeleportEntity moves items and other non-player entities between dimensions; the destination region is generated on demand, then the entity is re-homed.
  • Breaking: ITargetPositionResolver.Resolve now takes the source Entity instead of IServerPlayer, so one resolver serves both player and entity transit. Custom resolvers must update one parameter; the built-in resolvers and TeleportPlayer are unaffected.
  • NuGet: dotnet add package Pixnop.Manifold for the compile-time API.
  • Demo: the /vaultdim and /sendtestitem commands in the sample.

For Vintage Story 1.21+.

0.2.0 manifold
1.21.0-pre.1 - 1.22.2
23 May 21st at 11:23 PM Manifold-0.2.0.zip 1-click install

Streaming worldgen and refinements.

  • Streaming worldgen - opt-in per dimension via Streaming(loadRadius). Chunks are generated on demand as players move (no fixed region edge), spread across server ticks so there is no hitch. Bounded generation stays the default.
  • The streaming radius now covers the player's view distance, so generated terrain always reaches as far as they can see.
  • WithRelightHeight(maxY) to set the lit band height per dimension.
  • Demo: the /streamdim command in the sample.

For Vintage Story 1.21+.

0.1.0 manifold
1.21.0-pre.1 - 1.22.2
32 May 20th at 8:52 PM Manifold-0.1.0.zip 1-click install

First public release.

  • Public API to declare custom dimensions (persistent or ephemeral; boot-time or runtime).
  • Active worldgen via IWorldgenStrategy with a configurable bounded region.
  • Player transit (TeleportPlayer) with cancellable enter/leave events; portal-block and chat-command helpers.
  • Travel policy: spawn behavior (SameCoordinates / DimensionSpawn / LastVisited) and an optional forced game mode.
  • Persistence of dimensions, generated chunks and per-player positions; quarantine for dimensions whose owning mod was removed.
  • Built on the public API — zero Harmony patches.

Built against the 1.21.0 API and validated in-game on 1.22.2 — works across 1.21 and 1.22.

26 Comments (oldest first | newest first) (threaded | flat)

GrimoireODS, Sep 2nd at 10:12 PM

Is it possible to create a dimension that has biomes like minecraft with this?

yurajoh, Jul 18th at 7:41 PM

Would there ever be the possibility to support per-dimension temporal settings?

For example, a main dimension that has rifts, storms, and stability disabled; then a second dimension that has all of that enabled?

Spaturno, Jul 7th at 8:14 PM

New mod released using Manifold: https://mods.vintagestory.at/show/mod/56037

Moby_, Jun 12th at 10:35 AM

Hi! Got a few questions about this:

  • Does the travel dimension policy support what Minecraft calls the "subspace bubble"? (that is, scaling up or down a dimension to speed up or speed down travel relative to another dimension)
  • Do these support custom skyboxes yet, is it planned, or should I write a shader if I want that kind of stuff?
  • Do these support (now or planned) custom weather (or at least weather disabling), or will we get rain and clouds in the moon dimension?
Pixnop , Jun 12th at 8:43 PM
@Moby_: Hi! Got a few questions about this: Does the travel dimension policy support what Minecraft calls the "subspace bubble"? (that is, scaling up or down a dimension to speed up or speed down travel relative to another dimension) Do these support custom skybo

Hey Moby, good questions.

  1. Subspace bubble: yes, that works today. The landing position goes through ITargetPositionResolver - it receives the source entity and returns the target BlockPos, so a resolver that divides X/Z by 8 (or any ratio) gives you exactly the Nether-style compressed travel. Pass it via TransitionOptions.Resolver on TeleportPlayer, or bake it into your portal block's Options if you use PortalBlockBase. The built-in resolvers do 1:1, but a scaling one is about five lines.
  2. Custom skyboxes: not currently, and not on the short-term roadmap. Manifold runs on both sides (Universal) but its client half is only a read-only mirror of the dimension list - it does not touch rendering at all, and the skybox is pure client rendering. So today a shader (or a client render hook in your own mod) is the right tool. A skybox companion mod on top of Manifold is the kind of thing I would love to see exist, but I am not building it right now.
  3. Custom weather / weather disabling: honest answer - right now vanilla weather applies globally, so yes, you would get rain on your moon. It is tracked in https://github.com/Pixnop/Manifold/issues/55 (per-dimension weather and time of day); I still need to check how much of the VS weather system is hookable per-dimension without Harmony patches before promising anything. Feel free to add your use case on the issue, it helps with prioritisation.
DilanRona, Jun 12th at 6:36 AM

Checking it out tonight after work. Thank you

VaruunKaruk, Jun 3rd at 12:06 PM

Are there currently any alternate dimension mods already? not seeing any, but the existence of this mod implies that they exist.

Pixnop , Jun 5th at 11:21 PM
@VaruunKaruk: Are there currently any alternate dimension mods already? not seeing any, but the existence of this mod implies that they exist.

Hey VaruunKaruk - honest answer: not really, not yet. Manifold itself is recent (first public release a few weeks ago, currently at 0.4.0) and still in active development. Manifold Sample (the demo companion) is the only public consumer right now, and Chart (a companion map mod) sits next to it.

The library exists ahead of the third-party dimension mods that would use it - the goal was to make the "custom dimension" piece a clean, shared foundation so mod authors do not have to reinvent it. A few people are already prototyping mods on top (some publicly, some not), so I expect that to change in the coming weeks/months.

If you have a specific dimension idea in mind, feel free to mention it - I am happy to point you at the relevant API bits.

LilianaXolkiyr, Jun 9th at 5:49 AM
@VaruunKaruk: Are there currently any alternate dimension mods already? not seeing any, but the existence of this mod implies that they exist.

I'm extremely picky on releasing unfinished mods, but keep a look out. I should be releasing the first version of the PPD mod soon™️

LilianaXolkiyr, Jun 1st at 2:53 AM

Hey Pix, can I reach out to you on Discord? I always ask before I do, kinda wanted to pick your brain and show you one of two projects I'm building using your framework. I think you might be impressed but well, better to show you than to leak my details on the project here. Unlike my other two projects, I'm trying to keep this one hush hush.

Pixnop , Jun 1st at 10:28 AM
@LilianaXolkiyr: Hey Pix, can I reach out to you on Discord? I always ask before I do, kinda wanted to pick your brain and show you one of two projects I'm building using your framework. I think you might be impressed but well, better to show you than to leak my details o

Hey LilianaXolkiyr - sure, easiest is the official Vintage Story Discord.

You can find me there as Pixnop, just DM me. Looking forward to seeing what you're building on top of Manifold.

LilianaXolkiyr, Jun 1st at 6:31 PM (modified Jun 1st at 6:37 PM)
@Pixnop: Hey LilianaXolkiyr - sure, easiest is the official Vintage Story Discord. You can find me there as Pixnop, just DM me. Looking forward to seeing what you're building on top of Manifold.

Sent you a DM. Sorry it took so long to respond.

 

My guess is we live in very different timezones. Just lemme know when a good time is and what timezone. I also messaged in the Manifold mod thread in the official VS discord.

Zetal, May 27th at 1:34 PM (modified May 27th at 1:51 PM)

This is an absolutely incredible mod. I'm SUPER excited to see where this goes, and how it gets used. MIT Licensed too is huge. Massive props. 🥳

 

Is it possible to have separate weather/times of day per dimension?

Pixnop , May 28th at 1:02 PM
@Zetal: This is an absolutely incredible mod. I'm SUPER excited to see where this goes, and how it gets used. MIT Licensed too is huge. Massive props. 🥳 Is it possible to have separate weather/times of day per dimension?

Thanks, really appreciate it! 🙏

And yes on MIT: I think a library mod has to be permissively licensed or it isn't really a library. The whole point is for others to build on it and ship their own mods, so anything that blocks depending on it or redistributing it defeats the purpose.

Per-dimension weather and time of day is a good one. It's closer to the core philosophy than UI-side requests since it's about dimension behavior, though it does touch client rendering so it needs care. Could you open a GitHub issue with what you'd want (eternal night, fixed weather, a time offset)? If not I'll open it myself, but writing the use case down helps me judge how useful it is and whether it fits the lib's scope. No timeline yet, but I'd like Manifold to support it eventually.

Elocrypt, May 23rd at 10:56 AM

I was going to ask about per-dimension player inventory yesterday, but now its implemented. Nice.

Are you planning on implementing native land claiming compatibility (preventing coordinate overlap or claim bleed between dimensions via /land) and per-dimension chat or permission nodes?

 

Pixnop , May 23rd at 12:33 PM (modified May 23rd at 12:40 PM)
@Elocrypt: I was going to ask about per-dimension player inventory yesterday, but now its implemented. Nice. Are you planning on implementing native land claiming compatibility (preventing coordinate overlap or claim bleed between dimensions via /land) and per-dimen

Hi! Good timing on the inventory, glad it landed when you needed it.

You're right that the vanilla /land system isn't dimension-aware out of the box, so claims would technically overlap across dimensions. Making it dimension-aware (claim isolation, no bleed between dim 0 and Manifold dimensions) makes sense to me, same for per-dimension chat and permission nodes. I want to scope it properly before committing though. Could you open a GitHub issue with the behavior you'd expect and the edge cases you care about? If you'd rather not, I'll open it myself, just say the word. Same goes for chat and permissions if you want to flag a use case there.

No timeline on either yet. Right now my focus is on a companion mod that gives custom dimensions a proper dimension-aware minimap, since that's been the most requested thing so far.

Tisma, May 23rd at 10:43 AM

Hello! I've created issues report on github! 
Same as El_Neuman with all logs files

Pixnop , May 23rd at 12:36 PM
@Tisma: Hello! I've created issues report on github! Same as El_Neuman with all logs files

Hi both, thanks for the reports and the log files. The in-flight implementation work is now done so I can focus on the fix, and I'm aiming to have it out by end of day today. I'll use Tisma's GitHub issue to track the fix and post the update here once it's deployed. Sorry for the trouble!

Pixnop , May 23rd at 3:08 PM
@Tisma: Hello! I've created issues report on github! Same as El_Neuman with all logs files

Follow-up: 0.3.1 is up. Fixes the MissingFieldException (VS 1.22 changed Entity.Pos from a field to a property; 0.3.1 ships a reflection-cached accessor that works on both 1.21.x and 1.22.x). Validated in-game on 1.22.x. Please grab it from the Mod DB and let me know if anything else looks off. Thanks again for the logs.

El_Neuman, May 23rd at 10:35 AM

Why am I still seeing the error that prevents me from loading the world?
To rule out any interference, I created a separate clean VintageStoryData, but that didn’t help either.
As I understand it, everything works fine for you?

Spoiler!
23.5.2026 12:30:06 [Error] Exception: Field not found: 'Vintagestory.API.Common.Entities.Entity.Pos'.
at Manifold.Internal.StreamingWorldgenDriver.GatherStreamingPlayers(Dictionary`2& byUid)
at Manifold.Internal.StreamingWorldgenDriver.GatherStreamingPlayers(Dictionary`2& byUid)
at Manifold.Internal.StreamingWorldgenDriver.OnTick(Single dt)
at Vintagestory.Common.GameTickListener.OnTriggered(Int64 ellapsedMilliseconds) in VintagestoryLib\Common\Model\GameTickListener.cs:line 36
at Vintagestory.Common.EventManager.TriggerGameTick(Int64 ellapsedMilliseconds, IWorldAccessor world) in VintagestoryLib\Common\EventManager.cs:line 134
at Vintagestory.Server.CoreServerEventManager.TriggerGameTick(Int64 ellapsedMilliseconds, IWorldAccessor world) in VintagestoryLib\Server\ServerEventManager.cs:line 145
at Vintagestory.Server.ServerMain.Process() in VintagestoryLib\Server\ServerMain.cs:line 882
Necromunger, May 22nd at 1:14 AM

I have been looking for something like this for a very long time. Thankyou!

DanaCraluminum, May 21st at 10:42 AM

why there is no NuGet package?

Pixnop , May 21st at 2:34 PM
@DanaCraluminum: why there is no NuGet package?

Hi! It's planned, I'll try to add it tonight if I have time. Versions will be tagged as -alpha for now since the API is still moving, but it should make depending on Manifold a lot easier. I'll update here once it's up on nuget.

Pixnop , May 22nd at 5:29 PM
@DanaCraluminum: why there is no NuGet package?

It is up now