Triggers

do; local _, codeLoc = pcall(error, "", 2) --get line number where DebugUtils begins.
--[[
 --------------------------
 -- | Debug Utils 2.1a | --
 --------------------------

 --> https://www.hiveworkshop.com/threads/lua-debug-utils-incl-ingame-console.353720/

 - by Eikonium, with special thanks to:
    - @Bribe, for pretty table print, showing that xpcall's message handler executes before the stack unwinds and useful suggestions like name caching and stack trace improvements.
    - @Jampion, for useful suggestions like print caching and applying Debug.try to all code entry points
    - @Luashine, for useful feedback and building "WC3 Debug Console Paste Helper​" (https://github.com/Luashine/wc3-debug-console-paste-helper#readme)
    - @HerlySQR, for showing a way to get a stack trace in Wc3 (https://www.hiveworkshop.com/threads/lua-getstacktrace.340841/)
    - @Macadamia, for showing a way to print warnings upon accessing undeclared globals, where this all started with (https://www.hiveworkshop.com/threads/lua-very-simply-trick-to-help-lua-users-track-syntax-errors.326266/)

-----------------------------------------------------------------------------------------------------------------------------
| Provides debugging utility for Wc3-maps using Lua.                                                                        |
|                                                                                                                           |
| Including:                                                                                                                |
|   1. Automatic ingame error messages upon running erroneous code from triggers or timers.                                 |
|   2. Ingame Console that allows you to execute code via Wc3 ingame chat.                                                  |
|   3. Automatic warnings upon reading undeclared globals (which also triggers after misspelling globals)                   |
|   4. Debug-Library functions for manual error handling.                                                                   |
|   5. Caching of loading screen print messages until game start (which simplifies error handling during loading screen)    |
|   6. Overwritten tostring/print-functions to show the actual string-name of an object instead of the memory position.     |
|   7. Conversion of war3map.lua-error messages to local file error messages.                                               |
|   8. Other useful debug utility (table.print and Debug.wc3Type)                                                           |
-----------------------------------------------------------------------------------------------------------------------------

-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| Installation:                                                                                                                                                             |
|                                                                                                                                                                           |
|   1. Copy the code (DebugUtils.lua, StringWidth.lua and IngameConsole.lua) into your map. Use script files (Ctrl+U) in your trigger editor, not text-based triggers!      |
|   2. Order the files: DebugUtils above StringWidth above IngameConsole. Make sure they are above ALL other scripts (crucial for local line number feature).               |
|   3. Adjust the settings in the settings-section further below to receive the debug environment that fits your needs.                                                     |
|                                                                                                                                                                           |
| Deinstallation:                                                                                                                                                           |
|                                                                                                                                                                           |
|  - Debug Utils is meant to provide debugging utility and as such, shall be removed or invalidated from the map closely before release.                                    |
|  - Optimally delete the whole Debug library. If that isn't suitable (because you have used library functions at too many places), you can instead replace Debug Utils     |
|    by the following line of code that will invalidate all Debug functionality (without breaking your code):                                                               |
|    Debug = setmetatable({try = function(...) return select(2,pcall(...)) end}, {__index = function(t,k) return DoNothing end}); try = Debug.try                           |
|  - If that is also not suitable for you (because your systems rely on the Debug functionality to some degree), at least set ALLOW_INGAME_CODE_EXECUTION to false.         |
|  - Be sure to test your map thoroughly after removing Debug Utils.                                                                                                        |
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------

-------------------------------------------------------------------------------------------------------------------------------------------------------------------------
* Documentation and API-Functions:
*
*       - All automatic functionality provided by Debug Utils can be deactivated using the settings directly below the documentation.
*
* -------------------------
* | Ingame Code Execution |
* -------------------------
*       - Debug Utils provides the ability to run code via chat command from within Wc3, if you have conducted step 3 from the installation section.
*       - You can either open the ingame console by typing "-console" into the chat, or directly execute code by typing "-exec <code>".
*       - See IngameConsole script for further documentation.
*
* ------------------
* | Error Handling |
* ------------------
*        - Debug Utils automatically applies error handling (i.e. Debug.try) to code executed by your triggers and timers (error handling means that error messages are printed on screen, if anything doesn't run properly).
*        - You can still use the below library functions for manual debugging.
*
*    Debug.try(funcToExecute, ...) -> ...
*        - Help function for debugging another function (funcToExecute) that prints error messages on screen, if funcToExecute fails to execute.
*        - DebugUtils will automatically apply this to all code run by your triggers and timers, so you rarely need to apply this manually (maybe on code run in the Lua root).
*        - Calls funcToExecute with the specified parameters (...) in protected mode (which means that following code will continue to run even if funcToExecute fails to execute).
*        - If the call is successful, returns the specified function's original return values (so p1 = Debug.try(Player, 0) will work fine).
*        - If the call is unsuccessful, prints an error message on screen (including stack trace and parameters you have potentially logged before the error occured)
*        - By default, the error message consists of a line-reference to war3map.lua (which you can look into by forcing a syntax error in WE or by exporting it from your map via File -> Export Script).
*          You can get more helpful references to local script files instead, see section about "Local script references".
*        - Example: Assume you have a code line like "func(param1,param2)", which doesn't work and you want to know why.
*           Option 1: Change it to "Debug.try(func, param1, param2)", i.e. separate the function from the parameters.
*           Option 2: Change it to "Debug.try(function() return func(param1, param2) end)", i.e. pack it into an anonymous function (optionally skip the return statement).
*    Debug.log(...)
*        - Logs the specified parameters to the Debug-log. The Debug-log will be printed upon the next error being catched by Debug.try, Debug.assert or Debug.throwError.
*        - The Debug-log will only hold one set of parameters per code-location. That means, if you call Debug.log() inside any function, only the params saved within the latest call of that function will be kept.
*    Debug.throwError(...)
*        - Prints an error message including document, line number, stack trace, previously logged parameters and all specified parameters on screen. Parameters can have any type.
*        - In contrast to Lua's native error function, this can be called outside of protected mode and doesn't halt code execution.
*    Debug.assert(condition:boolean, errorMsg:string, ...) -> ...
*        - Prints the specified error message including document, line number, stack trace and previously logged parameters on screen, IF the specified condition fails (i.e. resolves to false/nil).
*        - Returns ..., IF the specified condition holds.
*        - This works exactly like Lua's native assert, except that it also works outside of protected mode and does not halt code execution.
*    Debug.traceback() -> string
*        - Returns the stack trace at the position where this is called. You need to manually print it.
*    Debug.getLine([depth: integer]) -> integer?
*        - Returns the line in war3map.lua, where this function is executed.
*        - You can specify a depth d >= 1 to instead return the line, where the d-th function in the stack trace was called. I.e. depth = 2 will return the line of execution of the function that calls Debug.getLine.
*        - Due to Wc3's limited stack trace ability, this might sometimes return nil for depth >= 3, so better apply nil-checks on the result.
*    Debug.getLocalErrorMsg(errorMsg:string) -> string
*        - Takes an error message containing a file and a linenumber and converts war3map.lua-lines to local document lines as defined by uses of Debug.beginFile() and Debug.endFile().
*        - Error Msg must be formatted like "<document>:<linenumber><Rest>".
*
* -----------------------------------
* | Warnings for undeclared globals |
* -----------------------------------
*        - DebugUtils will print warnings on screen, if you read an undeclared global variable.
*        - This is technically the case, when you misspelled on a function name, like calling CraeteUnit instead of CreateUnit.
*        - Keep in mind though that the same warning will pop up after reading a global that was intentionally nilled. If you don't like this, turn of this feature in the settings.
*
* -----------------
* | Print Caching |
* -----------------
*        - DebugUtils caches print()-calls occuring during loading screen and delays them to after game start.
*        - This also applies to loading screen error messages, so you can wrap erroneous parts of your Lua root in Debug.try-blocks and see the message after game start.
*
* -------------------------
* | Local File Stacktrace |
* -------------------------
*        - By default, error messages and stack traces printed by the error handling functionality of Debug Utils contain references to war3map.lua (a big file just appending all your local scripts).
*        - The Debug-library provides the two functions below to index your local scripts, activating local file names and line numbers (matching those in your IDE) instead of the war3map.lua ones.
*        - This allows you to inspect errors within your IDE (VSCode) instead of the World Editor.
*
*    Debug.beginFile(fileName: string [, depth: integer])
*        - Tells the Debug library that the specified file begins exactly here (i.e. in the line, where this is called).
*        - Using this improves stack traces of error messages. "war3map.lua"-references between <here> and the next Debug.endFile() will be converted to file-specific references.
*        - All war3map.lua-lines located between the call of Debug.beginFile(fileName) and the next call of Debug.beginFile OR Debug.endFile are treated to be part of "fileName".
*        - !!! To be called in the Lua root in Line 1 of every document you wish to track. Line 1 means exactly line 1, before any comment! This way, the line shown in the trace will exactly match your IDE.
*        - Depth can be ignored, except if you want to use a custom wrapper around Debug.beginFile(), in which case you need to set the depth parameter to 1 to record the line of the wrapper instead of the line of Debug.beginFile().
*    Debug.endFile([depth: integer])
*        - Ends the current file that was previously begun by using Debug.beginFile(). War3map.lua-lines after this will not be converted until the next instance of Debug.beginFile().
*        - The next call of Debug.beginFile() will also end the previous one, so using Debug.endFile() is optional. Mainly recommended to use, if you prefer to have war3map.lua-references in a certain part of your script (such as within GUI triggers).
*        - Depth can be ignored, except if you want to use a custom wrapper around Debug.endFile(), you need to increase the depth parameter to 1 to record the line of the wrapper instead of the line of Debug.endFile().
*
* ----------------
* | Name Caching |
* ----------------
*        - DebugUtils overwrites the tostring-function so that it prints the name of a non-primitive object (if available) instead of its memory position. The same applies to print().
*        - For instance, print(CreateUnit) will show "function: CreateUnit" on screen instead of "function: 0063A698".
*        - The table holding all those names is referred to as "Name Cache".
*        - All names of objects in global scope will automatically be added to the Name Cache both within Lua root and again at game start (to get names for overwritten natives and your own objects).
*        - New names entering global scope will also automatically be added, even after game start. The same applies to subtables of _G up to a depth of Debug.settings.NAME_CACHE_DEPTH.
*        - Objects within subtables will be named after their parent tables and keys. For instance, the name of the function within T = {{bla = function() end}} is "T[1].bla".
*        - The automatic adding doesn't work for objects saved into existing variables/keys after game start (because it's based on __newindex metamethod which simply doesn't trigger)
*        - You can manually add names to the name cache by using the following API-functions:
*
*    Debug.registerName(whichObject:any, name:string)
*        - Adds the specified object under the specified name to the name cache, letting tostring and print output "<type>: <name>" going foward.
*        - The object must be non-primitive, i.e. this won't work on strings, numbers and booleans.
*        - This will overwrite existing names for the specified object with the specified name.
*    Debug.registerNamesFrom(parentTable:table [, parentTableName:string] [, depth])
*        - Adds names for all values from within the specified parentTable to the name cache.
*        - Names for entries will be like "<parentTableName>.<key>" or "<parentTableName>[<key>]" (depending on the key type), using the existing name of the parentTable from the name cache.
*        - You can optionally specify a parentTableName to use that for the entry naming instead of the existing name. Doing so will also register that name for the parentTable, if it doesn't already has one.
*        - Specifying the empty string as parentTableName will suppress it in the naming and just register all values as "<key>". Note that only string keys will be considered this way.
*        - In contrast to Debug.registerName(), this function will NOT overwrite existing names, but just add names for new objects.
*    Debug.oldTostring(object:any) -> string
*        - The old tostring-function in case you still need outputs like "function: 0063A698".
*
* -----------------
* | Other Utility |
* -----------------
*
*    Debug.wc3Type(object:any) -> string
*        - Returns the Warcraft3-type of the input object. E.g. Debug.wc3Type(Player(0)) will return "player".
*        - Returns type(object), if used on Lua-objects.
*    table.tostring(whichTable [, depth:integer] [, pretty_yn:boolean])
*        - Creates a list of all (key,value)-pairs from the specified table. Also lists subtable entries up to the specified depth (unlimited, if not specified).
*        - E.g. for T = {"a", 5, {7}}, table.tostring(T) would output '{(1, "a"), (2, 5), (3, {(1, 7)})}' (if using concise style, i.e. pretty_yn being nil or false).
*        - Not specifying a depth can potentially lead to a stack overflow for self-referential tables (e.g X = {}; X[1] = X). Choose a sensible depth to prevent this (in doubt start with 1 and test upwards).
*        - Supports pretty style by setting pretty_yn to true. Pretty style is linebreak-separated, uses indentations and has other visual improvements. Use it on small tables only, because Wc3 can't show that many linebreaks at once.
*        - All of the following is valid syntax: table.tostring(T), table.tostring(T, depth), table.tostring(T, pretty_yn) or table.tostring(T, depth, pretty_yn).
*        - table.tostring is not multiplayer-synced.
*    table.print(whichTable [, depth:integer] [, pretty_yn:boolean])
*        - Prints table.tostring(...).
*
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------]]

    -- disable sumneko extension warnings for imported resource
    ---@diagnostic disable

    ----------------
    --| Settings |--
    ----------------

    Debug = {
        --BEGIN OF SETTINGS--
        settings = {
                SHOW_TRACE_ON_ERROR = true                      ---Set to true to show a stack trace on every error in addition to the regular message (msg sources: automatic error handling, Debug.try, Debug.throwError, ...)
            ,   INCLUDE_DEBUGUTILS_INTO_TRACE = true            ---Set to true to include lines from Debug Utils into the stack trace. Those show the source of error handling, which you might consider redundant.
            ,   USE_TRY_ON_TRIGGERADDACTION = true              ---Set to true for automatic error handling on TriggerAddAction (applies Debug.try on every trigger action).
            ,   USE_TRY_ON_CONDITION = true                     ---Set to true for automatic error handling on boolexpressions created via Condition() or Filter() (essentially applies Debug.try on every trigger condition).
            ,   USE_TRY_ON_TIMERSTART = true                    ---Set to true for automatic error handling on TimerStart (applies Debug.try on every timer callback).
            ,   USE_TRY_ON_ENUMFUNCS = true                     ---Set to true for automatic error handling on ForGroup, ForForce, EnumItemsInRect and EnumDestructablesInRect (applies Debug.try on every enum callback)
            ,   USE_TRY_ON_COROUTINES = true                    ---Set to true for improved stack traces on errors within coroutines (applies Debug.try on coroutine.create and coroutine.wrap). This lets stack traces point to the erroneous function executed within the coroutine (instead of the function creating the coroutine).
            ,   ALLOW_INGAME_CODE_EXECUTION = true              ---Set to true to enable IngameConsole and -exec command.
            ,   WARNING_FOR_UNDECLARED_GLOBALS = true           ---Set to true to print warnings upon accessing undeclared globals (i.e. globals with nil-value). This is technically the case after having misspelled on a function name (like CraeteUnit instead of CreateUnit).
            ,   SHOW_TRACE_FOR_UNDECLARED_GLOBALS = false       ---Set to true to include a stack trace into undeclared global warnings. Only takes effect, if WARNING_FOR_UNDECLARED_GLOBALS is also true.
            ,   USE_PRINT_CACHE = true                          ---Set to true to let print()-calls during loading screen be cached until the game starts.
            ,   PRINT_DURATION = nil                            ---Adjust the duration in seconds that values printed by print() last on screen. Set to nil to use default duration (which depends on string length).
            ,   USE_NAME_CACHE = true                           ---Set to true to let tostring/print output the string-name of an object instead of its memory location (except for booleans/numbers/strings). E.g. print(CreateUnit) will output "function: CreateUnit" instead of "function: 0063A698".
            ,   AUTO_REGISTER_NEW_NAMES = true                  ---Automatically adds new names from global scope (and subtables of _G up to NAME_CACHE_DEPTH) to the name cache by adding metatables with the __newindex metamethod to ALL tables accessible from global scope.
            ,   NAME_CACHE_DEPTH = 4                            ---Set to 0 to only affect globals. Experimental feature: Set to an integer > 0 to also cache names for subtables of _G (up to the specified depth). Warning: This will alter the __newindex metamethod of subtables of _G (but not break existing functionality).
        }
        --END OF SETTINGS--
        --START OF CODE--
        ,   data = {
                nameCache = {}                                  ---@type table<any,string> contains the string names of any object in global scope (random for objects that have multiple names)
            ,   nameCacheMirror = {}                            ---@type table<string,any> contains the (name,object)-pairs of all objects in the name cache. Used to prevent name duplicates that might otherwise occur upon reassigning globals.
            ,   nameDepths = {}                                 ---@type table<any,integer> contains the depth of the name used by by any object in the name cache (i.e. the depth within the parentTable).
            ,   autoIndexedTables = {}                          ---@type table<table,boolean> contains (t,true), if DebugUtils already set a __newindex metamethod for name caching in t. Prevents double application.
            ,   paramLog = {}                                   ---@type table<string,string> saves logged information per code location. to be filled by Debug.log(), to be printed by Debug.try()
            ,   sourceMap = {{firstLine= 1,file='DebugUtils'}}  ---@type table<integer,{firstLine:integer,file:string,lastLine?:integer}> saves lines and file names of all documents registered via Debug.beginFile().
            ,   printCache = {n=0}                              ---@type string[] contains the strings that were attempted to print during loading screen.
        }
    }
    --localization
    local settings, paramLog, nameCache, nameDepths, autoIndexedTables, nameCacheMirror, sourceMap, printCache = Debug.settings, Debug.data.paramLog, Debug.data.nameCache, Debug.data.nameDepths, Debug.data.autoIndexedTables, Debug.data.nameCacheMirror, Debug.data.sourceMap, Debug.data.printCache

    --Write DebugUtils first line number to sourceMap:
    ---@diagnostic disable-next-line
    Debug.data.sourceMap[1].firstLine = tonumber(codeLoc:match(":\x25d+"):sub(2,-1))

    -------------------------------------------------
    --| File Indexing for local Error Msg Support |--
    -------------------------------------------------

    -- Functions for war3map.lua -> local file conversion for error messages.

    ---Returns the line number in war3map.lua, where this is called (for depth = 0).
    ---Choose a depth d > 0 to instead return the line, where the d-th function in the stack leading to this call is executed.
    ---@param depth? integer default: 0.
    ---@return number?
    function Debug.getLine(depth)
        depth = depth or 0
        local _, location = pcall(error, "", depth + 3) ---@diagnostic disable-next-line
        local line = location:match(":\x25d+") --extracts ":1000" from "war3map.lua:1000:..."
        return tonumber(line and line:sub(2,-1)) --check if line is nil before applying string.sub to prevent errors (nil can result from string.match above, although it should never do so in our case)
    end

    ---Tells the Debug library that the specified file begins exactly here (i.e. in the line, where this is called).
    ---
    ---Using this improves stack traces of error messages. Stack trace will have "war3map.lua"-references between this and the next Debug.endFile() converted to file-specific references.
    ---
    ---To be called in the Lua root in Line 1 of every file you wish to track! Line 1 means exactly line 1, before any comment! This way, the line shown in the trace will exactly match your IDE.
    ---
    ---If you want to use a custom wrapper around Debug.beginFile(), you need to increase the depth parameter to 1 to record the line of the wrapper instead of the line of Debug.beginFile().
    ---@param fileName string
    ---@param depth? integer default: 0. Set to 1, if you call this from a wrapper (and use the wrapper in line 1 of every document).
    ---@param lastLine? integer Ignore this. For compatibility with Total Initialization.
    function Debug.beginFile(fileName, depth, lastLine)
        depth, fileName = depth or 0, fileName or '' --filename is not actually optional, we just default to '' to prevent crashes.
        local line = Debug.getLine(depth + 1)
        if line then --for safety reasons. we don't want to add a non-existing line to the sourceMap
            table.insert(sourceMap, {firstLine = line, file = fileName, lastLine = lastLine}) --automatically sorted list, because calls of Debug.beginFile happen logically in the order of the map script.
        end
    end

    ---Tells the Debug library that the file previously started with Debug.beginFile() ends here.
    ---This is in theory optional to use, as the next call of Debug.beginFile will also end the previous. Still good practice to always use this in the last line of every file.
    ---If you want to use a custom wrapper around Debug.endFile(), you need to increase the depth parameter to 1 to record the line of the wrapper instead of the line of Debug.endFile().
    ---@param depth? integer
    function Debug.endFile(depth)
        depth = depth or 0
        local line = Debug.getLine(depth + 1)
        sourceMap[#sourceMap].lastLine = line
    end

    ---Takes an error message containing a file and a linenumber and converts both to local file and line as saved to Debug.sourceMap.
    ---@param errorMsg string must be formatted like "<document>:<linenumber><RestOfMsg>".
    ---@return string convertedMsg a string of the form "<localDocument>:<localLinenumber><RestOfMsg>"
    function Debug.getLocalErrorMsg(errorMsg)
        local startPos, endPos = errorMsg:find(":\x25d*") --start and end position of line number. The part before that is the document, part after the error msg.
        if startPos and endPos then --can be nil, if input string was not of the desired form "<document>:<linenumber><RestOfMsg>".
            local document, line, rest = errorMsg:sub(1, startPos), tonumber(errorMsg:sub(startPos+1, endPos)), errorMsg:sub(endPos+1, -1) --get error line in war3map.lua
            if document == 'war3map.lua:' and line then --only convert war3map.lua-references to local position. Other files such as Blizzard.j.lua are not converted (obiously).
                for i = #sourceMap, 1, -1 do --find local file containing the war3map.lua error line.
                    if line >= sourceMap[i].firstLine then --war3map.lua line is part of sourceMap[i].file
                        if not sourceMap[i].lastLine or line <= sourceMap[i].lastLine then --if lastLine is given, we must also check for it
                            return sourceMap[i].file .. ":" .. (line - sourceMap[i].firstLine + 1) .. rest
                        else --if line is larger than firstLine and lastLine of sourceMap[i], it is not part of a tracked file -> return global war3map.lua position.
                            break --prevent return within next step of the loop ("line >= sourceMap[i].firstLine" would be true again, but wrong file)
                        end
                    end
                end
            end
        end
        return errorMsg
    end
    local convertToLocalErrorMsg = Debug.getLocalErrorMsg

    ----------------------
    --| Error Handling |--
    ----------------------

    local concat
    ---Applies tostring() on all input params and concatenates them 4-space-separated.
    ---@param firstParam any
    ---@param ... any
    ---@return string
    concat = function(firstParam, ...)
        if select('#', ...) == 0 then
            return tostring(firstParam)
        end
        return tostring(firstParam) .. '    ' .. concat(...)
    end

    ---Returns the stack trace between the specified startDepth and endDepth.
    ---The trace lists file names and line numbers. File name is only listed, if it has changed from the previous traced line.
    ---The previous file can also be specified as an input parameter to suppress the first file name in case it's identical.
    ---@param startDepth integer
    ---@param endDepth integer
    ---@return string trace
    local function getStackTrace(startDepth, endDepth)
        local trace, separator = "", ""
        local _, currentFile, lastFile, tracePiece, lastTracePiece
        for loopDepth = startDepth, endDepth do --get trace on different depth level
            _, tracePiece = pcall(error, "", loopDepth) ---@type boolean, string
            tracePiece = convertToLocalErrorMsg(tracePiece)
            if #tracePiece > 0 and lastTracePiece ~= tracePiece then --some trace pieces can be empty, but there can still be valid ones beyond that
                currentFile = tracePiece:match("^.-:")
                --Hide DebugUtils in the stack trace (except main reference), if settings.INCLUDE_DEBUGUTILS_INTO_TRACE is set to true.
                if settings.INCLUDE_DEBUGUTILS_INTO_TRACE or (loopDepth == startDepth) or currentFile ~= "DebugUtils:" then
                    trace = trace .. separator .. ((currentFile == lastFile) and tracePiece:match(":\x25d+"):sub(2,-1) or tracePiece:match("^.-:\x25d+"))
                    lastFile, lastTracePiece, separator = currentFile, tracePiece, " <- "
                end
            end
        end
        return trace
    end

    ---Message Handler to be used by the try-function below.
    ---Adds stack trace plus formatting to the message and prints it.
    ---@param errorMsg string
    ---@param startDepth? integer default: 4 for use in xpcall
    local function errorHandler(errorMsg, startDepth)
        startDepth = startDepth or 4 --xpcall doesn't specify this param, so it must default to 4 for this case
        errorMsg = convertToLocalErrorMsg(errorMsg)
        --Print original error message and stack trace.
        print("|cffff5555ERROR at " .. errorMsg .. "|r")
        if settings.SHOW_TRACE_ON_ERROR then
            print("|cffff5555Traceback (most recent call first):|r")
            print("|cffff5555" .. getStackTrace(startDepth,200) .. "|r")
        end
        --Also print entries from param log, if there are any.
        for location, loggedParams in pairs(paramLog) do
            print("|cff888888Logged at " .. convertToLocalErrorMsg(location) .. loggedParams .. "|r")
            paramLog[location] = nil
        end
    end

    ---Tries to execute the specified function with the specified parameters in protected mode and prints an error message (including stack trace), if unsuccessful.
    ---
    ---Example use: Assume you have a code line like "CreateUnit(0,1,2)", which doesn't work and you want to know why.
    ---* Option 1: Change it to "Debug.try(CreateUnit, 0, 1, 2)", i.e. separate the function from the parameters.
    ---* Option 2: Change it to "Debug.try(function() return CreateUnit(0,1,2) end)", i.e. pack it into an anonymous function. You can skip the "return", if you don't need the return values.
    ---When no error occured, the try-function will return all values returned by the input function.
    ---When an error occurs, try will print the resulting error and stack trace.
    ---@param funcToExecute function the function to call in protected mode
    ---@param ... any params for the input-function
    ---@return ... any
    function Debug.try(funcToExecute, ...)
        return select(2, xpcall(funcToExecute, errorHandler,...))
    end
    ---@diagnostic disable-next-line lowercase-global
    try = Debug.try

    ---Prints "ERROR:" and the specified error objects on the Screen. Also prints the stack trace leading to the error. You can specify as many arguments as you wish.
    ---
    ---In contrast to Lua's native error function, this can be called outside of protected mode and doesn't halt code execution.
    ---@param ... any objects/errormessages to be printed (doesn't have to be strings)
    function Debug.throwError(...)
        errorHandler(getStackTrace(4,4) .. ": " .. concat(...), 5)
    end

    ---Prints the specified error message, if the specified condition fails (i.e. if it resolves to false or nil).
    ---
    ---Returns all specified arguments after the errorMsg, if the condition holds.
    ---
    ---In contrast to Lua's native assert function, this can be called outside of protected mode and doesn't halt code execution (even in case of condition failure).
    ---@param condition any actually a boolean, but you can use any object as a boolean.
    ---@param errorMsg string the message to be printed, if the condition fails
    ---@param ... any will be returned, if the condition holds
    function Debug.assert(condition, errorMsg, ...)
        if condition then
            return ...
        else
            errorHandler(getStackTrace(4,4) .. ": " .. errorMsg, 5)
        end
    end

    ---Returns the stack trace at the code position where this function is called.
    ---The returned string includes war3map.lua/blizzard.j.lua code positions of all functions from the stack trace in the order of execution (most recent call last). It does NOT include function names.
    ---@return string
    function Debug.traceback()
        return getStackTrace(3,200)
    end

    ---Saves the specified parameters to the debug log at the location where this function is called. The Debug-log will be printed for all affected locations upon the try-function catching an error.
    ---The log is unique per code location: Parameters logged at code line x will overwrite the previous ones logged at x. Parameters logged at different locations will all persist and be printed.
    ---@param ... any save any information, for instance the parameters of the function call that you are logging.
    function Debug.log(...)
        local _, location = pcall(error, "", 3) ---@diagnostic disable-next-line: need-check-nil
        paramLog[location or ''] = concat(...)
    end

    ------------------------------------
    --| Name Caching (API-functions) |--
    ------------------------------------

    --Help-table. The registerName-functions below shall not work on call-by-value-types, i.e. booleans, strings and numbers (renaming a value of any primitive type doesn't make sense).
    local skipType = {boolean = true, string = true, number = true, ['nil'] = true}
    --Set weak keys to nameCache and nameDepths and weak values for nameCacheMirror to prevent garbage collection issues
    setmetatable(nameCache, {__mode = 'k'})
    setmetatable(nameDepths, getmetatable(nameCache))
    setmetatable(nameCacheMirror, {__mode = 'v'})

    ---Removes the name from the name cache, if already used for any object (freeing it for the new object). This makes sure that a name is always unique.
    ---This doesn't solve the 
    ---@param name string
    local function removeNameIfNecessary(name)
        if nameCacheMirror[name] then
            nameCache[nameCacheMirror[name]] = nil
            nameCacheMirror[name] = nil
        end
    end

    ---Registers a name for the specified object, which will be the future output for tostring(whichObject).
    ---You can overwrite existing names for whichObject by using this.
    ---@param whichObject any
    ---@param name string
    function Debug.registerName(whichObject, name)
        if not skipType[type(whichObject)] then
            removeNameIfNecessary(name)
            nameCache[whichObject] = name
            nameCacheMirror[name] = whichObject
            nameDepths[name] = 0
        end
    end

    ---Registers a new name to the nameCache as either just <key> (if parentTableName is the empty string), <table>.<key> (if parentTableName is given and string key doesn't contain whitespace) or <name>[<key>] notation (for other keys in existing tables).
    ---Only string keys without whitespace support <key>- and <table>.<key>-notation. All other keys require a parentTableName.
    ---@param parentTableName string | '""' empty string suppresses <table>-affix.
    ---@param key any
    ---@param object any only call-be-ref types allowed
    ---@param parentTableDepth? integer
    local function addNameToCache(parentTableName, key, object, parentTableDepth)
        parentTableDepth = parentTableDepth or -1
        --Don't overwrite existing names for the same object, don't add names for primitive types.
        if nameCache[object] or skipType[type(object)] then
            return
        end
        local name
        --apply dot-syntax for string keys without whitespace
        if type(key) == 'string' and not string.find(key, "\x25s") then
            if parentTableName == "" then
                name = key
                nameDepths[object] = 0
            else
                name =  parentTableName .. "." .. key
                nameDepths[object] = parentTableDepth + 1
            end
        --apply bracket-syntax for all other keys. This requires a parentTableName.
        elseif parentTableName ~= "" then
            name = type(key) == 'string' and ('"' .. key .. '"') or key
            name = parentTableName .. "[" .. tostring(name) .. "]"
            nameDepths[object] = parentTableDepth + 1
        end
        --Stop in cases without valid name (like parentTableName = "" and key = [1])
        if name then
            removeNameIfNecessary(name)
            nameCache[object] = name
            nameCacheMirror[name] = object
        end
    end

    ---Registers all call-by-reference objects in the given parentTable to the nameCache.
    ---Automatically filters out primitive objects and already registed Objects.
    ---@param parentTable table
    ---@param parentTableName? string
    local function registerAllObjectsInTable(parentTable, parentTableName)
        parentTableName = parentTableName or nameCache[parentTable] or ""
        --Register all call-by-ref-objects in parentTable
        for key, object in pairs(parentTable) do
            addNameToCache(parentTableName, key, object, nameDepths[parentTable])
        end
    end

    ---Adds names for all values of the specified parentTable to the name cache. Names will be "<parentTableName>.<key>" or "<parentTableName>[<key>]", depending on the key type.
    ---
    ---Example: Given a table T = {f = function() end, [1] = {}}, tostring(T.f) and tostring(T[1]) will output "function: T.f" and "table: T[1]" respectively after running Debug.registerNamesFrom(T).
    ---The name of T itself must either be specified as an input parameter OR have previously been registered. It can also be suppressed by inputting the empty string (so objects will just display by their own names).
    ---The names of objects in global scope are automatically registered during loading screen.
    ---@param parentTable table base table of which all entries shall be registered (in the Form parentTableName.objectName).
    ---@param parentTableName? string|'""' Nil: takes <parentTableName> as previously registered. Empty String: Skips <parentTableName> completely. String <s>: Objects will show up as "<s>.<objectName>".
    ---@param depth? integer objects within sub-tables up to the specified depth will also be added. Default: 1 (only elements of whichTable). Must be >= 1.
    ---@overload fun(parentTable:table, depth:integer)
    function Debug.registerNamesFrom(parentTable, parentTableName, depth)
        --Support overloaded definition fun(parentTable:table, depth:integer)
        if type(parentTableName) == 'number' then
            depth = parentTableName
            parentTableName = nil
        end
        --Apply default values
        depth = depth or 1
        parentTableName = parentTableName or nameCache[parentTable] or ""
        --add name of T in case it hasn't already
        if not nameCache[parentTable] and parentTableName ~= "" then
            Debug.registerName(parentTable, parentTableName)
        end
        --Register all call-by-ref-objects in parentTable. To be preferred over simple recursive approach to ensure that top level names are preferred.
        registerAllObjectsInTable(parentTable, parentTableName)
        --if depth > 1 was specified, also register Names from subtables.
        if depth > 1 then
            for _, object in pairs(parentTable) do
                if type(object) == 'table' then
                    Debug.registerNamesFrom(object, nil, depth - 1)
                end
            end
        end
    end

    -------------------------------------------
    --| Name Caching (Loading Screen setup) |--
    -------------------------------------------

    ---Registers all existing object names from global scope and Lua incorporated libraries to be used by tostring() overwrite below.
    local function registerNamesFromGlobalScope()
        --Add all names from global scope to the name cache.
        Debug.registerNamesFrom(_G, "")
        --Add all names of Warcraft-enabled Lua libraries as well:
        --Could instead add a depth to the function call above, but we want to ensure that these libraries are added even if the user has chosen depth 0.
        for _, lib in ipairs({coroutine, math, os, string, table, utf8, Debug}) do
            Debug.registerNamesFrom(lib)
        end
        --Add further names that are not accessible from global scope:
        --Player(i)
        for i = 0, GetBJMaxPlayerSlots() - 1 do
            Debug.registerName(Player(i), "Player(" .. i .. ")")
        end
    end

    --Set empty metatable to _G. __index is added when game starts (for "attempt to read undeclared global"-errors), __newindex is added right below (for building the name cache).
    setmetatable(_G, getmetatable(_G) or {}) --getmetatable(_G) should always return nil provided that DebugUtils is the topmost script file in the trigger editor, but we still include this for safety-

    -- Save old tostring into Debug Library before overwriting it.
    Debug.oldTostring = tostring

    if settings.USE_NAME_CACHE then
        local oldTostring = tostring
        tostring = function(obj) --new tostring(CreateUnit) prints "function: CreateUnit"
            --tostring of non-primitive object is NOT guaranteed to be like "<type>:<hex>", because it might have been changed by some __tostring-metamethod.
            if settings.USE_NAME_CACHE then --return names from name cache only if setting is enabled. This allows turning it off during runtime (via Ingame Console) to revert to old tostring.
                return nameCache[obj] and ((oldTostring(obj):match("^.-: ") or (oldTostring(obj) .. ": ")) .. nameCache[obj]) or oldTostring(obj)
            end
            return Debug.oldTostring(obj)
        end
        --Add names to Debug.data.objectNames within Lua root. Called below the other Debug-stuff to get the overwritten versions instead of the original ones.
        registerNamesFromGlobalScope()

        --Prepare __newindex-metamethod to automatically add new names to the name cache
        if settings.AUTO_REGISTER_NEW_NAMES then
            local nameRegisterNewIndex
            ---__newindex to be used for _G (and subtables up to a certain depth) to automatically register new names to the nameCache.
            ---Tables in global scope will use their own name. Subtables of them will use <parentName>.<childName> syntax.
            ---Global names don't support container[key]-notation (because "_G[...]" is probably not desired), so we only register string type keys instead of using prettyTostring.
            ---@param t table
            ---@param k any
            ---@param v any
            ---@param skipRawset? boolean set this to true when combined with another __newindex. Suppresses rawset(t,k,v) (because the other __newindex is responsible for that).
            nameRegisterNewIndex = function(t,k,v, skipRawset)
                local parentDepth = nameDepths[t] or 0
                --Make sure the parent table has an existing name before using it as part of the child name
                if t == _G or nameCache[t] then
                    local existingName = nameCache[v]
                    if not existingName then
                        addNameToCache((t == _G and "") or nameCache[t], k, v, parentDepth)
                    end
                    --If v is a table and the parent table has a valid name, inherit __newindex to v's existing metatable (or create a new one), if that wasn't already done.
                    if type(v) == 'table' and nameDepths[v] < settings.NAME_CACHE_DEPTH then
                        if not existingName then
                            --If v didn't have a name before, also add names for elements contained in v by construction (like v = {x = function() end} ).
                            Debug.registerNamesFrom(v, settings.NAME_CACHE_DEPTH - nameDepths[v])
                        end
                        --Apply __newindex to new tables.
                        if not autoIndexedTables[v] then
                            autoIndexedTables[v] = true
                            local mt = getmetatable(v)
                            if not mt then
                                mt = {}
                                setmetatable(v, mt) --only use setmetatable when we are sure there wasn't any before to prevent issues with "__metatable"-metamethod.
                            end
                            ---@diagnostic disable-next-line: assign-type-mismatch
                            local existingNewIndex = mt.__newindex
                            local isTable_yn = (type(existingNewIndex) == 'table')
                            --If mt has an existing __newindex, add the name-register effect to it (effectively create a new __newindex using the old)
                            if existingNewIndex then
                                mt.__newindex = function(t,k,v)
                                    nameRegisterNewIndex(t,k,v, true) --setting t[k] = v might not be desired in case of existing newindex. Skip it and let existingNewIndex make the decision.
                                    if isTable_yn then
                                        existingNewIndex[k] = v
                                    else
                                        return existingNewIndex(t,k,v)
                                    end
                                end
                            else
                            --If mt doesn't have an existing __newindex, add one that adds the object to the name cache.
                                mt.__newindex = nameRegisterNewIndex
                            end
                        end
                    end
                end
                --Set t[k] = v.
                if not skipRawset then
                    rawset(t,k,v)
                end
            end

            --Apply metamethod to _G.
            local existingNewIndex = getmetatable(_G).__newindex --should always be nil provided that DebugUtils is the topmost script in your trigger editor. Still included for safety.
            local isTable_yn = (type(existingNewIndex) == 'table')
            if existingNewIndex then
                getmetatable(_G).__newindex = function(t,k,v)
                    nameRegisterNewIndex(t,k,v, true)
                    if isTable_yn then
                        existingNewIndex[k] = v
                    else
                        existingNewIndex(t,k,v)
                    end
                end
            else
                getmetatable(_G).__newindex = nameRegisterNewIndex
            end
        end
    end

    ------------------------------------------------------
    --| Native Overwrite for Automatic Error Handling  |--
    ------------------------------------------------------

    --A table to store the try-wrapper for each function. This avoids endless re-creation of wrapper functions within the hooks below.
    --Weak keys ensure that garbage collection continues as normal.
    local tryWrappers = setmetatable({}, {__mode = 'k'}) ---@type table<function,function>
    local try = Debug.try

    ---Takes a function and returns a wrapper executing the same function within Debug.try.
    ---Wrappers are permanently stored (until the original function is garbage collected) to ensure that they don't have to be created twice for the same function.
    ---@param func? function
    ---@return function
    local function getTryWrapper(func)
        if func then
            tryWrappers[func] = tryWrappers[func] or function(...) return try(func, ...) end
        end
        return tryWrappers[func] --returns nil for func = nil (important for TimerStart overwrite below)
    end

    --Overwrite TriggerAddAction, TimerStart, Condition, Filter and Enum natives to let them automatically apply Debug.try.
    --Also overwrites coroutine.create and coroutine.wrap to let stack traces point to the function executed within instead of the function creating the coroutine.
    if settings.USE_TRY_ON_TRIGGERADDACTION then
        local originalTriggerAddAction = TriggerAddAction
        TriggerAddAction = function(whichTrigger, actionFunc)
            return originalTriggerAddAction(whichTrigger, getTryWrapper(actionFunc))
        end
    end
    if settings.USE_TRY_ON_TIMERSTART then
        local originalTimerStart = TimerStart
        TimerStart = function(whichTimer, timeout, periodic, handlerFunc)
            originalTimerStart(whichTimer, timeout, periodic, getTryWrapper(handlerFunc))
        end
    end
    if settings.USE_TRY_ON_CONDITION then
        local originalCondition = Condition
        Condition = function(func)
            return originalCondition(getTryWrapper(func))
        end
        Filter = Condition
    end
    if settings.USE_TRY_ON_ENUMFUNCS then
        local originalForGroup = ForGroup
        ForGroup = function(whichGroup, callback)
            originalForGroup(whichGroup, getTryWrapper(callback))
        end
        local originalForForce = ForForce
        ForForce = function(whichForce, callback)
            originalForForce(whichForce, getTryWrapper(callback))
        end
        local originalEnumItemsInRect = EnumItemsInRect
        EnumItemsInRect = function(r, filter, actionfunc)
            originalEnumItemsInRect(r, filter, getTryWrapper(actionfunc))
        end
        local originalEnumDestructablesInRect = EnumDestructablesInRect
        EnumDestructablesInRect = function(r, filter, actionFunc)
            originalEnumDestructablesInRect(r, filter, getTryWrapper(actionFunc))
        end
    end
    if settings.USE_TRY_ON_COROUTINES then
        local originalCoroutineCreate = coroutine.create
        ---@diagnostic disable-next-line: duplicate-set-field
        coroutine.create = function(f)
            return originalCoroutineCreate(getTryWrapper(f))
        end
        local originalCoroutineWrap = coroutine.wrap
        ---@diagnostic disable-next-line: duplicate-set-field
        coroutine.wrap = function(f)
            return originalCoroutineWrap(getTryWrapper(f))
        end
    end

    ------------------------------------------
    --| Cache prints during Loading Screen |--
    ------------------------------------------

    -- Apply the duration as specified in the settings.
    if settings.PRINT_DURATION then
        local display, getLocalPlayer, dur = DisplayTimedTextToPlayer, GetLocalPlayer, settings.PRINT_DURATION
        print = function(...) ---@diagnostic disable-next-line: param-type-mismatch
            display(getLocalPlayer(), 0, 0, dur, concat(...))
        end
    end

    -- Delay loading screen prints to after game start.
    if settings.USE_PRINT_CACHE then
        local oldPrint = print
        --loading screen print will write the values into the printCache
        print = function(...)
            if bj_gameStarted then
                oldPrint(...)
            else --during loading screen only: concatenate input arguments 4-space-separated, implicitely apply tostring on each, cache to table
                ---@diagnostic disable-next-line
                printCache.n = printCache.n + 1
                printCache[printCache.n] = concat(...)
            end
        end
    end

    -------------------------
    --| Modify Game Start |--
    -------------------------

    local originalMarkGameStarted = MarkGameStarted
    --Hook certain actions into the start of the game.
    MarkGameStarted = function()
        originalMarkGameStarted()
        if settings.WARNING_FOR_UNDECLARED_GLOBALS then
            local existingIndex = getmetatable(_G).__index
            local isTable_yn = (type(existingIndex) == 'table')
            getmetatable(_G).__index = function(t, k) --we made sure that _G has a metatable further above.
                if string.sub(tostring(k),1,3) ~= 'bj_' then --prevents intentionally nilled bj-variables from triggering the check within Blizzard.j-functions, like bj_cineFadeFinishTimer.
                    print("Trying to read undeclared global at " .. getStackTrace(4,4) .. ": " .. tostring(k)
                        .. (settings.SHOW_TRACE_FOR_UNDECLARED_GLOBALS and "\nTraceback (most recent call first):\n" .. getStackTrace(4,200) or ""))
                end
                if existingIndex then
                    if isTable_yn then
                        return existingIndex[k]
                    end
                    return existingIndex(t,k)
                end
                return rawget(t,k)
            end
        end

        --Add names to Debug.data.objectNames again to ensure that overwritten natives also make it to the name cache.
        --Overwritten natives have a new value, but the old key, so __newindex didn't trigger. But we can be sure that objectNames[v] doesn't yet exist, so adding again is safe.
        if settings.USE_NAME_CACHE then
            for _,v in pairs(_G) do
                nameCache[v] = nil
            end
            registerNamesFromGlobalScope()
        end

        --Print messages that have been cached during loading screen.
        if settings.USE_PRINT_CACHE then
            --Note that we don't restore the old print. The overwritten variant only applies caching behaviour to loading screen prints anyway and "unhooking" always adds other risks.
            for _, str in ipairs(printCache) do
                print(str)
            end ---@diagnostic disable-next-line: cast-local-type
            XXX = printCache
            printCache = nil --frees reference for the garbage collector
        end

        --Create triggers listening to "-console" and "-exec" chat input.
        if settings.ALLOW_INGAME_CODE_EXECUTION and IngameConsole then
            IngameConsole.createTriggers()
        end
    end

    ---------------------
    --| Other Utility |--
    ---------------------

    do
        ---Returns the type of a warcraft object as string, e.g. "unit" upon inputting a unit.
        ---@param input any
        ---@return string
        function Debug.wc3Type(input)
            local typeString = type(input)
            if typeString == 'userdata' then
                typeString = tostring(input) --tostring returns the warcraft type plus a colon and some hashstuff.
                return typeString:sub(1, (typeString:find(":", nil, true) or 0) -1) --string.find returns nil, if the argument is not found, which would break string.sub. So we need to replace by 0.
            else
                return typeString
            end
        end
        Wc3Type = Debug.wc3Type --for backwards compatibility

        local conciseTostring, prettyTostring

        ---Translates a table into a comma-separated list of its (key,value)-pairs. Also translates subtables up to the specified depth.
        ---E.g. {"a", 5, {7}} will display as '{(1, "a"), (2, 5), (3, {(1, 7)})}'.
        ---@param object any
        ---@param depth? integer default: unlimited. Unlimited depth will throw a stack overflow error on self-referential tables.
        ---@return string
        conciseTostring = function (object, depth)
            depth = depth or -1
            if type(object) == 'string' then
                return '"' .. object .. '"'
            elseif depth ~= 0 and type(object) == 'table' then
                local elementArray = {}
                local keyAsString
                for k,v in pairs(object) do
                    keyAsString = type(k) == 'string' and ('"' .. tostring(k) .. '"') or tostring(k)
                    table.insert(elementArray, '(' .. keyAsString .. ', ' .. conciseTostring(v, depth -1) .. ')')
                end
                return '{' .. table.concat(elementArray, ', ') .. '}'
            end
            return tostring(object)
        end

        ---Creates a list of all (key,value)-pairs from the specified table. Also lists subtable entries up to the specified depth.
        ---Major differences to concise print are:
        --- * Format: Linebreak-formatted instead of one-liner, uses "[key] = value" instead of "(key,value)"
        --- * Will also unpack tables used as keys
        --- * Also includes the table's memory position as returned by tostring(table).
        --- * Tables referenced multiple times will only be unpacked upon first encounter and abbreviated on subsequent encounters
        --- * As a consequence, pretty version can be executed with unlimited depth on self-referential tables.
        ---@param object any
        ---@param depth? integer default: unlimited.
        ---@param constTable table
        ---@param indent string
        ---@return string
        prettyTostring = function(object, depth, constTable, indent)
            depth = depth or -1
            local objType = type(object)
            if objType == "string" then
                return '"'..object..'"' --wrap the string in quotes.
            elseif objType == 'table' and depth ~= 0 then
                if not constTable[object] then
                    constTable[object] = tostring(object):gsub(":","")
                    if next(object)==nil then
                        return constTable[object]..": {}"
                    else
                        local mappedKV = {}
                        for k,v in pairs(object) do
                            table.insert(mappedKV, '\n  ' .. indent ..'[' .. prettyTostring(k, depth - 1, constTable, indent .. "  ") .. '] = ' .. prettyTostring(v, depth - 1, constTable, indent .. "  "))
                        end
                        return constTable[object]..': {'.. table.concat(mappedKV, ',') .. '\n'..indent..'}'
                    end
                end
            end
            return constTable[object] or tostring(object)
        end

        ---Creates a list of all (key,value)-pairs from the specified table. Also lists subtable entries up to the specified depth.
        ---Supports concise style and pretty style.
        ---Concise will display {"a", 5, {7}} as '{(1, "a"), (2, 5), (3, {(1, 7)})}'.
        ---Pretty is linebreak-separated, so consider table size before converting. Pretty also abbreviates tables referenced multiple times.
        ---Can be called like table.tostring(T), table.tostring(T, depth), table.tostring(T, pretty_yn) or table.tostring(T, depth, pretty_yn).
        ---table.tostring is not multiplayer-synced.
        ---@param whichTable table
        ---@param depth? integer default: unlimited
        ---@param pretty_yn? boolean default: false (concise)
        ---@return string
        ---@overload fun(whichTable:table, pretty_yn?:boolean):string
        function table.tostring(whichTable, depth, pretty_yn)
            --reassign input params, if function was called as table.tostring(whichTable, pretty_yn)
            if type(depth) == 'boolean' then
                pretty_yn = depth
                depth = -1
            end
            return pretty_yn and prettyTostring(whichTable, depth, {}, "") or conciseTostring(whichTable, depth)
        end

        ---Prints a list of (key,value)-pairs contained in the specified table and its subtables up to the specified depth.
        ---Supports concise style and pretty style. Pretty is linebreak-separated, so consider table size before printing.
        ---Can be called like table.print(T), table.print(T, depth), table.print(T, pretty_yn) or table.print(T, depth, pretty_yn).
        ---@param whichTable table
        ---@param depth? integer default: unlimited
        ---@param pretty_yn? boolean default: false (concise)
        ---@overload fun(whichTable:table, pretty_yn?:boolean)
        function table.print(whichTable, depth, pretty_yn)
            print(table.tostring(whichTable, depth, pretty_yn))
        end
    end
end
Debug.endFile()

if Debug and Debug.beginFile then Debug.beginFile("IngameConsole") end
--[[

--------------------------
----| Ingame Console |----
--------------------------

/**********************************************
* Allows you to use the following ingame commands:
* "-exec <code>" to execute any code ingame.
* "-console" to start an ingame console interpreting any further chat input as code and showing both return values of function calls and error messages. Furthermore, the print function will print
*    directly to the console after it got started. You can still look up all print messages in the F12-log.
***********************
* -------------------
* |Using the console|
* -------------------
* Any (well, most) chat input by any player after starting the console is interpreted as code and directly executed. You can enter terms (like 4+5 or just any variable name), function calls (like print("bla"))
* and set-statements (like y = 5). If the code has any return values, all of them are printed to the console. Erroneous code will print an error message.
* Chat input starting with a hyphen is being ignored by the console, i.e. neither executed as code nor printed to the console. This allows you to still use other chat commands like "-exec" without prompting errors.
***********************
* ------------------
* |Multiline-Inputs|
* ------------------
* You can prevent a chat input from being immediately executed by preceeding it with the '>' character. All lines entered this way are halted, until any line not starting with '>' is being entered.
* The first input without '>' will execute all halted lines (and itself) in one chunk.
* Example of a chat input (the console will add an additional '>' to every line):
* >function a(x)
* >return x
* end
***********************
* Note that multiline inputs don't accept pure term evaluations, e.g. the following input is not supported and will prompt an error, while the same lines would have worked as two single-line inputs:
* >x = 5
* x
***********************
* -------------------
* |Reserved Keywords|
* -------------------
* The following keywords have a reserved functionality, i.e. are direct commands for the console and will not be interpreted as code:
* - 'help'          - will show a list of all reserved keywords along very short explanations.
* - 'exit'          - will shut down the console
* - 'share'         - will share the players console with every other player, allowing others to read and write into it. Will force-close other players consoles, if they have one active.
* - 'clear'         - will clear all text from the console, except the word 'clear'
* - 'lasttrace'     - will show the stack trace of the latest error that occured within IngameConsole
* - 'show'          - will show the console, after it was accidently hidden (you can accidently hide it by showing another multiboard, while the console functionality is still up and running).
* - 'printtochat'   - will let the print function return to normal behaviour (i.e. print to the chat instead of the console).
* - 'printtoconsole'- will let the print function print to the console (which is default behaviour).
* - 'autosize on'   - will enable automatic console resize depending on the longest string in the display. This is turned on by default.
* - 'autosize off'  - will disable automatic console resize and instead linebreak long strings into multiple lines.
* - 'textlang eng'  - lets the console use english Wc3 text language font size to compute linebreaks (look in your Blizzard launcher settings to find out)
* - 'textlang ger'  - lets the console use german Wc3 text language font size to compute linebreaks (look in your Blizzard launcher settings to find out)
***********************
* --------------
* |Paste Helper|
* --------------
* @Luashine has created a tool that simplifies pasting multiple lines of code from outside Wc3 into the IngameConsole.
* This is particularly useful, when you want to execute a large chunk of testcode containing several linebreaks.
* Goto: https://github.com/Luashine/wc3-debug-console-paste-helper#readme
*
*************************************************/
--]]

----------------
--| Settings |--
----------------

---@class IngameConsole
IngameConsole = {
    --Settings
    numRows = 20                        ---@type integer Number of Rows of the console (multiboard), excluding the title row. So putting 20 here will show 21 rows, first being the title row.
    ,   autosize = true                 ---@type boolean Defines, whether the width of the main Column automatically adjusts with the longest string in the display.
    ,   currentWidth = 0.5              ---@type number Current and starting Screen Share of the console main column.
    ,   mainColMinWidth = 0.3           ---@type number Minimum Screen share of the console main column.
    ,   mainColMaxWidth = 0.8           ---@type number Maximum Scren share of the console main column.
    ,   tsColumnWidth = 0.06            ---@type number Screen Share of the Timestamp Column
    ,   linebreakBuffer = 0.008         ---@type number Screen Share that is added to longest string in display to calculate the screen share for the console main column. Compensates for the small inaccuracy of the String Width function.
    ,   maxLinebreaks = 8               ---@type integer Defines the maximum amount of linebreaks, before the remaining output string will be cut and not further displayed.
    ,   printToConsole = true           ---@type boolean defines, if the print function should print to the console or to the chat
    ,   sharedConsole = false           ---@type boolean defines, if the console is displayed to each player at the same time (accepting all players input) or if all players much start their own console.
    ,   showTraceOnError = false        ---@type boolean defines, if the console shows a trace upon printing errors. Usually not too useful within console, because you have just initiated the erroneous call.
    ,   textLanguage = 'eng'            ---@type string text language of your Wc3 installation, which influences font size (look in the settings of your Blizzard launcher). Currently only supports 'eng' and 'ger'.
    ,   colors = {
        timestamp = "bbbbbb"            ---@type string Timestamp Color
        ,   singleLineInput = "ffffaa"  ---@type string Color to be applied to single line console inputs
        ,   multiLineInput = "ffcc55"   ---@type string Color to be applied to multi line console inputs
        ,   returnValue = "00ffff"      ---@type string Color applied to return values
        ,   error = "ff5555"            ---@type string Color to be applied to errors resulting of function calls
        ,   keywordInput = "ff00ff"     ---@type string Color to be applied to reserved keyword inputs (console reserved keywords)
        ,   info = "bbbbbb"             ---@type string Color to be applied to info messages from the console itself (for instance after creation or after printrestore)
    }
    --Privates
    ,   numCols = 2                     ---@type integer Number of Columns of the console (multiboard). Adjusting this requires further changes on code base.
    ,   player = nil                    ---@type player player for whom the console is being created
    ,   currentLine = 0                 ---@type integer Current Output Line of the console.
    ,   inputload = ''                  ---@type string Input Holder for multi-line-inputs
    ,   output = {}                     ---@type string[] Array of all output strings
    ,   outputTimestamps = {}           ---@type string[] Array of all output string timestamps
    ,   outputWidths = {}               ---@type number[] remembers all string widths to allow for multiboard resize
    ,   trigger = nil                   ---@type trigger trigger processing all inputs during console lifetime
    ,   multiboard = nil                ---@type multiboard
    ,   timer = nil                     ---@type timer gets started upon console creation to measure timestamps
    ,   errorHandler = nil              ---@type fun(errorMsg:string):string error handler to be used within xpcall. We create one per console to make it compatible with console-specific settings.
    ,   lastTrace = ''                  ---@type string trace of last error occured within console. To be printed via reserved keyword "lasttrace"
    --Statics
    ,   keywords = {}                   ---@type table<string,function> saves functions to be executed for all reserved keywords
    ,   playerConsoles = {}             ---@type table<player,IngameConsole> Consoles currently being active. up to one per player.
    ,   originalPrint = print           ---@type function original print function to restore, after the console gets closed.
}
IngameConsole.__index = IngameConsole
IngameConsole.__name = 'IngameConsole'

------------------------
--| Console Creation |--
------------------------

---Creates and opens up a new console.
---@param consolePlayer player player for whom the console is being created
---@return IngameConsole
function IngameConsole.create(consolePlayer)
    local new = {} ---@type IngameConsole
    setmetatable(new, IngameConsole)
    ---setup Object data
    new.player = consolePlayer
    new.output = {}
    new.outputTimestamps = {}
    new.outputWidths = {}
    --Timer
    new.timer = CreateTimer()
    TimerStart(new.timer, 3600., true, nil) --just to get TimeElapsed for printing Timestamps.
    --Trigger to be created after short delay, because otherwise it would fire on "-console" input immediately and lead to stack overflow.
    new:setupTrigger()
    --Multiboard
    new:setupMultiboard()
    --Create own error handler per console to be compatible with console-specific settings
    new:setupErrorHandler()
    --Share, if settings say so
    if IngameConsole.sharedConsole then
        new:makeShared() --we don't have to exit other players consoles, because we look for the setting directly in the class and there just logically can't be other active consoles.
    end
    --Welcome Message
    new:out('info', 0, false, "Console started. Any further chat input will be executed as code, except when beginning with \x22-\x22.")
    return new
end

---Creates the multiboard used for console display.
function IngameConsole:setupMultiboard()
    self.multiboard = CreateMultiboard()
    MultiboardSetRowCount(self.multiboard, self.numRows + 1) --title row adds 1
    MultiboardSetColumnCount(self.multiboard, self.numCols)
    MultiboardSetTitleText(self.multiboard, "Console")
    local mbitem
    for col = 1, self.numCols do
        for row = 1, self.numRows + 1 do --Title row adds 1
            mbitem = MultiboardGetItem(self.multiboard, row -1, col -1)
            MultiboardSetItemStyle(mbitem, true, false)
            MultiboardSetItemValueColor(mbitem, 255, 255, 255, 255)	-- Colors get applied via text color code
            MultiboardSetItemWidth(mbitem, (col == 1 and self.tsColumnWidth) or self.currentWidth )
            MultiboardReleaseItem(mbitem)
        end
    end
    mbitem = MultiboardGetItem(self.multiboard, 0, 0)
    MultiboardSetItemValue(mbitem, "|cffffcc00Timestamp|r")
    MultiboardReleaseItem(mbitem)
    mbitem = MultiboardGetItem(self.multiboard, 0, 1)
    MultiboardSetItemValue(mbitem, "|cffffcc00Line|r")
    MultiboardReleaseItem(mbitem)
    self:showToOwners()
end

---Creates the trigger that responds to chat events.
function IngameConsole:setupTrigger()
    self.trigger = CreateTrigger()
    TriggerRegisterPlayerChatEvent(self.trigger, self.player, "", false) --triggers on any input of self.player
    TriggerAddCondition(self.trigger, Condition(function() return string.sub(GetEventPlayerChatString(),1,1) ~= '-' end)) --console will not react to entered stuff starting with '-'. This still allows to use other chat orders like "-exec".
    TriggerAddAction(self.trigger, function() self:processInput(GetEventPlayerChatString()) end)
end

---Creates an Error Handler to be used by xpcall below.
---Adds stack trace plus formatting to the message.
function IngameConsole:setupErrorHandler()
    self.errorHandler = function(errorMsg)
        errorMsg = Debug.getLocalErrorMsg(errorMsg)
        local _, tracePiece, lastFile = nil, "", errorMsg:match("^.-:") or "<unknown>" -- errors on objects created within Ingame Console don't have a file and linenumber. Consider "x = {}; x[nil] = 5".
        local fullMsg = errorMsg .. "\nTraceback (most recent call first):\n" .. (errorMsg:match("^.-:\x25d+") or "<unknown>")
        --Get Stack Trace. Starting at depth 5 ensures that "error", "messageHandler", "xpcall" and the input error message are not included.
        for loopDepth = 5, 50 do --get trace on depth levels up to 50
            ---@diagnostic disable-next-line: cast-local-type, assign-type-mismatch
            _, tracePiece = pcall(error, "", loopDepth) ---@type boolean, string
            tracePiece = Debug.getLocalErrorMsg(tracePiece)
            if #tracePiece > 0 then --some trace pieces can be empty, but there can still be valid ones beyond that
                fullMsg = fullMsg .. " <- " .. ((tracePiece:match("^.-:") == lastFile) and tracePiece:match(":\x25d+"):sub(2,-1) or tracePiece:match("^.-:\x25d+"))
                lastFile = tracePiece:match("^.-:")
            end
        end
        self.lastTrace = fullMsg
        return "ERROR: " .. (self.showTraceOnError and fullMsg or errorMsg)
    end
end

---Shares this console with all players.
function IngameConsole:makeShared()
    local player
    for i = 0, GetBJMaxPlayers() -1 do
        player = Player(i)
        if (GetPlayerSlotState(player) == PLAYER_SLOT_STATE_PLAYING) and (IngameConsole.playerConsoles[player] ~= self) then --second condition ensures that the player chat event is not added twice for the same player.
            IngameConsole.playerConsoles[player] = self
            TriggerRegisterPlayerChatEvent(self.trigger, player, "", false) --triggers on any input
        end
    end
    self.sharedConsole = true
end

---------------------
--|      In       |--
---------------------

---Processes a chat string. Each input will be printed. Incomplete multiline-inputs will be halted until completion. Completed inputs will be converted to a function and executed. If they have an output, it will be printed.
---@param inputString string
function IngameConsole:processInput(inputString)
    --if the input is a reserved keyword, conduct respective actions and skip remaining actions.
    if IngameConsole.keywords[inputString] then --if the input string is a reserved keyword
        self:out('keywordInput', 1, false, inputString)
        IngameConsole.keywords[inputString](self) --then call the method with the same name. IngameConsole.keywords["exit"](self) is just self.keywords:exit().
        return
    end
    --if the input is a multi-line-input, queue it into the string buffer (inputLoad), but don't yet execute anything
    if string.sub(inputString, 1, 1) == '>' then --multiLineInput
        inputString = string.sub(inputString, 2, -1)
        self:out('multiLineInput',2, false, inputString)
        self.inputload = self.inputload .. inputString .. '\n'
    else --if the input is either singleLineInput OR the last line of multiLineInput, execute the whole thing.
        self:out(self.inputload == '' and 'singleLineInput' or 'multiLineInput', 1, false, inputString)
        self.inputload = self.inputload .. inputString
        local loadedFunc, errorMsg = load("return " .. self.inputload) --adds return statements, if possible (works for term statements)
        if loadedFunc == nil then
            loadedFunc, errorMsg = load(self.inputload)
        end
        self.inputload = '' --empty inputload before execution of pcall. pcall can break (rare case, can for example be provoked with metatable.__tostring = {}), which would corrupt future console inputs.
        --manually catch case, where the input did not define a proper Lua statement (i.e. loadfunc is nil)
        local results = loadedFunc and table.pack(xpcall(loadedFunc, self.errorHandler)) or {false, "Input is not a valid Lua-statement: " .. errorMsg}
        --output error message (unsuccessful case) or return values (successful case)
        if not results[1] then --results[1] is the error status that pcall always returns. False stands for: error occured.
            self:out('error', 0, true, results[2]) -- second result of pcall is the error message in case an error occured
        elseif results.n > 1 then --Check, if there was at least one valid output argument. We check results.n instead of results[2], because we also get nil as a proper return value this way.
            self:out('returnValue', 0, true, table.unpack(results, 2, results.n))
        end
    end
end

----------------------
--|      Out       |--
----------------------

-- split color codes, split linebreaks, print lines separately, print load-errors, update string width, update text, error handling with stack trace.

---Duplicates Color coding around linebreaks to make each line printable separately.
---Operates incorrectly on lookalike color codes invalidated by preceeding escaped vertical bar (like "||cffffcc00bla|r").
---Also operates incorrectly on multiple color codes, where the first is missing the end sequence (like "|cffffcc00Hello |cff0000ffWorld|r")
---@param inputString string
---@return string, integer
function IngameConsole.spreadColorCodes(inputString)
    local replacementTable = {} --remembers all substrings to be replaced and their replacements.
    for foundInstance, color in inputString:gmatch("((|c\x25x\x25x\x25x\x25x\x25x\x25x\x25x\x25x).-|r)") do
        replacementTable[foundInstance] = foundInstance:gsub("(\r?\n)", "|r\x251" .. color)
    end
    return inputString:gsub("((|c\x25x\x25x\x25x\x25x\x25x\x25x\x25x\x25x).-|r)", replacementTable)
end

---Concatenates all inputs to one string, spreads color codes around line breaks and prints each line to the console separately.
---@param colorTheme? '"timestamp"'| '"singleLineInput"' | '"multiLineInput"' | '"result"' | '"keywordInput"' | '"info"' | '"error"' | '"returnValue"' Decides about the color to be applied. Currently accepted: 'timestamp', 'singleLineInput', 'multiLineInput', 'result', nil. (nil equals no colorTheme, i.e. white color)
---@param numIndentations integer Number of '>' chars that shall preceed the output
---@param hideTimestamp boolean Set to false to hide the timestamp column and instead show a "->" symbol.
---@param ... any the things to be printed in the console.
function IngameConsole:out(colorTheme, numIndentations, hideTimestamp, ...)
    local inputs = table.pack(...)
    for i = 1, inputs.n do
        inputs[i] = tostring(inputs[i]) --apply tostring on every input param in preparation for table.concat
    end
    --Concatenate all inputs (4-space-separated)
    local printOutput = table.concat(inputs, '    ', 1, inputs.n)
    printOutput = printOutput:find("(\r?\n)") and IngameConsole.spreadColorCodes(printOutput) or printOutput
    local substrStart, substrEnd = 1, 1
    local numLinebreaks, completePrint = 0, true
    repeat
        substrEnd = (printOutput:find("(\r?\n)", substrStart) or 0) - 1
        numLinebreaks, completePrint = self:lineOut(colorTheme, numIndentations, hideTimestamp, numLinebreaks, printOutput:sub(substrStart, substrEnd))
        hideTimestamp = true
        substrStart = substrEnd + 2
    until substrEnd == -1 or numLinebreaks > self.maxLinebreaks
    if substrEnd ~= -1 or not completePrint then
        self:lineOut('info', 0, false, 0, "Previous value not entirely printed after exceeding maximum number of linebreaks. Consider adjusting 'IngameConsole.maxLinebreaks'.")
    end
    self:updateMultiboard()
end

---Prints the given string to the console with the specified colorTheme and the specified number of indentations.
---Only supports one-liners (no \n) due to how multiboards work. Will add linebreaks though, if the one-liner doesn't fit into the given multiboard space.
---@param colorTheme? '"timestamp"'| '"singleLineInput"' | '"multiLineInput"' | '"result"' | '"keywordInput"' | '"info"' | '"error"' | '"returnValue"' Decides about the color to be applied. Currently accepted: 'timestamp', 'singleLineInput', 'multiLineInput', 'result', nil. (nil equals no colorTheme, i.e. white color)
---@param numIndentations integer Number of greater '>' chars that shall preceed the output
---@param hideTimestamp boolean Set to false to hide the timestamp column and instead show a "->" symbol.
---@param numLinebreaks integer
---@param printOutput string the line to be printed in the console.
---@return integer numLinebreaks, boolean hasPrintedEverything returns true, if everything could be printed. Returns false otherwise (can happen for very long strings).
function IngameConsole:lineOut(colorTheme, numIndentations, hideTimestamp, numLinebreaks, printOutput)
    --add preceeding greater chars
    printOutput = ('>'):rep(numIndentations) .. printOutput
    --Print a space instead of the empty string. This allows the console to identify, if the string has already been fully printed (see while-loop below).
    if printOutput == '' then
        printOutput = ' '
    end
    --Compute Linebreaks.
    local linebreakWidth = ((self.autosize and self.mainColMaxWidth) or self.currentWidth )
    local partialOutput = nil
    local maxPrintableCharPosition
    local printWidth
    while string.len(printOutput) > 0  and numLinebreaks <= self.maxLinebreaks do --break, if the input string has reached length 0 OR when the maximum number of linebreaks would be surpassed.
        --compute max printable substring (in one multiboard line)
        maxPrintableCharPosition, printWidth = IngameConsole.getLinebreakData(printOutput, linebreakWidth - self.linebreakBuffer, self.textLanguage)
        --adds timestamp to the first line of any output
        if numLinebreaks == 0 then
            partialOutput = printOutput:sub(1, numIndentations) .. ((IngameConsole.colors[colorTheme] and "|cff" .. IngameConsole.colors[colorTheme] .. printOutput:sub(numIndentations + 1, maxPrintableCharPosition) .. "|r") or printOutput:sub(numIndentations + 1, maxPrintableCharPosition)) --Colorize the output string, if a color theme was specified. IngameConsole.colors[colorTheme] can be nil.
            table.insert(self.outputTimestamps, "|cff" .. IngameConsole.colors['timestamp'] .. ((hideTimestamp and '            ->') or IngameConsole.formatTimerElapsed(TimerGetElapsed(self.timer))) .. "|r")
        else
            partialOutput = (IngameConsole.colors[colorTheme] and "|cff" .. IngameConsole.colors[colorTheme] .. printOutput:sub(1, maxPrintableCharPosition) .. "|r") or printOutput:sub(1, maxPrintableCharPosition) --Colorize the output string, if a color theme was specified. IngameConsole.colors[colorTheme] can be nil.
            table.insert(self.outputTimestamps, '            ..') --need a dummy entry in the timestamp list to make it line-progress with the normal output.
        end
        numLinebreaks = numLinebreaks + 1
        --writes output string and width to the console tables.
        table.insert(self.output, partialOutput)
        table.insert(self.outputWidths, printWidth + self.linebreakBuffer) --remember the Width of this printed string to adjust the multiboard size in case. 0.5 percent is added to avoid the case, where the multiboard width is too small by a tiny bit, thus not showing some string without spaces.
        --compute remaining string to print
        printOutput = string.sub(printOutput, maxPrintableCharPosition + 1, -1) --remaining string until the end. Returns empty string, if there is nothing left
    end
    self.currentLine = #self.output
    return numLinebreaks, string.len(printOutput) == 0 --printOutput is the empty string, if and only if everything has been printed
end

---Lets the multiboard show the recently printed lines.
function IngameConsole:updateMultiboard()
    local startIndex = math.max(self.currentLine - self.numRows, 0) --to be added to loop counter to get to the index of output table to print
    local outputIndex = 0
    local maxWidth = 0.
    local mbitem
    for i = 1, self.numRows do --doesn't include title row (index 0)
        outputIndex = i + startIndex
        mbitem = MultiboardGetItem(self.multiboard, i, 0)
        MultiboardSetItemValue(mbitem, self.outputTimestamps[outputIndex] or '')
        MultiboardReleaseItem(mbitem)
        mbitem = MultiboardGetItem(self.multiboard, i, 1)
        MultiboardSetItemValue(mbitem, self.output[outputIndex] or '')
        MultiboardReleaseItem(mbitem)
        maxWidth = math.max(maxWidth, self.outputWidths[outputIndex] or 0.) --looping through non-defined widths, so need to coalesce with 0
    end
    --Adjust Multiboard Width, if necessary.
    maxWidth = math.min(math.max(maxWidth, self.mainColMinWidth), self.mainColMaxWidth)
    if self.autosize and self.currentWidth ~= maxWidth then
        self.currentWidth = maxWidth
        for i = 1, self.numRows +1 do
            mbitem = MultiboardGetItem(self.multiboard, i-1, 1)
            MultiboardSetItemWidth(mbitem, maxWidth)
            MultiboardReleaseItem(mbitem)
        end
        self:showToOwners() --reshow multiboard to update item widths on the frontend
    end
end

---Shows the multiboard to all owners (one or all players)
function IngameConsole:showToOwners()
    if self.sharedConsole or GetLocalPlayer() == self.player then
        MultiboardDisplay(self.multiboard, true)
        MultiboardMinimize(self.multiboard, false)
    end
end

---Formats the elapsed time as "mm: ss. hh" (h being a hundreds of a sec)
function IngameConsole.formatTimerElapsed(elapsedInSeconds)
    return string.format("\x2502d: \x2502.f. \x2502.f", elapsedInSeconds // 60, math.fmod(elapsedInSeconds, 60.) // 1, math.fmod(elapsedInSeconds, 1) * 100)
end

---Computes the max printable substring for a given string and a given linebreakWidth (regarding a single line of console).
---Returns both the substrings last char position and its total width in the multiboard.
---@param stringToPrint string the string supposed to be printed in the multiboard console.
---@param linebreakWidth number the maximum allowed width in one line of the console, before a string must linebreak
---@param textLanguage string 'ger' or 'eng'
---@return integer maxPrintableCharPosition, number printWidth
function IngameConsole.getLinebreakData(stringToPrint, linebreakWidth, textLanguage)
    local loopWidth = 0.
    local bytecodes = table.pack(string.byte(stringToPrint, 1, -1))
    for i = 1, bytecodes.n do
        loopWidth = loopWidth + string.charMultiboardWidth(bytecodes[i], textLanguage)
        if loopWidth > linebreakWidth then
            return i-1, loopWidth - string.charMultiboardWidth(bytecodes[i], textLanguage)
        end
    end
    return bytecodes.n, loopWidth
end

-------------------------
--| Reserved Keywords |--
-------------------------

---Exits the Console
---@param self IngameConsole
function IngameConsole.keywords.exit(self)
    DestroyMultiboard(self.multiboard)
    DestroyTrigger(self.trigger)
    DestroyTimer(self.timer)
    IngameConsole.playerConsoles[self.player] = nil
    if next(IngameConsole.playerConsoles) == nil then --set print function back to original, when no one has an active console left.
        print = IngameConsole.originalPrint
    end
end

---Lets the console print to chat
---@param self IngameConsole
function IngameConsole.keywords.printtochat(self)
    self.printToConsole = false
    self:out('info', 0, false, "The print function will print to the normal chat.")
end

---Lets the console print to itself (default)
---@param self IngameConsole
function IngameConsole.keywords.printtoconsole(self)
    self.printToConsole = true
    self:out('info', 0, false, "The print function will print to the console.")
end

---Shows the console in case it was hidden by another multiboard before
---@param self IngameConsole
function IngameConsole.keywords.show(self)
    self:showToOwners() --might be necessary to do, if another multiboard has shown up and thereby hidden the console.
    self:out('info', 0, false, "Console is showing.")
end

---Prints all available reserved keywords plus explanations.
---@param self IngameConsole
function IngameConsole.keywords.help(self)
    self:out('info', 0, false, "The Console currently reserves the following keywords:")
    self:out('info', 0, false, "'help' shows the text you are currently reading.")
    self:out('info', 0, false, "'exit' closes the console.")
    self:out('info', 0, false, "'lasttrace' shows the stack trace of the latest error that occured within IngameConsole.")
    self:out('info', 0, false, "'share' allows other players to read and write into your console, but also force-closes their own consoles.")
    self:out('info', 0, false, "'clear' clears all text from the console.")
    self:out('info', 0, false, "'show' shows the console. Sensible to use, when displaced by another multiboard.")
    self:out('info', 0, false, "'printtochat' lets Wc3 print text to normal chat again.")
    self:out('info', 0, false, "'printtoconsole' lets Wc3 print text to the console (default).")
    self:out('info', 0, false, "'autosize on' enables automatic console resize depending on the longest line in the display.")
    self:out('info', 0, false, "'autosize off' retains the current console size.")
    self:out('info', 0, false, "'textlang eng' will use english text installation font size to compute linebreaks (default).")
    self:out('info', 0, false, "'textlang ger' will use german text installation font size to compute linebreaks.")
    self:out('info', 0, false, "Preceeding a line with '>' prevents immediate execution, until a line not starting with '>' has been entered.")
end

---Clears the display of the console.
---@param self IngameConsole
function IngameConsole.keywords.clear(self)
    self.output = {}
    self.outputTimestamps = {}
    self.outputWidths = {}
    self.currentLine = 0
    self:out('keywordInput', 1, false, 'clear') --we print 'clear' again. The keyword was already printed by self:processInput, but cleared immediately after.
end

---Shares the console with other players in the same game.
---@param self IngameConsole
function IngameConsole.keywords.share(self)
    for _, console in pairs(IngameConsole.playerConsoles) do
        if console ~= self then
            IngameConsole.keywords['exit'](console) --share was triggered during console runtime, so there potentially are active consoles of others players that need to exit.
        end
    end
    self:makeShared()
    self:showToOwners() --showing it to the other players.
    self:out('info', 0,false, "The console of player " .. GetConvertedPlayerId(self.player) .. " is now shared with all players.")
end

---Enables auto-sizing of console (will grow and shrink together with text size)
---@param self IngameConsole
IngameConsole.keywords["autosize on"] = function(self)
    self.autosize = true
    self:out('info', 0,false, "The console will now change size depending on its content.")
end

---Disables auto-sizing of console
---@param self IngameConsole
IngameConsole.keywords["autosize off"] = function(self)
    self.autosize = false
    self:out('info', 0,false, "The console will retain the width that it currently has.")
end

---Lets linebreaks be computed by german font size
---@param self IngameConsole
IngameConsole.keywords["textlang ger"] = function(self)
    self.textLanguage = 'ger'
    self:out('info', 0,false, "Linebreaks will now compute with respect to german text installation font size.")
end

---Lets linebreaks be computed by english font size
---@param self IngameConsole
IngameConsole.keywords["textlang eng"] = function(self)
    self.textLanguage = 'eng'
    self:out('info', 0,false, "Linebreaks will now compute with respect to english text installation font size.")
end

---Prints the stack trace of the latest error that occured within IngameConsole.
---@param self IngameConsole
IngameConsole.keywords["lasttrace"] = function(self)
    self:out('error', 0,false, self.lastTrace)
end

--------------------
--| Main Trigger |--
--------------------

do
    --Actions to be executed upon typing -exec
    local function execCommand_Actions()
        local input = string.sub(GetEventPlayerChatString(),7,-1)
        print("Executing input: |cffffff44" .. input .. "|r")
        --try preceeding the input by a return statement (preparation for printing below)
        local loadedFunc, errorMsg = load("return ".. input)
        if not loadedFunc then --if that doesn't produce valid code, try without return statement
            loadedFunc, errorMsg = load(input)
        end
        --execute loaded function in case the string defined a valid function. Otherwise print error.
        if errorMsg then
            print("|cffff5555Invalid Lua-statement: " .. Debug.getLocalErrorMsg(errorMsg) .. "|r")
        else
            ---@diagnostic disable-next-line: param-type-mismatch
            local results = table.pack(Debug.try(loadedFunc))
            if results[1] ~= nil or results.n > 1 then
                for i = 1, results.n do
                    results[i] = tostring(results[i])
                end
                --concatenate all function return values to one colorized string
                print("|cff00ffff" .. table.concat(results, '    ', 1, results.n) .. "|r")
            end
        end
    end

    local function execCommand_Condition()
        return string.sub(GetEventPlayerChatString(), 1, 6) == "-exec "
    end

    local function startIngameConsole()
        --if the triggering player already has a console, show that console and stop executing further actions
        if IngameConsole.playerConsoles[GetTriggerPlayer()] then
            IngameConsole.playerConsoles[GetTriggerPlayer()]:showToOwners()
            return
        end
        --create Ingame Console object
        IngameConsole.playerConsoles[GetTriggerPlayer()] = IngameConsole.create(GetTriggerPlayer())
        --overwrite print function
        print = function(...)
            IngameConsole.originalPrint(...) --the new print function will also print "normally", but clear the text immediately after. This is to add the message to the F12-log.
            if IngameConsole.playerConsoles[GetLocalPlayer()] and IngameConsole.playerConsoles[GetLocalPlayer()].printToConsole then
                ClearTextMessages() --clear text messages for all players having an active console
            end
            for player, console in pairs(IngameConsole.playerConsoles) do
                if console.printToConsole and (player == console.player) then --player == console.player ensures that the console only prints once, even if the console was shared among all players
                    console:out(nil, 0, false, ...)
                end
            end
        end
    end

    ---Creates the triggers listening to "-console" and "-exec" chat input.
    ---Being executed within DebugUtils (MarkGameStart overwrite).
    function IngameConsole.createTriggers()
        --Exec
        local execTrigger = CreateTrigger()
        TriggerAddCondition(execTrigger, Condition(execCommand_Condition))
        TriggerAddAction(execTrigger, execCommand_Actions)
        --Real Console
        local consoleTrigger = CreateTrigger()
        TriggerAddAction(consoleTrigger, startIngameConsole)
        --Events
        for i = 0, GetBJMaxPlayers() -1 do
            TriggerRegisterPlayerChatEvent(execTrigger, Player(i), "-exec ", false)
            TriggerRegisterPlayerChatEvent(consoleTrigger, Player(i), "-console", true)
        end
    end
end

--[[
    used by Ingame Console to determine multiboard size
    every unknown char will be treated as having default width (see constants below)
--]]

do
    ----------------------------
    ----| String Width API |----
    ----------------------------

    local multiboardCharTable = {}                        ---@type table  -- saves the width in screen percent (on 1920 pixel width resolutions) that each char takes up, when displayed in a multiboard.
    local DEFAULT_MULTIBOARD_CHAR_WIDTH = 1. / 128.        ---@type number    -- used for unknown chars (where we didn't define a width in the char table)
    local MULTIBOARD_TO_PRINT_FACTOR = 1. / 36.            ---@type number    -- 36 is actually the lower border (longest width of a non-breaking string only consisting of the letter "i")

    ---Returns the width of a char in a multiboard, when inputting a char (string of length 1) and 0 otherwise.
    ---also returns 0 for non-recorded chars (like ` and ´ and ß and § and €)
    ---@param char string | integer integer bytecode representations of chars are also allowed, i.e. the results of string.byte().
    ---@param textlanguage? '"ger"'| '"eng"' (default: 'eng'), depending on the text language in the Warcraft 3 installation settings.
    ---@return number
    function string.charMultiboardWidth(char, textlanguage)
        return multiboardCharTable[textlanguage or 'eng'][char] or DEFAULT_MULTIBOARD_CHAR_WIDTH
    end

    ---returns the width of a string in a multiboard (i.e. output is in screen percent)
    ---unknown chars will be measured with default width (see constants above)
    ---@param multichar string
    ---@param textlanguage? '"ger"'| '"eng"' (default: 'eng'), depending on the text language in the Warcraft 3 installation settings.
    ---@return number
    function string.multiboardWidth(multichar, textlanguage)
        local chartable = table.pack(multichar:byte(1,-1)) --packs all bytecode char representations into a table
        local charWidth = 0.
        for i = 1, chartable.n do
            charWidth = charWidth + string.charMultiboardWidth(chartable[i], textlanguage)
        end
        return charWidth
    end

    ---The function should match the following criteria: If the value returned by this function is smaller than 1.0, than the string fits into a single line on screen.
    ---The opposite is not necessarily true (but should be true in the majority of cases): If the function returns bigger than 1.0, the string doesn't necessarily break.
    ---@param char string | integer integer bytecode representations of chars are also allowed, i.e. the results of string.byte().
    ---@param textlanguage? '"ger"'| '"eng"' (default: 'eng'), depending on the text language in the Warcraft 3 installation settings.
    ---@return number
    function string.charPrintWidth(char, textlanguage)
        return string.charMultiboardWidth(char, textlanguage) * MULTIBOARD_TO_PRINT_FACTOR
    end

    ---The function should match the following criteria: If the value returned by this function is smaller than 1.0, than the string fits into a single line on screen.
    ---The opposite is not necessarily true (but should be true in the majority of cases): If the function returns bigger than 1.0, the string doesn't necessarily break.
    ---@param multichar string
    ---@param textlanguage? '"ger"'| '"eng"' (default: 'eng'), depending on the text language in the Warcraft 3 installation settings.
    ---@return number
    function string.printWidth(multichar, textlanguage)
        return string.multiboardWidth(multichar, textlanguage) * MULTIBOARD_TO_PRINT_FACTOR
    end

    ----------------------------------
    ----| String Width Internals |----
    ----------------------------------

    ---@param charset '"ger"'| '"eng"' (default: 'eng'), depending on the text language in the Warcraft 3 installation settings.
    ---@param char string|integer either the char or its bytecode
    ---@param lengthInScreenWidth number
    local function setMultiboardCharWidth(charset, char, lengthInScreenWidth)
        multiboardCharTable[charset] = multiboardCharTable[charset] or {}
        multiboardCharTable[charset][char] = lengthInScreenWidth
    end

    ---numberPlacements says how often the char can be placed in a multiboard column, before reaching into the right bound.
    ---@param charset '"ger"'| '"eng"' (default: 'eng'), depending on the text language in the Warcraft 3 installation settings.
    ---@param char string|integer either the char or its bytecode
    ---@param numberPlacements integer
    local function setMultiboardCharWidthBase80(charset, char, numberPlacements)
        setMultiboardCharWidth(charset, char, 0.8 / numberPlacements) --1-based measure. 80./numberPlacements would result in Screen Percent.
        setMultiboardCharWidth(charset, char:byte(1,-1), 0.8 / numberPlacements)
    end

    -- Set Char Width for all printable ascii chars in screen width (1920 pixels). Measured on a 80percent screen width multiboard column by counting the number of chars that fit into it.
    -- Font size differs by text install language and patch (1.32- vs. 1.33+)
    if BlzGetUnitOrderCount then --identifies patch 1.33+
        --German font size for patch 1.33+
        setMultiboardCharWidthBase80('ger', "a", 144)
        setMultiboardCharWidthBase80('ger', "b", 131)
        setMultiboardCharWidthBase80('ger', "c", 144)
        setMultiboardCharWidthBase80('ger', "d", 120)
        setMultiboardCharWidthBase80('ger', "e", 131)
        setMultiboardCharWidthBase80('ger', "f", 240)
        setMultiboardCharWidthBase80('ger', "g", 120)
        setMultiboardCharWidthBase80('ger', "h", 131)
        setMultiboardCharWidthBase80('ger', "i", 288)
        setMultiboardCharWidthBase80('ger', "j", 288)
        setMultiboardCharWidthBase80('ger', "k", 144)
        setMultiboardCharWidthBase80('ger', "l", 288)
        setMultiboardCharWidthBase80('ger', "m", 85)
        setMultiboardCharWidthBase80('ger', "n", 131)
        setMultiboardCharWidthBase80('ger', "o", 120)
        setMultiboardCharWidthBase80('ger', "p", 120)
        setMultiboardCharWidthBase80('ger', "q", 120)
        setMultiboardCharWidthBase80('ger', "r", 206)
        setMultiboardCharWidthBase80('ger', "s", 160)
        setMultiboardCharWidthBase80('ger', "t", 206)
        setMultiboardCharWidthBase80('ger', "u", 131)
        setMultiboardCharWidthBase80('ger', "v", 131)
        setMultiboardCharWidthBase80('ger', "w", 96)
        setMultiboardCharWidthBase80('ger', "x", 144)
        setMultiboardCharWidthBase80('ger', "y", 131)
        setMultiboardCharWidthBase80('ger', "z", 144)
        setMultiboardCharWidthBase80('ger', "A", 103)
        setMultiboardCharWidthBase80('ger', "B", 120)
        setMultiboardCharWidthBase80('ger', "C", 111)
        setMultiboardCharWidthBase80('ger', "D", 103)
        setMultiboardCharWidthBase80('ger', "E", 144)
        setMultiboardCharWidthBase80('ger', "F", 160)
        setMultiboardCharWidthBase80('ger', "G", 96)
        setMultiboardCharWidthBase80('ger', "H", 96)
        setMultiboardCharWidthBase80('ger', "I", 240)
        setMultiboardCharWidthBase80('ger', "J", 240)
        setMultiboardCharWidthBase80('ger', "K", 120)
        setMultiboardCharWidthBase80('ger', "L", 144)
        setMultiboardCharWidthBase80('ger', "M", 76)
        setMultiboardCharWidthBase80('ger', "N", 96)
        setMultiboardCharWidthBase80('ger', "O", 90)
        setMultiboardCharWidthBase80('ger', "P", 131)
        setMultiboardCharWidthBase80('ger', "Q", 90)
        setMultiboardCharWidthBase80('ger', "R", 120)
        setMultiboardCharWidthBase80('ger', "S", 131)
        setMultiboardCharWidthBase80('ger', "T", 144)
        setMultiboardCharWidthBase80('ger', "U", 103)
        setMultiboardCharWidthBase80('ger', "V", 120)
        setMultiboardCharWidthBase80('ger', "W", 76)
        setMultiboardCharWidthBase80('ger', "X", 111)
        setMultiboardCharWidthBase80('ger', "Y", 120)
        setMultiboardCharWidthBase80('ger', "Z", 120)
        setMultiboardCharWidthBase80('ger', "1", 144)
        setMultiboardCharWidthBase80('ger', "2", 120)
        setMultiboardCharWidthBase80('ger', "3", 120)
        setMultiboardCharWidthBase80('ger', "4", 120)
        setMultiboardCharWidthBase80('ger', "5", 120)
        setMultiboardCharWidthBase80('ger', "6", 120)
        setMultiboardCharWidthBase80('ger', "7", 131)
        setMultiboardCharWidthBase80('ger', "8", 120)
        setMultiboardCharWidthBase80('ger', "9", 120)
        setMultiboardCharWidthBase80('ger', "0", 120)
        setMultiboardCharWidthBase80('ger', ":", 288)
        setMultiboardCharWidthBase80('ger', ";", 288)
        setMultiboardCharWidthBase80('ger', ".", 288)
        setMultiboardCharWidthBase80('ger', "#", 120)
        setMultiboardCharWidthBase80('ger', ",", 288)
        setMultiboardCharWidthBase80('ger', " ", 286) --space
        setMultiboardCharWidthBase80('ger', "'", 180)
        setMultiboardCharWidthBase80('ger', "!", 180)
        setMultiboardCharWidthBase80('ger', "$", 131)
        setMultiboardCharWidthBase80('ger', "&", 90)
        setMultiboardCharWidthBase80('ger', "/", 180)
        setMultiboardCharWidthBase80('ger', "(", 240)
        setMultiboardCharWidthBase80('ger', ")", 240)
        setMultiboardCharWidthBase80('ger', "=", 120)
        setMultiboardCharWidthBase80('ger', "?", 144)
        setMultiboardCharWidthBase80('ger', "^", 144)
        setMultiboardCharWidthBase80('ger', "<", 144)
        setMultiboardCharWidthBase80('ger', ">", 144)
        setMultiboardCharWidthBase80('ger', "-", 180)
        setMultiboardCharWidthBase80('ger', "+", 120)
        setMultiboardCharWidthBase80('ger', "*", 180)
        setMultiboardCharWidthBase80('ger', "|", 287) --2 vertical bars in a row escape to one. So you could print 960 ones in a line, 480 would display. Maybe need to adapt to this before calculating string width.
        setMultiboardCharWidthBase80('ger', "~", 111)
        setMultiboardCharWidthBase80('ger', "{", 240)
        setMultiboardCharWidthBase80('ger', "}", 240)
        setMultiboardCharWidthBase80('ger', "[", 240)
        setMultiboardCharWidthBase80('ger', "]", 240)
        setMultiboardCharWidthBase80('ger', "_", 144)
        setMultiboardCharWidthBase80('ger', "\x25", 103) --percent
        setMultiboardCharWidthBase80('ger', "\x5C", 205) --backslash
        setMultiboardCharWidthBase80('ger', "\x22", 120) --double quotation mark
        setMultiboardCharWidthBase80('ger', "\x40", 90) --at sign
        setMultiboardCharWidthBase80('ger', "\x60", 144) --Gravis (Accent)

        --English font size for patch 1.33+
        setMultiboardCharWidthBase80('eng', "a", 144)
        setMultiboardCharWidthBase80('eng', "b", 120)
        setMultiboardCharWidthBase80('eng', "c", 131)
        setMultiboardCharWidthBase80('eng', "d", 120)
        setMultiboardCharWidthBase80('eng', "e", 120)
        setMultiboardCharWidthBase80('eng', "f", 240)
        setMultiboardCharWidthBase80('eng', "g", 120)
        setMultiboardCharWidthBase80('eng', "h", 120)
        setMultiboardCharWidthBase80('eng', "i", 288)
        setMultiboardCharWidthBase80('eng', "j", 288)
        setMultiboardCharWidthBase80('eng', "k", 144)
        setMultiboardCharWidthBase80('eng', "l", 288)
        setMultiboardCharWidthBase80('eng', "m", 80)
        setMultiboardCharWidthBase80('eng', "n", 120)
        setMultiboardCharWidthBase80('eng', "o", 111)
        setMultiboardCharWidthBase80('eng', "p", 111)
        setMultiboardCharWidthBase80('eng', "q", 111)
        setMultiboardCharWidthBase80('eng', "r", 206)
        setMultiboardCharWidthBase80('eng', "s", 160)
        setMultiboardCharWidthBase80('eng', "t", 206)
        setMultiboardCharWidthBase80('eng', "u", 120)
        setMultiboardCharWidthBase80('eng', "v", 144)
        setMultiboardCharWidthBase80('eng', "w", 90)
        setMultiboardCharWidthBase80('eng', "x", 131)
        setMultiboardCharWidthBase80('eng', "y", 144)
        setMultiboardCharWidthBase80('eng', "z", 144)
        setMultiboardCharWidthBase80('eng', "A", 103)
        setMultiboardCharWidthBase80('eng', "B", 120)
        setMultiboardCharWidthBase80('eng', "C", 103)
        setMultiboardCharWidthBase80('eng', "D", 96)
        setMultiboardCharWidthBase80('eng', "E", 131)
        setMultiboardCharWidthBase80('eng', "F", 160)
        setMultiboardCharWidthBase80('eng', "G", 96)
        setMultiboardCharWidthBase80('eng', "H", 90)
        setMultiboardCharWidthBase80('eng', "I", 240)
        setMultiboardCharWidthBase80('eng', "J", 240)
        setMultiboardCharWidthBase80('eng', "K", 120)
        setMultiboardCharWidthBase80('eng', "L", 131)
        setMultiboardCharWidthBase80('eng', "M", 76)
        setMultiboardCharWidthBase80('eng', "N", 90)
        setMultiboardCharWidthBase80('eng', "O", 85)
        setMultiboardCharWidthBase80('eng', "P", 120)
        setMultiboardCharWidthBase80('eng', "Q", 85)
        setMultiboardCharWidthBase80('eng', "R", 120)
        setMultiboardCharWidthBase80('eng', "S", 131)
        setMultiboardCharWidthBase80('eng', "T", 144)
        setMultiboardCharWidthBase80('eng', "U", 96)
        setMultiboardCharWidthBase80('eng', "V", 120)
        setMultiboardCharWidthBase80('eng', "W", 76)
        setMultiboardCharWidthBase80('eng', "X", 111)
        setMultiboardCharWidthBase80('eng', "Y", 120)
        setMultiboardCharWidthBase80('eng', "Z", 111)
        setMultiboardCharWidthBase80('eng', "1", 103)
        setMultiboardCharWidthBase80('eng', "2", 111)
        setMultiboardCharWidthBase80('eng', "3", 111)
        setMultiboardCharWidthBase80('eng', "4", 111)
        setMultiboardCharWidthBase80('eng', "5", 111)
        setMultiboardCharWidthBase80('eng', "6", 111)
        setMultiboardCharWidthBase80('eng', "7", 111)
        setMultiboardCharWidthBase80('eng', "8", 111)
        setMultiboardCharWidthBase80('eng', "9", 111)
        setMultiboardCharWidthBase80('eng', "0", 111)
        setMultiboardCharWidthBase80('eng', ":", 288)
        setMultiboardCharWidthBase80('eng', ";", 288)
        setMultiboardCharWidthBase80('eng', ".", 288)
        setMultiboardCharWidthBase80('eng', "#", 103)
        setMultiboardCharWidthBase80('eng', ",", 288)
        setMultiboardCharWidthBase80('eng', " ", 286) --space
        setMultiboardCharWidthBase80('eng', "'", 360)
        setMultiboardCharWidthBase80('eng', "!", 288)
        setMultiboardCharWidthBase80('eng', "$", 131)
        setMultiboardCharWidthBase80('eng', "&", 120)
        setMultiboardCharWidthBase80('eng', "/", 180)
        setMultiboardCharWidthBase80('eng', "(", 206)
        setMultiboardCharWidthBase80('eng', ")", 206)
        setMultiboardCharWidthBase80('eng', "=", 111)
        setMultiboardCharWidthBase80('eng', "?", 180)
        setMultiboardCharWidthBase80('eng', "^", 144)
        setMultiboardCharWidthBase80('eng', "<", 111)
        setMultiboardCharWidthBase80('eng', ">", 111)
        setMultiboardCharWidthBase80('eng', "-", 160)
        setMultiboardCharWidthBase80('eng', "+", 111)
        setMultiboardCharWidthBase80('eng', "*", 144)
        setMultiboardCharWidthBase80('eng', "|", 479) --2 vertical bars in a row escape to one. So you could print 960 ones in a line, 480 would display. Maybe need to adapt to this before calculating string width.
        setMultiboardCharWidthBase80('eng', "~", 144)
        setMultiboardCharWidthBase80('eng', "{", 160)
        setMultiboardCharWidthBase80('eng', "}", 160)
        setMultiboardCharWidthBase80('eng', "[", 206)
        setMultiboardCharWidthBase80('eng', "]", 206)
        setMultiboardCharWidthBase80('eng', "_", 120)
        setMultiboardCharWidthBase80('eng', "\x25", 103) --percent
        setMultiboardCharWidthBase80('eng', "\x5C", 180) --backslash
        setMultiboardCharWidthBase80('eng', "\x22", 180) --double quotation mark
        setMultiboardCharWidthBase80('eng', "\x40", 85) --at sign
        setMultiboardCharWidthBase80('eng', "\x60", 206) --Gravis (Accent)
    else
        --German font size up to patch 1.32
        setMultiboardCharWidthBase80('ger', "a", 144)
        setMultiboardCharWidthBase80('ger', "b", 144)
        setMultiboardCharWidthBase80('ger', "c", 144)
        setMultiboardCharWidthBase80('ger', "d", 131)
        setMultiboardCharWidthBase80('ger', "e", 144)
        setMultiboardCharWidthBase80('ger', "f", 240)
        setMultiboardCharWidthBase80('ger', "g", 120)
        setMultiboardCharWidthBase80('ger', "h", 144)
        setMultiboardCharWidthBase80('ger', "i", 360)
        setMultiboardCharWidthBase80('ger', "j", 288)
        setMultiboardCharWidthBase80('ger', "k", 144)
        setMultiboardCharWidthBase80('ger', "l", 360)
        setMultiboardCharWidthBase80('ger', "m", 90)
        setMultiboardCharWidthBase80('ger', "n", 144)
        setMultiboardCharWidthBase80('ger', "o", 131)
        setMultiboardCharWidthBase80('ger', "p", 131)
        setMultiboardCharWidthBase80('ger', "q", 131)
        setMultiboardCharWidthBase80('ger', "r", 206)
        setMultiboardCharWidthBase80('ger', "s", 180)
        setMultiboardCharWidthBase80('ger', "t", 206)
        setMultiboardCharWidthBase80('ger', "u", 144)
        setMultiboardCharWidthBase80('ger', "v", 131)
        setMultiboardCharWidthBase80('ger', "w", 96)
        setMultiboardCharWidthBase80('ger', "x", 144)
        setMultiboardCharWidthBase80('ger', "y", 131)
        setMultiboardCharWidthBase80('ger', "z", 144)
        setMultiboardCharWidthBase80('ger', "A", 103)
        setMultiboardCharWidthBase80('ger', "B", 131)
        setMultiboardCharWidthBase80('ger', "C", 120)
        setMultiboardCharWidthBase80('ger', "D", 111)
        setMultiboardCharWidthBase80('ger', "E", 144)
        setMultiboardCharWidthBase80('ger', "F", 180)
        setMultiboardCharWidthBase80('ger', "G", 103)
        setMultiboardCharWidthBase80('ger', "H", 103)
        setMultiboardCharWidthBase80('ger', "I", 288)
        setMultiboardCharWidthBase80('ger', "J", 240)
        setMultiboardCharWidthBase80('ger', "K", 120)
        setMultiboardCharWidthBase80('ger', "L", 144)
        setMultiboardCharWidthBase80('ger', "M", 80)
        setMultiboardCharWidthBase80('ger', "N", 103)
        setMultiboardCharWidthBase80('ger', "O", 96)
        setMultiboardCharWidthBase80('ger', "P", 144)
        setMultiboardCharWidthBase80('ger', "Q", 90)
        setMultiboardCharWidthBase80('ger', "R", 120)
        setMultiboardCharWidthBase80('ger', "S", 144)
        setMultiboardCharWidthBase80('ger', "T", 144)
        setMultiboardCharWidthBase80('ger', "U", 111)
        setMultiboardCharWidthBase80('ger', "V", 120)
        setMultiboardCharWidthBase80('ger', "W", 76)
        setMultiboardCharWidthBase80('ger', "X", 111)
        setMultiboardCharWidthBase80('ger', "Y", 120)
        setMultiboardCharWidthBase80('ger', "Z", 120)
        setMultiboardCharWidthBase80('ger', "1", 288)
        setMultiboardCharWidthBase80('ger', "2", 131)
        setMultiboardCharWidthBase80('ger', "3", 144)
        setMultiboardCharWidthBase80('ger', "4", 120)
        setMultiboardCharWidthBase80('ger', "5", 144)
        setMultiboardCharWidthBase80('ger', "6", 131)
        setMultiboardCharWidthBase80('ger', "7", 144)
        setMultiboardCharWidthBase80('ger', "8", 131)
        setMultiboardCharWidthBase80('ger', "9", 131)
        setMultiboardCharWidthBase80('ger', "0", 131)
        setMultiboardCharWidthBase80('ger', ":", 480)
        setMultiboardCharWidthBase80('ger', ";", 360)
        setMultiboardCharWidthBase80('ger', ".", 480)
        setMultiboardCharWidthBase80('ger', "#", 120)
        setMultiboardCharWidthBase80('ger', ",", 360)
        setMultiboardCharWidthBase80('ger', " ", 288) --space
        setMultiboardCharWidthBase80('ger', "'", 480)
        setMultiboardCharWidthBase80('ger', "!", 360)
        setMultiboardCharWidthBase80('ger', "$", 160)
        setMultiboardCharWidthBase80('ger', "&", 96)
        setMultiboardCharWidthBase80('ger', "/", 180)
        setMultiboardCharWidthBase80('ger', "(", 288)
        setMultiboardCharWidthBase80('ger', ")", 288)
        setMultiboardCharWidthBase80('ger', "=", 160)
        setMultiboardCharWidthBase80('ger', "?", 180)
        setMultiboardCharWidthBase80('ger', "^", 144)
        setMultiboardCharWidthBase80('ger', "<", 160)
        setMultiboardCharWidthBase80('ger', ">", 160)
        setMultiboardCharWidthBase80('ger', "-", 144)
        setMultiboardCharWidthBase80('ger', "+", 160)
        setMultiboardCharWidthBase80('ger', "*", 206)
        setMultiboardCharWidthBase80('ger', "|", 480) --2 vertical bars in a row escape to one. So you could print 960 ones in a line, 480 would display. Maybe need to adapt to this before calculating string width.
        setMultiboardCharWidthBase80('ger', "~", 144)
        setMultiboardCharWidthBase80('ger', "{", 240)
        setMultiboardCharWidthBase80('ger', "}", 240)
        setMultiboardCharWidthBase80('ger', "[", 240)
        setMultiboardCharWidthBase80('ger', "]", 288)
        setMultiboardCharWidthBase80('ger', "_", 144)
        setMultiboardCharWidthBase80('ger', "\x25", 111) --percent
        setMultiboardCharWidthBase80('ger', "\x5C", 206) --backslash
        setMultiboardCharWidthBase80('ger', "\x22", 240) --double quotation mark
        setMultiboardCharWidthBase80('ger', "\x40", 103) --at sign
        setMultiboardCharWidthBase80('ger', "\x60", 240) --Gravis (Accent)

        --English Font size up to patch 1.32
        setMultiboardCharWidthBase80('eng', "a", 144)
        setMultiboardCharWidthBase80('eng', "b", 120)
        setMultiboardCharWidthBase80('eng', "c", 131)
        setMultiboardCharWidthBase80('eng', "d", 120)
        setMultiboardCharWidthBase80('eng', "e", 131)
        setMultiboardCharWidthBase80('eng', "f", 240)
        setMultiboardCharWidthBase80('eng', "g", 120)
        setMultiboardCharWidthBase80('eng', "h", 131)
        setMultiboardCharWidthBase80('eng', "i", 360)
        setMultiboardCharWidthBase80('eng', "j", 288)
        setMultiboardCharWidthBase80('eng', "k", 144)
        setMultiboardCharWidthBase80('eng', "l", 360)
        setMultiboardCharWidthBase80('eng', "m", 80)
        setMultiboardCharWidthBase80('eng', "n", 131)
        setMultiboardCharWidthBase80('eng', "o", 120)
        setMultiboardCharWidthBase80('eng', "p", 120)
        setMultiboardCharWidthBase80('eng', "q", 120)
        setMultiboardCharWidthBase80('eng', "r", 206)
        setMultiboardCharWidthBase80('eng', "s", 160)
        setMultiboardCharWidthBase80('eng', "t", 206)
        setMultiboardCharWidthBase80('eng', "u", 131)
        setMultiboardCharWidthBase80('eng', "v", 144)
        setMultiboardCharWidthBase80('eng', "w", 90)
        setMultiboardCharWidthBase80('eng', "x", 131)
        setMultiboardCharWidthBase80('eng', "y", 144)
        setMultiboardCharWidthBase80('eng', "z", 144)
        setMultiboardCharWidthBase80('eng', "A", 103)
        setMultiboardCharWidthBase80('eng', "B", 120)
        setMultiboardCharWidthBase80('eng', "C", 103)
        setMultiboardCharWidthBase80('eng', "D", 103)
        setMultiboardCharWidthBase80('eng', "E", 131)
        setMultiboardCharWidthBase80('eng', "F", 160)
        setMultiboardCharWidthBase80('eng', "G", 103)
        setMultiboardCharWidthBase80('eng', "H", 96)
        setMultiboardCharWidthBase80('eng', "I", 288)
        setMultiboardCharWidthBase80('eng', "J", 240)
        setMultiboardCharWidthBase80('eng', "K", 120)
        setMultiboardCharWidthBase80('eng', "L", 131)
        setMultiboardCharWidthBase80('eng', "M", 76)
        setMultiboardCharWidthBase80('eng', "N", 96)
        setMultiboardCharWidthBase80('eng', "O", 85)
        setMultiboardCharWidthBase80('eng', "P", 131)
        setMultiboardCharWidthBase80('eng', "Q", 85)
        setMultiboardCharWidthBase80('eng', "R", 120)
        setMultiboardCharWidthBase80('eng', "S", 131)
        setMultiboardCharWidthBase80('eng', "T", 144)
        setMultiboardCharWidthBase80('eng', "U", 103)
        setMultiboardCharWidthBase80('eng', "V", 120)
        setMultiboardCharWidthBase80('eng', "W", 76)
        setMultiboardCharWidthBase80('eng', "X", 111)
        setMultiboardCharWidthBase80('eng', "Y", 120)
        setMultiboardCharWidthBase80('eng', "Z", 111)
        setMultiboardCharWidthBase80('eng', "1", 206)
        setMultiboardCharWidthBase80('eng', "2", 131)
        setMultiboardCharWidthBase80('eng', "3", 131)
        setMultiboardCharWidthBase80('eng', "4", 111)
        setMultiboardCharWidthBase80('eng', "5", 131)
        setMultiboardCharWidthBase80('eng', "6", 120)
        setMultiboardCharWidthBase80('eng', "7", 131)
        setMultiboardCharWidthBase80('eng', "8", 111)
        setMultiboardCharWidthBase80('eng', "9", 120)
        setMultiboardCharWidthBase80('eng', "0", 111)
        setMultiboardCharWidthBase80('eng', ":", 360)
        setMultiboardCharWidthBase80('eng', ";", 360)
        setMultiboardCharWidthBase80('eng', ".", 360)
        setMultiboardCharWidthBase80('eng', "#", 103)
        setMultiboardCharWidthBase80('eng', ",", 360)
        setMultiboardCharWidthBase80('eng', " ", 288) --space
        setMultiboardCharWidthBase80('eng', "'", 480)
        setMultiboardCharWidthBase80('eng', "!", 360)
        setMultiboardCharWidthBase80('eng', "$", 131)
        setMultiboardCharWidthBase80('eng', "&", 120)
        setMultiboardCharWidthBase80('eng', "/", 180)
        setMultiboardCharWidthBase80('eng', "(", 240)
        setMultiboardCharWidthBase80('eng', ")", 240)
        setMultiboardCharWidthBase80('eng', "=", 111)
        setMultiboardCharWidthBase80('eng', "?", 180)
        setMultiboardCharWidthBase80('eng', "^", 144)
        setMultiboardCharWidthBase80('eng', "<", 131)
        setMultiboardCharWidthBase80('eng', ">", 131)
        setMultiboardCharWidthBase80('eng', "-", 180)
        setMultiboardCharWidthBase80('eng', "+", 111)
        setMultiboardCharWidthBase80('eng', "*", 180)
        setMultiboardCharWidthBase80('eng', "|", 480) --2 vertical bars in a row escape to one. So you could print 960 ones in a line, 480 would display. Maybe need to adapt to this before calculating string width.
        setMultiboardCharWidthBase80('eng', "~", 144)
        setMultiboardCharWidthBase80('eng', "{", 240)
        setMultiboardCharWidthBase80('eng', "}", 240)
        setMultiboardCharWidthBase80('eng', "[", 240)
        setMultiboardCharWidthBase80('eng', "]", 240)
        setMultiboardCharWidthBase80('eng', "_", 120)
        setMultiboardCharWidthBase80('eng', "\x25", 103) --percent
        setMultiboardCharWidthBase80('eng', "\x5C", 180) --backslash
        setMultiboardCharWidthBase80('eng', "\x22", 206) --double quotation mark
        setMultiboardCharWidthBase80('eng', "\x40", 96) --at sign
        setMultiboardCharWidthBase80('eng', "\x60", 206) --Gravis (Accent)
    end
end

if Debug and Debug.endFile then Debug.endFile() end

do
    local funcs = {}
    
    function onInit(code)
        if type(code) == "function" then
            table.insert(funcs, code)
        end
    end
    
    local old = InitBlizzard
    function InitBlizzard()
        old()
        
        for i = 1, #funcs do
            funcs[i]()
        end
        
        funcs = nil
    end
end

SimpleUtils = {}
SimpleUtils.debug = false
SimpleUtils.debugTime = false

function SimpleUtils.debugFunc(func, name)
    local name = name or ""
    local result
    local passed, data = pcall(function()
        result = func()
        return "func " .. name .. " passed"
    end)
    if not passed then
        print(name, passed, data)
    end
    passed = nil
    data = nil
    return result
end

function SimpleUtils.printTime(since, name)
    if SimpleUtils.debugTime then
        local call = SimpleUtils.timedCalls[name] or 0
        call = call + 1
        SimpleUtils.timedCalls[name] = call
        local duration = os.time() - since
        --if duration > 0 then
        print(name .. ": " .. tostring(call) .. ". call took " .. tostring(duration) .. "ms")
        --end
    end
end

function SimpleUtils.debugFuncTimed(func, name)
    local start = os.time()
    local name = name or ""
    local result
    local passed, data = pcall(function()
        result = func()
        SimpleUtils.printTime(start, name)
        return "func " .. name .. " passed"
    end)
    if not passed then
        print(name, passed, data)
    end
    passed = nil
    data = nil
    SimpleUtils.printTime(start, name)
    return result
end

function SimpleUtils.newClass(t, constructor)
    local t = t
    t.__index = t
    t.lookupt = {}
    t.new = function()
        local o = {}
        setmetatable(o, t)
        if not (constructor == nil) then
            constructor(o)
        end
        return o
    end
    t.destroy = function()
        t.lookupt[t] = nil
    end
    if SimpleUtils.debug then
        print("made new class for " .. tostring(t))
    end
end

function SimpleUtils.timed(dur, func)
    local tmr = CreateTimer()
    TimerStart(tmr, dur, false, function()
        func()
        SimpleUtils.releaseTimer(tmr)
    end)
    return tmr;
end

function SimpleUtils.timedSkippable(dur, func)
    SkippableTimers:start(dur, func)
end

function SimpleUtils.timedRepeat(dur, count, func)
    local tmr = CreateTimer()
    local t, c = count, 0
    if t == nil then
        TimerStart(tmr, dur, true, function()
            func(tmr)
        end)
    else
        TimerStart(tmr, dur, true, function()
            func(tmr)
            c = c + 1
            if c >= t then
                SimpleUtils.releaseTimer(tmr)
            end
        end)
    end
    return tmr;
end

-- :: clones a table and any child tables (setting metatables)
-- @t = table to copy
function SimpleUtils.deepCopy(t)
    local t2 = {}
    if getmetatable(t) then
        setmetatable(t2, getmetatable(t))
    end
    for k, v in pairs(t) do
        if type(v) == "table" then
            local newt = {}
            if getmetatable(v) then
                setmetatable(newt, getmetatable(v))
            end
            for k2, v2 in pairs(v) do
                newt[k2] = v2
            end
            t2[k] = newt
        else
            t2[k] = v
        end
    end
    return t2
end

function SimpleUtils.destroyTable(t)
    for i, v in pairs(t) do
        if type(v) == "table" then
            for i2, v2 in pairs(v) do
                v2 = nil
                i2 = nil
            end
        else
            v = nil
            i = nil
        end
    end
end

function SimpleUtils.playSound(snd)
    StopSound(snd, false, false)
    StartSound(snd)
end

function SimpleUtils.tableLength(t)
    if not t then
        return nil
    end
    local count = 0
    for _ in pairs(t) do
        count = count + 1
    end
    return count
end

function SimpleUtils.ifElse(condition, onTrue, onFalse)
    if condition == true then
        return onTrue
    else
        return onFalse
    end
end

function SimpleUtils.printDupa()
    print("dupa")
end

function SimpleUtils.fadeOut(duration)
    CinematicFadeBJ(bj_CINEFADETYPE_FADEOUT, duration, "ReplaceableTextures\\CameraMasks\\Black_mask.blp", 1, 1, 1, 0)
end

function SimpleUtils.fadeIn(duration)
    CinematicFadeBJ(bj_CINEFADETYPE_FADEIN, duration, "ReplaceableTextures\\CameraMasks\\Black_mask.blp", 1, 1, 1, 0)
end

function SimpleUtils.valueToString(v, prefix)
    if type(v) == "table" then
        return SimpleUtils.toString(v, prefix .. " ")
    else
        return tostring(v)
    end
end

function SimpleUtils.toString(o, prefix)
    local s = "{\n"
    for key, value in pairs(o) do
        local valueString = SimpleUtils.valueToString(value, prefix)
        s = s .. prefix .. "\"" .. key .. "\": \"" .. valueString .. "\",\n"
    end
    s = s .. "\n}\n"
    return s
end

function SimpleUtils.printToString(label, o)
    print(label .. ": " .. SimpleUtils.toString(o, " "))
end

function SimpleUtils.getRandomNumbers(min, max, count)
    local rangeLength = max - min + 1
    --print("rangeLength: " .. rangeLength)
    if rangeLength < count then
        print("Invalid args for SimpleUtils.getRandomNumbers: " .. tostring(min) .. " > " .. tostring(max))
        return {}
    end
    local range = {}
    for i = min, max do
        table.insert(range, i)
        --print("range insert " .. tostring(i))
    end

    local output = {}
    for _ = 0, count - 1 do
        local nextNumberIndex = math.random(1, rangeLength)
        --print("nextNumberIndex " .. tostring(nextNumberIndex))
        local nextNumber = table.remove(range, nextNumberIndex)
        --print("removed nextNumber " .. tostring(nextNumber))
        table.insert(output, nextNumber)
        rangeLength = rangeLength - 1
    end
    return output
end

function SimpleUtils.releaseTimer(whichTimer)
    PauseTimer(whichTimer)
    DestroyTimer(whichTimer)
end

function SimpleUtils.printWarn(msg)
    print("[WARN] " .. msg)
end

FrameUtils = {
    FRAME_POINTS = { -- shorthand 'FRAMEPOINT' for terser code.
        tl = FRAMEPOINT_TOPLEFT,
        t = FRAMEPOINT_TOP,
        tr = FRAMEPOINT_TOPRIGHT,
        r = FRAMEPOINT_RIGHT,
        br = FRAMEPOINT_BOTTOMRIGHT,
        b = FRAMEPOINT_BOTTOM,
        bl = FRAMEPOINT_BOTTOMLEFT,
        l = FRAMEPOINT_LEFT,
        c = FRAMEPOINT_CENTER,
    }
}

-- @bool = true to fade out (hide); false to fade in (show).
function FrameUtils.fadeFrame(fade, frame, duration)
    BlzFrameSetVisible(frame, true)
    local bool = fade
    local alpha = 255
    local int = math.floor(255 / math.floor(duration / 0.03))
    -- show:
    if bool then
        BlzFrameSetVisible(frame, true)
        BlzFrameSetAlpha(frame, 255)
        SimpleUtils.timedRepeat(0.03, nil, function(timer)
            if BlzFrameGetAlpha(frame) > 0 and BlzFrameGetAlpha(frame) > int then
                alpha = alpha - int
                BlzFrameSetAlpha(frame, alpha)
            else
                BlzFrameSetAlpha(frame, 0)
                BlzFrameSetVisible(frame, false)
                SimpleUtils.releaseTimer(timer)
            end
        end)
        -- hide:
    else
        BlzFrameSetVisible(frame, true)
        BlzFrameSetAlpha(frame, 0)
        SimpleUtils.timedRepeat(0.03, nil, function(timer)
            if BlzFrameGetAlpha(frame) ~= 255 and BlzFrameGetAlpha(frame) < 255 - int then
                alpha = alpha + int
                BlzFrameSetAlpha(frame, alpha)
            else
                BlzFrameSetAlpha(frame, 255)
                BlzFrameSetVisible(frame, true)
                SimpleUtils.releaseTimer(timer)
            end
        end)
    end
end


function FrameUtils.printFrameStructure(frame)
    print("STRUCTURE OF FRAME " .. BlzFrameGetName(frame) .. ": ")
    local childrenCount = BlzFrameGetChildrenCount(frame)
    print("  CHILDREN COUNT: " .. tostring(childrenCount))
    for i = 0, childrenCount do
        print("  CHILD " .. tostring(i) .. ": " .. BlzFrameGetName(BlzFrameGetChild(frame, i)))
    end
end

function FrameUtils.getChildByName(parent, expectedChildName)
    local childrenCount = BlzFrameGetChildrenCount(parent)
    for i = 0, childrenCount do
        local child = BlzFrameGetChild(parent, i)
        local childName = BlzFrameGetName(child)
        if childName == expectedChildName then
            return child
        end
    end
end


function FrameUtils.fixFocus(fh)
    BlzFrameSetEnable(fh, false)
    BlzFrameSetEnable(fh, true)
end

SkippableTimers = {
    skippableTimers = {}
}

function SkippableTimers:start(dur, func)
    local timer = SimpleUtils.timed(dur, func)
    table.insert(self.skippableTimers, timer)
    return timer
end

function SkippableTimers:skip()
    for index, timer in ipairs(self.skippableTimers) do
        SimpleUtils.releaseTimer(timer)
    end
    self.skippableTimers = {}
end

ScreenplayUtils = {} -- utility class with functions you can use in your screenplays
ScreenplayUtils.debug = false

function ScreenplayUtils.interpolateCameraFromCurrentTillEndOfCurrentItem(cameraTo)
    return ScreenplayUtils.interpolateCameraFromCurrent(cameraTo, ScreenplayUtils.getCurrentItemDuration())
end

function ScreenplayUtils.interpolateCameraFromCurrent(cameraTo, duration)
    return ScreenplayUtils.interpolateCamera(GetCurrentCameraSetup(), cameraTo, duration)
end

function ScreenplayUtils.interpolateCameraTillEndOfCurrentItem(cameraFrom, cameraTo)
    ScreenplayUtils.interpolateCamera(cameraFrom, cameraTo, ScreenplayUtils.getCurrentItemDuration())
end

function ScreenplayUtils.interpolateCamera(cameraFrom, cameraTo, duration)
    ScreenplayUtils.clearInterpolation()
    CameraSetupApply(cameraFrom, true)
    local cameraFromX = CameraSetupGetDestPositionX(cameraFrom)
    local cameraFromY = CameraSetupGetDestPositionY(cameraFrom)
    local cameraFromDistance = CameraSetupGetField(cameraFrom, CAMERA_FIELD_TARGET_DISTANCE)

    SetCameraPosition(cameraFromX, cameraFromY)
    SetCameraField(CAMERA_FIELD_TARGET_DISTANCE, cameraFromDistance, 0.0)

    CameraSetupApplyForceDuration(cameraTo, true, duration)
    local timer = CreateTimer()
    ScreenplaySystem.cameraInterpolationTimer = timer
    local durationInt = math.floor(duration)
    local durationLeft = durationInt
    TimerStart(timer, 1.0, true, function()
        --print("durationLeft: " .. tostring(durationLeft) .. " / " .. tostring(durationInt))
        durationLeft = durationLeft - 1
        if durationLeft <= 0 then
            CameraSetupApplyForceDuration(cameraTo, true, 9999)
            SimpleUtils.releaseTimer(timer)
        else
            local interpolatedX = ScreenplayUtils.interpolate(CameraSetupGetDestPositionX(cameraFrom), CameraSetupGetDestPositionX(cameraTo), (durationInt - durationLeft) / durationInt)
            local interpolatedY = ScreenplayUtils.interpolate(CameraSetupGetDestPositionY(cameraFrom), CameraSetupGetDestPositionY(cameraTo), (durationInt - durationLeft) / durationInt)
            local interpolatedDistance = ScreenplayUtils.interpolate(CameraSetupGetField(cameraFrom, CAMERA_FIELD_TARGET_DISTANCE), CameraSetupGetField(cameraTo, CAMERA_FIELD_TARGET_DISTANCE), (durationInt - durationLeft) / durationInt)
            local sceneCameraX = GetCameraTargetPositionX()
            local sceneCameraY = GetCameraTargetPositionY()
            local sceneCameraDistance = GetCameraField(CAMERA_FIELD_TARGET_DISTANCE)
            local ERROR_MARGIN = 5.0
            --local ERROR_MARGIN_ANGLE = 1.0
            local fixed = false
            if math.abs(sceneCameraX - interpolatedX) > ERROR_MARGIN or math.abs(sceneCameraY - interpolatedY) > ERROR_MARGIN then
                if ScreenplaySystem.debug then
                    print("interpolateCamera: " .. tostring(interpolatedX) .. ", " .. tostring(interpolatedY))
                    print("sceneCamera: " .. tostring(sceneCameraX) .. ", " .. tostring(sceneCameraY))
                    print("fixing camera pos")
                end
                --CameraSetupSetDestPosition(speak.scenecam, interpolatedX, interpolatedY)
                SetCameraPosition(interpolatedX, interpolatedY)
                fixed = true
            end
            if math.abs(sceneCameraDistance - interpolatedDistance) > ERROR_MARGIN then
                if ScreenplaySystem.debug then
                    print("fixing camera distance" .. tostring(sceneCameraDistance) .. " -> " .. interpolatedDistance)
                end
                SetCameraField(CAMERA_FIELD_TARGET_DISTANCE, interpolatedDistance, 0.0)
                fixed = true
            end
            if fixed == true then
                CameraSetupApplyForceDuration(cameraTo, true, durationLeft)
            end
        end
    end)
    return timer
end

function ScreenplayUtils.interpolate(from, to, fraction)
    return from + (to - from) * fraction
end

function ScreenplayUtils.clearInterpolation()
    if ScreenplaySystem.cameraInterpolationTimer then
        SimpleUtils.releaseTimer(ScreenplaySystem.cameraInterpolationTimer)
    end
    StopCamera()
end

function ScreenplayUtils.getCurrentItemDuration()
    local currentItem = ScreenplaySystem:currentItem()
    if currentItem == nil then
        return 0.0
    end
    return currentItem:getDuration()
end

--[[
    Map of screenplay configuration variants. Feel free to edit and add your own.
]]
ScreenplayVariants = {
    --[[
        An "automated" cutscene which sets cinematic mode and displays dialog lines similarly to Blizz standard
        cutscenes. Unlike standard cutscenes, this one has user controls enabled so that the player can skip single
        lines or make dialog choices. A pleasant "side effect" is that you can pause a game, save and load during cutscenes.
        Typically you still need some logic to happen on certain messages, e.g. camera movements, fadeins/fadeouts,
        units turning to each other etc., which you do by defining 'func', 'trigger' or 'actions' props of a dialog line.
        See elf screenplay in a demo map.
    ]]
    inCutsceneAutoplay = {
        anchorX = 0.565,
        anchorY = 0.08,
        width = 0.98,
        height = 0.12,
        cinematicMode = true,
        cinematicInteractive = true,
        hideUI = false,
        pauseAll = false,
        lockCamera = false,
        disableSelection = true,
        unitPan = false,
        cameraSpeed = 0.0,
        unitFlash = true,
        speed = 0.04,
        autoMoveNext = true,
        autoMoveNextDelay = 3,
        autoMoveNextDelayPerChar = 0.02,
        skippable = true,
        rewindable = true,
        interruptExisting = true,
    },
    --[[
        A modification of above that also pauses all units. Typically I use 'inCutsceneAutoplayPause' for mid-game
        cutscenes in maps with base-building. and 'inCutsceneAutoplay' for intros, outros and maps without a base.
    ]]
    inCutsceneAutoplayPause = {
        anchorX = 0.565,
        anchorY = 0.08,
        width = 0.98,
        height = 0.12,
        cinematicMode = true,
        cinematicInteractive = true,
        hideUI = false,
        pauseAll = true,
        lockCamera = false,
        disableSelection = true,
        unitPan = false,
        cameraSpeed = 0.0,
        unitFlash = true,
        speed = 0.04,
        autoMoveNext = true,
        autoMoveNextDelay = 3,
        autoMoveNextDelayPerChar = 0.02,
        skippable = true,
        rewindable = true,
        interruptExisting = true,
    },
    --[[
        A modification of above that requires pressing right arrow to move to the next line.
    ]]
    inCutsceneNoAutoplay = {
        anchorX = 0.565, -- x-offset for dialogue box's center framepoint.
        anchorY = 0.08, -- y-offset ``.
        width = 0.98, -- 1 -- x-width of dialogue frame.
        height = 0.12, -- y-width ``.
        cinematicMode = true,
        cinematicInteractive = true,
        hideUI = false, -- should the default game ui be hidden when scenes run?
        pauseAll = false,
        lockCamera = false,
        disableSelection = true,
        unitPan = false, -- should the camera pan to the speaking actor's unit?
        cameraSpeed = 0.0, -- how fast the camera pans when scenes start/end/shift.
        unitFlash = true, -- should transmission indicators flash on the speaking unit?
        autoMoveNext = false,
        speed = 0.04, -- cadence to show new string characters (you could increase for dramatic effect).
        skippable = true,
        rewindable = true,
        interruptExisting = true,
    },
    --[[
        A small dialog window that pauses the game and keeps the camera pointing at a currently speaking actor. Good for
        minor interactions with NPCs, merchants, dialogs without a cutscene that still require the player to make a choice
        or have several available topics to discuss.
    ]]
    inGamePause = {
        anchorX = 0.4,
        anchorY = 0.22,
        width = 0.37,
        height = 0.11,
        cinematicMode = false,
        cinematicInteractive = false,
        pauseAll = true,
        hideUI = false,
        lockCamera = true,
        disableSelection = true,
        unitPan = true,
        cameraSpeed = 0.75,
        unitFlash = true,
        autoMoveNext = true,
        autoMoveNextDelay = 3,
        speed = 0.04,
        skippable = true,
        rewindable = true,
        interruptExisting = false,
    },
    --[[
        A simple in-game dialog that's not supposed to pause or disrupt the gameplay. Not meant for long dialogs, choices,
        etc., just quick comments or interactions in combat or when entering some new region.
    ]]
    inGame = {
        anchorX = 0.4,
        anchorY = 0.2,
        width = 0.37,
        height = 0.11,
        cinematicMode = false,
        cinematicInteractive = false,
        pauseAll = false,
        hideUI = false,
        lockCamera = false,
        disableSelection = false,
        unitPan = false,
        cameraSpeed = 0.0,
        unitFlash = true,
        autoMoveNext = true,
        autoMoveNextDelay = 3,
        speed = 0.04,
        skippable = false,
        rewindable = false,
        interruptExisting = false,
    }
}

--[[
    Important API functions you may need - see their documentation below
        ScreenplaySystem.chain:buildFromObject({
            [1] = {
                text = "Lorem ipsum...",
                actor = actorFootman,
            }) - validates and builds a chain of messages

        ScreenplaySystem:startSceneByName('myScreenplayName', 'inGame', gg_trg_MyScreenplayEndTrigger, true)
        - starts a scene by name previously saved using ScreenplayFactory.saveBuilder() function

        ScreenplaySystem.currentChain - get currently played message chain if present. Note that it's a field, not a function.

        ScreenplaySystem:currentItem() - get currently played item from the current chain if exists

        ScreenplaySystem:goTo(index) - immediately go to given index.

        ScreenplaySystem:isActive() - is any scene playing at the moment?
]]
ScreenplaySystem = {   -- main dialogue class, configuration options can be found in ScreenplayVariants.lua
    FDF_BACKDROP = "EscMenuBackdrop",
    FDF_TITLE = "CustomText", -- from imported .fdf
    FDF_TEXT_AREA = "CustomTextArea", -- ``
    TITLE_COLOR_HEX = "|cffffce22", -- character title text color.
    TEXT_COLOR_HEX = "|cffffffff", -- character speech text color.
    INACTIVE_CHOICE_COLOR_HEX = "|cff808080", -- greyish text color for choices other than the selected one

    debug = false, -- print debug messages for certain functions.

    --leftovers from original lib, could be moved to ScreenplayVariants, but so far I saw no need to customize them
    fade = true, -- should dialogue components have fading eye candy effects?
    fadeDuration = 0.81, -- how fast to fade if fade is enabled.

    --internal state of the config and the screenplay
    frameInitialized = false,
    currentVariantConfig = nil,
    onSceneEndTrigger = nil,
    messageUncoverTimer = nil,
    trackingCameraTimer = nil,
    autoplayTimer = nil,
    cameraInterpolationTimer = nil,
    delayTimer = nil,
    fadeoutTimer = nil,
    lastActorUnitTypeSpeaking = nil,
}

ScreenplaySystem.item = {   -- sub class for dialogue strings and how they play.
    text = nil, -- the dialogue string to display.
    actor = nil, -- the actor that owns this speech item.
    anim = nil, -- play a string animation when the speech item is played.
    sound = nil, -- play a sound when this item begins.
    func = nil, -- call this function when the speech item is played (e.g. move a unit).
    trigger = nil, -- call this trigger (referred by gg_trg_TriggerName) when the speech item is played (e.g. move a unit).
    actions = {}, -- an alternative to two fields above, allows to put an entire list of itemAction objects (see below) to be executed on message
    thenGoTo = nil, -- next message index to play after the current one, defaults to current index + 1
    thenGoToFunc = nil, -- function to dynamically choose next message index to play after current one
    thenEndScene = false, -- alternatively to above, just end scene after this message
    skippable = true, -- if current item can be skipped by RIGHT arrow. NOTE: it doesn't affect skipping whole scene.
    delayText = 0, --delay before starting displaying message characters
    delayNextItem = 0, --delay after displaying all message characters, before moving to next item
    fadeInDuration = 0, --duration of fade in from black before displaying this item
    fadeOutDuration = 0, -- duration of fade out to black after displaying this item, remember to add 'fadeInDuration' to the following item or fade in by script/trigger
    skipTimers = false, --if true, upon skipping this message timed actions added via SimpleUtils.skippable() will be cancelled. Set to true for messages that begin a new shot, with fade, new camera etc.
    stopOnRewind = false, --if true, rewinding a cutscene (ESC) will stop at this message
    onRewindGoTo = 0, --used to pick new message when skipping choices
}

ScreenplaySystem.itemAction = {
    func = nil,
    trigger = nil
}

ScreenplaySystem.choice = {
    text = nil, -- choice text to display
    onChoice = nil, -- function to execute after selecting a choice
    visible = true, -- whether this choice should be initially visible. Can be modified in runtime to dynamically show/hide dialog options
    visibleFunc = nil, -- additional visibility mechanism, optional function returning boolean whether this choice should be visible, note that it should not modify any state as it is called multiple times
    chosen = false, -- set by the script after selecting a choice. Can be used for conditions to show other dialog options
}

ScreenplaySystem.actor = {   -- sub class for storing actor settings.
    unit = nil, -- the unit which owns the actor object.
    name = nil, -- the name of the actor (defaults to unit name).
}
ScreenplaySystem.chain = {}  -- sub class for chaining speech items in order.

do
    local function printDebug(msg)
        if ScreenplaySystem.debug then
            print(msg)
        end
    end

    --- @param bool boolean  true to animate out (hide), false to animate in (show).
    local function fadeOutFrame(bool)
        FrameUtils.fadeFrame(bool, ScreenplaySystem.frame.backdrop, ScreenplaySystem.fadeDuration)
    end

    --- @param bool boolean  true to show, false to hide.
    --- @param skipeffects boolean  optional - set to true skip fade animation.
    local function show(show, skipEffects)
        if show then
            if ScreenplaySystem.fade and not skipEffects then
                fadeOutFrame(show)
            else
                for _, fh in pairs(ScreenplaySystem.frame) do
                    if fh ~= ScreenplaySystem.frame.skipbtn then
                        BlzFrameSetVisible(fh, true)
                    end
                end
            end
        else
            for _, fh in pairs(ScreenplaySystem.frame) do
                BlzFrameSetVisible(fh, false)
            end
        end
    end

    local function initFrames()
        ScreenplaySystem.frame = {}
        ScreenplaySystem.frame.backdrop = BlzCreateFrame(ScreenplaySystem.FDF_BACKDROP, ScreenplaySystem.gameui, 0, 0)
        ScreenplaySystem.frame.title = BlzCreateFrame(ScreenplaySystem.FDF_TITLE, ScreenplaySystem.frame.backdrop, 0, 0)
        ScreenplaySystem.frame.text = BlzCreateFrame(ScreenplaySystem.FDF_TEXT_AREA, ScreenplaySystem.frame.backdrop, 0, 0)

        show(false, true)
        --BlzFrameSetEnable(ScreenplaySystem.frame.backdrop, false)
        --BlzFrameSetEnable(ScreenplaySystem.frame.title, false)
        --BlzFrameSetEnable(ScreenplaySystem.frame.text, false)
        ScreenplaySystem.frameInitialized = true
    end

    local function playCurrentItem()
        --can't join choices with delayText
        ScreenplaySystem:currentItem():play()
    end

    local function refreshFrames()
        BlzFrameSetSize(ScreenplaySystem.frame.backdrop, ScreenplaySystem.currentVariantConfig.width, ScreenplaySystem.currentVariantConfig.height)
        BlzFrameSetAbsPoint(ScreenplaySystem.frame.backdrop, FrameUtils.FRAME_POINTS.c, ScreenplaySystem.currentVariantConfig.anchorX, ScreenplaySystem.currentVariantConfig.anchorY)

        BlzFrameSetSize(ScreenplaySystem.frame.title, ScreenplaySystem.currentVariantConfig.width, ScreenplaySystem.currentVariantConfig.height * 0.1)
        BlzFrameSetPoint(ScreenplaySystem.frame.title, FrameUtils.FRAME_POINTS.tl, ScreenplaySystem.frame.backdrop, FrameUtils.FRAME_POINTS.tl, ScreenplaySystem.currentVariantConfig.height * 0.2, -ScreenplaySystem.currentVariantConfig.height * 0.17)
        BlzFrameSetText(ScreenplaySystem.frame.title, "")

        BlzFrameSetSize(ScreenplaySystem.frame.text, ScreenplaySystem.currentVariantConfig.width, ScreenplaySystem.currentVariantConfig.height * 0.5)
        BlzFrameSetPoint(ScreenplaySystem.frame.text, FrameUtils.FRAME_POINTS.tl, ScreenplaySystem.frame.title, FrameUtils.FRAME_POINTS.tl, 0, -ScreenplaySystem.currentVariantConfig.height * 0.18)
        BlzFrameSetText(ScreenplaySystem.frame.text, "")
    end

    local function loadAndInitFrames()
        if not BlzLoadTOCFile('war3mapImported\\CustomFrameTOC.toc') then
            print("error: .fdf file failed to load")
            print("tip: are you missing a curly brace in the fdf?")
            print("tip: does the .toc file have the correct file paths?")
            print("tip: .toc files require an empty newline at the end")
        end
        ScreenplaySystem.consoleBackdrop = BlzGetFrameByName("ConsoleUIBackdrop",0)
        ScreenplaySystem.gameui    = BlzGetOriginFrame(ORIGIN_FRAME_GAME_UI, 0)
        initFrames()
        if ScreenplaySystem.initialized then
            refreshFrames()
            playCurrentItem()
        end
    end

    ---enableCamera
    ---@param bool boolean  true - enable dialogue camera; false - return to game camera.
    ---@param sync boolean  true - execute instantly; false - enabling/disabling takes cameraSpeed seconds
    local function enableCamera(bool, sync)
        local cameraSpeed = SimpleUtils.ifElse(sync, 0, ScreenplaySystem.currentVariantConfig.cameraSpeed)
        if bool then
            ClearTextMessagesBJ(bj_FORCE_ALL_PLAYERS)
            TimerStart(ScreenplaySystem.trackingCameraTimer, 0.03, true, function()
                CameraSetupApplyForPlayer(true, ScreenplaySystem.sceneCamera, GetLocalPlayer(), cameraSpeed)
                PanCameraToTimedForPlayer(GetLocalPlayer(), ScreenplaySystem.cameraTargetX, ScreenplaySystem.cameraTargetY, cameraSpeed)
            end)
        else
            PauseTimer(ScreenplaySystem.trackingCameraTimer)
            ResetToGameCameraForPlayer(GetLocalPlayer(), cameraSpeed)
        end
    end

    --- when a new chain is being played, initialize the default display.
    local function clear()
        ScreenplayUtils.clearInterpolation()
        BlzFrameSetText(ScreenplaySystem.frame.text, "")
        BlzFrameSetText(ScreenplaySystem.frame.title, "")
        if ScreenplaySystem.fade then
            BlzFrameSetAlpha(ScreenplaySystem.frame.text, 0)
            BlzFrameSetAlpha(ScreenplaySystem.frame.title, 0)
        end
    end

    --- initialize the scene interface (e.g. typically if you are running a cinematic component first).
    local function initScene()
        clear()
        if ScreenplaySystem.currentVariantConfig.cinematicMode then
            CinematicModeBJ(true, GetPlayersAll())
            ClearSelection()
        end
        if ScreenplaySystem.currentVariantConfig.cinematicInteractive then
            SetUserControlForceOn(GetPlayersAll())
        end
        if ScreenplaySystem.currentVariantConfig.hideUI then
            BlzHideOriginFrames(true)
            BlzFrameSetVisible(ScreenplaySystem.consoleBackdrop, false)
        end
        if ScreenplaySystem.currentVariantConfig.disableSelection then
            BlzEnableSelections(false, false)
            EnablePreSelect(true, false)
        end
        if ScreenplaySystem.currentVariantConfig.lockCamera then
            enableCamera(true, false)
        end
        if ScreenplaySystem.currentVariantConfig.pauseAll then
            PauseAllUnitsBJ(true)
        end
        -- set flag for any GUI triggers that might need it:
        udg_screenplayActive = true
        ScreenplaySystem.initialized = true
    end

    --- initialize classes and class specifics, always called at map init
    function ScreenplaySystem:init()
        SimpleUtils.newClass(ScreenplaySystem.actor)
        SimpleUtils.newClass(ScreenplaySystem.item)
        SimpleUtils.newClass(ScreenplaySystem.itemAction)
        SimpleUtils.newClass(ScreenplaySystem.chain)
        SimpleUtils.newClass(ScreenplaySystem.choice)
        self.prevActor = nil   -- control for previous actor if frames animate on change.
        self.itemFullyDisplayed = false -- flag for controlling quick-complete vs. next speech item.
        self.currentIndex = 0     -- the item currently being played from an item queue.
        self.cameraTargetX = 0     -- X coord to pan camera to.
        self.cameraTargetY = 0     -- Y coord to pan camera to.
        self.paused = false
        self.initialized = false
        self.sceneCamera = gg_cam_sceneCam
        self.trackingCameraTimer = CreateTimer()
        -- time elapsed init.
        SimpleUtils.timed(0.0, function()
            loadAndInitFrames()
        end)
    end

    local function buildScreenplay(name)
        local builder = ScreenplayFactory.screenplayBuilders[name]
        printDebug("calling builder for " .. tostring(name))
        return builder()
    end

    ---startSceneByName
    --- start a scene by name previously saved using ScreenplayFactory.saveBuilder() function, display it using a given
    --- variant from ScreenplayVariants. Optionally pass trigger to run on scene end and a bool flag whether it should
    --- interrupt existing scene
    ---@param name string
    ---@param variant string
    ---@param onSceneEndTrigger trigger
    ---@param interruptExisting boolean
    function ScreenplaySystem:startSceneByName(name, variant, onSceneEndTrigger, interruptExisting)
        ScreenplaySystem:startScene(buildScreenplay(name), variant, onSceneEndTrigger, interruptExisting)
    end

    function ScreenplaySystem:startScene(chain, variant, onSceneEndTrigger, interruptExisting)
        if self:isActive() then
            if interruptExisting == true or variant.interruptExisting == true then
                printDebug("interrupting existing scene...")
                clear()
                self:endScene(true)
            else
                printDebug("existing scene found, aborting...")
                return
            end
        end

        printDebug("Starting scene...")
        ClearTextMessages()

        self.currentVariantConfig = ScreenplayVariants[variant]
        self.onSceneEndTrigger = onSceneEndTrigger
        assert(self.currentVariantConfig, "invalid frame variant: " .. variant)
        self.currentIndex = 0
        self.currentChain = SimpleUtils.deepCopy(chain)
        self.paused = false
        if not self.initialized then
            initScene()
        end
        if self.frameInitialized then
            refreshFrames()
        end

        if self.fade then
            fadeOutFrame(false)
        else
            BlzFrameSetVisible(self.frame.backdrop, true)
        end
        printDebug("calling first playNext")
        self.currentChain:playNext()
    end

    local function sendDummyTransmission()
        if ScreenplaySystem.lastActorUnitTypeSpeaking then
            DoTransmissionBasicsXYBJ(ScreenplaySystem.lastActorUnitTypeSpeaking, GetPlayerColor(ScreenplaySystem.lastActorPlayerSpeaking),0, 0, nil, "", "", 0.5)
            ScreenplaySystem.lastActorUnitTypeSpeaking = nil
        end
    end

    function ScreenplaySystem:endScene()
        self:endScene(false)
    end

    -- end the dialogue sequence.
    function ScreenplaySystem:endScene(sync)
        SkippableTimers:skip()
        if self.currentVariantConfig.cinematicMode then
            sendDummyTransmission()
        end
        if self.currentVariantConfig.cinematicMode then
            CinematicModeBJ(false, GetPlayersAll())
            ResetToGameCameraForPlayer(GetLocalPlayer(), 0)
        end
        if self.currentVariantConfig.hideUI then
            BlzHideOriginFrames(false)
            BlzFrameSetVisible(self.consoleBackdrop, true)
        end
        if self.currentVariantConfig.disableSelection then
            BlzEnableSelections(true, true)
            EnablePreSelect(true, true)
        end
        if self.fade then
            fadeOutFrame(true)
        else
            BlzFrameSetVisible(self.frame.backdrop, false)
        end
        if self.currentVariantConfig.pauseAll then
            printDebug("unpausing all")
            PauseAllUnitsBJ(false)
        end
        if self.currentVariantConfig.lockCamera then
            enableCamera(false, sync)
        end

        udg_screenplayActive = false
        self.currentIndex = 0
        self.currentChoiceIndex = 0
        self.currentChoices = nil
        self.currentVariantConfig = nil
        self.initialized = false
        if self.messageUncoverTimer then
            SimpleUtils.releaseTimer(self.messageUncoverTimer)
        end
        if self.autoplayTimer then
            SimpleUtils.releaseTimer(self.autoplayTimer)
        end
        if self.cameraInterpolationTimer then
            SimpleUtils.releaseTimer(self.cameraInterpolationTimer)
        end
        if self.delayTimer then
            SimpleUtils.releaseTimer(self.delayTimer)
        end
        if self.fadeoutTimer then
            SimpleUtils.releaseTimer(self.fadeoutTimer)
        end
        -- clear cache:
        if not self.paused then
            SimpleUtils.destroyTable(self.currentChain)
        end
        if self.onSceneEndTrigger then
            ConditionalTriggerExecute(self.onSceneEndTrigger)
        end
    end

    -- function to run when the "next" is clicked.
    local function clickNext()
        if ScreenplaySystem.currentChain then
            if ScreenplaySystem.delayTimer then
                SimpleUtils.releaseTimer(ScreenplaySystem.delayTimer)
                ScreenplaySystem.delayTimer = nil
                playCurrentItem()
            elseif ScreenplaySystem.itemFullyDisplayed then
                ScreenplaySystem.currentChain:playNext()
            else
                ScreenplaySystem.itemFullyDisplayed = true
            end
        else
            ScreenplaySystem:endScene()
        end
    end

    -- get currently played item from the current chain if exists
    function ScreenplaySystem:currentItem()
        return self.currentChain[self.currentIndex]
    end

    local function isValidChoice()
        if ScreenplaySystem.currentChoiceIndex <= 0 then
            return false
        end
        local choice = ScreenplaySystem.currentChoices[ScreenplaySystem.currentChoiceIndex]
        return choice and choice:isVisible()
    end

    local function canSkipItem()
        return ScreenplaySystem.currentVariantConfig.skippable == true and ScreenplaySystem:currentItem().skippable == true and ScreenplaySystem.fadeoutTimer == nil
    end

    -- action listener functions, typically called by predefined triggers available in demo map
    function ScreenplaySystem:onPreviousChoice()
        printDebug("onPreviousChoice: ", tostring(self.currentChoiceIndex))
        if not self.currentChoiceIndex or not self.currentChoices then
            return
        end
        if self.currentChoiceIndex > 1
        then
            repeat
                self.currentChoiceIndex = self.currentChoiceIndex - 1
            until self.currentChoices[self.currentChoiceIndex]:isVisible() or self.currentChoiceIndex == 1
            playCurrentItem()
        end
    end

    function ScreenplaySystem:onNextChoice()
        printDebug("onNextChoice: ", tostring(self.currentChoiceIndex))
        if not self.currentChoiceIndex or not self.currentChoices then
            return
        end
        local tableLength = SimpleUtils.tableLength(self.currentChoices)
        if self.currentChoiceIndex < tableLength
        then
            repeat
                self.currentChoiceIndex = self.currentChoiceIndex + 1
            until self.currentChoices[self.currentChoiceIndex]:isVisible() or self.currentChoiceIndex == tableLength
            playCurrentItem()
        end
    end

    function ScreenplaySystem:onSelectChoice()
        printDebug("onSelectChoice: " .. tostring(self.currentChoiceIndex))
        if self.currentChoices then
            if isValidChoice() then
                printDebug("currentChoices:onChoice() - valid choice")
                self.currentChoices[self.currentChoiceIndex]:onChoice()
                self.currentChoices[self.currentChoiceIndex].chosen = true
                self.currentChoices = nil
                self.currentChoiceIndex = 0
                self.currentChain:playNextInternal()
            end
        elseif (canSkipItem()) then
            printDebug("will call clickNext()")
            clickNext()
        else
            printDebug("Couldn't select choice")
        end
    end

    function ScreenplaySystem:onRewind()
        if self.currentVariantConfig.rewindable == true then
            printDebug("onRewind, currentItemIndex: ", tostring(self.currentIndex))
            self.currentChain:rewind()
        end
    end

    function ScreenplaySystem:onLoad()
        loadAndInitFrames()
        refreshFrames()
        playCurrentItem()
    end

    -- END action listener functions

    local function goToInternal(index)
        printDebug("index " .. ScreenplaySystem.currentIndex .. " -> " .. index .. ", table length " .. SimpleUtils.tableLength(ScreenplaySystem.currentChain))
        ScreenplaySystem.currentIndex = index
    end

    ---
    --- Immediately go to given index. Mostly meant to be used in screenplay choices, in onChoice function. If given index
    --- from outside current chain range, it will print warning and do nothing. When called by external scripts, should be
    --- followed by ScreenplaySystem:playCurrentItem().
    ---
    ---@param index number
    function ScreenplaySystem:goTo(index)
        if not self.currentChain:isValidIndex(index) then
            SimpleUtils.printWarn("Invalid goTo index " .. tostring(index) .. ", cannot proceed")
            return
        end
        goToInternal(index)
    end

    local function sendTransmission(actor, text)
        local count = string.len(text)
        local msgLength = ScreenplaySystem.currentVariantConfig.autoMoveNextDelay + count * ScreenplaySystem.currentVariantConfig.speed * 2 --FIXME attempt to compensate diff between expected and real time of SimpleUtils.timedRepeat()

        local unitType
        local player
        local x
        local y
        if actor.unit then
            unitType = GetUnitTypeId(actor.unit)
            player = GetOwningPlayer(actor.unit)
            x = GetUnitX(actor.unit)
            y = GetUnitY(actor.unit)
        else
            unitType = actor.unitType
            player = actor.player
            x = 0
            y = 0
        end

        ScreenplaySystem.lastActorUnitTypeSpeaking = unitType
        ScreenplaySystem.lastActorPlayerSpeaking = player
        DoTransmissionBasicsXYBJ(unitType, GetPlayerColor(player), x, y, nil, "", "", msgLength)
    end

    --- Is any scene playing at the moment?
    ---@return boolean
    function ScreenplaySystem:isActive()
        return udg_screenplayActive
    end

    local function speechIndicator(unit)
        UnitAddIndicatorBJ(unit, 0.00, 100, 0.00, 0)
    end

    -- play a speech item, rendering its string characters over time and displaying actor details.
    function ScreenplaySystem.item:play()
        -- initialize timer settings:
        if ScreenplaySystem.messageUncoverTimer then
            SimpleUtils.releaseTimer(ScreenplaySystem.messageUncoverTimer)
            ScreenplaySystem.messageUncoverTimer = nil
        end

        BlzFrameSetVisible(ScreenplaySystem.frame.backdrop, true)
        BlzFrameSetText(ScreenplaySystem.frame.title, ScreenplaySystem.TITLE_COLOR_HEX .. self.actor.name .. "|r")
        if self.choices then
            self:playChoices()
        else
            self:playText()
        end

        if self.actor.unit then
            -- run additional speech inputs if present:
            if ScreenplaySystem.currentVariantConfig.unitFlash then
                speechIndicator(self.actor.unit)
            end
            if not (self.anim == nil) then
                ResetUnitAnimation(self.actor.unit)
                QueueUnitAnimation(self.actor.unit, self.anim)
                QueueUnitAnimation(self.actor.unit, "stand")
            end
        end
        if not (self.sound == nil) then
            SimpleUtils.playSound(self.sound)
        end

        BlzFrameSetVisible(ScreenplaySystem.frame.title, true)
        BlzFrameSetVisible(ScreenplaySystem.frame.text, true)
        if ScreenplaySystem.fade and ScreenplaySystem.prevActor ~= self.actor then
            FrameUtils.fadeFrame(false, ScreenplaySystem.frame.title, ScreenplaySystem.fadeDuration)
            FrameUtils.fadeFrame(false, ScreenplaySystem.frame.text, ScreenplaySystem.fadeDuration)
        end

        if self.actor.unit and ScreenplaySystem.currentVariantConfig.unitPan then
            ScreenplaySystem.cameraTargetX = GetUnitX(self.actor.unit)
            ScreenplaySystem.cameraTargetY = GetUnitY(self.actor.unit)
        end
        ScreenplaySystem.prevActor = self.actor
    end

    function ScreenplaySystem.item:playText()
        ScreenplaySystem.currentChoices = nil
        ScreenplaySystem.currentChoiceIndex = 0
        -- a flag for skipping the text animation:
        ScreenplaySystem.itemFullyDisplayed = false

        local count = string.len(self.text)
        local pos = 1
        local ahead = ''

        -- render string characters:
        local delay = self:getDuration()

        if ScreenplaySystem.currentVariantConfig.cinematicMode then
            sendTransmission(self.actor, self.text)
        end

        --send msg and clear it immediately - just for the purpose of having the messages in transmission log
        DisplayTimedTextToPlayer(GetLocalPlayer(), 0.0, 0.0, 0.1, ScreenplaySystem.TITLE_COLOR_HEX .. self.actor.name .. "|r: " .. self.text)
        ClearTextMessages()

        ScreenplaySystem.messageUncoverTimer = SimpleUtils.timedRepeat(ScreenplaySystem.currentVariantConfig.speed, count, function(timer)
            if pos < count and not ScreenplaySystem.itemFullyDisplayed then
                ahead = string.sub(self.text, pos, pos + 1)
                -- scan for formatting patterns:
                if ahead == '|c' then
                    pos = pos + 10
                elseif ahead == '|r' or ahead == '|n' then
                    pos = pos + 2
                else
                    pos = pos + 1
                end
                BlzFrameSetText(ScreenplaySystem.frame.text, ScreenplaySystem.TEXT_COLOR_HEX .. string.sub(self.text, 1, pos))
                FrameUtils.fixFocus(ScreenplaySystem.frame.text)
            else
                ScreenplaySystem.itemFullyDisplayed = true
                BlzFrameSetText(ScreenplaySystem.frame.text, ScreenplaySystem.TEXT_COLOR_HEX .. self.text)
                SimpleUtils.releaseTimer(timer)
                if ScreenplaySystem.currentVariantConfig.autoMoveNext == true then
                    ScreenplaySystem.autoplayTimer = SimpleUtils.timed(delay, function()
                        ScreenplaySystem.currentChain:playNext()
                    end)
                end
            end
        end)
    end

    function ScreenplaySystem.item:playChoices()
        local text = "";
        ScreenplaySystem.currentChoices = self.choices
        local displayedIndex = 1
        for index, choice in ipairs(ScreenplaySystem.currentChoices) do
            if choice:isVisible() then
                local color = SimpleUtils.ifElse(index == ScreenplaySystem.currentChoiceIndex, ScreenplaySystem.TEXT_COLOR_HEX, ScreenplaySystem.INACTIVE_CHOICE_COLOR_HEX)
                text = text .. color .. ((displayedIndex) .. ". " .. choice.text .. "|n")
                displayedIndex = displayedIndex + 1
            end
        end
        BlzFrameSetText(ScreenplaySystem.frame.text, text)
        ScreenplaySystem.itemFullyDisplayed = true
    end

    function ScreenplaySystem.choice:isVisible()
        return self.visible and (self.visibleFunc == nil or self.visibleFunc())
    end

    function ScreenplaySystem.item:getDuration()
        if not ScreenplaySystem.currentVariantConfig.autoMoveNext then
            return 0
        end
        return ScreenplaySystem.currentVariantConfig.autoMoveNextDelay + string.len(self.text) * ScreenplaySystem.currentVariantConfig.speed + self.delayNextItem + self.fadeInDuration + self.fadeOutDuration
    end

    function ScreenplaySystem.item:isActorAlive()
        if self.actor.unitType and self.actor.player then
            return true
        end
        if self.actor.unit then
            return IsUnitAliveBJ(self.actor.unit)
        end
        return false
    end

    -- after a speech item completes, see what needs to happen next (load next item or close, etc.)
    function ScreenplaySystem.chain:playNext()
        printDebug("playNext: currentIndex: " .. tostring(ScreenplaySystem.currentIndex))
        local fadeOutDuration
        if ScreenplaySystem:currentItem() == nil then
            fadeOutDuration = 0
        else
            fadeOutDuration = ScreenplaySystem:currentItem().fadeOutDuration
        end
        if fadeOutDuration > 0 then
            SimpleUtils.fadeOut(fadeOutDuration)
            ScreenplaySystem.fadeoutTimer = SimpleUtils.timed(fadeOutDuration * 1.2, function()
                self:moveAndPlayNextInternal()
            end)
        else
            self:moveAndPlayNextInternal()
        end
    end

    function ScreenplaySystem.chain:moveAndPlayNextInternal()
        local nextIndex = self:getNextIndex();
        goToInternal(nextIndex)
        self:playNextInternal()
    end

    function ScreenplaySystem.chain:playNextInternal()
        if ScreenplaySystem.messageUncoverTimer then
            SimpleUtils.releaseTimer(ScreenplaySystem.messageUncoverTimer)
        end
        if ScreenplaySystem.autoplayTimer then
            SimpleUtils.releaseTimer(ScreenplaySystem.autoplayTimer)
        end
        if ScreenplaySystem.delayTimer then
            SimpleUtils.releaseTimer(ScreenplaySystem.delayTimer)
        end
        if ScreenplaySystem.fadeoutTimer then
            SimpleUtils.releaseTimer(ScreenplaySystem.fadeoutTimer)
            ScreenplaySystem.fadeoutTimer = nil
        end
        if not self:isValidIndex(ScreenplaySystem.currentIndex) then
            clear()
            ScreenplaySystem:endScene()
        else
            local currentItem = self[ScreenplaySystem.currentIndex]
            if currentItem == nil or currentItem.skipTimers == true then
                SkippableTimers:skip()
            end
            if not self[ScreenplaySystem.currentIndex] or not self[ScreenplaySystem.currentIndex]:isActorAlive() then
                -- if next item was set to nil or is empty, try to skip over:
                self:playNext()
            else
                if self[ScreenplaySystem.currentIndex].func and not self[ScreenplaySystem.currentIndex].text then
                    self[ScreenplaySystem.currentIndex]:func()
                    self:playNext()
                else
                    printDebug("trying to play index item: " .. ScreenplaySystem.currentIndex .. " with actor: " .. self[ScreenplaySystem.currentIndex].actor.name)

                    ScreenplaySystem.currentChoiceIndex = 0
                    local currentItem = self[ScreenplaySystem.currentIndex]
                    if currentItem.trigger then
                        ConditionalTriggerExecute(currentItem.trigger)
                    end
                    if currentItem.func then
                        currentItem:func()
                    end
                    if currentItem.actions then
                        for index, action in ipairs(currentItem.actions) do
                            if action.func then
                                action:func()
                            end
                            if action.trigger then
                                ConditionalTriggerExecute(action.trigger)
                            end
                        end
                    end

                    local initialDelay = currentItem.delayText + currentItem.fadeInDuration

                    if initialDelay > 0 then
                        if currentItem.fadeInDuration > 0 then
                            SimpleUtils.fadeIn(currentItem.fadeInDuration)
                        end

                        BlzFrameSetVisible(ScreenplaySystem.frame.backdrop, false)
                        sendDummyTransmission()
                        ScreenplaySystem.delayTimer = SimpleUtils.timed(initialDelay, function()
                            ScreenplaySystem.delayTimer = nil
                            currentItem:play()
                        end)
                        printDebug("delayed playing index item: " .. tostring(ScreenplaySystem.currentIndex))
                    else
                        currentItem:play()
                        printDebug("played index item: " .. tostring(ScreenplaySystem.currentIndex))
                    end

                end
            end
        end
    end

    function ScreenplaySystem.chain:getNextIndex()
        return self:getNextIndexForIndex(ScreenplaySystem.currentIndex);
    end

    function ScreenplaySystem.chain:getNextIndexForIndex(index)
        if self[index] then
            if self[index].thenEndScene == true then
                return -1
            elseif self[index].thenGoTo then
                return self[index].thenGoTo
            elseif self[index].thenGoToFunc then
                return self[index].thenGoToFunc()
            else
                return index + 1
            end
        else
            return index + 1
        end
    end

    function ScreenplaySystem.chain:isCurrentChoiceRewindable(index)
        return not (self[index].onRewindGoTo == nil or self[index].onRewindGoTo == 0)
    end

    function ScreenplaySystem.chain:getNextIndexForRewind(index)
        if self[index].choices ~= nil and self:isCurrentChoiceRewindable(index) then
            return self[index].onRewindGoTo
        end
        return self:getNextIndexForIndex(index)
    end

    -- rewinds a current chain to the next interactive and non-rewindable item (usually a choice). If it reaches the end, ends scene
    function ScreenplaySystem.chain:rewind()
        local currentIndex = ScreenplaySystem.currentIndex;
        printDebug("Rewind - current index: " .. tostring(currentIndex))
        if currentIndex == nil then
            return
        end
        if self[currentIndex].choices ~= nil and not self:isCurrentChoiceRewindable(currentIndex) then
            return
        end
        local tableLength = SimpleUtils.tableLength(ScreenplaySystem.currentChain)
        local prevIndex
        repeat
            prevIndex = currentIndex
            currentIndex = self:getNextIndexForRewind(currentIndex)
            printDebug("Rewind - moving from " .. tostring(prevIndex) .. " to " .. tostring(currentIndex))
        until currentIndex <= 0
                or currentIndex > tableLength
                or currentIndex == ScreenplaySystem.currentIndex
                or (self[currentIndex].choices ~= nil and not self:isCurrentChoiceRewindable(currentIndex))
                or self[currentIndex].stopOnRewind == true
        if currentIndex == ScreenplaySystem.currentIndex then
            SimpleUtils.printWarn("Cycle detected on index " .. currentIndex .. ", this dialog will never end, can't rewind")
            return
        end

        goToInternal(currentIndex)
        self:playNextInternal()
    end

    --[[
      Validates and builds a screenplay chain of messages to be run in
        a scene. See demo map for examples. I recommend using it together with a builder function so that it is
        invoked lazily upon scene start, when all actors are present. So, you can keep your screenplays in separate
        scripts like below:
            ScreenplayFactory:saveBuilder('myScreenplayName', function()  --'myScreenplayName' should be unique within a map
                actorFootman = ScreenplayFactory.createActor(udg_footman, 'Footman Valdeck') -- created actors can be kept either locally within each script, or saved to some global variables
                actorOrc = ScreenplayFactory.createActor(udg_orc)
                return ScreenplaySystem.chain:buildFromObject({
                [1] = {
                    text = "Lorem ipsum...",
                    actor = actorFootman, --
                }),
                [2] = ...
            })
    ]]
    ---buildFromObject
    ---@param buildFrom array of ScreenplaySystem.item
    ---@return ScreenplaySystem.chain
    function ScreenplaySystem.chain:buildFromObject(buildFrom)
        assert(buildFrom and buildFrom[1], "error: ScreenplaySystem.chain:buildFromObject is missing an index-value table argument.")
        local newChain = ScreenplaySystem.chain:new()

        for itemIndex, item in pairs(buildFrom) do
            printDebug("building pair " .. tostring(itemIndex) .. ": " .. tostring(item.text) .. ", " .. tostring(item.choices))
            assert(item.text or item.choices, "error in item " .. itemIndex .. ": text or choices must not be empty")
            assert(item.actor, "error in item " .. itemIndex .. ": actor must not be empty")
            assert(item.actor.unit or (item.actor.unitType and item.actor.player), "error in item " .. itemIndex .. ": actor must have either a unit, or unit type and player")
            newChain[itemIndex] = ScreenplaySystem.item:new()
            if item.text then
                newChain[itemIndex].text = item.text
            end
            newChain[itemIndex].actor = item.actor
            if item.emotion then
                newChain[itemIndex].emotion = item.emotion
            end
            if item.anim then
                newChain[itemIndex].anim = item.anim
            end
            if item.sound then
                newChain[itemIndex].sound = item.sound
            end
            if item.delayText then
                newChain[itemIndex].delayText = item.delayText
            else
                newChain[itemIndex].delayText = 0
            end
            if item.delayNextItem then
                newChain[itemIndex].delayNextItem = item.delayNextItem
            else
                newChain[itemIndex].delayNextItem = 0
            end
            if item.func then
                newChain[itemIndex].func = item.func
            end
            if item.trigger then
                newChain[itemIndex].trigger = item.trigger
            end
            if item.thenGoTo then
                newChain[itemIndex].thenGoTo = item.thenGoTo
            end
            if not (item.thenEndScene == nil) then
                newChain[itemIndex].thenEndScene = item.thenEndScene
            end
            if item.thenGoToFunc then
                newChain[itemIndex].thenGoToFunc = item.thenGoToFunc
            end
            if not (item.skippable == nil) then
                newChain[itemIndex].skippable = item.skippable
            end
            if not (item.interruptExisting == nil) then
                newChain[itemIndex].interruptExisting = item.interruptExisting
            else
                newChain[itemIndex].interruptExisting = false
            end
            if not (item.fadeOutDuration == nil) then
                newChain[itemIndex].fadeOutDuration = item.fadeOutDuration
            end
            if not (item.fadeInDuration == nil) then
                newChain[itemIndex].fadeInDuration = item.fadeInDuration
            end
            if not (item.skipTimers == nil) then
                newChain[itemIndex].skipTimers = item.skipTimers
            end
            if not (item.stopOnRewind == nil) then
                newChain[itemIndex].stopOnRewind = item.stopOnRewind
            end
            if item.onRewindGoTo ~= nil and item.onRewindGoTo > 0 then
                newChain[itemIndex].onRewindGoTo = item.onRewindGoTo
            end
            if item.choices then
                newChain[itemIndex].choices = {}
                for choiceIndex, choiceBuildFrom in pairs(item.choices) do
                    printDebug("building choice " .. choiceIndex .. ": " .. choiceBuildFrom.text .. ", visible: " .. tostring(choiceBuildFrom.visible))
                    local choice = ScreenplaySystem.choice:new()
                    choice.text = choiceBuildFrom.text
                    choice.onChoice = choiceBuildFrom.onChoice
                    if not (choiceBuildFrom.visible == nil) then
                        choice.visible = choiceBuildFrom.visible
                    else
                        choice.visible = true
                    end
                    if not (choiceBuildFrom.visibleFunc == nil) then
                        choice.visibleFunc = choiceBuildFrom.visibleFunc
                    end
                    choice.chosen = false
                    newChain[itemIndex].choices[choiceIndex] = choice
                end
            end
        end
        return newChain
    end

    -- @item  = add this item as the next item in the chain.
    -- @index = [optional] insert @item into this index location instead.
    function ScreenplaySystem.chain:add(item, index)
        if index then
            table.insert(self, index, item)
        else
            self[#self + 1] = item
        end
    end


    -- @item = remove this item from the chain (accepts item object or the index location in the chain).
    function ScreenplaySystem.chain:remove(item)
        -- remove by index:
        if type(item) == "number" then
            table.remove(self, item)
            -- remove by value:
        else
            for i, v in ipairs(self) do
                if v == item then
                    table.remove(self, i)
                end
            end
        end
    end

    function ScreenplaySystem.chain:isValidIndex(index)
        return index > 0 and index <= SimpleUtils.tableLength(self)
    end

    onInit(function()
        ScreenplaySystem:init()
    end)
end

ScreenplayFactory = {
    screenplayBuilders = {}
}

do

    --- Creates an actor to be used in screenplay dialog lines. You can either create your actors every time in the beginning
    --- of a screenplay or create them all on map init and store in some global variables
    ---@param unit unit
    ---@param customName string
    ---@return ScreenplaySystem.actor
    function ScreenplayFactory.createActor(unit, customName)
        local actor = ScreenplaySystem.actor:new()
        actor.unit = unit
        if customName then
            actor.name = customName
        else
            actor.name = GetUnitName(unit)
        end
        return actor
    end

    --- Alternatively if you don't want to create a unit, you can also assign unit type and player to an actor, optionally with custom name
    --- Of course, with such actors camera panning, unit flashes and animations are not available
    ---@param unitType number
    ---@param player player
    ---@param customName string
    ---@return ScreenplaySystem.actor
    function ScreenplayFactory.createActorFromType(unitType, player, customName)
        local actor = ScreenplaySystem.actor:new()
        actor.unitType = unitType
        actor.player = player
        if customName then
            actor.name = customName
        else
            actor.name = GetObjectName(unitType)
        end
        return actor
    end

    local function printDebug(msg)
        if ScreenplaySystem.debug then
            print(msg)
        end
    end

    --- Stores a screenplay builder function under a given name. The function will be called when starting a scene by name.
    ---@param name string
    ---@param screenplayBuilderFunction function
    function ScreenplayFactory:saveBuilder(name, screenplayBuilderFunction)
        if (ScreenplayFactory.screenplayBuilders[name]) then
            SimpleUtils.printWarn("Duplicate screenplay key " .. name .. ", previous one will be overriden")
        end
        printDebug("Saving screenplay builder " .. tostring(name))
        ScreenplayFactory.screenplayBuilders[name] = screenplayBuilderFunction
    end

    --- Stores a screenplay builder function under a given name. The function will be called when starting a scene by name.
    ---@param name string
    ---@param screenplayBuilderFunction function
    function ScreenplayFactory:saveBuilderForMessageChain(name, messageChainFunction)
        return self:saveBuilder(name, function()
            return ScreenplaySystem.chain:buildFromObject(messageChainFunction())
        end)
    end
end

function createActors()
    actorFootman = ScreenplayFactory.createActor(udg_footman, 'Footman Valdeck')
    actorDwarf = ScreenplayFactory.createActor(udg_dwarf, 'Rifleman Isgrinn')
    actorElf = ScreenplayFactory.createActor(udg_elf, "Elven Priest with Stick in his Holy Arse")
    actorGrunt = ScreenplayFactory.createActor(udg_grunt, 'Bored Grunt')
    actorPeon = ScreenplayFactory.createActor(udg_peon, 'Fearful Peon')
end

ScreenplayFactory:saveBuilderForMessageChain("intro", function()
    return {
        [1] = {
            text = "Ahhh, the world's spinning! What did this fucking dwarf pour me!? Gotta find some beer.",
            actor = actorFootman,
        },
    }
end)

ScreenplayFactory:saveBuilderForMessageChain("dwarf", function()
    return {
        [1] = {
            text = "Hey, lad. Good time drinkin' with ya! Until the next time!",
            actor = actorDwarf,
        },
        [2] = {
            text = "Yeeeeah, s-s-s-sure thing, pal!",
            actor = actorFootman,
        },
    }
end)

ScreenplayFactory:saveBuilderForMessageChain('orc', function()
    local sounds = {}
    sounds.grunt01      = gg_snd_GruntWhat2
    sounds.footman01    = gg_snd_FootmanWarcry1

    return {
        [1] = {
            text = "|cffff0000Hey, orc!|r",
            actor = actorFootman,
        },
        [2] = {
            text = "Whazzup, hummie?",
            actor = actorGrunt,
            anim = "stand two",
            sound = sounds.grunt01,
        },
        [3] = {
            actor = actorFootman,
            choices = {
                [1] = {
                    text = "I will fuck you up!",
                    onChoice = function()
                        ScreenplaySystem:currentItem().choices[1].visible = false
                        ScreenplaySystem:goTo(4)
                    end
                },
                [2] = {
                    text = "Show me your wares.",
                    onChoice = function()
                        ScreenplaySystem:goTo(7)
                    end
                },
                [3] = {
                    text = "Where can I get drunk here?",
                    onChoice = function()
                        ScreenplaySystem:currentItem().choices[3].visible = false
                        ScreenplaySystem:currentItem().choices[4].visible = true
                        ScreenplaySystem:goTo(9)
                    end
                },
                [4] = {
                    text = "You sure you have no alcohol left?",
                    visible = false,
                    onChoice = function()
                        ScreenplaySystem:currentItem().choices[4].visible = false
                        ScreenplaySystem:goTo(11)
                    end
                },
                [5] = {
                    text = "I have to go.",
                    onChoice = function()
                        ScreenplaySystem:goTo(19)
                    end
                }
            }
        },
        [4] = {
            text = "I will fuck you up, for Lordaeron and the King!",
            actor = actorFootman,
            sound = sounds.footman01
        },
        [5] = {
            text = "Waaaaahaaaaa!",
            actor = actorPeon,
            trigger = gg_trg_Scene_Orc_Peon_Escape
        },
        [6] = {
            text = "Go home, hummie, you're drunk.",
            actor = actorGrunt,
            thenGoTo = 3
        },
        [7] = {
            text = "Show me your wares!",
            actor = actorFootman,
            thenGoToFunc = function()
                if sceneOrcAlreadyAskedAboutWares == true
                then return 18
                else
                    sceneOrcAlreadyAskedAboutWares = true
                    return 8
                end
            end
        },
        [8] = {
            text = "Do I look like a merchant, hummie?!",
            actor = actorGrunt,
            thenGoTo = 3
        },
        [9] = {
            text = "Where can I get drunk here?",
            actor = actorFootman,
        },
        [10] = {
            text = "Sorry, drinking is Ur-Gora, we burned the last tavern in town yesterday. Besides, you're already drunk.",
            actor = actorGrunt,
            thenGoTo = 3,
        },
        [11] = {
            text = "You sure you have no alcohol left?",
            actor = actorFootman,
        },
        [12] = {
            text = "Ehhh, actually, I think I kept one last keg of beer. It will be yours in exchange for the location of your camp.",
            actor = actorGrunt,
        },
        [13] = {
            actor = actorFootman,
            choices = {
                [1] = {
                    text = "I'll take you there, just gimme my beer!",
                    onChoice = function()
                        ScreenplaySystem:goTo(14)
                    end
                },
                [2] = {
                    text = "Forget it, Horde filth!",
                    onChoice = function()
                        ScreenplaySystem:goTo(16)
                    end
                },
            }
        },
        [14] = {
            text = "I'll take you there, just gimme my beer!",
            actor = actorFootman,
        },
        [15] = {
            text = "Okay. Let's go.",
            actor = actorGrunt,
            thenEndScene = true,
            trigger = gg_trg_Scene_Orc_Follow,
        },
        [16] = {
            text = "Forget it, Horde filth!",
            actor = actorFootman,
        },
        [17] = {
            text = "Eh, it was worth a try",
            actor = actorGrunt,
            thenGoTo = 3
        },
        [18] = {
            text = "Told you, dumbass, I'm not a fucking merchant. Trading is Ur-Gora.",
            actor = actorGrunt,
            thenGoTo = 3,
        },
        [19] = {
            text = "I have to go.",
            actor = actorFootman,
        },
        [20] = {
            text = "Yeah, yeah, whatever.",
            actor = actorGrunt,
        },
    }
end)

ScreenplayFactory:saveBuilderForMessageChain("elf", function()
    --an example of an actor without a unit
    local narratorUnitType = FourCC('nmed')
    local narratorPlayer = Player(1)
    local actorNarrator = ScreenplayFactory.createActorFromType(narratorUnitType, narratorPlayer, "Narrator")

    return {
        [1] = {
            text = "Soon, in his epic quest our mighty hero stood upon a High Elven sanctuary...",
            actor = actorNarrator,
            func = function()
                ScreenplayUtils.interpolateCamera(gg_cam_elf01a, gg_cam_elf01b, 90)
            end,
        },
        [2] = {
            text = "Greeting, noble warrior. I am a priest and can enlighten you so you can fully embrace the Holy Light on your path. Holy light blablala holy light blablala holy light blablala holy light blabla (you may wanna skip that or check if scrolling works) blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala holy light blablala ",
            actor = actorElf,
        },
        [3] = {
            text = "Ssssscrew this. Got anything to drink, longear?",
            actor = actorFootman,
        },
        [4] = {
            text = "I do not think you should drink anymore. Allow me to cast Dispel on you so that you are sober again.",
            actor = actorElf,
        },
        [5] = {
            text = "What!? No, no, don't you dare, inhuman beast!",
            actor = actorFootman,
            trigger = gg_trg_Scene_Elf_Cast_Dispel,
            fadeOutDuration = 1.0,
        },
        [6] = {
            text = "Was this the end of our hero's journey, you might ask? Well...",
            actor = actorNarrator,
        },
        [7] = {
            fadeInDuration = 1.0,
            delayText = 2.0,
            text = "Hahahahaha, your foul magic doesn't work on me, inhuman! I'm still drunk! And I wanna drink even more!",
            actor = actorFootman,
            fadeOutDuration = 2.0,
            func = function()
                ScreenplayUtils.interpolateCamera(gg_cam_elf02a, gg_cam_elf02b, 30)
            end
        },
    }
end)

ScreenplayFactory:saveBuilderForMessageChain("elfBeer", function()
    return {
        [1] = {
            text = "Heh, I just knew this priest wouldn't speak this Holy Light bullcrap sober.",
            actor = actorFootman,
        },
    }
end)

ScreenplayFactory:saveBuilderForMessageChain("orcBeer", function()
    return {
        [1] = {
            text = "Ahh, there you have a camp, hummies. Gotta tell the warchief. Here's your beer, loser. Enjoy it... while you can, hehehe.",
            actor = actorGrunt,
        },
    }
end)

ScreenplayFactory:saveBuilderForMessageChain('ghost', function()
    --an example of an actor without a unit
    local ghostUnitType = FourCC('ngh1')
    local ghostPlayer = Player(2)
    local actorGhost = ScreenplayFactory.createActorFromType(ghostUnitType, ghostPlayer, "Forest Ghost")
    
    return {
        [1] = {
            text = "Who dares disrupt my slumber!?",
            actor = actorGhost,
        },
        [2] = {
            text = "What's that? There's nobody here.",
            actor = actorFootman,
        },
        [3] = {
            text = "I am the forest ghost! You can't see me! Tremble before me, mortal!",
            actor = actorGhost,
        },
        [4] = {
            text = "Screw this, I'm out.",
            actor = actorFootman,
        },
    }
end)