Creating an API

In this section, you will be moving the code to generate the map into an API. Because a lot more code will be added later, it makes sense to think about organizing this now while the code is small.

Create MapBuilder Script

Create a new script called MapBuilder and move it to the My APIs folder in Project Content.

Add Custom Properties

The MapBuilder script will need custom properties for the ASCIIParser and the Tiles data table.

1. Select the MapBuilder script in Project Content so it is the active item selected.
2. Add the ASCIIParser script as a custom property called ASCIIParser.
3. Add the Tiles data table as a custom property called Tiles.

Add Script Variables

Open up the MapBuilder script and add variables for the custom properties so you have access to the ASCIIParser and the map Tiles data table.

Add a variable called MapBuilder and store an empty table. This variable will hold all the properties and functions that will be returned at the end so that scripts which require this API can use it.

local ASCIIParser = require(script:GetCustomProperty("ASCIIParser"))
local TILES = require(script:GetCustomProperty("Tiles"))

local MapBuilder = {}
Code language: Lua (lua)

Create Build Function

The build function will be responsible for forwarding on options to other functions in the API, and also responsible for spawning the map based on the table generated from the ASCIIParser script.

Notice that the function for Build is prefixed with MapBuilder. This is so that the Build function is added to the MapBuilder table so it will be exposed to scripts that require the API.

function MapBuilder.Build(opts)
	local map, mapStr = ASCIIParser.BuildMap(opts.map, opts.width, opts.height)

	MapBuilder.Spawn(map, opts.width, opts.height, opts.size, opts.container)
end
Code language: Lua (lua)

Create Spawn Function

The spawn function will be responsible for spawning the tiles for the map built by the ASCIIParser in the Build function.

Notice the first if statement inside the spawn function is checking the environment the script is being run in. Because this is a script in a static context, you need to make sure the spawn functions are done on the server, or you will get an error.

function MapBuilder.Spawn(map, width, height, size, container)
	if not Environment.IsServer() then
		return
	end

	for row = 1, height do
		for col = 1, width do
			local tileRow = TILES[map[row][col]]

			if tileRow ~= nil then
				local scale = Vector3.New(size / 100, size / 100, size / 100)

				if tileRow.floor then
					scale.z = 1
				end

				local x = -(row * size) + (height * size) / 2
				local y = (col * size) - (width * size) / 2
			
				local params = {

					scale = scale,
					position = Vector3.New(x, y, 0),

				}

				container:SpawnSharedAsset(tileRow.tile, params)
			end
		end
	end
end
Code language: Lua (lua)

Return the MapBuilder

The MapBuilder API needs the MapBuilder table returned at the end of the script so that scripts which require this API will be given the MapBuilder table.

return MapBuilder
Code language: Lua (lua)

The MapBuilder Script

local ASCIIParser = require(script:GetCustomProperty("ASCIIParser"))
local TILES = require(script:GetCustomProperty("Tiles"))

local MapBuilder = {}

function MapBuilder.Build(opts)
	local map, mapStr = ASCIIParser.BuildMap(opts.map, opts.width, opts.height)

	MapBuilder.Spawn(map, opts.width, opts.height, opts.size, opts.container)
end

function MapBuilder.Spawn(map, width, height, size, container)
	if not Environment.IsServer() then
		return
	end

	for row = 1, height do
		for col = 1, width do
			local tileRow = TILES[map[row][col]]

			if tileRow ~= nil then
				local scale = Vector3.New(size / 100, size / 100, size / 100)

				if tileRow.floor then
					scale.z = 1
				end

				local x = -(row * size) + (height * size) / 2
				local y = (col * size) - (width * size) / 2
			
				local params = {

					scale = scale,
					position = Vector3.New(x, y, 0),

				}

				container:SpawnSharedAsset(tileRow.tile, params)
			end
		end
	end
end

return MapBuilder
Code language: Lua (lua)

Edit GenerateMap Script

The GenerateMap script in the Hierarchy will need to be modified to use the new API. It will also need the custom properties changed so it no longer uses the ASCIIParser API, but the MapBuilder API.

Edit Custom Properties

1. In the Hierarchy select the GenerateMap Script in the Generated Map folder.
2. Remove the custom property called ASCIIParser.
3. Add the MapBuilder API as a custom property on the GenerateMap script called MapBuilder.

Edit GenerateMap Script

Open up the GenerateMap script and remove all the code in the script. You will be using the MapBuilder API and passing options to the Build function that will handle spawning in the tiles. From now on, any algorithm changes that need to be done to determine tile spawns and other items will be done from within the API.

Require MapBuilder API

You can require the MapBuilder API by using the require keyword in the script.

local MapBuilder = require(script:GetCustomProperty("MapBuilder"))
Code language: Lua (lua)

Build the Map

Call the Build function from the MapBuilder API to build the map. The Build function requires a table as the input that passes in the information about the map that needs to be built.

MapBuilder.Build({

	container = script.parent,
	width = 10,
	height = 10,
	size = 1000,
	map = [[

		1111111111
		1100001101
		1001100101
		1111101101
		1100000001
		1001111001
		1011001001
		1011101011
		1010000011
		1111111111

	]]

})
Code language: Lua (lua)

The GenerateMap Script

local MapBuilder = require(script:GetCustomProperty("MapBuilder"))

MapBuilder.Build({

	container = script.parent,
	width = 10,
	height = 10,
	size = 1000,
	map = [[

		1111111111
		1100001101
		1001100101
		1111101101
		1100000001
		1001111001
		1011001001
		1011101011
		1010000011
		1111111111

	]]

})
Code language: Lua (lua)

Test the Game

Test the game to make sure the build is still created correctly. Try a few different sizes and ASCII strings.