# cheahjs/palworld-save-tools architecture

> Architecture diagram of the GitHub repository cheahjs/palworld-save-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cheahjs/palworld-save-tools
- Repository: https://github.com/cheahjs/palworld-save-tools

## Overview

##### Project type and purpose
- This is an open-source, command-line tool and Python library (“palworld-save-tools”) for converting Unreal-based Palworld “.sav” save files into JSON and back, with deep parsing of game-specific structures.
- It is not a full-stack web app but a standalone CLI utility and library, intended for local file I/O, scripting, and embedding in other tools.

##### File structure
- Top-level:
- convenience_tools/convert.cmd – Windows batch wrapper
- palworld_save_tools/ – core Python package
- scripts/ – one-off Python utilities
- tests/ – pytest suite + testdata
- pyproject.toml & hatch.toml – packaging/config
- .github/workflows – CI (package, pre-merge, publish)
- Inside palworld_save_tools/:
- commands/convert.py, resave_test.py – CLI subcommands
- archive.py – compress/decompress save archives
- gvas.py – low-level Unreal “Gvas” reader/writer
- json_tools.py – JSON <-> intermediate data mappings
- palsav.py – top-level orchestrator (SAV ↔ JSON)
- paltypes.py – type definitions & custom decode paths
- rawdata/… – per-structure parsers (group, character, map, work, etc.)

##### README for additional insights
- Python 3.9+ requirement, no extra runtime dependencies by design.
- CLI usage: drag-and-drop or `python convert.py` with flags (`--to-json`, `--from-json`, etc.).
- Packaging via PyPI; CI does builds and publishes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layered Architecture for palworld-save-tools

    CLIEntrypoint["CLI Entrypoint\nconvert.cmd\nconvert.py"]:::cli
    CommandDispatcher["Command Dispatcher\n(convert.py)"]:::cli
    CoreEngine["Core Conversion Engine\npalsav.py"]:::core
    ArchiveLayer["Archive Layer\narchive.py"]:::parsing
    Gvasiolayer["GVAS I/O Layer\ngvas.py"]:::parsing
    DataParsing["Data Parsing Layer\nrawdata/*\npaltypes.py"]:::parsing
    SerializationLayer["Serialization Layer\njson_tools.py"]:::serialization
    FileIO["File I/O\nOS filesystem"]:::fs
    TestCI["Test & CI Infrastructure\ntests/\n.github/workflows/"]:::ci

    CLIEntrypoint -->|"invokes"| CommandDispatcher
    CommandDispatcher -->|"dispatches"| CoreEngine
    CoreEngine -->|".sav file"| ArchiveLayer
    ArchiveLayer -->|"raw bytes"| Gvasiolayer
    Gvasiolayer -->|"GVAS blocks"| DataParsing
    DataParsing -->|"Domain objects"| SerializationLayer
    SerializationLayer -->|"JSON text"| FileIO
    FileIO -->|"writes output"| CLIEntrypoint

    TestCI -->|"verifies roundtrip"| CoreEngine

    %% Click Events
    click CLIEntrypoint "https://github.com/cheahjs/palworld-save-tools/blob/main/convenience_tools/convert.cmd"
    click CLIEntrypoint "https://github.com/cheahjs/palworld-save-tools/blob/main/palworld_save_tools/commands/convert.py"
    click CommandDispatcher "https://github.com/cheahjs/palworld-save-tools/blob/main/palworld_save_tools/commands/convert.py"
    click CoreEngine "https://github.com/cheahjs/palworld-save-tools/blob/main/palworld_save_tools/palsav.py"
    click ArchiveLayer "https://github.com/cheahjs/palworld-save-tools/blob/main/palworld_save_tools/archive.py"
    click Gvasiolayer "https://github.com/cheahjs/palworld-save-tools/blob/main/palworld_save_tools/gvas.py"
    click DataParsing "https://github.com/cheahjs/palworld-save-tools/tree/main/palworld_save_tools/rawdata/"
    click DataParsing "https://github.com/cheahjs/palworld-save-tools/blob/main/palworld_save_tools/paltypes.py"
    click SerializationLayer "https://github.com/cheahjs/palworld-save-tools/blob/main/palworld_save_tools/json_tools.py"
    click TestCI "https://github.com/cheahjs/palworld-save-tools/tree/main/tests/"
    click TestCI "https://github.com/cheahjs/palworld-save-tools/tree/main/.github/workflows/"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef parsing fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef serialization fill:#FFDAB9,stroke:#333,stroke-width:1px
    classDef fs fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef ci fill:#D8BFD8,stroke:#333,stroke-width:1px
```
