Storing Levels as Strings

In this appendix a method to use text strings to define and store levels is demonstrated.

So far levels were represented by 2d Lua tables. This is acceptable for small maps, but quickly becomes inconvenient as level size and complexity grows. A widely used technique is to store levels as text strings. This can be a good solution for medium-sized maps, where tables are already inefficient and specialized libraries such as Tiled are overkill.

For Arkanoid, it is natural to represent a level as a multiline string. Each line corresponds to a row of bricks, and each character in this line - to specific position. To define multiline strings, Lua provides special syntax - double square brackets. Let's agree that the hash symbol '#' denotes a brick, and the space ' ' or the underscore '_' denote empty space. That way it is possible to use underscores to visually indicate size of the map.

levels.sequence = {}
levels.sequence[1] = [[  --(*1)
___________

# # ### # #
# # #   # #
### ##   # 
# # #    # 
# # ###  # 
___________
]]

levels.sequence[2] = [[
___________

##  # # ###
# # # # #  
###  #  ## 
# #  #  #  
###  #  ###
___________
]]

(*1): Care should be taken not to put any whitespaces or any other characters after opening brackets, because Lua will treat it as an additional line that will be added to the level data (I've put several spaces and a comment here to illustrate the point, but they are not present in the actual code). Depending on the way it's parsed, it may or may not cause errors.

To construct levels from such data, it is necessary to iterate over each line and each character of each line. Lua doesn't allow to iterate over contents of the string directly, but it has built-in capabilities for pattern matching and regular expressions, which can be used instead. In this case, gmatch string method is a good choice: for a given string and a regexp pattern, it allows to iterate over each substring in the string that matches the pattern. Typically it is used in constructions with the for-loop, such as

for pattern_match in some_string:gmatch( pattern ) do
   print( pattern_match )
end

To extract a single line from a multiline string, a '(.-)\n' pattern can be used. Dot '.' matches arbitrary character, minus '-' means "match the previous character or class of characters zero or more times, as few times as possible", brackets '()' denote a group and '\n' stands for the new line character. Literally '(.-)\n' reads as "match shortest sequence of arbitrary characters of lengths zero or more followed by newline". So, effectively, '(.-)' matches everything from the beginning of the line to the nearest end-of-line character, which is precisely a single line of a multiline string. That value will be assigned to row variable. Next, it is necessary to iterate over each character in the row and do some action depending on the symbol we found.

function bricks.construct_level( level_bricks_arrangement )
   bricks.no_more_bricks = false
   local row_index = 0
   for row in level_bricks_arrangement:gmatch( '(.-)\n' ) do          --(*1)
      row_index = row_index + 1
      print( "row", row_index, row )
      local col_index = 0
      for bricktype in row:gmatch('.') do                             --(*2)
         col_index = col_index + 1
         print( "col", col_index, bricktype )
         if bricktype == '#' then                                     --(*3)
            local new_brick_position_x = bricks.top_left_position_x +
               ( col_index - 1 ) *
               ( bricks.brick_width + bricks.horizontal_distance )
            local new_brick_position_y = bricks.top_left_position_y +
               ( row_index - 1 ) *
               ( bricks.brick_height + bricks.vertical_distance )
            local new_brick = bricks.new_brick( new_brick_position_x,
                                                new_brick_position_y )
            table.insert( bricks.current_level_bricks, new_brick )
         end
      end
   end
end

(*1): dot '.' means arbitrary character, minus '-' means "match the previous character or class of characters zero or more times, as few times as possible", brackets '()' denote a group and '\n' stands for new line character. '(.-)\n' matches shortest sequence of arbitrary characters of lengths zero or more followed by newline. Basically, '(.-)' matches everything from the beginning of the line to the nearest end-of-line character. That value will be assigned to row variable.
(*2): row:gmatch('.') iterates over each character of the string row.
(*3): each character in the row is analyzed and depending on it's type certain actions are performed.