-- # Settings
return {
    -- If this table is present, then various script related functionality
    -- will be performed.
    script = {
        -- The path of the root file used to generate the script.
        --
        -- This setting is required.
        input = 'path/to/input.lua',

        -- The path to use when creating the output script.
        --
        -- This setting is required.
        output = 'path/to/output.lua',

        -- Value to be used as the `package.path` when generating the
        -- script.  If absent, defaults to the `package.path` used for Map.
        package = {
            path = table.concat ({
                'lib/?.lua',
                'lib/?/init.lua'
            }, ';')
        },

        options = {
            -- Indicates whether to enable debug mode.  This will cause file
            -- names and line numbers in error messages to reflect the
            -- original locations.
            --
            -- By default, this option is disabled.  Listed are the accepted
            -- values for debug mode.  Note that 'name', the default mode
            -- should `true` be specified, will display the module's name.
            -- Setting the option to 'path' will display the file path.
            debug = false or nil or true or 'name' or 'path',

            -- Indicates whether to skip running Luacheck.
            --
            -- By default, this option is disabled.  Should `true` be
            -- specified, then all checks are disabled.  Setting the option
            -- to 'check' or 'build' will skip checks for those commands.
            skip_checks = false or nil or true or 'check' or 'build'
        }
    },

    -- If this table is present, then user build files will be processed.
    build = {
        -- The directory containing all user files that can be used to
        -- access and change the map environment.  It will be recursively
        -- traversed, and all Lua files within will be processed.
        --
        -- Note that when traversing directories, entries within are sorted
        -- using `table.sort ()`.  This should represent alphanumeric
        -- sorting.  This knowledge can be leveraged to ensure deterministic
        -- behavior.
        --
        -- If the build table is specified, this setting is required.
        directory = 'path/to/user/build/files',

        -- Values to be used as the `package.path` and `package.cpath`
        -- within user build files.  If absent, defaults to the paths used
        -- by Map.
        package = {
            path = table.concat ({
                'lib/?.lua',
                'lib/?/init.lua'
            }, ';'),

            cpath = table.concat ({
                'lib/?.so'
            }, ';')
        },

        options = {
            -- Indicates whether to disable build files, causing Map to
            -- behave as if the table was absent.
            --
            -- By default, this option is disabled.  Should `true` be
            -- specified, then build files are disabled.  Setting the
            -- option to 'check' or 'build' will disable build files for
            -- those commands.
            disable = false or nil or true or 'check' or 'build'
        }
    },

    -- If this table is present, then the input archive will be sourced for
    -- information to provide to the build environment.  Additionally, an
    -- output archive may be produced, depending on the command.
    map = {
        -- Path to the map file or directory that will be used as a basis
        -- for the built map.
        --
        -- If the map table is specified, this setting is required.
        input = 'path/to/input.w3x',

        -- The path to use when creating the output map.  Take care when
        -- specifying the path, as any existing file or directory at this
        -- specified location will be removed.
        --
        -- If the map table is specified, this setting is required.
        output = 'path/to/output.w3x',

        options = {
            -- Indicates that the output W3X archive should be directory
            -- based instead of MPQ based.  By default, this option is
            -- disabled.
            directory = false or nil or true
        }
    }
}

-- Name the build environment exposed by **Map** however you prefer.  This
-- table will be shared between all user build files.  One could store their
-- own data within, if they desire.  Just do not use one of the above keys.
local map = ...

-- Automatically loads `war3map.wts`, if found.
local strings = map.strings

-- Doing this clears the specified key from the build environment, thus
-- preventing Map from processing it and writing a new file.  Instead, the
-- status of the file will be pulled from the imports table.
map.strings = nil

-- It is the key within the build environment that is special, not the
-- returned data.
print (#strings)

-- This will write an empty `war3map.wts` into the output archive.  Note
-- that an empty table is not a valid input for all files supported by Map,
-- and errors may be encountered.
map.strings = {}

-- This will error, as there is expected data missing.
map.information = {}

local map = ...

print (map.settings.script.input) -- 'path/to/input.lua'

local map = ...

map.information.map.name = 'A Map'

local map = ...

-- The file with this name will be copied from the input archive to the
-- output archive.
map.imports ['file.txt'] = true

-- Import the file specified by the provide path to the output archive using
-- the given name.
map.imports ['A/B/stuff.txt'] = 'path/to/imports/other.txt'

-- Clear an already specified import.
map.imports ['file.txt'] = nil

-- Import a directory's contents, preserving its structure.  Note that
-- `number` keys are iterated in ascending order, and do not need to be
-- contiguous.  These are processed after `string` keys.
map.imports [1] = 'path/to/directory'
map.imports [2] = 'path/to/another/directory'

local map = ...

map.objects ['A000'] = {
    type = 'ability', -- Indicates the type of object.  See below.
    base = 'ACev' -- If present, implies a 'custom' object.

    -- Example of a modification that has no levels.
    anam = {
        type = 'string',
        value = 'An Example'
    },

    -- Example of a modification that has levels.
    atp1 = {
        type = 'string',
        values = {
            [1] = 'Based on Evasion!',
            [2] = 'Definitely based on Evasion!'
        }
    },

    -- Example of a modification that has 'custom' data.
    Eev1 = {
        data = 1,
        type = 'unreal',
        values = {
            [1] = 0,
            [2] = 0
        }
    }
}

local map = ...

print (map.constants.interface.FrameDef.LUMBER) --> nil
map.constants.interface.FrameDef.LUMBER = 'Not Lumber'

local map = ...

print (map.strings [1]) --> 'Force 1'
map.strings [2] = 'Just another Warcraft III map'

local map = ...

print (map.regions [1].name) --> 'Region 000'
map.regions [1].name = 'New Name'

local map = ...

print (map.cameras [1].name) --> 'Camera ABC'
map.cameras [1].name = 'Camera XYZ'

local map = ...

print (map.doodads [1].type) --> 'LTlt'
map.doodads [1].life = 50

local map = ...

print (map.units [1].type) --> 'hfoo'
map.units [1].player = 3

local map = ...

print (map.sounds [1].effect) --> 'SpellsEAX'
map.sounds [1].volume = 10

local map = ...

map.terrain.tileset = 'A'

for _, row in ipairs (map.terrain.tiles) do
    for _, tile in ipairs (row) do
        print (tile.ground.texture) --> 0
    end
end

local map = ...

for _, row in ipairs (map.pathing.cells) do
    for _, cell in ipairs (row) do
        print (cell.buildable) --> false
    end
end