Skip to main content
Engineering LibreTexts

10.12: About the Star Pusher Map File Format

  • Page ID

    \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)

    \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)

    \( \newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\)

    ( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\)

    \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\)

    \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\)

    \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\)

    \( \newcommand{\Span}{\mathrm{span}}\)

    \( \newcommand{\id}{\mathrm{id}}\)

    \( \newcommand{\Span}{\mathrm{span}}\)

    \( \newcommand{\kernel}{\mathrm{null}\,}\)

    \( \newcommand{\range}{\mathrm{range}\,}\)

    \( \newcommand{\RealPart}{\mathrm{Re}}\)

    \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\)

    \( \newcommand{\Argument}{\mathrm{Arg}}\)

    \( \newcommand{\norm}[1]{\| #1 \|}\)

    \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\)

    \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\AA}{\unicode[.8,0]{x212B}}\)

    \( \newcommand{\vectorA}[1]{\vec{#1}}      % arrow\)

    \( \newcommand{\vectorAt}[1]{\vec{\text{#1}}}      % arrow\)

    \( \newcommand{\vectorB}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)

    \( \newcommand{\vectorC}[1]{\textbf{#1}} \)

    \( \newcommand{\vectorD}[1]{\overrightarrow{#1}} \)

    \( \newcommand{\vectorDt}[1]{\overrightarrow{\text{#1}}} \)

    \( \newcommand{\vectE}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash{\mathbf {#1}}}} \)

    \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)

    \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)

    We need the level text file to be in a specific format. Which characters represent walls, or stars, or the player’s starting position? If we have the maps for multiple levels, how can we tell when one level’s map ends and the next one begins?

    Fortunately, the map file format we will use is already defined for us. There are many Sokoban games out there (you can find more at, and they all use the same map file format. If you download the levels file from and open it in a text editor, you’ll see something like this:

    ; Star Pusher (Sokoban clone)
    ; By Al Sweigart
    ; Everything after the ; is a comment and will be ignored by the game that
    ; reads in this file.
    ; The format is described at:
    ;   @ - The starting position of the player.
    ;   $ - The starting position for a pushable star.
    ;   . - A goal where a star needs to be pushed.
    ;   + - Player & goal
    ;   * - Star & goal
    ;  (space) - an empty open space.
    ;   # - A wall.
    ; Level maps are separated by a blank line (I like to use a ; at the start
    ; of the line since it is more visible.)
    ; I tried to use the same format as other people use for their Sokoban games,
    ; so that loading new levels is easy. Just place the levels in a text file
    ; and name it "starPusherLevels.txt" (after renaming this file, of course).
    ; Starting demo level:
    ##      #
    #   .   #
    #   $   #
    # .$@$. #
    ####$   #
       #.   #
       #   ##
    ; These Sokoban levels come from David W. Skinner, who has many more puzzles at:
    ; Sasquatch Set I
    ; 1
      ## # ####
    ##  ###  #
    ## $      #
    #   @$ #  #
    ### $###  #
      #  #..  #
    ## ##.# ##
    #      ##
    #     ##

    The comments at the top of the file explain the file’s format. When you load the first level, it looks like this:

    Figure 56

    def readLevelsFile(filename):
        assert os.path.exists(filename), 'Cannot find the level file: %s' % (filename)
        mapFile = open(filename, 'r')
        # Each level must end with a blank line
        content = mapFile.readlines() + ['\r\n']
        levels = [] # Will contain a list of level objects.
        levelNum = 0
        mapTextLines = [] # contains the lines for a single level's map.
        mapObj = [] # the map object made from the data in mapTextLines
        for lineNum in range(len(content)):
            # Process each line that was in the level file.
            line = content[lineNum].rstrip('\r\n')
            if ';' in line:
                # Ignore the ; lines, they're comments in the level file.
                line = line[:line.find(';')]
            if line != '':
                # This line is part of the map.
            elif line == '' and len(mapTextLines) > 0:
                # A blank line indicates the end of a level's map in the file.
                # Convert the text in mapTextLines into a level object.
                # Find the longest row in the map.
                maxWidth = -1
                for i in range(len(mapTextLines)):
                    if len(mapTextLines[i]) > maxWidth:
                        maxWidth = len(mapTextLines[i])
                # Add spaces to the ends of the shorter rows. This
                # ensures the map will be rectangular.
                for i in range(len(mapTextLines)):
                    mapTextLines[i] += ' ' * (maxWidth - len(mapTextLines[i]))
                # Convert mapTextLines to a map object.
                for x in range(len(mapTextLines[0])):
                for y in range(len(mapTextLines)):
                    for x in range(maxWidth):
                # Loop through the spaces in the map and find the @, ., and $
                # characters for the starting game state.
                startx = None # The x and y for the player's starting position
                starty = None
                goals = [] # list of (x, y) tuples for each goal.
                stars = [] # list of (x, y) for each star's starting position.
                for x in range(maxWidth):
                    for y in range(len(mapObj[x])):
                        if mapObj[x][y] in ('@', '+'):
                            # '@' is player, '+' is player & goal
                            startx = x
                            starty = y
                        if mapObj[x][y] in ('.', '+', '*'):
                            # '.' is goal, '*' is star & goal
                            goals.append((x, y))
                        if mapObj[x][y] in ('$', '*'):
                            # '$' is star
                            stars.append((x, y))
                # Basic level design sanity checks:
                assert startx != None and starty != None, 'Level %s (around line %s) in %s is missing a "@" or "+" to mark the start point.' % (levelNum+1, lineNum, filename)
                assert len(goals) > 0, 'Level %s (around line %s) in %s must have at least one goal.' % (levelNum+1, lineNum, filename)
                assert len(stars) >= len(goals), 'Level %s (around line %s) in %s is impossible to solve. It has %s goals but only %s stars.' % (levelNum+1, lineNum, filename, len(goals), len(stars))
                # Create level object and starting game state object.
                gameStateObj = {'player': (startx, starty),
                                'stepCounter': 0,
                                'stars': stars}
                levelObj = {'width': maxWidth,
                            'height': len(mapObj),
                            'mapObj': mapObj,
                            'goals': goals,
                            'startState': gameStateObj}
                # Reset the variables for reading the next map.
                mapTextLines = []
                mapObj = []
                gameStateObj = {}
                levelNum += 1
        return levels

    The os.path.exists() function will return True if the file specified by the string passed to the function exists. If it does not exist, os.path.exists() returns False.

    The file object for the level file that is opened for reading is stored in mapFile. All of the text from the level file is stored as a list of strings in the content variable, with a blank line added to the end. (The reason that this is done is explained later.)

    After the level objects are created, they will be stored in the levels list. The levelNum variable will keep track of how many levels are found inside the level file. The mapTextLines list will be a list of strings from the content list for a single map (as opposed to how content stores the strings of all maps in the level file). The mapObj variable will be a 2D list.

    The for loop on line 12 [437] will go through each line that was read from the level file one line at a time. The line number will be stored in lineNum and the string of text for the line will be stored in line. Any newline characters at the end of the string will be stripped off.

    Any text that exists after a semicolon in the map file is treated like a comment and is ignored. This is just like the # sign for Python comments. To make sure that our code does not accidentally think the comment is part of the map, the line variable is modified so that it only consists of the text up to (but not including) the semicolon character. (Remember that this is only changing the string in the content list. It is not changing the level file on the hard drive.)

    There can be maps for multiple levels in the map file. The mapTextLines list will contain the lines of text from the map file for the current level being loaded. As long as the current line is not blank, the line will be appended to the end of mapTextLines.

    When there is a blank line in the map file, that indicates that the map for the current level has ended. And future lines of text will be for the later levels. Note however, that there must at least be one line in mapTextLines so that multiple blank lines together are not counted as the start and stop to multiple levels.

    All of the strings in mapTextLines need to be the same length (so that they form a rectangle), so they should be padded with extra blank spaces until they are all as long as the longest string. The for loop goes through each of the strings in mapTextLines and updates maxWidth when it finds a new longest string. After this loop finishes executing, the maxWidth variable will be set to the length of the longest string in mapTextLines.

    The for loop on line 34 [459] goes through the strings in mapTextLines again, this time to add enough space characters to pad each to be as long as maxWidth.

    The mapTextLines variable just stores a list of strings. (Each string in the list represents a row, and each character in the string represents a character at a different column. This is why line 42 [467] has the Y and X indexes reversed, just like the SHAPES data structure in the Tetromino game.) But the map object will have to be a list of list of single-character strings such that mapObj[x][y] refers to the tile at the XY coordinates. The for loop on line 38 [463] adds an empty list to mapObj for each column in mapTextLines.

    The nested for loops on line 465 and 466 will fill these lists with single-character strings to represent each tile on the map. This creates the map object that Star Pusher uses.

    After creating the map object, the nested for loops on lines 40 [475] and 41 [476] will go through each space to find the XY coordinates three things:

    1. The player’s starting position. This will be stored in the startx and starty variables, which will then be stored in the game state object later on line 69 [494].
    2. The starting position of all the stars These will be stored in the stars list, which is later stored in the game state object on line 71 [496].
    3. The position of all the goals. These will be stored in the goals list, which is later stored in the level object on line 75 [500].

    Remember, the game state object contains all the things that can change. This is why the player’s position is stored in it (because the player can move around) and why the stars are stored in it (because the stars can be pushed around by the player). But the goals are stored in the level object, since they will never move around.

    At this point, the level has been read in and processed. To be sure that this level will work properly, a few assertions must pass. If any of the conditions for these assertions are False, then Python will produce an error (using the string from the assert statement) saying what is wrong with the level file.

    The first assertion on line 64 [489] checks to make sure that there is a player starting point listed somewhere on the map. The second assertion on line 65 [490] checks to make sure there is at least one goal (or more) somewhere on the map. And the third assertion on line 66 [491] checks to make sure that there is at least one star for each goal (but having more stars than goals is allowed).

    Finally, these objects are stored in the game state object, which itself is stored in the level object. The level object is added to a list of level objects on line 78 [503]. It is this levels list that will be returned by the readLevelsFile() function when all of the maps have been processed.

    Now that this level is done processing, the variables for mapTextLines, mapObj, and gameStateObj should be reset to blank values for the next level that will be read in from the level file. The levelNum variable is also incremented by 1 for the next level’s level number.

    This page titled 10.12: About the Star Pusher Map File Format is shared under a CC BY-NC-SA 3.0 license and was authored, remixed, and/or curated by Al Sweigart via source content that was edited to the style and standards of the LibreTexts platform; a detailed edit history is available upon request.

    • Was this article helpful?