Valheim Save Tools Python API

A Pythonic wrapper for Valheim Save Tools, providing an intuitive API to manipulate Valheim save files programmatically.

Features

✅ File Conversion - Convert between binary formats (.db, .fwl, .fch) and JSON
✅ Item Parsing - Parse and read Valheim inventory/item data from base64
✅ Global Keys Management - Add, remove, or list global keys (boss defeats, events)
✅ Structure Cleaning - Remove abandoned structures with configurable thresholds
✅ World Reset - Reset world to initial state while preserving progress
✅ Method Chaining - Fluent API for complex operations
✅ Context Manager - Automatic cleanup and resource management

Installation

pip install valheim-save-tools-py

Quick Start

from valheim_save_tools_py import ValheimSaveTools

vst = ValheimSaveTools()

# Convert to JSON and get data
data = vst.to_json("world.db")
print(f"World version: {data['version']}")

# Add boss defeat
vst.add_global_key("world.db", "defeated_eikthyr")

# Clean and reset with method chaining
vst.process("world.db") \
   .clean_structures(threshold=30) \
   .reset_world() \
   .save("cleaned_world.db")

# Context manager for automatic cleanup
with vst.process("world.db") as p:
    p.clean_structures()
    p.reset_world()

Documentation

• 🌐 Live Documentation - Full documentation site
• 📚 API Reference - Complete API documentation
• 📖 Usage Guide - Detailed usage patterns and examples
• 🎯 Examples - Working code examples

Common Use Cases

Convert Save Files

# Binary to JSON - returns parsed data
data = vst.to_json("world.db")
print(f"World has {len(data.get('globalKeys', []))} global keys")

# Also save to file
data = vst.to_json("world.db", "backup.json")

# JSON to Binary
vst.from_json("backup.json", "world.db")

Manage Boss Defeats

# List all global keys
keys = vst.list_global_keys("world.db")

# Add boss defeats
vst.add_global_key("world.db", "defeated_eikthyr")
vst.add_global_key("world.db", "defeated_gdking")

Clean Structures

# Clean with default threshold (25)
vst.clean_structures("world.db")

# Clean with custom threshold
vst.clean_structures("world.db", threshold=50)

Parse Inventory Items

from valheim_save_tools_py import parse_items_from_base64

# Parse base64-encoded inventory data
base64_data = "AQAAAAIAAAAKQXhlQnJvbnpl..."  # From save file
items = parse_items_from_base64(base64_data)

# Access item information
for item in items:
    print(f"Item: {item['name']}")
    print(f"Stack: {item['stack']}")
    print(f"Durability: {item['durability']}")
    print(f"Quality: {item['quality']}")
    print(f"Equipped: {item['equipped']}")

Use File-Like Objects

from io import BytesIO

# Process files in memory without disk I/O
with open("world.db", "rb") as f:
    db_data = BytesIO(f.read())

# Convert to JSON
json_output = BytesIO()
data = vst.to_json(db_data, json_output)

# Modify in-place
db_data.seek(0)
vst.add_global_key(db_data, "defeated_eikthyr")

# Save back to file
with open("world_modified.db", "wb") as f:
    db_data.seek(0)
    f.write(db_data.read())

Benefits:

• Process files in memory without disk I/O
• Better integration with web frameworks
• Easier testing with mock data
• Work with network streams or uploaded files

Requirements

• Python 3.8 or higher
• Java 17 or higher (for running the bundled JAR)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

This is a Python wrapper for Valheim Save Tools by kakoen. Big shout-out for creating such a cool tool 🙏.

I encourage you to contribute to the Valheim Save Tools project!