CarryOnLib

CarryOnLib is the shared API and library behind the CarryOn mod. It provides stable interfaces and core models so modders can interact with carryable blocks, entities and inventories - and so any mod can include optional CarryOn functionality.

Carry On 2.0 depends on CarryOnLib, so install it alongside Carry On. Other mods can list CarryOnLib as a dependency to use carry functionality when Carry On is present; if Carry On is not loaded, CarryOnLibSystem.CarryManager is null and integrating mods should check for that.

CarryOnLib 1.0.0-rc.1 - release candidate

This is the first release candidate of the CarryOnLib 1.0 line. It requires Vintage Story 1.22.0 or newer. As a release candidate the public API can still change before 1.0.0, and mods built against the 1.0.0-pre.* releases must update (see Breaking changes below).

What's new in 1.0

• Carryable entities. Pick up whole entities with ICarryableEntityPickupHandler, spawn them back with ICarryEntitySpawnerFactory (registered on ICarryManager for dependency injection), and attach single carried blocks to entity slots (boats, packs) with ICarryableEntitySlotHandler.
• Full spawn context. Spawner factories receive the carried block, owner uid, position, block position, dropped-vs-placed state, and an optional hit face/position via EntitySpawnContext.
• Spawn helpers. SpawnPositionHelper (face-aware, collision-aware placement with depenetration), GravitySpawnHelper (gravity drop resolution), and the shared BlockCollisionUtils.
• Language-aware errors. CarryErrorHelper resolves a full language key verbatim and prefixes bare codes with carryon:, then shows or sends the message in the player's language.
• Priority permission handlers. CarryEvents.RegisterCheckPermissionAt(priority, handler) runs handlers in ascending priority order; the first non-null result decides.
• Protected carried-data reads. CarriedBlockTreeSerializer.DeserializeSafe returns CarriedBlockReadResult (Ok / Empty / Failed) with stored-code recovery, so a present-but-unreadable carry - for example from a removed mod - is never silently dropped.
• Manager additions. ICarryManager gains GetCarriedReadResult, IsCarrySlotOccupied, GetRenderableCarried and SetCarriedRaw (for unreadable carries), ground-storage bag entry points, entity transform group resolver registration, and registries for the handler families.
• Carried block additions. CarriedBlock gains SpawnerFactoryCode and SpawnAsEntityOnPlacement, persisted in carry state.

Breaking changes since 1.0.0-pre.*

• ICarryableTransfer becomes ICarryableBlockSlotHandler, with per-slot routing and validation (GetSlotIndex, IsValidSlot, IsSlotEmpty, IsSlotCarryable), a separate GetInteractDelay, and a Can*/Try* split.
• ICarryableEntityHandler splits into ICarryableEntityPickupHandler and ICarryEntitySpawnerFactory.
• Failure codes are now full language keys (for example mymod:slot-full); {0} placeholders are gone and the __continue__ sentinel is retired (__ignore__ / __default__ / __stop__ keep their meaning).
• The client no longer invokes Try*; the server re-validates authoritatively.
• ICarryManager.TryAttach / TryDetach (manager-level entity attach) are removed - use slot handlers.
• The CarryEvents.CheckPermissionAt C# event is removed - use RegisterCheckPermissionAt.
• IEntityTransformGroupResolver.GetCacheSignature is removed (the framework never read it).
• JsonHelper.TryGetValueTrimmedIgnoreCase / TryGetTrailingWildcardValue moved to WildcardMatcher.
• InventoryConverter conversions return null (not empty trees); BlockDroppedEventArgs is init-only.
• CarriedBlockReadResult / CarriedBlockReadStatus now live in CarryOn.API.Common.Models (moved out of CarryOn.Utility).

The full interface reference and step-by-step migration notes are in the CarryOnLib README.

Mods using CarryOnLib

• RackEmUp

Installation

1. Download CarryOnLib from this page.
2. If you use Carry On, download Carry On as well.
3. Open the mod folder from the in-game Mod Manager and copy the .zip file(s) in without extracting them.

Alternatively, use the Vintage Story Launcher to manage the mod.

For modders

Reference CarryOnLib in your mod project to access carry operations via ICarryManager, listen for carry events, implement custom transform group resolvers, implement ICarryableBlockSlotHandler for block entity inventory integration, use the inventory conversion and attribute tree utilities, and register carryable block behaviors.

Note: CarryOnConfig, CarryCodes and related configuration types live in the CarryOn mod itself, not in CarryOnLib. CarryOnLib provides CarryConstants as a small subset of codes for modder use.

Source, interface reference and issues: GitHub.

Support the author

Please support my caffeine consumption