Minion Rush Windows Store Edition save data editor (AI generated)

A developer released version 1.2.0 of a Python-based save data editor for the Windows Store edition of Minion Rush. The tool rebuilds savegame files from JSON, using XTEA encryption and patching wallet shadow values to ensure consistency. It supports custom keys and connectivity trackers, offering a practical utility for modding the game.

| /usr/bin/env python3 | | """ | | Minion Rush savegame encoder, version 1.2.0. | | | | Rebuilds a Windows Store Minion Rush savegame from JSON produced by | | minion save decoder v2 modified.py. | | | | A template savegame is required because the decoded JSON intentionally does not | | contain every opaque RedundantStream marker byte. The encoder preserves the | | physical wrapper and replaces each valid redundant payload copy in-place. | | | | Typical use: | | python minion save encoder v1.py savegame.json --template savegame --out savegame.new | | | | The top-level decoded values object is applied to the Player and MapMgr blobs. | | Optionally, the same banana/token values can also be written to a raw | | connectivity trackers file using --connectivity-template/--connectivity-out. | | | | Important: version-0x1C Player data contains an on-disk wallet shadow near the | | end of the serialized blob. When its valid flag is 1, the deserializer uses the | | shadow values to overwrite the ordinary banana/token fields. This encoder patches | | both representations together. | | | | Fields: | | banana count - Player + 0x10 u32 little-endian | | token count - Player + 0x0C u32 little-endian | | current jelly lab level - MapMgr + 0x08 u32 little-endian | | """ | | | | from future import annotations | | | | import argparse | | import base64 | | import copy | | import json | | import math | | import struct | | import sys | | import zlib | | from pathlib import Path | | from typing import Any | | | | HEADER MARKER SIZE = 0xB0 | | HEADER SIZE = HEADER MARKER SIZE + 8 | | PAYLOAD MARKER SIZE = 0x90 | | SAVE MAGIC = 0xED | | DEFAULT KEY SOURCE = b"ERROR: invalid stream" | | MAX U32 = 0xFFFFFFFF | | VERSION = "1.2.0" | | | | | | class EncodeError Exception : | | pass | | | | | | def derive xtea key source: bytes - bytes: | | key = bytearray 16 | | for i, byte in enumerate source : | | key i & 0x0F ^= byte | | return bytes key | | | | | | def xtea encrypt block block: bytes, key: bytes - bytes: | | if len block = 8: | | raise ValueError "XTEA block must be exactly 8 bytes" | | if len key = 16: | | raise ValueError "XTEA key must be exactly 16 bytes" | | | | v0, v1 = struct.unpack "<2I", block | | k = struct.unpack "<4I", key | | delta = 0x9E3779B9 | | total = 0 | | | | for in range 32 : | | v0 = | | v0 | | + | | v1 << 4 ^ v1 5 + v1 | | ^ total + k total & 3 & MAX U32 | | | | & MAX U32 | | total = total + delta & MAX U32 | | v1 = | | v1 | | + | | v0 << 4 ^ v0 5 + v0 | | ^ total + k total 11 & 3 & MAX U32 | | | | & MAX U32 | | | | return struct.pack "<2I", v0, v1 | | | | | | def xtea encrypt data: bytes, key: bytes - bytes: | | if len data % 8: | | raise EncodeError "XTEA plaintext must be padded to a multiple of 8 bytes" | | return b"".join | | xtea encrypt block data offset:offset + 8 , key | | for offset in range 0, len data , 8 | | | | | | | | def parse key args: argparse.Namespace - bytes: | | supplied = sum | | value is not None | | for value in args.key source, args.key source hex, args.xtea key hex | | | | if supplied 1: | | raise EncodeError | | "use only one of --key-source, --key-source-hex, or --xtea-key-hex" | | | | | | if args.xtea key hex is not None: | | try: | | key = bytes.fromhex args.xtea key hex | | except ValueError as exc: | | raise EncodeError f"invalid --xtea-key-hex: {exc}" from exc | | if len key = 16: | | raise EncodeError "--xtea-key-hex must decode to exactly 16 bytes" | | return key | | | | if args.key source hex is not None: | | try: | | source = bytes.fromhex args.key source hex | | except ValueError as exc: | | raise EncodeError f"invalid --key-source-hex: {exc}" from exc | | return derive xtea key source | | | | if args.key source is not None: | | return derive xtea key args.key source.encode args.key encoding | | | | return derive xtea key DEFAULT KEY SOURCE | | | | | | def checked u32 value: Any, name: str - int: | | if isinstance value, bool or not isinstance value, int : | | raise EncodeError f"{name} must be an integer" | | if not 0 <= value <= MAX U32: | | raise EncodeError f"{name} must be in the range 0..{MAX U32}" | | return value | | | | | | | | def rol32 value: int, count: int - int: | | count &= 31 | | value &= MAX U32 | | return value << count | value 32 - count & 31 & MAX U32 | | | | | | def wallet shadow encode value: int - int: | | return rol32 checked u32 value, "wallet shadow value" , 10 ^ 0x48607922 | | | | | | def patch wallet shadow | | blob: bytearray, | | old tokens: int, | | old bananas: int, | | new tokens: int, | | new bananas: int, | | - dict str, Any : | | """Patch the serialized wallet shadow used by Player format 0x1C. | | | | Serialized layout is contiguous: | | uint8 valid flag == 1 | | uint32 token shadow | | uint32 banana shadow | | | | shadow value = ROL32 value, 10 XOR 0x48607922. | | """ | | old seq = | | b"\x01" | | + struct.pack "<I", wallet shadow encode old tokens | | + struct.pack "<I", wallet shadow encode old bananas | | | | new seq = | | b"\x01" | | + struct.pack "<I", wallet shadow encode new tokens | | + struct.pack "<I", wallet shadow encode new bananas | | | | matches = | | start = 0 | | while True: | | pos = blob.find old seq, start | | if pos < 0: | | break | | matches.append pos | | start = pos + 1 | | | | if len matches = 1: | | raise EncodeError | | "could not identify a unique version-0x1C wallet shadow: " | | f"expected one sequence for tokens={old tokens}, bananas={old bananas}, " | | f"found {len matches }" | | | | | | offset = matches 0 | | blob offset:offset + len old seq = new seq | | return { | | "offset": offset, | | "old token shadow": f"0x{wallet shadow encode old tokens :08X}", | | "old banana shadow": f"0x{wallet shadow encode old bananas :08X}", | | "new token shadow": f"0x{wallet shadow encode new tokens :08X}", | | "new banana shadow": f"0x{wallet shadow encode new bananas :08X}", | | } | | | | def decode blob record: dict str, Any , name: str - bytearray: | | if record.get "kind" = "blob" or "data base64" not in record: | | raise EncodeError f"record {name r} is not a Base64 blob" | | try: | | return bytearray base64.b64decode record "data base64" , validate=True | | except ValueError, TypeError as exc: | | raise EncodeError f"record {name r} has invalid data base64" from exc | | | | | | def patch u32 blob: bytearray, offset: int, value: Any, field: str - None: | | value = checked u32 value, field | | if offset + 4 len blob : | | raise EncodeError | | f"cannot write {field}: blob is {len blob } bytes, offset is 0x{offset:X}" | | | | struct.pack into "<I", blob, offset, value | | | | | | def apply decoded values document: dict str, Any - dict str, Any : | | records = document.get "records" | | if not isinstance records, dict : | | raise EncodeError "JSON root must contain a 'records' object" | | | | report: dict str, Any = {} | | top = document.get "decoded values" | | if top is None: | | top = {} | | if not isinstance top, dict : | | raise EncodeError "decoded values must be an object" | | | | player = records.get "Player" | | if isinstance player, dict : | | values: dict str, Any = {} | | if isinstance player.get "decoded" , dict : | | values.update player "decoded" | | values.update {k: top k for k in "token count", "banana count" if k in top} | | | | if values: | | blob = decode blob player, "Player" | | old tokens = struct.unpack from "<I", blob, 0x0C 0 | | old bananas = struct.unpack from "<I", blob, 0x10 0 | | new tokens = checked u32 values.get "token count", old tokens , "token count" | | new bananas = checked u32 values.get "banana count", old bananas , "banana count" | | | | shadow report = patch wallet shadow | | blob, old tokens, old bananas, new tokens, new bananas | | | | patch u32 blob, 0x0C, new tokens, "token count" | | patch u32 blob, 0x10, new bananas, "banana count" | | | | player "data base64" = base64.b64encode blob .decode "ascii" | | player "length" = len blob | | player " aux" = len blob | | report "Player" = { | | "old token count": old tokens, | | "old banana count": old bananas, | | "new token count": new tokens, | | "new banana count": new bananas, | | "wallet shadow": shadow report, | | } | | | | map mgr = records.get "MapMgr" | | if isinstance map mgr, dict : | | values = {} | | if isinstance map mgr.get "decoded" , dict : | | values.update map mgr "decoded" | | if "current jelly lab level" in top: | | values "current jelly lab level" = top "current jelly lab level" | | | | if "current jelly lab level" in values: | | blob = decode blob map mgr, "MapMgr" | | patch u32 | | blob, | | 0x08, | | values "current jelly lab level" , | | "current jelly lab level", | | | | map mgr "data base64" = base64.b64encode blob .decode "ascii" | | map mgr "length" = len blob | | map mgr " aux" = len blob | | report "MapMgr" = { | | "current jelly lab level": values "current jelly lab level" | | } | | | | return report | | | | def encode record string value: str - bytes: | | if not isinstance value, str : | | raise EncodeError "record name/string value must be a string" | | raw = value.encode "utf-8" | | if len raw 0xFFFF: | | raise EncodeError "record name/string exceeds 65535 encoded bytes" | | return struct.pack "<H", len raw + raw | | | | | | def parse nonfinite value: Any, field: str - float: | | if isinstance value, int, float and not isinstance value, bool : | | return float value | | if isinstance value, str : | | mapping = { | | "nan": math.nan, | | "inf": math.inf, | | "+inf": math.inf, | | "-inf": -math.inf, | | } | | parsed = mapping.get value.lower | | if parsed is not None: | | return parsed | | raise EncodeError f"{field} must be a number, 'nan', 'inf', or '-inf'" | | | | | | def encode record value record: dict str, Any - bytes: | | if not isinstance record, dict : | | raise EncodeError "each record value must be an object" | | try: | | type id = int record " type" | | except KeyError, TypeError, ValueError as exc: | | raise EncodeError "record is missing a valid type" from exc | | | | body: bytes | | aux: int | | | | if type id == 0: | | encoded = record.get "data base64", "" | | try: | | body = base64.b64decode encoded, validate=True if encoded else b"" | | except ValueError, TypeError as exc: | | raise EncodeError "type-0 record has invalid data base64" from exc | | aux = len body | | | | elif type id == 1: | | if "raw" in record: | | raw = checked u32 record "raw" , "type-1 raw" | | else: | | raw = 1 if bool record.get "value" else 0 | | body = struct.pack "<I", raw | | aux = checked u32 record.get " aux", 0 , "type-1 aux" | | | | elif type id == 2: | | raw hex = record.get "raw hex" | | if raw hex is not None: | | try: | | body = bytes.fromhex raw hex | | except ValueError as exc: | | raise EncodeError "type-2 raw hex is invalid" from exc | | if len body = 8: | | raise EncodeError "type-2 raw hex must contain 8 bytes" | | elif "unsigned" in record: | | body = struct.pack "<Q", int record "unsigned" | | elif "signed" in record: | | body = struct.pack "<q", int record "signed" | | else: | | raise EncodeError "type-2 record needs raw hex, unsigned, or signed" | | aux = checked u32 record.get " aux", 0 , "type-2 aux" | | | | elif type id == 3: | | raw hex = record.get "raw hex" | | if raw hex is not None: | | try: | | body = bytes.fromhex raw hex | | except ValueError as exc: | | raise EncodeError "type-3 raw hex is invalid" from exc | | if len body = 4: | | raise EncodeError "type-3 raw hex must contain 4 bytes" | | elif "unsigned" in record: | | body = struct.pack "<I", checked u32 record "unsigned" , "unsigned" | | elif "signed" in record: | | body = struct.pack "<i", int record "signed" | | else: | | raise EncodeError "type-3 record needs raw hex, unsigned, or signed" | | aux = checked u32 record.get " aux", 0 , "type-3 aux" | | | | elif type id == 4: | | raw hex = record.get "raw hex" | | if raw hex is not None: | | try: | | body = bytes.fromhex raw hex | | except ValueError as exc: | | raise EncodeError "type-4 raw hex is invalid" from exc | | if len body = 4: | | raise EncodeError "type-4 raw hex must contain 4 bytes" | | else: | | body = struct.pack "<f", parse nonfinite record.get "value" , "float32" | | aux = checked u32 record.get " aux", 0 , "type-4 aux" | | | | elif type id == 5: | | raw hex = record.get "raw hex" | | if raw hex is not None: | | try: | | body = bytes.fromhex raw hex | | except ValueError as exc: | | raise EncodeError "type-5 raw hex is invalid" from exc | | if len body = 8: | | raise EncodeError "type-5 raw hex must contain 8 bytes" | | else: | | body = struct.pack "<d", parse nonfinite record.get "value" , "float64" | | aux = checked u32 record.get " aux", 0 , "type-5 aux" | | | | elif type id == 6: | | body = encode record string record.get "value", "" | | aux = checked u32 record.get " aux", 0 , "type-6 aux" | | | | elif type id == 7: | | body = bytes decode blob record, "<blob " | | aux = len body | | | | elif type id == 8: | | nested = record.get "value" | | if not isinstance nested, dict : | | raise EncodeError "type-8 record is missing nested 'value' RecordDB" | | body = encode record db nested | | aux = checked u32 record.get " aux", 0 , "type-8 aux" | | | | else: | | raise EncodeError f"unsupported RecordDB type {type id}" | | | | return struct.pack "<BI", type id, aux + body | | | | | | def ordered entries database: dict str, Any - list tuple str, dict str, Any : | | records = database.get "records" | | if not isinstance records, dict : | | raise EncodeError "RecordDB object is missing a 'records' object" | | | | entries: list tuple str, dict str, Any = | | duplicate names: set str = set | | duplicates = database.get " duplicates", {} | | | | if isinstance duplicates, dict : | | for name, group in duplicates.items : | | if not isinstance group, list : | | raise EncodeError f"duplicate group {name r} must be a list" | | duplicate names.add name | | for record in group: | | if not isinstance record, dict : | | raise EncodeError f"duplicate record {name r} must be an object" | | entries.append name, record | | | | for name, record in records.items : | | if not isinstance record, dict : | | raise EncodeError f"record {name r} must be an object" | | For duplicate names, duplicates already contains the first occurrence | | as well as every later occurrence. | | if name not in duplicate names: | | entries.append name, record | | | | def sort key item: tuple str, dict str, Any - tuple int, str : | | index = item 1 .get " record index" | | return index if isinstance index, int else 1 << 60, item 0 | | | | entries.sort key=sort key | | return entries | | | | | | def encode record db database: dict str, Any - bytes: | | entries = ordered entries database | | out = bytearray struct.pack "<I", len entries | | for name, record in entries: | | out += encode record string name | | out += encode record value record | | return bytes out | | | | | | def build logical payload recorddb: bytes, key: bytes - bytes: | | inner crc = zlib.crc32 recorddb & MAX U32 | | plaintext = struct.pack "<I", inner crc + recorddb | | padded length = len plaintext + 7 & ~7 | | padded = plaintext + b"\x00" padded length - len plaintext | | ciphertext = xtea encrypt padded, key | | section length = 4 + len ciphertext | | return | | struct.pack "<BI", SAVE MAGIC, 1 | | + struct.pack "<II", section length, len plaintext | | + ciphertext | | | | | | | | def find all data: bytes, pattern: bytes - list int : | | positions: list int = | | start = 0 | | while True: | | pos = data.find pattern, start | | if pos < 0: | | return positions | | positions.append pos | | start = pos + 1 | | | | | | def locate template payloads data: bytes - tuple int, int, list int , list int : | | if len data < 2 HEADER SIZE + PAYLOAD MARKER SIZE: | | raise EncodeError "template is too small to contain a RedundantStream wrapper" | | | | header marker = data :HEADER MARKER SIZE | | stored crc, payload len = struct.unpack from "<II", data, HEADER MARKER SIZE | | header positions = find all data, header marker | | header set = set header positions | | | | candidate starts: list int = | | for pos in header positions: | | if pos - HEADER SIZE in header set and pos + HEADER SIZE not in header set: | | candidate starts.append pos + HEADER SIZE + PAYLOAD MARKER SIZE | | for pos in header positions: | | candidate starts.append pos + HEADER SIZE + PAYLOAD MARKER SIZE | | | | valid starts: list int = | | for start in dict.fromkeys candidate starts : | | if start + payload len <= len data : | | payload = data start:start + payload len | | if zlib.crc32 payload & MAX U32 == stored crc: | | valid starts.append start | | | | if not valid starts: | | raise EncodeError "could not locate any CRC-valid payload copies in template" | | | | valid headers: list int = | | for pos in header positions: | | if pos + HEADER SIZE <= len data : | | crc, length = struct.unpack from "<II", data, pos + HEADER MARKER SIZE | | if crc == stored crc and length == payload len: | | valid headers.append pos | | | | return stored crc, payload len, sorted set valid starts , valid headers | | | | | | def rewrite template template: bytes, logical payload: bytes - tuple bytes, int, int : | | , old length, payload starts, header positions = locate template payloads template | | if len logical payload = old length: | | raise EncodeError | | "encoded logical payload length changed from " | | f"{old length} to {len logical payload } bytes. This encoder currently " | | "supports in-place, same-length edits only. Editing decoded counters works; " | | "adding/removing records or changing string/blob lengths does not." | | | | | | result = bytearray template | | new crc = zlib.crc32 logical payload & MAX U32 | | | | for start in payload starts: | | result start:start + old length = logical payload | | | | for pos in header positions: | | struct.pack into "<II", result, pos + HEADER MARKER SIZE, new crc, old length | | | | return bytes result , len payload starts , len header positions | | | | | | | | def parse connectivity trackers data: bytes - tuple int, int, list dict str, Any : | | """Parse the observed compact connectivity trackers container.""" | | if len data < 13: | | raise EncodeError "connectivity trackers template is too small" | | declared size, version, stored crc = struct.unpack from "<IBI", data, 0 | | body = data 9: | | actual crc = zlib.crc32 body & MAX U32 | | if actual crc = stored crc: | | raise EncodeError | | "connectivity trackers CRC mismatch: " | | f"stored={stored crc:08x}, calculated={actual crc:08x}" | | | | count = struct.unpack from "<I", body, 0 0 | | offset = 4 | | records: list dict str, Any = | | for index in range count : | | if offset + 2 len body : | | raise EncodeError f"truncated connectivity record {index}" | | name len = struct.unpack from "<H", body, offset 0 | | offset += 2 | | if offset + name len + 5 len body : | | raise EncodeError f"truncated connectivity record {index}" | | try: | | name = body offset:offset + name len .decode "utf-8" | | except UnicodeDecodeError as exc: | | raise EncodeError f"invalid connectivity record name at index {index}" from exc | | offset += name len | | type code, size = struct.unpack from "<BI", body, offset | | offset += 5 | | if offset + size len body : | | raise EncodeError f"truncated connectivity value {name r}" | | raw = body offset:offset + size | | offset += size | | records.append {"name": name, "type code": type code, "raw": raw} | | if offset = len body : | | raise EncodeError | | f"connectivity trackers has {len body - offset} unexpected trailing bytes" | | | | bias = declared size - len data | | return version, bias, records | | | | | | def encode connectivity value type code: int, value: int, name: str - bytes: | | value = checked u32 value, name | | if type code = 3: | | raise EncodeError | | f"connectivity field {name r} has type {type code}; expected uint32 type 3" | | | | return struct.pack "<I", value | | | | | | def patch connectivity trackers | | template: bytes, | | banana count: int | None, | | token count: int | None, | | - tuple bytes, list str : | | version, bias, records = parse connectivity trackers template | | patches = {"bananas": banana count, "tokens": token count} | | found: set str = set | | body = bytearray struct.pack "<I", len records | | for rec in records: | | name = rec "name" | | raw = rec "raw" | | if name in patches and patches name is not None: | | raw = encode connectivity value rec "type code" , patches name , name | | found.add name | | name raw = name.encode "utf-8" | | body += struct.pack "<H", len name raw + name raw | | body += struct.pack "<BI", rec "type code" , len raw + raw | | requested = {name for name, value in patches.items if value is not None} | | missing = requested - found | | if missing: | | raise EncodeError | | "connectivity trackers is missing requested fields: " + ", ".join sorted missing | | | | file size = 9 + len body | | declared size = file size + bias | | crc = zlib.crc32 body & MAX U32 | | return struct.pack "<IBI", declared size, version, crc + body, sorted found | | | | | | def resolve cli values document: dict str, Any , args: argparse.Namespace - tuple int | None, int | None : | | top = document.setdefault "decoded values", {} | | if not isinstance top, dict : | | raise EncodeError "decoded values must be an object" | | if args.bananas is not None: | | top "banana count" = checked u32 args.bananas, "--bananas" | | if args.tokens is not None: | | top "token count" = checked u32 args.tokens, "--tokens" | | bananas = top.get "banana count" | | tokens = top.get "token count" | | if bananas is not None: | | bananas = checked u32 bananas, "banana count" | | if tokens is not None: | | tokens = checked u32 tokens, "token count" | | return bananas, tokens | | | | def main - int: | | parser = argparse.ArgumentParser | | description="Encode decoder JSON back into a Minion Rush savegame" | | | | parser.add argument "json file", type=Path, help="JSON produced by the decoder" | | parser.add argument "--template", required=True, type=Path, help="original savegame" | | parser.add argument "--out", required=True, type=Path, help="output savegame path" | | parser.add argument "--bananas", type=int, help="override Player banana count" | | parser.add argument "--tokens", type=int, help="override Player token count" | | parser.add argument | | "--connectivity-template", | | type=Path, | | help="optional raw connectivity trackers file to patch with the same balances", | | | | parser.add argument | | "--connectivity-out", | | type=Path, | | help="output path for patched connectivity trackers", | | | | parser.add argument "--key-source" | | parser.add argument "--key-source-hex" | | parser.add argument "--xtea-key-hex" | | parser.add argument "--key-encoding", default="utf-8" | | args = parser.parse args | | | | try: | | document = json.loads args.json file.read text encoding="utf-8" | | if not isinstance document, dict : | | raise EncodeError "JSON root must be an object" | | | | document = copy.deepcopy document | | bananas, tokens = resolve cli values document, args | | patch report = apply decoded values document | | recorddb = encode record db document | | key = parse key args | | logical payload = build logical payload recorddb, key | | template = args.template.read bytes | | output, payload copies, headers = rewrite template template, logical payload | | args.out.write bytes output | | | | connectivity result = None | | if args.connectivity template is not None or args.connectivity out is not None: | | if args.connectivity template is None or args.connectivity out is None: | | raise EncodeError | | "--connectivity-template and --connectivity-out must be used together" | | | | if bananas is None and tokens is None: | | raise EncodeError | | "no banana/token values are available for connectivity trackers" | | | | connectivity template = args.connectivity template.read bytes | | connectivity output, patched fields = patch connectivity trackers | | connectivity template, bananas, tokens | | | | args.connectivity out.write bytes connectivity output | | connectivity result = { | | "template": str args.connectivity template , | | "output": str args.connectivity out , | | "patched fields": patched fields, | | "output size": len connectivity output , | | "output crc32": f"{zlib.crc32 connectivity output & MAX U32:08x}", | | } | | | | result = { | | "encoder version": VERSION, | | "json": str args.json file , | | "template": str args.template , | | "output": str args.out , | | "recorddb length": len recorddb , | | "logical payload length": len logical payload , | | "redundant payload copies replaced": payload copies, | | "header checksums updated": headers, | | "output size": len output , | | "output crc32": f"{zlib.crc32 output & MAX U32:08x}", | | "requested balances": { | | "banana count": bananas, | | "token count": tokens, | | }, | | "patch report": patch report, | | "connectivity trackers": connectivity result, | | "wallet note": | | "Patched the ordinary Player currency fields and the version-0x1C " | | "serialized wallet shadow used to overwrite them during load." | | , | | } | | print json.dumps result, indent=2 | | return 0 | | | | except OSError, json.JSONDecodeError, EncodeError, ValueError, struct.error as exc: | | print f"error: {exc}", file=sys.stderr | | return 1 | | | | | | if name == " main ": | | raise SystemExit main |