API doc object oriented

Client->Debugger communication

struct cmd_base {
    enum {
        invalid = 0,
        getVersionInfo = 1,
        addBreakpoint = 2,
        delBreakpoint = 3,
        BPContinue = 4,//Tell's breakpoint to leave breakState
        MonitorDump = 5, //Dump's all Monitors
        setHookEnable = 6,
        getVariable = 7,
        getCurrentCode = 8, //While in breakState returns full preproced code of last Instructions script file
        getAllScriptCommands = 9,
        getAvailableVariables = 10,
        haltNow = 11 //Makes debugger break on next possible instruction
    } command;
}

struct cmd_getVersionInfo : cmd_base {}; //returns versionInfo(1)

struct cmd_addBreakpoint : cmd_base {
    struct {
        string filename; //full path to scriptfile. Example "\\x\\cba\\addons\\common\\fnc_currentUnit.sqf"
        number line; //line of the script
        [[optional]] string label; //a optional name for this breakpoint. Currently only used for LogCallstack action
        [[optional]] breakpoint_condition condition;
        breakpoint_action action;
    } data;
};

struct cmd_delBreakpoint : cmd_base {
    struct {
        string filename; //full path to scriptfile. Example "\\x\\cba\\addons\\common\\fnc_currentUnit.sqf"
        number line; //line of the script
    } data;
};

struct cmd_BPContinue : cmd_base { //returns <ContinueExecution> and might immediately after return a <halt_step>
    struct {
        enum {
            continue = 0,
            stepInto = 1,
            stepOver = 2,
            stepOut = 3
        } StepType;
    } data;
};


//Dumps all Monitors to "P:\\Monitor_knownScriptFiles.json" Which should contain all known script files. This is a debug command.. A debugger debug command...
struct cmd_MonitorDump : cmd_base {};

//Enables/Disables the "hook". Was a special feature to "disable" the debugger to allow all scripts to run at full speed without the debugger interfering. Currently not used.
struct cmd_setHookEnable : cmd_base {};

struct cmd_getVariable : cmd_base { //returns <VariableReturn>
    struct {
        array<string> name; //ARRAY of Strings. List of variable names to retrieve. Might also be a local variable.
        bitset variableScope {
            invalid = 0,
            callstack = 1,
            local = 2,
            missionNamespace = 4,
            uiNamespace = 8,
            profileNamespace = 16,
            parsingNamespace = 32
        } scope; //a bitset of scopes to check.
    } data;
};


//This only works when currently halting. It traverses the entire callstack to find the file and returns it's content
struct cmd_getCurrentCode : cmd_base { //returns a BARE string of the content
    string file; //Filename of the file.
};

//returns all script commands in the format: https://gist.github.com/dedmen/75ae1319d9a958c6492e44b734fdb609
struct cmd_getAllScriptCommands : cmd_base {}; 

struct breakpoint_condition {
    enum {
        code = 1
    } type; //1: code
    [[if type == 1]] string code; //this contains a SQF script that will be executed and should return true/false
};

struct breakpoint_action {
    enum {
        ExecCode = 1,
        Halt = 2,
        LogCallstack = 3
    } type;

    [[if type == 1]] string code; //this contains a SQF script that will be executed when the breakpoint is hit.
    [[if type == 3]] string basePath ; //this contains the path to a file where the log will be written to. The filename will be <basePath><label><hitcount>.json so you should end the basePath with a \. If you set this to "send" it instead sends a BreakpointLog event with the callstack attached.
};

Debugger->Client communication

struct cmd_base {
    enum {
        invalid = 0,
        versionInfo = 1,
        halt_breakpoint = 2,
        halt_step = 3,
        halt_error = 4,
        halt_scriptAssert = 5,
        halt_scriptHalt = 6,
        halt_placeholder = 7,
        ContinueExecution = 8,
        VariableReturn = 9, //returning from getVariable
        AvailableVariablesReturn = 10, //returning from getAvailableVariables
        BreakpointLog = 11, //Breakpoint action LogCallstack has hit and is transmitting the stack
        LogMessage //A log message from the game, for example from echo script command
    } command;
}



struct cmd_versionInfo : cmd_base {
    number build; //buildnumber of the debugger
    string version; //versionstring of the debugger
    string arch; //The string "X64" or "X86"
    string gameType; //"game type" of the Arma binary. Release/performance/profiling/diag
    string gameVersion; //version of the Arma binary. "1.82.144709"
    struct { //"Hook Integrity" structure. Contains information about whether the debugger correctly initialized.
        bool "SvmCon"; //HI.__scriptVMConstructor
        bool "SvmSimSt"; //HI.__scriptVMSimulateStart
        bool "SvmSimEn"; //HI.__scriptVMSimulateEnd
        bool "InstrBP"; //HI.__instructionBreakpoint
        bool "WSim"; //HI.__worldSimulate
        bool "WMEVS"; //HI.__worldMissionEventStart
        bool "WMEVE"; //HI.__worldMissionEventEnd
        bool "ScrErr"; //HI.__onScriptError
        bool "PreDef"; //HI.scriptPreprocDefine
        bool "PreCon"; //HI.scriptPreprocConstr
        bool "ScrAass"; //HI.scriptAssert
        bool "ScrHalt"; //HI.scriptHalt
        bool "Alive"; //HI.engineAlive
        bool "EnMouse"; //HI.enableMouse
    } HI;
};

struct halt_base : cmd_base {
    [[optional]] Array<CallstackItem> callstack; //If it doesn't exist, just assume empty
};


//The debugger halted because of a set breakpoint (https://gist.github.com/dedmen/747a8d2eb7c0e2a82b90c60a810a2987) 
struct cmd_halt_breakpoint : halt_base {
    [[optional]] game_instruction instruction;
    //This should definitely have a callstack
};

//The debugger halted because you are stepping 
struct cmd_halt_step : halt_base {
    [[optional]] game_instruction instruction;
    //This should definitely have a callstack
};

//The debugger halted because of a script error 
struct cmd_halt_error : halt_base {
    struct {
        array<number> fileOffset; //sourceline, offset from start of file, offset from start of line
        enum {
            //https://github.com/dedmen/ArmaDebugEngine/blob/e0025310a2c7ca795e400ef460e9975ba3ec5268/BIDebugEngine/BIDebugEngine/RVClasses.cpp#L150
        } type;

        string message; //error message from the game (like in RPT)
        string filename; //error file (like in RPT)
        string content; //the full content of the script file
    } error;
};


//The debugger halted because a https://community.bistudio.com/wiki/assert failed 
struct cmd_halt_scriptAssert : halt_base {
    //This stuff only exists if there is no instruction. Probably a bug though, might fix someday.
    struct {
        array<number> fileOffset; //sourceline, offset from start of file, offset from start of line
        string filename;
        string content; // the full content of the script file
    } halt;
};

/7The debugger halted because a https://community.bistudio.com/wiki/halt was executed 
struct cmd_halt_scriptHalt : cmd_halt_scriptAssert {}; //Same

//We have left the halt state and the game is now executing again.
struct cmd_ContinueExecution : cmd_base {};

//Answer to getVariable request. 
struct cmd_VariableReturn {
    struct {
        string type; //"void"/...
        string name; //Name of the variable
        variableScope ns; //The namespace enum. (Only if variable was found) See <variableScope> from client->debugger communication
        stuff value; //if type is array then this is an array of "values". If it's string then just string. If it's code then the compact(removes empty newlines) string version of the code.
    } variable;
};
 
struct cmd_LogMessage {
    string message;
};


struct game_instruction {
    string type;
    string name;
    string filename;
    array<number> fileOffset; //sourceline, offset from start of file, offset from start of line
};

//See https://gist.github.com/dedmen/747a8d2eb7c0e2a82b90c60a810a2987#file-bp_cba_currentunit-json-L1326
struct Variable {
    string type;
    [[if type == "array"]] array<game_value> value;
    [[if type != "array"]] string value;
};


struct CallStackItem {
    string type; //"class CallStackItemData"/"class CallStackItemSimple" (These strings might be changed later in development) Look below for Callstack Item types.halted on. game_instruction type


    //local variables of that scope https://gist.github.com/dedmen/747a8d2eb7c0e2a82b90c60a810a2987#file-bp_cba_currentunit-json-L1326
    [[may_be_null]] map<string, Variable> variables; //will be null when empty
};

struct CallStackItemSimple : CallStackItem {
    string fileName; //Filepath to source file of contained code.
    string contentSample; //First 100 characters of code.
    number ip; //Current Instruction pointer
    game_instruction lastInstruction; //Current executing instruction
};

struct CallStackItemData : CallStackItem {
    string fileName; //Filepath to source file of contained code.
    string contentSample; //First 100 characters of code.
    number ip; //Current Instruction pointer
    game_instruction lastInstruction //Current executing instruction
    array<game_instruction> compiled; //list of all script instructions of that scope. ip is the 1-based index of this array of the current instruction https://gist.github.com/dedmen/747a8d2eb7c0e2a82b90c60a810a2987#file-bp_cba_currentunit-json-L12
    bool final; //whether code was compileFinal'ed
};

// (https://community.bistudio.com/wiki/forEach)
struct CallStackItemArrayForEach : CallStackItem {
    number forEachIndex; //Current index the loop is at.
};

// (https://community.bistudio.com/wiki/apply)
struct CallStackItemApply : CallStackItem {
    number forEachIndex; //Current index the loop is at.
};

// (https://community.bistudio.com/wiki/select)
struct CallStackItemConditionSelect : CallStackItem {
    number forEachIndex; //Current index the loop is at.
};

// (https://community.bistudio.com/wiki/findIf)
struct CallStackItemArrayFindCond : CallStackItem {
    forEachIndex Number. Current index the loop is at.
};

// (https://community.bistudio.com/wiki/for non-array variant)
struct CallStackItemForBASIC : CallStackItem {
    string varName;
    number varValue;
    number to;
    number step;
};