-
Notifications
You must be signed in to change notification settings - Fork 10
API doc object oriented
Dedmen Miller edited this page Feb 20, 2020
·
5 revisions
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;
};