path: root/srb_lib.py

#!/usr/bin/env python3
# Startdate: 2024-03-08-6 15:28
# File: srb_lib.py
# Purpose: library for srb.exe savegame hacking
# SPDX-License-Identifier: GPL-3.0-only
# History:
# Usage:
#    from srb.py
# Reference:
#    blog posts 2024-03
#    <https://github.com/8051Enthusiast/delsum>
#    crc width=32 poly=0x4c11db7 init=0x0 xorout=0x235b4b9c refin=false refout=false out_endian=little
#    Incorrect functions: https://gist.github.com/djsweet/3477115595efab31905be7000bb013bc FAILED
#    Fuctions that worked: https://gist.github.com/Lauszus/6c787a3bc26fea6e842dfb8296ebd630 Author: Lauszus
#    https://stackoverflow.com/questions/46109815/reversing-the-byte-order-of-a-string-containing-hexadecimal-characters
#    https://gamefaqs.gamespot.com/pc/930591-snoopy-vs-the-red-baron/faqs/46161
# Documentation:
#    winetricks vd=1024x768
#    winetricks vd=off
# Dependencies:

import sys, struct
srb_lib_version = "20240318a"

# Table of byte positions of values in the savegame file, minus the first four bytes which are the checksum. Due to zero-indexing of python lists, but for ease of usage, we will always put a zero as the value of index 0. That is, profile 1 will use index 1 of the list.
# "Z<dddddddd" is the start of a profile.
CHECKSUM_LENGTH = 0x4
PROFILE_START_POSITION = [0, 0x10, 0x142C, 0x2848]
POS_MONEY = 0x270
POS_HEALTH = 0x274 # 0-3 is available levels
POS_STUNT = 0x280 # 0-3 is available levels
POS_GUN = 0x27C # 0-3 is available levels
POS_EQUIPPED_WEAPON = 0x284
POS_PROFILE_IN_USE = 0x290
POS_NAME = 0x294
# absolute 0x3fc is profile 1, so relative to start position
# relative to profile: 0x3E8 is level 0, levelset 0
# rel 0x404 is level 0 of levelset 1

NAME_CHARS = " ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890!?"

POS_BYTES_WEAPONS_PURCHASED = 0x028C
# Woodstock Missile and Bottle Rockets are always available to use.
# for equipped-weapon
# id = value of equipped byte
# e = equippable
# p = purchase flag, where in the two bytes (when looking at it big-endian) the entry is.
WEAPONS = [
   {"id":0x0,"e":False,"p":0x0,   "name":"none"}, # custom for this library
   {"id":0x1,"e":False,"p":0x0,   "name":"machine-gun-single"}, # not part of the game, but works if you set manually
   {"id":0x2,"e":False,"p":0x0,   "name":"machine-gun-double"}, # not part of the game, but works if you set manually
   {"id":0x3,"e":False,"p":0x0,   "name":"machine-gun-triple"}, # not part of the game, but works if you set manually
   {"id":0x4,"e":False,"p":0x0,   "name":"machine-gun-four"},
   {"id":0x5,"e":True, "p":0x0020,"name":"Potato Gun"}, # always available to buy
   {"id":0x6,"e":True, "p":0x0040,"name":"Stinger"}, # always available to buy
   {"id":0x7,"e":True, "p":0x0,   "name":"Woodstock Missile"}, # always available to player
   {"id":0x8,"e":True, "p":0x0100,"name":"Water Balloon Cannon"},
   {"id":0x9,"e":True, "p":0x0200,"name":"Snow Blower"},
   {"id":0xA,"e":True, "p":0x0400,"name":"Fire Boomerang"},
   {"id":0xB,"e":True, "p":0x0800,"name":"Lightning Rod"},
   {"id":0xC,"e":True, "p":0x0,   "name":"Bottle Rockets"}, # always available to player
   {"id":0xD,"e":True, "p":0x2000,"name":"Roman Candles"},
   {"id":0xE,"e":True, "p":0x4000,"name":"10 Gauge Pumpkin"},
   {"id":0xF,"e":False,"p":0x6F60,"name":"all"}, # custom for this library
]

POS_PLANES_PURCHASED = 0x288
PLANES = [
   {"p":0x0000,"name":"none"},
   {"p":0x0100,"name":"marcie"},
   {"p":0x0020,"name":"sally"},
   {"p":0x0800,"name":"rerun"},
   {"p":0x0200,"name":"pigpen"},
   {"p":0x1000,"name":"woodstock"},
   {"p":0x2000,"name":"baron"},
   {"p":0x3B20,"name":"all"},
]

# c = balloon color
# l = level count
# le = letters, calculated
# b = balloon count, calculated
LEVELSETS = [
   {"id":0,"l":6,"c":"red"   ,"b":0,"le":"","name":"Aerodrome Island"},
   {"id":1,"l":3,"c":"yellow","b":0,"le":"","name":"Woods of Montsec"},
   {"id":2,"l":3,"c":"green" ,"b":0,"le":"","name":"Front Lines of Verdun"},
   {"id":3,"l":5,"c":"blue"  ,"b":0,"le":"","name":"Mines of the Matterhorn"},
   {"id":4,"l":3,"c":"orange","b":0,"le":"","name":"Verdon Gorge"},
   {"id":5,"l":2,"c":"none"  ,"b":0,"le":"","name":"Flying Fortress"},
]

INT_SIZE = 0x4
# relative to player profile
POS_LEVEL_START = 0x2D4
POS_LEVEL_BALLOONS = 0x4B4
POS_LEVEL_BALLOONS_MULTIPLIER_LEVELSET = 0x238
POS_LEVEL_BALLOONS_MULTIPLIER_LEVEL = 0x50
POS_LEVELSET_COMPLETED_LETTERS_COUNT = 0x3A0
POS_LEVEL_LETTERS = 0x3E8
POS_LEVEL_LETTERS_MULTIPLIER_LEVELSET = 7
POS_LEVELSET_COMPLETED_MISSIONS_MASK = 0x2B8

# pos_r = relative position for level status
# set_pos = level number within the levelset. Necessary for certain position calculations including letters.
LEVELS = [
   {"id":0, "pos_r":0, "set_pos":0,"setid":0,"b":10,"l":"m"  ,"name":"Defend Island"},
   {"id":1, "pos_r":1, "set_pos":1,"setid":0,"b":10,"l":"a"  ,"name":"Recover Plans"},
   {"id":2, "pos_r":2, "set_pos":2,"setid":0,"b":10,"l":"r"  ,"name":"Protect the Trucks"},
   {"id":3, "pos_r":3, "set_pos":3,"setid":0,"b":10,"l":"c"  ,"name":"Attack of the U-Boats"},
   {"id":4, "pos_r":4, "set_pos":4,"setid":0,"b":10,"l":"i"  ,"name":"Cripple Outpost Island"},
   {"id":5, "pos_r":5, "set_pos":5,"setid":0,"b":10,"l":"e"  ,"name":"Sink the Battleship"},
   {"id":6, "pos_r":7, "set_pos":0,"setid":1,"b":10,"l":"sa" ,"name":"Rerun's Challenge"},
   {"id":7, "pos_r":8, "set_pos":1,"setid":1,"b":10,"l":"l"  ,"name":"Eliminate Tree Village"},
   {"id":8, "pos_r":9, "set_pos":2,"setid":1,"b":10,"l":"ly" ,"name":"Tree Chopper"},
   {"id":9, "pos_r":14,"set_pos":0,"setid":2,"b":10,"l":"re" ,"name":"Trench Warfare"},
   {"id":10,"pos_r":15,"set_pos":1,"setid":2,"b":10,"l":"r"  ,"name":"Recover Allied Base"},
   {"id":11,"pos_r":16,"set_pos":2,"setid":2,"b":10,"l":"un" ,"name":"Giant Tank"},
   {"id":12,"pos_r":21,"set_pos":0,"setid":3,"b":10,"l":"pi" ,"name":"Surprise Attack"},
   {"id":13,"pos_r":22,"set_pos":1,"setid":3,"b":10,"l":"g"  ,"name":"Derail the Train"},
   {"id":14,"pos_r":23,"set_pos":2,"setid":3,"b":10,"l":"p"  ,"name":"Enter the Mines"},
   {"id":15,"pos_r":24,"set_pos":3,"setid":3,"b":10,"l":"e"  ,"name":"Explore the Mines"},
   {"id":16,"pos_r":25,"set_pos":4,"setid":3,"b":10,"l":"n"  ,"name":"Destroy Driller Boss"},
   {"id":17,"pos_r":28,"set_pos":0,"setid":4,"b":10,"l":"woo","name":"Navigate the Canyon"},
   {"id":18,"pos_r":29,"set_pos":1,"setid":4,"b":10,"l":"dst","name":"Destroy Circus City"},
   {"id":19,"pos_r":30,"set_pos":2,"setid":4,"b":10,"l":"ock","name":"Circus Aircraft Carrier"},
   {"id":20,"pos_r":35,"set_pos":0,"setid":5,"b": 0,"l":"bar","name":"Rescue Allies"},
   {"id":21,"pos_r":36,"set_pos":1,"setid":5,"b": 0,"l":"on" ,"name":"Battle the Red Baron"}
]

# hex values
# INCOMPLETE: I think balloons and letters merely count as one of the types of requirements. there can up to 5 secondary objectives in a level (maybe the levels without balloons though?). This is probably a bitmask for secondary objectives (including all-balloons,all-letters),health,time.
# Definitely 0x64 means the whole level is 100% complete, rank General.
#LEVEL_STATUSES = {
#   "4A": "3-balloons,no-letters,under-time,good-health,corporal",
#   "47": "2-balloons,no-letters,under-time,good-health,corporal",
#   "59": "all-balloons,all-letters,under-time,good-health,sergeant",
#   "5B": "all-balloons,all-letters,under-time,good-health,colonel",
#   "5B": "9-balloons,no-letter,under-time,good-health,colonel",
#   "5D": "all-balloons,all-letters,under-time,good-health,colonel",
#   "5E": "all-balloons,no-letter,under-time,good-health,colonel",
#   "60": "all-balloons,all-letters,under-time,good-health,colonel",
#   "61": "all-balloons,all-letters,under-time,2/3obj,good-health,colonel",
#   "62": "all-balloons,all-letters,under-time,good-health,colonel",
#   "63": "all-balloons,all-letters,under-time,good-health,colonel",
#   "64": "all-balloons,all-letters,under-time,good-health,general"
#}

# While there are other bitmasks for most ranks, general is only ever 0x64.
LEVEL_STATUSES = [
   {"b":0x00,"name":"none"},
   {"b":0x47,"name":"corporal"},
   {"b":0x59,"name":"sergeant"},
   {"b":0x5B,"name":"colonel"},
   {"b":0x64,"name":"general"}, # depends on all secondary objectives, all letters, all balloons, under time, at least 50/100 health, not lost any lives.
]

POS_TUTORIAL_COMPLETED = 0x2D0 # bool

# DEFINE FUNCTIONS
def ferror(*args, **kwargs):
   print(*args, file=sys.stderr, **kwargs)

def debuglev(_numbertocheck, debuglevel):
   # if _numbertocheck <= debuglevel then return truthy
   _debuglev = False
   try:
      if int(_numbertocheck) <= int(debuglevel):
         _debuglev = True
   except Exception as e:
      pass
   return _debuglev

def read_file(filename):
   """ Return the stored checksum and contents of the file """
   with open(filename, 'rb') as f:
      # Read the entire file
      file_contents = f.read()
      checksum = file_contents[0:4]
      file_contents_without_checksum = file_contents[4:]
   return checksum, file_contents_without_checksum

def write_file(filename, checksum, data):
   """ Write the checksum and data to the file. We are assuming the checksum is already correct. """
   print(f"debug: checksum(type={type(checksum).__name__})={checksum}")
   if type(checksum) == int:
      checksum = checksum
   elif type(checksum) == str:
      checksum = int(checksum)
   elif type(checksum) == bytes:
      checksum = int.from_bytes(checksum)
   with open(filename, 'wb') as f:
      f.write(struct.pack('>L',checksum))
      #f.write(struct.pack('>I',int(checksum)))
      f.write(data)

######## start copy-paste 2
#  https://gist.github.com/Lauszus/6c787a3bc26fea6e842dfb8296ebd630

def reflect_data(x, width):
   # See: https://stackoverflow.com/a/20918545
   if width == 8:
      x = ((x & 0x55) << 1) | ((x & 0xAA) >> 1)
      x = ((x & 0x33) << 2) | ((x & 0xCC) >> 2)
      x = ((x & 0x0F) << 4) | ((x & 0xF0) >> 4)
   elif width == 16:
      x = ((x & 0x5555) << 1) | ((x & 0xAAAA) >> 1)
      x = ((x & 0x3333) << 2) | ((x & 0xCCCC) >> 2)
      x = ((x & 0x0F0F) << 4) | ((x & 0xF0F0) >> 4)
      x = ((x & 0x00FF) << 8) | ((x & 0xFF00) >> 8)
   elif width == 32:
      x = ((x & 0x55555555) << 1) | ((x & 0xAAAAAAAA) >> 1)
      x = ((x & 0x33333333) << 2) | ((x & 0xCCCCCCCC) >> 2)
      x = ((x & 0x0F0F0F0F) << 4) | ((x & 0xF0F0F0F0) >> 4)
      x = ((x & 0x00FF00FF) << 8) | ((x & 0xFF00FF00) >> 8)
      x = ((x & 0x0000FFFF) << 16) | ((x & 0xFFFF0000) >> 16)
   else:
      raise ValueError('Unsupported width')
   return x

def crc_poly(data, n, poly, crc=0, ref_in=False, ref_out=False, xor_out=0):
   g = 1 << n | poly  # Generator polynomial
   # Loop over the data
   for d in data:
      # Reverse the input byte if the flag is true
      if ref_in:
         d = reflect_data(d, 8)
      # XOR the top byte in the CRC with the input byte
      crc ^= d << (n - 8)
      # Loop over all the bits in the byte
      for _ in range(8):
         # Start by shifting the CRC, so we can check for the top bit
         crc <<= 1
         # XOR the CRC if the top bit is 1
         if crc & (1 << n):
            crc ^= g
   # Reverse the output if the flag is true
   if ref_out:
      crc = reflect_data(crc, n)
   # Return the CRC value
   return crc ^ xor_out
##### end copy-paste 2

def _get_data_from_data_object(data_object):
   """ Helper function to either open file, or pass bytes through. """
   data = None
   if type(data_object) == str:
      _, data = read_file(data_object)
   elif type(data_object) == bytes:
      data = data_object
   return data

def _convert_dec_to_reverse_bytes(num_dec):
   """ Helper function to turn a given decimal value into the little-endian values for insertion into the data. """
   # Here is how to do this manually.
   #num_str = str(hex(num_dec))[2:]
   #num_str = ("0" if len(num_str) % 2 else "") + num_str
   #num_bytes = bytearray.fromhex(num_str)
   #num_bytes.reverse()
   #return bytes(num_bytes)
   # I learned how to do this the pythonic way.
   return struct.pack('<i',num_dec)

def get_money(data_object,profile_id):
   """ Print in decimal the current money value of the profile_id. """
   data = _get_data_from_data_object(data_object)
   money_dec = data[PROFILE_START_POSITION[profile_id]+POS_MONEY] + (data[PROFILE_START_POSITION[profile_id]+POS_MONEY+1] * 0x100)
   #money_dec = int(money_hex, base=16)
   return money_dec

def set_money(data_object,profile_id, money_dec):
   """ Using data, set the money given in decimal for the given profile_id. """
   data = _get_data_from_data_object(data_object)
   #money_bytes = _convert_dec_to_reverse_bytes(money_dec)
   data = srb_pack('<i',data,PROFILE_START_POSITION[profile_id]+POS_MONEY,money_dec)
   print(f"after setting money to {money_dec}, we checked and got {get_money(data,profile_id)}")
   return data

def get_weapon(data_object,profile_id):
   """ For given profile, print currently equipped weapon. """
   data = _get_data_from_data_object(data_object)
   weapon_id = data[PROFILE_START_POSITION[profile_id]+POS_EQUIPPED_WEAPON]
   weapon_id = int(weapon_id)
   try:
      weapon, message = get_weapon_info(weapon_id)
   except:
      return f"unable to determine weapon"
   if message != "":
      return f"failed to get weapon due to {message}"
   print(f"debug: got weapon {weapon}")
   return weapon["name"]

def set_weapon(data_object,profile_id,weapon):
   data = _get_data_from_data_object(data_object)
   weapon, message = get_weapon_info(weapon)
   if (not bool(weapon)) or message != "":
      ferror(f"Warning: cannot set weapon to {weapon}, because {message}")
      return -1
   # armed with weapon as the index number, let's change the savegame data
   data = srb_pack('<i',data,PROFILE_START_POSITION[profile_id]+POS_EQUIPPED_WEAPON,weapon["id"])
   print(f"after setting weapon to {weapon['name']}, we checked and got {get_weapon(data,profile_id)}")
   return data

def get_weapon_info(weapon):
   """
   Returns tuple of (weapon object, message) searching by name or id. Message is empty if the weapon object is returned.
   """
   try:
      weapon = int(weapon)
   except:
      pass
   if type(weapon) == str:
      try:
         weapon_obj = [i for i in WEAPONS if i["name"].lower() == weapon.lower()][0]
         #weapon_id = [index for index in range(len(WEAPONS)) if WEAPONS[index].lower() == weapon.lower()][0]
         return weapon_obj, ""
      except:
         return {}, f"cannot find weapon {weapon}" # must be an incorrect name
   elif type(weapon) == int:
      if weapon in range(0,16):
         weapon_obj = [i for i in WEAPONS if i["id"] == weapon][0]
         return weapon_obj, ""
         #return weapon, WEAPONS[weapon]
      else:
         return {}, f"invalid index {weapon}; use 0-15" # must be <0 or >15
   return {}, f"invalid way to reference weapon: [{type(weapon)}]. Use index or name."

def get_purchased_weapons(data_object,profile_id,silent=False):
   """
   For the given profile, return which weapons are already purchased, as a comma-separated string and a bitmask.
   """
   data = _get_data_from_data_object(data_object)
   weapons_purchased = struct.unpack_from('<1i',data,PROFILE_START_POSITION[profile_id]+POS_BYTES_WEAPONS_PURCHASED)[0]
   #print(f"debug: got weapons_purchased 0x{weapons_purchased:0x}")
   all_weapons_mask = [i for i in WEAPONS if i["name"] == "all"][0]["p"]
   none_weapons_mask = [i for i in WEAPONS if i["name"] == "none"][0]["p"]
   # short-circuit if all
   if weapons_purchased & all_weapons_mask == all_weapons_mask:
      return "all", all_weapons_mask
   # short-circuit if none
   elif weapons_purchased | none_weapons_mask == 0:
      return "none", none_weapons_mask
   weapons_list = []
   weapons_mask = 0x0
   for i in WEAPONS:
      #result = weapons_purchased & i["p"]
      #print(f"debug: checking {i['p']:x} \"{i['name']}\" bitwise against {weapons_purchased:x}: {result:x}")
      if weapons_purchased & i["p"] and (i["name"] not in ["all","none"]):
         weapons_list.append(i["name"])
         weapons_mask += i["p"]
   if not silent:
      print(f"debug: currently have 0x{weapons_mask:04x} b{weapons_mask:016b}, {weapons_list}")
   return ','.join(weapons_list), weapons_mask

def get_level_status(data_object,profile_id,level,silent=False):
   """ Display all sorts of useful info about a level for the profile. The return value is not as useful as the printed info. """
   data = _get_data_from_data_object(data_object)
   level_obj, message = get_level_info(level)
   if message != "" or level == -1:
      ferror(f"Unable to get level status for {level}.")
   levelset_obj, message = get_levelset_info(level_obj["setid"])
   if message != "" or levelset_obj == -1:
      ferror(f"Unable to get levelset info for {level_obj['setid']}.")
   if not silent:
      print(f"Debug: for input {level} found level_obj {level_obj} and message {message}")
   pos_level_status = PROFILE_START_POSITION[profile_id]+POS_LEVEL_START+(INT_SIZE*level_obj["pos_r"])
   pos_level_balloons = PROFILE_START_POSITION[profile_id]+POS_LEVEL_BALLOONS+(level_obj["setid"]*POS_LEVEL_BALLOONS_MULTIPLIER_LEVELSET)+(POS_LEVEL_BALLOONS_MULTIPLIER_LEVEL*level_obj["set_pos"])
   pos_level_which_balloons = pos_level_balloons + INT_SIZE
   pos_level_letters = PROFILE_START_POSITION[profile_id]+POS_LEVEL_LETTERS+(INT_SIZE*level_obj["set_pos"])+(INT_SIZE*POS_LEVEL_LETTERS_MULTIPLIER_LEVELSET*level_obj["setid"])
   profile_level_status = data[pos_level_status]
   profile_level_balloons = data[pos_level_balloons]
   profile_level_which_balloons = struct.unpack_from('<1i',data,pos_level_which_balloons)[0]
   profile_level_letters = data[pos_level_letters]
   if not silent:
      print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_level_status:04x} level status 0x{profile_level_status:x}")
      print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_level_balloons:04x} collected balloon count: {profile_level_balloons}/{level_obj['b']}")
      print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_level_which_balloons:04x} which balloons: b{profile_level_which_balloons:010b}")
      print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_level_letters:04x} letter count: {profile_level_letters}/{len(level_obj['l'])}")
   # it comes back as an int, but does it look better as a hex?
   return hex(profile_level_status)

def set_level_status(data_object,profile_id,level,status):
   data = _get_data_from_data_object(data_object)
   level_obj, message = get_level_info(level)
   if message != "" or level_obj == -1:
      ferror(f"Unable to get level status for {level}.")
   current_status = get_level_status(data, profile_id, level, silent=True)
   print(f"Before changing, level {level} has status {current_status}")
   bits = 0x0
   try:
      bits = [i for i in LEVEL_STATUSES if i["name"]==status][0]["b"]
   except:
      return data, "", f"unable-to-set-level-completion-status-{status}"
   #print(f"debug: will try to set bits {bits:02x}")
   data = srb_pack('<1i',data,PROFILE_START_POSITION[profile_id]+POS_LEVEL_START+(INT_SIZE*level_obj["pos_r"]),bits)
   current_status = get_level_status(data, profile_id, level, silent=True)
   levelset_available_levels = get_levelset_available_levels(data,profile_id,level_obj["setid"])
   print(f"debug: levelset {level_obj['setid']} currently has {levelset_available_levels} available levels.")
   # if setting to any completed status, if the levelset available levels is less than this level, then make it this.
   if levelset_available_levels < (level_obj["set_pos"] + 1) and status not in ["none"]:
      data, message = set_levelset_available_levels(data,profile_id,level_obj["setid"],level_obj["set_pos"] + 1)
      if message != "":
         return -1, -1, f"Unable to set levelset available levels to minimum of this level set_pos {level_obj['set_pos']}"
   # decrement the available levels in the levelset if clearing out this level and the available levels is exactly this one.
   if levelset_available_levels == (level_obj["set_pos"] + 1) and status in ["none"]:
      data, message = set_levelset_available_levels(data,profile_id,level_obj["setid"],level_obj["set_pos"])
      if message != "":
         return -1, -1, f"Unable to decrement levelset available levels."
   return data, current_status, ""

def set_level_balloons(data_object,profile_id,level,count):
   data = _get_data_from_data_object(data_object)
   level_obj, message = get_level_info(level)
   if message != "" or level == -1:
      ferror(f"Unable to get level status for {level}.")
   # simplify the task; does a user really need to set individual balloons?!
   if count not in ["all","none"]:
      return -1, f"Can only set balloons to all or none for a level."
   pos_level_balloons = PROFILE_START_POSITION[profile_id]+POS_LEVEL_BALLOONS+(level_obj["setid"]*POS_LEVEL_BALLOONS_MULTIPLIER_LEVELSET)+(POS_LEVEL_BALLOONS_MULTIPLIER_LEVEL*level_obj["set_pos"])
   pos_level_which_balloons = pos_level_balloons + INT_SIZE
   #profile_level_balloons = data[pos_level_balloons]
   #profile_level_which_balloons = struct.unpack_from('<1i',data,pos_level_which_balloons)[0]
   #print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_level_balloons:04x} collected balloon count: {profile_level_balloons}/{level_obj['b']}")
   #print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_level_which_balloons:04x} which balloons: b{profile_level_which_balloons:010b}")
   if count == "all":
      target_count = 10
      target_which = 0x3FF # b1111111111, or bitmask that is 10 bits long
   else:
      target_count = 0
      target_which = 0x0
   data = srb_pack('<1i',data,pos_level_balloons,target_count)
   data = srb_pack('<1i',data,pos_level_which_balloons,target_which)
   return data, ""

def get_levelset_status(data_object,profile_id,levelset,silent=False):
   """ Display all sorts of useful info about a levelset for the profile. The return value is not as useful as the printed info. """
   data = _get_data_from_data_object(data_object)
   levelset_obj, message = get_levelset_info(levelset)
   if message != "" or levelset == -1:
      ferror(f"Unable to get levelset status for {levelset_obj['setid']}.")
   if not silent:
      print(f"Debug: got levelset {levelset_obj}")
   pos_levelset_completed_letters_count = PROFILE_START_POSITION[profile_id]+POS_LEVELSET_COMPLETED_LETTERS_COUNT+(INT_SIZE*2*levelset_obj["id"])
   pos_levelset_completed_letters_mask = pos_levelset_completed_letters_count + INT_SIZE
   pos_levelset_completed_mission_mask = PROFILE_START_POSITION[profile_id]+POS_LEVELSET_COMPLETED_MISSIONS_MASK+(INT_SIZE*levelset_obj["id"])
   profile_levelset_completed_letters_count = data[pos_levelset_completed_letters_count]
   # for some reason bit 1 is not used, so bitshift right 1.
   profile_levelset_completed_letters_mask = struct.unpack_from('<1i',data,pos_levelset_completed_letters_mask)[0] >> 1
   # python trick to reverse a custom-formatted string and convert back to int while reading the string as base 2
   profile_levelset_completed_letters_mask = int(f"{profile_levelset_completed_letters_mask:0{len(levelset_obj['le'])}b}"[::-1],2)
   profile_levelset_completed_mission_mask = data[pos_levelset_completed_mission_mask]
   profile_levelset_status = f"b{profile_levelset_completed_mission_mask:06b}"
   collected_balloons_for_levelset, message = get_collected_balloons_for_levelset(data,profile_id,levelset,silent=True)
   if message != "":
      ferror("Unable to count collected balloons.")
   if not silent:
      print(f"Debug: levelset {levelset_obj['id']},\"{levelset_obj['name']:23s}\" has mission mask: b{pow(2,levelset_obj['l'])-1:06b}")
      print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_levelset_completed_mission_mask:04x} levelset_obj {levelset_obj['id']}          completed missions: {profile_levelset_status}")
      print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_levelset_completed_letters_count:04x} completed letter count: {profile_levelset_completed_letters_count}/{len(levelset_obj['le'])}")
      print(f"Debug: abs 0x{CHECKSUM_LENGTH+pos_levelset_completed_letters_mask:04x} completed letter mask: b{profile_levelset_completed_letters_mask:0{len(levelset_obj['le'])}b}")
      print(f"Debug: collected balloons: {collected_balloons_for_levelset}/{levelset_obj['b']} {levelset_obj['c']}")
   completed_letters = list(levelset_obj['le'])
   x = 0
   for i in f"{profile_levelset_completed_letters_mask:0{len(levelset_obj['le'])}b}":
      completed_letters[x] = completed_letters[x].upper() if int(i) == 1 else completed_letters[x]
      x += 1
   completed_letters = ''.join(completed_letters)
   if not silent:
      print(f"Debug:  letters, uppercase is collected:  {completed_letters}")
   # it comes back as an int, but does it look better as a hex?
   return profile_levelset_status

def set_level_letters(data_object,profile_id,level,letters):
   """ Set collected letters for given level to all or none. """
   data = _get_data_from_data_object(data_object)
   level_obj, message = get_level_info(level)
   if message != "" or level == -1:
      return -1, f"Unable to get level status for {level}."
   levelset_obj, message = get_levelset_info(level_obj["setid"])
   if message != "":
      return -1, f"For set_level_letters unable to get levelset for {level_obj['setid']}."
   pos_level_letters = PROFILE_START_POSITION[profile_id]+POS_LEVEL_LETTERS+(INT_SIZE*level_obj["set_pos"])+(INT_SIZE*POS_LEVEL_LETTERS_MULTIPLIER_LEVELSET*level_obj["setid"])
   if letters not in ["all","none"]:
      return -1, f"Cannot set level letters to {letters}. Use all or none."
   if letters == "all":
      letter_count = len(level_obj["l"])
   else:
      letter_count = 0
   # update letter count for level.
   data = srb_pack('<1i',data,pos_level_letters,letter_count)
   pos_levelset_completed_letters_count = PROFILE_START_POSITION[profile_id]+POS_LEVELSET_COMPLETED_LETTERS_COUNT+(INT_SIZE*2*levelset_obj["id"])
   #print(f"debug: setting abs 0x{CHECKSUM_LENGTH+pos_levelset_completed_letters_count:04x} to {letter_count}")
   #data = srb_pack('<1i',data,pos_levelset_completed_letters_count,letter_count)
   # prepare to update the levelset completed letters count and mask
   pos_levelset_completed_letters_mask = pos_levelset_completed_letters_count + INT_SIZE
   # need to get current letter bitmask for levelset
   # convert the left-1-bitshifted value to useful, left-to-right mask
   profile_levelset_completed_letters_mask = struct.unpack_from('<1i',data,pos_levelset_completed_letters_mask)[0] >> 1
   # python trick to reverse a custom-formatted string and convert back to int while reading the string as base 2
   profile_levelset_completed_letters_mask = int(f"{profile_levelset_completed_letters_mask:0{len(levelset_obj['le'])}b}"[::-1],2)
   print(f"debug: levelset {levelset_obj['id']} before changes has letters mask {profile_levelset_completed_letters_mask:0{len(levelset_obj['le'])}b}")
   levels_to_check = [i for i in LEVELS if i["setid"] == levelset_obj["id"]]
   #print(f"need to check levels {levels_to_check}")
   levelset_letters_count = 0
   x = 0
   bitmask_pos = 0
   while x < len(levels_to_check):
      ltc = [i for i in levels_to_check if i["set_pos"] == x][0]
      this_level_count = data[PROFILE_START_POSITION[profile_id]+POS_LEVEL_LETTERS+(INT_SIZE*ltc["set_pos"])+(INT_SIZE*POS_LEVEL_LETTERS_MULTIPLIER_LEVELSET*ltc["setid"])]
      #print(f"debug: level {ltc['id']} has count {this_level_count}")
      levelset_letters_count += this_level_count
      if ltc["id"] == level_obj["id"]:
         this_bitmask_pos = bitmask_pos
      bitmask_pos += len(ltc["l"])
      x += 1
   # so now that this_bitmask_pos is populated with the location in the levelset letter mask of this level's letters, we need to manipulate it.
   #print(f"debug: need to manipulate letter mask {profile_levelset_completed_letters_mask:0{len(levelset_obj['le'])}b} at position {this_bitmask_pos} length {len(level_obj['l'])}")
   new_letter_mask = list(f"{profile_levelset_completed_letters_mask:0{len(levelset_obj['le'])}b}")
   #print(f"debug: this_bitmask_pos={this_bitmask_pos},len(level_obj['l'])={len(level_obj['l'])}, thing={(['1'] if letters == 'all' else ['0'])*len(level_obj['l'])}")
   # I could not get this pythonic thing working the way I wanted. I think the slice manipulation that uses len(level_obj["l"]) was not working....
   #new_letter_mask[this_bitmask_pos:len(level_obj["l"])+1] = (["1"] if letters == "all" else ["0"]) * len(level_obj["l"])
   # ... so I just run it per spot individually.
   x = 0
   while x < len(level_obj["l"]):
      new_letter_mask[this_bitmask_pos+x] = "1" if letters == "all" else "0"
      x += 1
   #print(f"debug: intermediate, new_letter_mask={new_letter_mask}")
   new_letter_mask = "".join(new_letter_mask)
   new_letter_mask_int = int(new_letter_mask,2)
   #print(f"debug: new_letter_mask updated list is str {new_letter_mask}, int {new_letter_mask_int}")
   #print(f"debug: total letters collected for levelset {levelset_obj['id']}: {levelset_letters_count}")
   print(f"debug: new letters bitmask for levelset {levelset_obj['id']}: {new_letter_mask_int:0{len(new_letter_mask)}b}")
   # bitmask needs to be reversed and left-1-bitshifted
   new_letter_mask_final = int(f"{new_letter_mask_int:0{len(levelset_obj['le'])}b}"[::-1],2) << 1
   print(f"debug: so that final bitmask should be {new_letter_mask_final:016b}")
   # set levelset letter count
   data = srb_pack('<1i',data,pos_levelset_completed_letters_count,levelset_letters_count)
   # set levelset letter mask
   data = srb_pack('<1i',data,pos_levelset_completed_letters_mask,new_letter_mask_final)
   return data, ""

def get_levelset_available_levels(data_object,profile_id,levelset):
   data = _get_data_from_data_object(data_object)
   levelset_obj, message = get_levelset_info(levelset)
   if message != "":
      return -1, f"For set_levelset_available_levels unable to get levelset for {levelset}."
   pos_levelset_completed_mission_mask = PROFILE_START_POSITION[profile_id]+POS_LEVELSET_COMPLETED_MISSIONS_MASK+(INT_SIZE*levelset_obj["id"])
   return data[pos_levelset_completed_mission_mask]

def set_levelset_available_levels(data_object,profile_id,levelset,completed_count):
   data = _get_data_from_data_object(data_object)
   levelset_obj, message = get_levelset_info(levelset)
   if message != "":
      return -1, f"For set_levelset_available_levels unable to get levelset for {levelset}."
   if completed_count == "all":
      completed_count = 8 # no levelset has more than 6 levels so this is a safe maximum, and it will get checked farther below.
   if completed_count == "none":
      completed_count = 0
   # by this point, it better be an integer
   try:
      completed_count = int(completed_count)
   except:
      return -1, f"cannot set levelset available levels to {completed_count}"
   if completed_count < 0:
      completed_count = 0
   completed_count = min(levelset_obj["l"], completed_count)
   pos_levelset_completed_mission_mask = PROFILE_START_POSITION[profile_id]+POS_LEVELSET_COMPLETED_MISSIONS_MASK+(INT_SIZE*levelset_obj["id"])
   completed_bitmask = pow(2,completed_count)-1
   #print(f"debug: need to set levelset {levelset} available count to {completed_count}, which stored as a bitmask should be {completed_bitmask:07b}")
   data = srb_pack('<1i',data,pos_levelset_completed_mission_mask,completed_bitmask)
   return data, ""

def get_collected_balloons_for_levelset(data_object,profile_id,levelset,silent=False):
   data = _get_data_from_data_object(data_object)
   levelset_obj, message = get_levelset_info(levelset)
   if message != "":
      ferror(f"For balloon count unable to get levelset for {levelset}.")
      return -1, "failed"
   levels = [i for i in LEVELS if i["setid"] == levelset_obj["id"]]
   x = 0
   profile_balloons = 0
   while x < levelset_obj["l"]:
      level_obj = [i for i in levels if i["set_pos"] == x][0]
      pos_level_balloons = PROFILE_START_POSITION[profile_id]+POS_LEVEL_BALLOONS+(level_obj["setid"]*POS_LEVEL_BALLOONS_MULTIPLIER_LEVELSET)+(POS_LEVEL_BALLOONS_MULTIPLIER_LEVEL*level_obj["set_pos"])
      profile_level_balloons = data[pos_level_balloons]
      profile_balloons += profile_level_balloons
      x += 1
   if not silent:
      print(f"Debug: for levelset {levelset_obj['id']}, collected {profile_balloons} balloons.")
   return profile_balloons, ""

def get_level_info(level):
   """ Returns dictionary of level from LEVELS, searching by id or name. """
   try:
      # if it is an integer, make sure it shows up as one in the next check
      level = int(level)
   except:
      pass
   if type(level) == str:
      try:
         level = [i for i in LEVELS if i["name"].lower() == level.lower()][0]
         return level, ""
      except:
         return -1, f"cannot find level {level}"
   elif type(level) == int:
      if level in range(0,len(LEVELS)+1):
         try:
            level = [i for i in LEVELS if i["id"] == level][0]
            return level, ""
         except:
            return -1, f"cannot find level by id {level}"
      else:
         return -1, f"invalid level index {level}; use 0-{len(LEVELS)}"
   return -1, f"invalid way to reference level: [{type(level)}]. Use id or name."

def get_levelset_info(levelset):
   """
   Returns dictionary of levelset from LEVELSETS with the addition of the letters and balloon counts from the associated missions.
   Search by id or name.
   """
   try:
      # if it is an integer, make sure it shows up as one in the next check
      levelset = int(levelset)
   except:
      pass
   if type(levelset) == str:
      try:
         levelset = [i for i in LEVELSETS if i["name"].lower() == levelset.lower()][0]
      except:
         return -1, f"cannot find levelset {levelset}"
   elif type(levelset) == int:
      if levelset in range(0,len(LEVELSETS)+1):
         try:
            levelset = [i for i in LEVELSETS if i["id"] == levelset][0]
            #return levelset, "valid"
         except:
            return -1, f"cannot find levelset by id {levelset}"
      else:
         return -1, f"invalid levelset index {levelset}; use 0-{len(LEVELSETS)}"
   if type(levelset) != dict:
      return -1, f"invalid way to reference levelset: [{type(levelset)}]. Use id or name."
   # so now we have the dictionary and we need to add the letters and balloons
   these_levels = [i for i in LEVELS if i["setid"] == levelset["id"]]
   # thankfully every levelset has letters. Not all levelsets have balloons but we can check on only this.
   if len(levelset["le"]) == 0:
      x = 0
      while x < len(these_levels):
         this_level = [i for i in these_levels if i["set_pos"] == x][0]
         levelset["le"] += this_level["l"]
         # because we only add balloon count under that if statement.
         levelset["b"] += this_level["b"]
         x = x + 1
   return levelset, ""

def get_name(data_object,profile_id):
   """ Print the name of the profile_id. """
   data = _get_data_from_data_object(data_object)
   name_array = struct.unpack_from('<8i',data,PROFILE_START_POSITION[profile_id]+POS_NAME)
   #print(f"debug: name_array: {name_array}, type {type(name_array)}")
   name_str = ""
   for i in name_array:
      name_str += NAME_CHARS[i]
   return name_str

def set_name(data_object,profile_id,new_name):
   """ Set the name of the profile_id. Note that this allows you to set a name for a profile that is not in use, which preseeds the name when you select to make a profile in this slot in-game. """
   data = _get_data_from_data_object(data_object)
   # convert new_name to tuple of integer values
   name_array = []
   for i in new_name.upper():
      try:
         j = NAME_CHARS.index(i)
      except ValueError:
         return -1, f"Invalid characters in requested name {new_name}."
      name_array.append(j)
   # right-pad with spaces
   while len(name_array) < 8:
      name_array.append(0)
   if len(name_array) > 8 or len(name_array) < 0:
      return -1, f"Invalid length {len(name_array)} of name {new_name}."
   x = 0
   # How I was doing this before:
   #data_bytearray = bytearray(data)
   #for i in name_array:
   #   struct.pack_into('<1i',data_bytearray,PROFILE_START_POSITION[profile_id]+POS_NAME+(4*x),i)
   #   x = x + 1
   #data = bytes(data_bytearray)
   data = srb_pack('<8i',data,PROFILE_START_POSITION[profile_id]+POS_NAME+(INT_SIZE*x),*name_array)
   #print(f"debug: after setting name to {new_name}, we checked and got {get_name(data,profile_id)}")
   return data, ""

def get_profile_in_use(data_object,profile_id):
   """ Print if the profile_id is in use. """
   data = _get_data_from_data_object(data_object)
   # it always comes as a tuple
   in_use = struct.unpack_from('<1?',data,PROFILE_START_POSITION[profile_id]+POS_PROFILE_IN_USE)[0]
   #print(f"debug: in_use: {in_use}, type {type(in_use)}")
   return in_use

def get_tutorial_completed(data_object,profile_id):
   """ Print if the profile has completed the tutorial. """
   data = _get_data_from_data_object(data_object)
   # it always comes as a tuple
   tutorial_completed = struct.unpack_from('<1?',data,PROFILE_START_POSITION[profile_id]+POS_TUTORIAL_COMPLETED)[0]
   return tutorial_completed

def set_tutorial_completed(data_object,profile_id,completed):
   """ Set tutorial-completed for given profile. """
   data = _get_data_from_data_object(data_object)
   data = srb_pack('<?',data,PROFILE_START_POSITION[profile_id]+POS_TUTORIAL_COMPLETED,bool(completed))
   return data, get_tutorial_completed(data,profile_id)

def get_plane_stat(data_object,profile_id,stat):
   """ Get health/stunt/gun statistic for profile. """
   data = _get_data_from_data_object(data_object)
   stat = stat.lower()
   if stat not in ["health","stunt","gun"]:
      return -1, f"Available plane stats are health,stunt,gun."
   if "health" == stat:
      thispos = POS_HEALTH
   elif "stunt" == stat:
      thispos = POS_STUNT
   else: # gun
      thispos = POS_GUN
   output = struct.unpack_from('<1i',data,PROFILE_START_POSITION[profile_id]+thispos)[0]+1
   #print(f"debug: at offset {PROFILE_START_POSITION[profile_id]+thispos:x} got {output:1b}")
   return output, ""

def set_plane_stat(data_object,profile_id,stat,value):
   """ Set health/stunt/gun statistic for profile. """
   data = _get_data_from_data_object(data_object)
   stat = stat.lower()
   if stat not in ["health","stunt","gun"]:
      return -1, f"Available plane stats are health,stunt,gun."
   if value not in range(1,6) or (value == 5 and stat != "gun"):
      return -1, f"Invalid value {value} for stat."
   if "health" == stat:
      thispos = POS_HEALTH
   elif "stunt" == stat:
      thispos = POS_STUNT
   else: # gun
      thispos = POS_GUN
   data = srb_pack('<1i',data,PROFILE_START_POSITION[profile_id]+thispos,value-1)
   return data, ""

def set_purchased_weapons(data_object,profile_id,action,weapons_list):
   """ For the given profile, take action on weapons_list, where action is in ["add","remove"] from the player. """
   data = _get_data_from_data_object(data_object)
   if action not in ["add","remove"]:
      return -1, f"Failed: can only [\"add\",\"remove\"] purchased weapons"
   # validate weapons_list
   action_mask = 0x0
   for w in weapons_list:
      weapon, message = get_weapon_info(w)
      if message != "":
         return -1, f"unable to {action} weapons because {message} on weapon {w}"
      action_mask = action_mask | weapon["p"]
   cur_weapons, cur_mask = get_purchased_weapons(data,profile_id)
   #print(f"debug: action_mask(type {type(action_mask)})={action_mask}")
   #print(f"debug: cur_mask(type {type(cur_mask)})={cur_mask}")
   #print(f"debug: need to {action}-combine {cur_mask:016b} and {action_mask:016b}")
   if action == "add":
      final_mask = cur_mask | action_mask
   elif action == "remove":
      final_mask = cur_mask & ~action_mask
   if final_mask != cur_mask:
      print(f"debug: beginning  0x{cur_mask:04x}, b{cur_mask:016b} {cur_weapons}")
      print(   f"debug: {action:6s}     0x{action_mask:04x}, b{action_mask:016b} {','.join(weapons_list)}")
   data = srb_pack('<1i',data,PROFILE_START_POSITION[profile_id]+POS_BYTES_WEAPONS_PURCHASED, final_mask)
   print(   f"debug: final      0x{final_mask:04x}, b{final_mask:016b} {get_purchased_weapons(data,profile_id,silent=True)[0]}")
   # if we make it to the end
   return data, ""

def get_purchased_planes(data_object,profile_id, silent=False):
   """ List which planes are purchased already. """
   data = _get_data_from_data_object(data_object)
   planes_purchased = struct.unpack_from('<1i',data,PROFILE_START_POSITION[profile_id]+POS_PLANES_PURCHASED)[0]
   all_planes_mask = [i for i in PLANES if i["name"] == "all"][0]["p"]
   none_planes_mask = [i for i in PLANES if i["name"] == "none"][0]["p"]
   # short-circuit if all
   if planes_purchased & all_planes_mask == all_planes_mask:
      return "all", all_planes_mask
   # short-circuit if none
   elif planes_purchased | none_planes_mask == 0:
      return "none", none_planes_mask
   planes_list = []
   planes_mask = 0x0
   for i in PLANES:
      if planes_purchased & i["p"] and (i["name"] not in ["all","none"]):
         planes_list.append(i["name"])
         planes_mask += i["p"]
   if not silent:
      print(f"debug: currently have 0x{planes_mask:04x} b{planes_mask:016b}, {planes_list}")
   return ','.join(planes_list), planes_mask

def set_purchased_planes(data_object,profile_id,action,planes_list):
   """ For the given profile, take action on planes_list, where action is in ["add","remove"] from the player. """
   data = _get_data_from_data_object(data_object)
   if action not in ["add","remove"]:
      return -1, f"Failed: can only [\"add\",\"remove\"] purchased planes"
   # validate planes_list
   action_mask = 0x0
   for p in planes_list:
      try:
         plane = [i for i in PLANES if i["name"] == p][0]
      except:
         return -1, f"unable to {action} planes because {message} on plane {p}"
      action_mask = action_mask | plane["p"]
   cur_planes, cur_mask = get_purchased_planes(data,profile_id)
   #print(f"debug: action_mask(type {type(action_mask)})={action_mask}")
   #print(f"debug: cur_mask(type {type(cur_mask)})={cur_mask}")
   #print(f"debug: need to {action}-combine {cur_mask:016b} and {action_mask:016b}")
   if action == "add":
      final_mask = cur_mask | action_mask
   elif action == "remove":
      final_mask = cur_mask & ~action_mask
   if final_mask != cur_mask:
      print(f"debug: beginning  0x{cur_mask:04x}, b{cur_mask:016b} {cur_planes}")
      print(   f"debug: {action:6s}     0x{action_mask:04x}, b{action_mask:016b} {','.join(planes_list)}")
   data = srb_pack('<1i',data,PROFILE_START_POSITION[profile_id]+POS_PLANES_PURCHASED, final_mask)
   print(   f"debug: final      0x{final_mask:04x}, b{final_mask:016b} {get_purchased_planes(data,profile_id,silent=True)[0]}")
   # if we make it to the end
   return data, ""

def srb_pack(format_str, data, offset, *new_contents):
   """ Helper function that accepts data as bytes, instead of requiring bytesarray. """
   data_bytearray = bytearray(data)
   struct.pack_into(format_str,data_bytearray,offset,*new_contents)
   return bytes(data_bytearray)

def calculate_checksum(data):
   """ Return the 4-byte checksum used by the game for the provided data. """
   # aka # CRC-32/BZIP2
   # The polynomial appears to be a standard one like used for Ethernet, but I am uncertain of the xor is standard or not.
   # I learned all this only with <https://github.com/8051Enthusiast/delsum>
   # crc width=32 poly=0x4c11db7 init=0x0 xorout=0x235b4b9c refin=false refout=false out_endian=little
   csum = hex(crc_poly(data, 32, 0x4C11DB7, crc=0x0, ref_in=False, ref_out=False, xor_out=0x235b4b9c))
   # comes in as ceb434d4, but needs to be d434b4ce, and bytearray is convenient way to swap it like that
   # trim off the '0x' from the string
   print(f"debug: Got csum={csum}")
   # pad any odd-digit-count hex value with a leading 0 for bytearray.fromhex() which is not very smart.
   csum = ("0" if len(str(csum)) % 2 else "") + str(csum)[2:]
   csum = bytearray.fromhex(csum)
   csum.reverse()
   # and back to bytes because that is how we will want to use it.
   return bytes(csum)

def correct_file(filename, debuglevel = 0):
   """ Given a savegame file, calculate the correct checksum and store that sum instead of whatever is there. """
   cs, data = read_file(filename)
   csum = calculate_checksum(data)
   ran = False
   if csum != cs:
      if debuglev(5,debuglevel):
         ferror(f"Stored checksum is {cs} and will update it to {csum}")
      write_file(filename,csum,data)
      ran = True
   else:
      if debuglev(2,debuglevel):
         ferror(f"Stored checksum is still correct, {csum}. Skipping {filename}")
   return ran