tsacnhsaves

TypeScript library for reading Animal Crossing: New Horizons save files in the browser or Node. Ported from kwsch/NHSE (C#).

Targets the Web Crypto API, so it runs in browsers without a Node crypto polyfill. Read-only: decrypts save pairs, verifies hashes, and parses save structures (players, museum, recipes, villagers, buildings, achievements, turnips, etc).

Installation

pnpm add tsacnhsaves

Usage

import { loadHorizonSave } from 'tsacnhsaves';

// Map of relative path -> file bytes. Keys match the on-disk layout:
//   "main.dat", "mainHeader.dat",
//   "Villager0/personal.dat", "Villager0/personalHeader.dat", ...
const files = new Map<string, Uint8Array>();
files.set('main.dat', mainDat);
files.set('mainHeader.dat', mainHeader);
// ...add each Villager{N}/personal.dat + personalHeader.dat pair

const save = await loadHorizonSave(files);

console.log(save.versionString);
console.log(save.players[0].playerName, save.players[0].wallet);
console.log(save.museum.fish.filter(f => f.donated).length);

Lower-level building blocks (decrypt, loadFilePair, offset tables, per-structure readers) are exported from the package root.

License

GPL-3.0-or-later. This project is a port of NHSE by Kurt (kwsch), which is licensed under GPL-3.0.