CatLib

Foundation library for Cat Mail Co. mods.

CatLib does nothing to the game by itself. Mods are built on top of it, so when a mod needs it, your mod manager installs it for you.

For players

• Mods tab. Open Settings and you'll find a Mods tab with every installed mod, its icon, author, version and what it does. Change settings right there and most of them apply straight away. Point at a setting to see what it does and what the default is. Each mod has a reset button.
• Your language. Mods use the game's language, all 13 of them. If a translation reads wrong, you can fix it yourself with a small file, no need to wait for an update.
• Playing with friends. In the lobby, every player's mods are listed next to the host's, so you can see who has what. If someone is missing a mod, that mod is paused for the game instead of breaking it, and comes back once everyone has it.
• Your saves are safe. Mods keep their data in their own files next to your save. The game's save itself is never touched, so removing a mod leaves it exactly as it was.
• When the game crashes. A small window tells you what happened and keeps a report you can send to the mod's author. It also notices when the game freezes while quitting. This part is the CatLib Crash Watcher package, installed together with CatLib.
• Your own content. Some mods read packs you make yourself, like the stamp packs of Custom Stamps: a folder with pictures and a small text file. Every pack gets its own card on the Mods tab with its pictures, can be turned off, and one button builds a Thunderstore package of it to share.
• After a game update. A small paper label in the corner of the main menu shows the CatLib version; point at it to see your mods. If the game has been updated and CatLib hasn't caught up yet, or your game is older than CatLib expects, it says so there.

CatLib's own settings are on the Mods tab too: the crash window, and whether a player with other mods can stay in your lobby.

For mod developers

Everything below is documented in the repository.

• Settings. CatSettings.For(this) declares settings that apply live while the game runs and appear on the Mods tab with translated names, sliders, dropdowns and restart marks. Session settings come from the host.
• Translations. Put Lang/en.json, Lang/ru.json and so on next to the project. Plural forms, the game language and translation files from players are handled, and a check reports missing or broken texts.
• Multiplayer. CatNetwork.Declare puts your mod into the compatibility check over Steam. You get the session roster, paused mods when someone lacks yours, and CatNetwork.Channel for messages between your mod's copies.
• Saves. CatSaves.For(this) stores data per game save, written with the game's save, atomically and with a backup. Only the host writes. The game's save file is never opened.
• Game events. Loading, saving, the network and the player as plain .NET events, with their real order documented.
• UI. Notifications.Show for messages in the game's style, FoldoutList for lists built from the game's own UI, HudLayer and CountTable for small tables on the screen during a level.
• Parcels and storages. CatParcels lists every parcel of the level with its marks, size, damage and place, for every player. StoreGrid gives the grids of shelves and parcels, computed like the game does.
• Patching. CatPatches installs Harmony patches all or nothing and turns them off after repeated errors; CodePatch changes a few bytes of the game's code, found by a pattern and checked before every change.
• Game build. GameCompatibility.Status tells whether the running game is the build CatLib was made for.
• Assets. ImageData reads PNG and JPG images, trims, scales and outlines them and makes textures and sprites; GameImages copies pictures of the game. Content packs: folders of files that players make for your mod, each with a card on the Mods tab, previews, a toggle and a Thunderstore package from one button.
• Developer menu. DevMenu.Command adds your tools to one in-game panel on the ` key.
• Crash reports. Crashes in your mod come with a report, both logs, a memory dump and the stacks of all threads with the names of the game's methods.

Depend on CatLib-CatLib-<version> in your manifest. Start with Writing a mod.

Found a bug?

Report it on GitHub. Tell us what you did, which mods you had, and whether you were playing alone, hosting or joining.

• The game crashed: press Open the report folder in the crash window, zip that folder and attach it. Older reports are in BepInEx/CatLib/Crashes. Nothing is sent anywhere by itself.
• Something else went wrong: attach BepInEx/LogOutput.log before you start the game again, because the next start overwrites it.

Changelog

CatLib follows semantic versioning. The mods built on it, Boat Tweaks, Shelf Labels, Better Repair, Parcel Board, Stack it!, Too Late and Custom Stamps, and CatLib Crash Watcher have their own versions and changelogs.

0.7.2

• Updated BepInEx dependency version.

0.7.1

Released together with a new mod, Custom Stamps 0.1.0, with Too Late 0.1.1, CatLib Crash Watcher 1.1.0 and CatLib Tests 0.7.1. For players: your own stamps from folders of pictures, crash reports that name the method a crash happened in, a single player game that loads without the Steam network, and no more crash when Steam shuts down soon after a player left. For mod authors: the first part of the asset API with PNG and JPG images, pictures of the game and content packs of players, galleries and buttons on the Mods tab. Checked with two game copies on one computer.

Added

• Assets, the first part: see Assets.
  • ImageData in CatLib.Assets reads PNG and JPG files on any thread, trims, scales, pads and outlines images, makes collages, writes PNG and makes textures and sprites. JPG files are read by CatLib's own decoder: baseline and progressive, gray, color and CMYK, turned by their EXIF orientation. Interlaced PNG files are read too, also by UiSprites.FromPng.
  • GameImages finds a sprite or a texture the game has loaded by its name and copies the pixels of a sprite, a texture or a part of it into an ImageData.
  • Content packs: folders in BepInEx/plugins with a small text file that a mod reads. Every pack gets its own card on the Mods tab right below its mod, with its icon, a toggle, a button that opens its folder and one that builds a Thunderstore package into BepInEx/CatLib/Packages. Packs take part in the session check like mods, so a pack that not every player has can be paused.
  • ThunderstorePackage checks names, versions and descriptions the way Thunderstore does and writes a package of any folder.
• Cards on the Mods tab can show galleries of images and buttons like the game's key binding buttons next to settings, a summary like "12 stamps" instead of the number of settings, and follow another card with ParentId. See Mods tab items.
• New mod: Custom Stamps 0.1.0, packs of your own decorative and weight stamps made from PNG or JPG images. Every player needs the same packs.
• The setting CrashSymbols in [Diagnostics] lets the crash watcher download the public symbols of Unity and Windows, so crash reports name the functions of UnityPlayer.dll and other modules; on by default, in every language.
• CatNetwork.IsRemotePlayer(clientId) tells whether a connected client is another player, and CatNetwork.IsWithoutSteamNetwork whether the game runs its session without the Steam network. See Without the Steam network.
• The crash window names the method a crash happened in and the nearest method of the game on that thread, with "Method" and "Game code" lines in the details in every language. When the crash is inside Windows or the C runtime, for example in RaiseException, a "Called from" line names the code that called it. The names and the stacks of every thread come from CatLib Crash Watcher 1.1.0, see Crash reports.

Changed

• Documentation for mod authors: a documentation index with where to start, a new page Core helpers (logging, the frame loop, the main thread, safe events, game state, the game build, notifications, 2D arrays), "I want to…" tables in Writing a mod, Multiplayer compatibility and Core helpers, diagrams of the handshake and of starting a level, and out-of-date parts fixed: session settings, late join, keys of the developer tools.
• The README lists the mods with their icons and who in a lobby needs them, and the documentation as a table. The developer menu commands moved to Tests and developer tools. Every package links to its Thunderstore page, and the game badge to its Steam page.
• The crash watcher has a README for developers: how CatLib starts it, its parts and how to build it.
• The Thunderstore example in Writing a mod depends on CatLib-CatLib, the real package name.
• Before the game shuts Steam down, CatLib waits until the sessions it closed in the last minute are gone, at most 6 seconds, instead of a fixed 5 seconds after a player left, and writes the state of each such session to the log before and after waiting.

Fixed

• A player who left a game with others crashed on the way to the menu, and the host crashed when quitting soon after a player left. Before Steam shuts down, CatLib asks Steam about its recently closed sessions, and it did it through the game's own GetSessionConnectionInfo. Interop gives that method 8 bytes for each struct it returns, Steam wrote several hundred, and the stack of the call was overwritten. CatLib now calls the Steam function itself and does not ask for those structs. Writing a mod warns about such methods.
• When Steam cannot reach its relay network, the game plays over a socket on the computer and gives its own client the id 1. CatLib took that client for a player without CatLib, paused every mod that all players need and asked Steam for its name twice a second, which filled the log with Null. Now it leaves such a client alone and writes once that the game runs without the Steam network.

0.7.0

Released together with three new mods, Parcel Board 0.1.0, Stack it! 0.1.0 and Too Late 0.1.0, and with Boat Tweaks 0.3.1, Shelf Labels 0.2.1, Better Repair 0.1.1 and CatLib Crash Watcher 1.0.2. For players: the new mods, what every mod does on its card on the Mods tab, a paper label with the version in the main menu, no more crashes of the host in steamclient64.dll after a player leaves, and mod messages that keep arriving after a few quiet minutes. For mod authors: CatParcels, StoreGrid, HudLayer, CountTable, CatPatches, CodePatch, public GameEventStream.Publish, CatNetwork.PlayerName and a clearer developer menu. Checked with two game copies on one computer.

Added

• CatParcels in CatLib.Game: every parcel of the level as a ParcelInfo with its destination, marks, size, footprint on a shelf, weight, damage, missing stamps and place, the game's stamp icons and region names, on the host and on the other players, whose game keeps no list of parcels. See HUD and parcels.
• HudLayer in CatLib.UI: a layer on the game's HUD during a level that steps aside for the game's menus, and texts in the game's font.
• CountTable and CountList in CatLib.UI: a table and a list of icons and counts on a rounded, almost clear plate, with light outlined texts like the game's hints, rows with an icon and a faint hint, rows wrapped into columns and tables of the same height side by side; UiSprites.RoundedPlate, UiSprites.FromPng and UiSprites.FromResource.
• New mod: Parcel Board 0.1.0, counts of the parcels in the level by destination, per mark and size, only for the player who has it.
• CatPatches in CatLib.Patching: Harmony patches of a mod installed whole or not at all, each method and handler checked first; errors in handlers are written a few times, counted, and turn the patches off after 50. See Patching the game.
• StoreGrid and GridView in CatLib.Game: the grids of storages and parcels, free cells, roots of stacks and the cells a parcel takes, computed like the game does. See Storages, with how the game stacks parcels and checks their marks.
• Il2CppArrays.TryGet reads one cell of a two-dimensional IL2CPP array.
• New mod: Stack it! 0.1.0, parcels that stand across the joint of level parcels and fall when one is taken away. Every player needs it.
• CodePatch and BytePattern in CatLib.Patching: a few bytes of the game's code changed in place, found by a byte pattern and checked before every change, for rules compiled into a method where no Harmony patch reaches. See Patching the game.
• GameEventStream.Publish is public: mods add their own steps to the timelines.
• CatNetwork.PlayerName gives the Steam name of a player.
• New mod: Too Late 0.1.0, joining a game in progress and up to 8 players. Only the host needs it.
• The mod card on the Mods tab shows the mod's description under the author, across the whole card: mod.description from the catalog, else the description of the Thunderstore manifest. CatSettings.Description sets it from code. Every mod here has it in all 13 languages.

Changed

• The developer menu is easier to read and to find things in: the groups are a list on the left with the number of their commands, the commands on the right with a clear highlight and on/off marks for toggles, long lists scroll with the selection, the result of the last command shows its time and is red when it failed. Home, End, Page Up and Page Down work, and a click selects a group or runs a command where the cursor is free. See Developer menu.
• The CatLib version in the corner of the main menu is a paper label now, on the paper and tape of the game's lobby, with the CatLib icon and a slight tilt. Pointing at it straightens it and unfolds the game build it was made for and the list of installed mods. When the game build does not match, the label turns warm, shows the warning in red ink and gets a red stamp, pressed on as the menu opens.
• The mod list on the Mods tab has two lines per mod: the name, and under it the version and the number of settings, or a mark such as "needs a restart" in its place. Icons are bigger, their empty edges are cut off and dense icons are drawn a little smaller, so every icon looks about the same size.
• Tests started in a level open the game's pause menu and its settings to reach the Mods tab, and stop waiting for the tab when it did not appear earlier in the run, instead of waiting for it in every test.
• Tests of a mod that is not installed in the game are skipped and counted apart, instead of erroring on the missing assembly.

Fixed

• The game could crash in steamclient64.dll when it quit with a CatLib channel session open. CatLib now closes its sessions right before the game shuts Steam down (a patch of SteamAPI.Shutdown), when returning to the menu and when quitting. When a player left less than 5 seconds before, it waits for the rest of those 5 seconds first: the host crashed in steamclient64.dll when it quit or returned to the menu a moment after a player left, while Steam was still closing the session with that player.
• Mod messages sent after a few quiet minutes did not arrive, for example the cardboard stock of Better Repair at a new day: Steam closes an idle session and the other side has to accept the new one. CatLib now keeps accepting the host and every player for the whole session.
• When the game cannot decode PNG images, CatLib says so once and decodes every icon itself, instead of trying the game first for each image.

0.6.2

The first release on Thunderstore, together with CatLib Crash Watcher 1.0.0, Boat Tweaks 0.3.0, Shelf Labels 0.2.0 and Better Repair 0.1.0.

Changed

• The crash watcher is its own Thunderstore package, CatLib-CrashWatcher, with its own version and changelog, so a release of CatLib does not change the program and its review stays small. CatLib depends on it, so a mod manager installs both.
• CatLib finds CatLib.CrashWatcher.exe next to CatLib.dll or in any folder of BepInEx/plugins, and the log names its version and path.
• The session file starts with a format number. A watcher that reads an older format says in the report and in watcher.log that it should be updated, and the report names the version of the watcher.

0.6.1

Released together with Boat Tweaks 0.3.0, Shelf Labels 0.2.0 and Better Repair 0.1.0. For players: works with the game update of October 2026, the game no longer hangs when quitting after single player, the main menu shows the CatLib version and warns when the game and CatLib do not match, crash reports catch a hang while quitting. For mod authors: Thunderstore packages for CatLib and every mod, GameCompatibility.

Added

• The main menu shows the CatLib version in the bottom right corner. CatLib knows the game build it is made for (October 2026, Steam build 25651540) and compares it with the running game by the build date in the game version. When the game is newer, the corner asks to look for a CatLib update; when it is older, to update the game. Pointing at the corner shows both build dates, or the number of mods when everything matches. Mods can read the same check from GameCompatibility. The log and crash reports name the result.
• Crash reports catch a hang while quitting: when the game still runs 8 s after it began to quit, the crash watcher keeps a dump of every thread, and the report and the window say the game stopped responding while quitting. See Crash reports.
• Text settings on the Mods tab title the virtual keyboard of Steam Deck and Big Picture with the setting's name.
• Thunderstore packages: dotnet build -p:CatLibThunderstore=true packs CatLib, CatLib.Tests and every mod with Thunderstore/manifest.json into Thunderstore-build/, a folder and a zip per package with the manifest, icon, README, changelog and plugins. The build checks the manifest and the icon by Thunderstore's rules (CATLIB002, CATLIB003, CATLIB004), points relative links of the README and the changelog to the repository on GitHub, and warns when the changelog does not start with the package version. See Thunderstore package.
• Mods keep their changes in CHANGELOG.md next to README.md, and a README for players in Thunderstore/README.md.
• CatLib.Tests is its own package that depends on CatLib and the three mods.
• Developer menu of CatLib.Tests: Crash → Hang on quit, UI → Version badge preview.

Changed

• Works with the game update of October 2026 (Unity 6000.3.23, single player without internet).

Fixed

• The game could hang while quitting after a single-player game: since the October update the game's own UDP client of single player keeps waiting for a packet on a worker thread after the level is left, and the game waits for that thread forever when it quits. CatLib closes the socket of a game network client when the game replaces it and when the game quits, so the thread ends.

0.6.0

For players: the players' mods in the lobby with paused mods instead of disconnects, mod icons and authors on the Mods tab, gamepad navigation, every text in all 13 languages of the game, memory dumps and a translated crash window. For mod authors: the session roster, FoldoutList, texts loaded from Lang/*.json without code, plural forms, translation files and checks. New mod: Better Repair. Checked with two game copies on one computer.

Added

• Crash reports: when the game closes unexpectedly, a small window names what happened with a different cozy phrase every time, and a report folder keeps the report, both logs and the recorded session in BepInEx/CatLib/Crashes. Works for native crashes too, since the window comes from CatLib.CrashWatcher.exe, a separate program next to CatLib.dll. Can be turned off with CrashWindow in section [Diagnostics]. See Crash reports.

• Developer menu of CatLib.Tests: the Crash group with a native crash on the game thread, a native crash on a worker thread and a managed crash.

• Session roster: the host keeps every player's versions, mods and status and sends it to everyone (CatNetwork.Roster, CatNetwork.RosterChanged). Protocol 5.

• Paused mods: a RequiredOnAll mod runs only while every player has it in a compatible version, otherwise it is paused for everyone and the game runs as without it (CatNetwork.IsActive, CatNetwork.ActiveModsChanged). Boat Tweaks, Shelf Labels and Better Repair pause.

• Players' mods in the lobby: a folding list at the top of the lobby for every player, the host included, with each player's mods, versions and what to do about differences. The host switches what happens to players with other mods right there.

• Mod icons in the Mods tab: icon.png next to the mod's DLL or in its Thunderstore package folder is shown left of the mod's name and at the top of its settings (CatSettings.IconPath), a question mark stands in for a missing one. Every plugin project copies its icon.png next to its DLL and into the game; without one the build warns (CATLIB001) and still succeeds. The log names the icon of every mod or where it was looked for.

• The Mods tab: the author under the mod's version (CatSettings.Author, from the Thunderstore package folder or the assembly company), a short mark under a mod's name when it is paused in this game, waits for a restart or has settings set by the host, CatLib first in the list, and keyboard and gamepad navigation between the list, the settings and the reset button. A text setting starts typing on submit instead of on selection, so a gamepad moves past it. The mod list and the settings scroll to follow the selection.

• FoldoutList in CatLib.UI: a folding list built from the game's UI pieces, for mods too. See Folding lists.

• CatNetwork.IncompatiblePlayers reads and changes what the host does with incompatible players; a change applies to players already in the session.

• Developer menu of CatLib.Tests: Session roster and Lobby dump.

• Localization: texts in Lang/*.json are embedded by the build and loaded by CatSettings.For without code. Plural forms by the Unicode rules of each language (Plural, PluralRules), LocalText handles, CatLanguage.Changed, CatLanguage.GameLanguages and the game's own texts with CatLanguage.Game(term). A translation that cannot be filled in shows English instead of failing.

• Translation files of players in BepInEx/config/CatLib/Translations/<mod id>/<language>.json win over built-in texts. The developer menu writes a translation report, exports texts for translators and reloads the files. TranslationCheck finds missing, unknown and broken texts; the log lists them at the main menu. See Localization.

• Memory dumps: the crash watcher follows the game like a debugger and writes crash.dmp into the report folder at the moment of the crash, without Windows Error Reporting settings. The module, offset and thread of the crash come from the watcher itself, the report says whether it was the game thread and what memory access failed. Crashes that Unity closes itself on the game thread are caught the moment the exception is raised. The text of an unhandled .NET exception comes from CatLib when Windows logs nothing. Setting CrashDumps, on by default.

• The crash window in every game language, with texts from CatLib's translations; report.txt is always in English for the mod authors.

• CatLib, Better Repair, Boat Tweaks and Shelf Labels in every language of the game: English, French, Italian, German, Spanish, Brazilian Portuguese, Polish, Simplified and Traditional Chinese, Japanese, Korean, Ukrainian and Russian.

Changed

• The scrollbars of the Mods tab are copies of the game's own.
• A player that stays after a failed check gets the session settings of the mods it shares with the host.
• Protocol 5: players with CatLib 0.5.0 are told that their CatLib differs.
• CatLib's own texts live in src/CatLib/Lang/*.json (catalog catlib.core, keys ui.*), so they can be translated and fixed by files like any mod's.
• Notifications wrap Chinese and Japanese between characters, keep Korean words whole and split at a full-width colon.
• Mods no longer load their texts themselves and have no EmbeddedResource line for Lang.
• Mods in mods/ follow one folder layout (Settings, Logic, Scene, Sync, Data, Patches), with namespaces that follow the folders. See Writing a mod.

0.5.0

For mod authors: localization, mod data in game saves, messages between mods, a developer menu, safe access to two-dimensional IL2CPP arrays, player notifications and the session role. Checked with two game copies on one computer, including Boat Tweaks and Shelf Labels in multiplayer.

Added

• CatLib.Localization: a translation catalog per mod (CatLocalization.For, CatSettings.Texts) loaded from JSON files or embedded resources, lookup with fallback from a regional language to its base language and to English, CatLanguage.Current following the game language.
• The Mods tab takes the mod name, section names, setting labels, descriptions and dropdown values from the mod's catalog, and rebuilds its texts when the game language changes.
• CatLib.Saves: mod data per game save in CatLibSaves next to the game's save folder (CatSaves.For, ModSave). Written only after the game saved successfully and only by the host, atomically with a backup; damaged files are set aside, newer data is never overwritten, a new save never inherits data left under its name. See Mod data in game saves.
• Messages between mods: CatNetwork.Channel with SendToHost, Broadcast, SendTo, PeerJoined and PeerLeft. Only between the host and players that share the mod, with local delivery in single player and on the host, and a limit of 60 messages per second per player on the host. See Mod messages.
• Developer menu in CatLib.DevTools: one key opens a keyboard driven panel with commands mods register with DevMenu.Command and DevMenu.Toggle. See Developer menu.
• Il2CppArrays in CatLib.Il2Cpp: reads and writes two-dimensional IL2CPP arrays that interop only exposes as Il2CppObjectBase. Every call checks the array rank, the element size against the requested type and the bounds.
• Notifications.Show in CatLib.UI shows a mod's message as a game notification in a level and in the Mods tab status line.
• CatNetwork.Role (Offline, Host, Client) and CatNetwork.IsAuthority for mods whose decisions must match for every player.
• Setting<T>.LocalValue can be written from code: the file is saved and appliers run.
• SaveEvents in CatLib.Game.Events (SaveFileSelected, GameSavingStarted, SuccessfullySaved, UnsuccessfullySaved) and the current save in GameInfo (SaveDirectory, SaveFileName, SaveFilePath, IsNewSave, IsLoadingSave).
• The build copies plugins to a second game copy too when SecondGameDir is set in GamePaths.props.
• Developer tools in CatLib.Tests, all in the developer menu: entity dump, settings menu dump, notification preview, mod message probe, Steam self check, the list of visible Steam players and joining the first host.
• Documentation: Writing a mod, Localization, session role in Multiplayer compatibility.

Changed

• Network protocol 4: the verdict lists the mods both sides share. Players with an older CatLib are reported as incompatible.
• Notifications are wrapped by the width the game's notification font measures, not by a character count, so a line never runs past the screen edge when the notification settles. Lines are not broken inside quotes.
• When a client leaves through a game restart, the host's session settings stay until the main menu is loaded, so mods do not react to setting changes while the level is being destroyed.
• The context line of the Mods tab holds three lines, so long descriptions keep their default value line.

Fixed

• A crash when leaving a level in multiplayer: the Steam channel sessions of CatLib stayed open while the game shut its networking down. They are now closed when a player leaves, when the session stops and after the Steam self check.
• The scrollbars of the Mods tab stretch along their pane like the game's own, instead of sitting as a small square in the corner.

0.4.0

Multiplayer compatibility: a handshake over its own Steam channel checks that players have compatible mods, session settings take the host's values on clients, incompatible players are warned or disconnected with a clear message in the lobby and in a level. Fixed a crash when leaving a level after opening the Mods tab from the pause menu.

0.3.0

The Mods tab in the game's settings menu, in the main menu and in the pause menu: a list of mods, a card per mod, rows for every setting with toggles, sliders, dropdowns and text fields, player messages in English and Russian.

0.2.0

Live settings: settings declared in code, applied at once and whenever the file changes, value checks, settings that need a restart.

0.1.0

Game event bridge, main thread dispatcher, frame loop, logging and the in-game test runner.