@zebbedaja/er-save-parser 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Zsebedits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# ER Save Parser
+
+Parse Elden Ring PC save files into structured TypeScript/JavaScript objects.
+
+## Features
+
+- **Full save slot parsing** — all 10 slots with character data, attributes, Flask counts, regions visited, death count, and more
+- **Event flag decoding** — track boss defeats, quest progress, and ending states using bit-level BST map lookups
+- **Settings extraction** — camera, audio, HDR, ray tracing, and other game settings
+- **Profile summaries** — character name, level, play time, starting gift, and archetype per slot
+- **Zero runtime dependencies** — pure ESM, no bundled dependencies
+
+## Installation
+
+```bash
+npm install @zebbedaja/er-save-parser
+```
+
+## Usage
+
+```typescript
+import { parse, type Save, type Slot, type Character } from '@zebbedaja/er-save-parser'
+import { readFileSync } from 'fs'
+
+const buffer = readFileSync('ER0000.sl2').buffer
+const save: Save = parse(buffer)
+
+console.log(save.steamId)
+console.log(save.settings?.hud)
+
+const slot: Slot | undefined = save.slots?.[0]
+const char: Character | undefined = slot?.character
+
+if (char) {
+  console.log(char.characterName)    // "Tarnished"
+  console.log(char.level)            // 150
+  console.log(char.runes)            // 1234567
+  console.log(char.strength)         // 45
+  console.log(char.faith)            // 30
+  console.log(char.arcane)           // 20
+}
+
+// Check boss defeats
+slot?.eventFlags?.forEach((flag) => {
+  if (flag.state) {
+    console.log(`${flag.name} ✓`)
+  }
+})
+```
+
+### Reading from a file in the browser
+
+```typescript
+async function parseFromFile(file: File): Promise<Save> {
+  const buffer = await file.arrayBuffer()
+  return parse(buffer)
+}
+```
+
+## Parsed Data
+
+### `Save` (root)
+| Field | Type | Description |
+|---|---|---|
+| `magicBytes` | `string` | Hex string, always `424e4434` (`BND4`) |
+| `checksum` | `string` | Save file checksum |
+| `version` | `number` | Save file version |
+| `steamId` | `string` | Associated Steam64 ID |
+| `settings` | `Settings` | Game settings (camera, audio, HDR, ray tracing…) |
+| `activeProfiles` | `number[]` | Active profile flags per slot |
+| `profileSummaries` | `ProfileSummary[]` | Name, level, play time per slot |
+| `slots` | `Slot[]` | Up to 10 save slots (see below) |
+
+### `Slot`
+| Field | Type | Description |
+|---|---|---|
+| `checksum` | `string` | Slot-level checksum |
+| `version` | `number` | Slot version |
+| `mapId` | `string` | Current location map ID (hex) |
+| `character` | `Character` | Full character data |
+| `regions` | `object` | Regions visited ({ `regionCount`, `regionIds` }) |
+| `totalDeathCount` | `number` | Cumulative deaths across playthroughs |
+| `characterType` | `number` | Save type indicator |
+| `inOnlineSessionFlag` | `number` | Online session flag |
+| `lastRestedGrace` | `number` | Last grace site rested at |
+| `notAloneFlag` | `number` | Co-op phantoms present |
+| `inGameCountdownTimer` | `number` | Online timeout countdown |
+| `eventFlags` | `EventFlag[]` | Boss defeats, quest progress, endings |
+
+### `Character`
+| Field | Type | Description |
+|---|---|---|
+| `characterName` | `string` | In-game name |
+| `level` | `number` | Character level |
+| `runes` | `number` | Current runes (currency) |
+| `runesMemory` | `number` | Maximum runes that can be held |
+| `hp` / `maxHp` / `baseMaxHp` | `number` | HP current / max / base max |
+| `fp` / `maxFp` / `baseMaxFp` | `number` | FP current / max / base max |
+| `sp` / `maxSp` / `baseMaxSp` | `number` | Stamina current / max / base max |
+| `vigor` / `mind` / `endurance` | `number` | ATTRIBUTE: Vigor / Mind / Endurance |
+| `strength` / `dexterity` / `intelligence` / `faith` / `arcane` | `number` | ATTRIBUTE: STR / DEX / INT / FTH / ARC |
+| `poisonBuildup` | `number` | Current poison status effect |
+| `rotBuildup` | `number` | Current scarlet rot status effect |
+| `bleedBuildup` | `number` | Current hemorrhage status effect |
+| `frostBuildup` | `number` | Current frozen status effect |
+| `madnessBuildup` | `number` | Current madness status effect |
+| `bodyType` | `number` | Body type selection index |
+| `voiceType` | `number` | Voice type selection index |
+| `archetype` | `number` | Starting class selection index |
+| `gift` | `number` | Starting gift selection index |
+| `maxCrimsonTearFlaskCount` | `number` | Flask of Crimson Tears quantity |
+| `maxCeruleanTearFlaskCount` | `number` | Flask of Cerulean Tears quantity |
+| `additionalTalismanSlotCount` | `number` | Extra talisman slots unlocked |
+| `summonSpiritLevel` | `number` | Spirit Ash upgrade level |
+| `aquiredProjectilesCount` | `number` | Acquired projectile count |
+
+### `Settings`
+| Field | Type | Description |
+|---|---|---|
+| `cameraSpeed` | `number` | Camera rotation speed |
+| `brightness` | `number` | Display brightness |
+| `musicVolume` | `number` | Music volume |
+| `soundEffectsVolume` | `number` | SFX volume |
+| `voiceVolume` | `number` | Dialogue/voice volume |
+| `master_volume` | `number` | Master volume |
+| `hud` | `number` | HUD visibility |
+| `subtitles` | `number` | Subtitle toggle |
+| `displayBlood` | `number` | Gore/display filter |
+| `hdr` | `number` | HDR toggle |
+| `is_raytracing_on` | `number` | Ray tracing toggle |
+| `autotarget` | `number` | Auto-aim toggle |
+| `cameraXAxis` / `cameraYAxis` | `number` | Camera axis configuration |
+| `perform_matchmaking` | `number` | Online matchmaking toggle |
+| ... | | (and more) |
+
+### `EventFlag`
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Human-readable name (e.g., `"Godrick the Grafted"`) |
+| `id` | `number` | Internal game event ID |
+| `category` | `string` | Category: `boss`, `ending`, `quest`, etc. |
+| `location` | `string` | Location (if applicable) |
+| `state` | `boolean` | `true` if triggered |
+
+## Error handling
+
+```typescript
+try {
+  const save = parse(buffer)
+} catch (error: unknown) {
+  if (error instanceof Error) {
+    console.error('Failed to parse save file:', error.message)
+  }
+}
+```
+
+The parser will throw if:
+- The file magic bytes don't match `BND4`
+- Event flags reference blocks not found in the BST map
+- Calculated byte positions exceed save data bounds
+
+## Development
+
+```bash
+npm install       # Install dependencies
+npm run test      # Run Vitest suite
+npm run typecheck # Run TypeScript type check
+npm run build     # Bundle with tsdown
+npm run dev       # Watch mode
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,145 @@
+//#region src/types.d.ts
+interface Save {
+  magicBytes?: string;
+  checksum?: string;
+  version?: number;
+  slots?: Slot[];
+  steamId?: string;
+  settings?: Settings;
+  activeProfiles?: number[];
+  profileSummaries?: ProfileSummary[];
+}
+interface Settings {
+  cameraSpeed?: number;
+  controllerVibration?: number;
+  brightness?: number;
+  unk0x3?: number;
+  musicVolume?: number;
+  soundEffectsVolume?: number;
+  voiceVolume?: number;
+  displayBlood?: number;
+  subtitles?: number;
+  hud?: number;
+  cameraXAxis?: number;
+  cameraYAxis?: number;
+  toggle_auto_lockon?: number;
+  camera_auto_wall_recovery?: number;
+  unk0xe?: number;
+  unk0xf?: number;
+  reset_camera_y_axis?: number;
+  cinematic_effects?: number;
+  unk0x12?: number;
+  perform_matchmaking?: number;
+  unk0x14?: number;
+  unk0x15?: number;
+  manual_attack_aim?: number;
+  autotarget?: number;
+  launchsettings?: number;
+  send_summon_sign?: number;
+  unk0x1a?: number;
+  hdr?: number;
+  hdr_adjust_brightness?: number;
+  hdr_maximum_brightness?: number;
+  hdr_adjust_saturation?: number;
+  unk0x1f?: number;
+  master_volume?: number;
+  is_raytracing_on?: number;
+  mark_new_items?: number;
+  show_recent_tabs?: number;
+}
+interface ProfileSummary {
+  name?: string;
+  level?: number;
+  secondsPlayed?: number;
+  runesMemory?: number;
+  mapId?: string;
+  unk0x34?: number;
+  bodyType?: number;
+  archetype?: number;
+  startingGift?: number;
+}
+interface Slot {
+  checksum?: string;
+  version?: number;
+  mapId?: string;
+  character?: Character;
+  regions?: {
+    regionCount?: number;
+    regionIds?: number[];
+  };
+  totalDeathCount?: number;
+  characterType?: number;
+  inOnlineSessionFlag?: number;
+  characterTypeOnline?: number;
+  lastRestedGrace?: number;
+  notAloneFlag?: number;
+  inGameCountdownTimer?: number;
+  eventFlags?: EventFlag[];
+}
+interface Character {
+  unk0x0?: number;
+  unk0x4?: number;
+  hp?: number;
+  maxHp?: number;
+  baseMaxHp?: number;
+  fp?: number;
+  maxFp?: number;
+  baseMaxFp?: number;
+  unk0x20?: number;
+  sp?: number;
+  maxSp?: number;
+  baseMaxSp?: number;
+  unk0x30?: number;
+  vigor?: number;
+  mind?: number;
+  endurance?: number;
+  strength?: number;
+  dexterity?: number;
+  intelligence?: number;
+  faith?: number;
+  arcane?: number;
+  unk0x54?: number;
+  unk0x58?: number;
+  unk0x5c?: number;
+  level?: number;
+  runes?: number;
+  runesMemory?: number;
+  unk0x6c?: number;
+  poisonBuildup?: number;
+  rotBuildup?: number;
+  bleedBuildup?: number;
+  deathBuildup?: number;
+  frostBuildup?: number;
+  sleepBuildup?: number;
+  madnessBuildup?: number;
+  unk0x8c?: number;
+  unk0x90?: number;
+  characterName?: string;
+  bodyType?: number;
+  archetype?: number;
+  unk0xb8?: number;
+  unk0xb9?: number;
+  voiceType?: number;
+  gift?: number;
+  unk0xbc?: number;
+  unk0xbd?: number;
+  additionalTalismanSlotCount?: number;
+  summonSpiritLevel?: number;
+  unk0xc0?: number;
+  maxCrimsonTearFlaskCount?: number;
+  maxCeruleanTearFlaskCount?: number;
+  aquiredProjectilesCount?: number;
+}
+interface EventFlag {
+  name: string;
+  id: number;
+  category?: string;
+  location?: string;
+  state?: boolean;
+}
+//#endregion
+//#region src/parser.d.ts
+declare function fn(): string;
+declare function parse(buffer: ArrayBuffer): Save;
+//#endregion
+export { Character, EventFlag, ProfileSummary, Save, Settings, Slot, fn, parse };