载入中...
搜索中...
未找到

Script + frame debugger: pause/step, breakpoints, watches. 更多...

#include <Debugger.hpp>

Public 类型

using BreakpointEventFn = std::function< void(int id, const std::string &source, int line, bool verified)>
 Called once when a breakpoint line is first observed by the line hook.
 
using PumpFn = std::function< void()>
 

Public 成员函数

 Debugger (const Debugger &)=delete
 
Debugger & operator= (const Debugger &)=delete
 
void attach (HSQUIRRELVM vm)
 
void detach ()
 
bool isAttached () const
 
HSQUIRRELVM vm () const
 
void pause (PauseReason reason=PauseReason::PauseKey)
 Frame-level pause without a script site (PauseKey clears pauseLocation). For Exception / Snapshot, prefer pauseAt so DAP/MCP keep a source location.
 
void pauseAt (PauseReason reason, SourceLoc loc)
 Pause and record the script site (copied; Observed until the next pause/resume). Thread: VM / game loop that owns waitWhilePaused.
 
void resume ()
 
void stepFrame ()
 
void stepFrames (int count)
 Run count game frames then pause. Each frame is consumed by shouldRunUpdate / notifyFrameDone on the game loop.
 
void stepInto ()
 Enter calls: stop on the next script line at any depth.
 
void stepOver ()
 Skip calls: stop on the next line at ≤ current stack depth.
 
void stepOut ()
 Finish current function: stop when stack depth drops.
 
void stepLine ()
 Alias for stepInto (historical name).
 
void step ()
 Convenience: script stepOver when mid-hook; otherwise one game frame. Prefer stepInto/stepOver/stepOut from DAP / UI.
 
bool isPaused () const
 
RunMode mode () const
 
PauseReason lastPauseReason () const
 
const SourceLoc & pauseLocation () const
 
int scriptStackDepth () const
 Current Squirrel call depth (1 = topmost script frame). 0 if none.
 
bool shouldRunUpdate ()
 Frame loop: true ⇒ call eve_update this frame. Consumes StepFrame.
 
void notifyFrameDone ()
 After a frame when StepFrame was active → return to Paused.
 
void setCallGraph (CallGraph *graph)
 Use DevTool's CallGraph for stack names (same object the slicer sees). Pass nullptr to record calls on the debugger's own graph (unit tests).
 
void setVirtualSource (std::string source, std::string text)
 In-memory script text used to name anonymous name = function() bindings when the hook source is a compile buffer, not a file.
 
std::string onCall (SourceLoc loc)
 Squirrel call debug hook ('c'). Records a frame on the active CallGraph.
 
void onReturn (const SourceLoc &loc)
 Squirrel return debug hook ('r'). Pops the active CallGraph frame.
 
bool onScriptLine (const SourceLoc &loc)
 Called from Squirrel line debug hook. Returns true if execution should block (breakpoint / step).
 
void waitWhilePaused (const std::function< void()> &pump={})
 Block until resume/step/detach (processes external poll callbacks).
 
int setBreakpoint (std::string source, int line, bool enabled=true, std::string condition={})
 Add or update a line breakpoint. A later call with the same source+line replaces enabled and condition (empty condition clears a previous one).
 
bool clearBreakpoint (std::string source, int line)
 
void clearBreakpoints (const std::string &source={})
 
bool setBreakpointEnabled (int id, bool enabled)
 Enable or disable by id.
 
std::vector< Breakpoint > breakpoints () const
 
bool hasBreakpoint (const std::string &source, int line) const
 True if a breakpoint is registered at source+line. Ignores the skip-all master switch and the per-breakpoint enabled flag.
 
void addWatch (std::string expression)
 
bool removeWatch (const std::string &expression)
 
void clearWatches ()
 
std::vector< WatchEntry > watches () const
 
void refreshWatches ()
 Re-evaluate all watches against current VM (paused preferred).
 
VariableInfo evaluate (const std::string &expression, int frameLevel=0) const
 Evaluate an expression in the given frame's scope. Understands plain names, a.b paths, and full Squirrel expressions (arithmetic / calls / indexing) compiled against a locals+roottable env.
 
std::vector< VariableInfo > locals (int stackLevel=0) const
 Locals of the given call-stack level (0 = current script frame).
 
std::vector< VariableInfo > globals () const
 Root-table slots (globals).
 
std::vector< VariableInfo > containerChildren (VarKind kind, int frame, const std::vector< std::string > &path) const
 Children of a container variable. path is the key chain that locates the container from its root (locals frame or roottable). Empty path lists the root entries themselves.
 
std::vector< StackFrameInfo > stackTrace (int maxFrames=32) const
 
void setBreakOnError (bool on)
 Break on script errors (Godot "Break on Error"). Default off.
 
bool breakOnError () const
 
void setBreakpointsEnabled (bool on)
 Master switch for all breakpoints ("skip all breakpoints").
 
bool breakpointsEnabled () const
 
void setBreakpointEventFn (BreakpointEventFn fn)
 
void setPump (PumpFn pump)
 

静态 Public 成员函数

static Debugger & instance ()
 
static std::string normalizeSource (std::string source)
 Normalize source paths for breakpoint matching (basename fallback).
 
static std::string sourceBasename (const std::string &source)
 Basename of a normalized path (empty-safe).
 
static bool sourcesMatch (const std::string &a, const std::string &b)
 True when two source paths refer to the same script file. Matches exact path, or one path as a directory-bounded suffix of the other. A bare filename (no /) also matches any path with the same basename. Two directory-qualified paths that only share a basename do not match.
 

详细描述

Script + frame debugger: pause/step, breakpoints, watches.

Frame pause: game loop skips eve_update (see load.nut + shouldRunUpdate). Script pause: Squirrel line hook blocks until resume/step (waitWhilePaused).

Stepping (script, when stopped on a line):

  • stepInto — stop on the next line event (enter calls)
  • stepOver — stop on the next line at the same / outer stack depth
  • stepOut — stop after returning to the caller

在文件 Debugger.hpp 第 86 行定义.

成员类型定义说明

◆ BreakpointEventFn

using eve::dev::Debugger::BreakpointEventFn = std::function<void(int id, const std::string& source, int line, bool verified)>

Called once when a breakpoint line is first observed by the line hook.

在文件 Debugger.hpp 第 232 行定义.

◆ PumpFn

using eve::dev::Debugger::PumpFn = std::function<void()>

在文件 Debugger.hpp 第 236 行定义.

构造及析构函数说明

◆ Debugger()

eve::dev::Debugger::Debugger ( const Debugger &  )
delete

成员函数说明

◆ addWatch()

void eve::dev::Debugger::addWatch ( std::string  expression)

在文件 Debugger.cpp 第 869 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ attach()

void eve::dev::Debugger::attach ( HSQUIRRELVM  vm)

在文件 Debugger.cpp 第 440 行定义.

引用了 eve::dev::CallGraph::clear(), eve::dev::None, eve::dev::Running , 以及 vm().

被这些函数引用 eve::dev::DevTool::attach().

◆ breakOnError()

bool eve::dev::Debugger::breakOnError ( ) const
inline

在文件 Debugger.hpp 第 227 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ breakpoints()

std::vector< Breakpoint > eve::dev::Debugger::breakpoints ( ) const

在文件 Debugger.cpp 第 859 行定义.

◆ breakpointsEnabled()

bool eve::dev::Debugger::breakpointsEnabled ( ) const
inline

在文件 Debugger.hpp 第 230 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ clearBreakpoint()

bool eve::dev::Debugger::clearBreakpoint ( std::string  source,
int  line 
)

在文件 Debugger.cpp 第 827 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ clearBreakpoints()

void eve::dev::Debugger::clearBreakpoints ( const std::string &  source = {})

在文件 Debugger.cpp 第 838 行定义.

引用了 source.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ clearWatches()

void eve::dev::Debugger::clearWatches ( )

在文件 Debugger.cpp 第 886 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ containerChildren()

std::vector< VariableInfo > eve::dev::Debugger::containerChildren ( VarKind  kind,
int  frame,
const std::vector< std::string > &  path 
) const

Children of a container variable. path is the key chain that locates the container from its root (locals frame or roottable). Empty path lists the root entries themselves.

在文件 Debugger.cpp 第 1087 行定义.

引用了 eve::dev::Globals, globals(), kind, eve::dev::Locals, locals(), path, top , 以及 vm().

◆ detach()

void eve::dev::Debugger::detach ( )

在文件 Debugger.cpp 第 451 行定义.

引用了 eve::dev::CallGraph::clear(), eve::dev::None , 以及 eve::dev::Running.

被这些函数引用 eve::dev::DevTool::detach().

◆ evaluate()

VariableInfo eve::dev::Debugger::evaluate ( const std::string &  expression,
int  frameLevel = 0 
) const

Evaluate an expression in the given frame's scope. Understands plain names, a.b paths, and full Squirrel expressions (arithmetic / calls / indexing) compiled against a locals+roottable env.

在文件 Debugger.cpp 第 1106 行定义.

引用了 eve::script::captureCompileError(), eve::script::ScriptErrorContext::empty(), eve::script::formatScriptError(), info, level, n, eve::dev::VariableInfo::name, eve::script::takeLastScriptError(), top , 以及 vm().

被这些函数引用 eve::dev::DevTool::exposeScriptApi() , 以及 refreshWatches().

◆ globals()

std::vector< VariableInfo > eve::dev::Debugger::globals ( ) const

Root-table slots (globals).

在文件 Debugger.cpp 第 1035 行定义.

引用了 top , 以及 vm().

被这些函数引用 containerChildren().

◆ hasBreakpoint()

bool eve::dev::Debugger::hasBreakpoint ( const std::string &  source,
int  line 
) const

True if a breakpoint is registered at source+line. Ignores the skip-all master switch and the per-breakpoint enabled flag.

在文件 Debugger.cpp 第 864 行定义.

引用了 line , 以及 source.

◆ instance()

◆ isAttached()

bool eve::dev::Debugger::isAttached ( ) const
inline

在文件 Debugger.hpp 第 95 行定义.

◆ isPaused()

bool eve::dev::Debugger::isPaused ( ) const
inline

在文件 Debugger.hpp 第 133 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ lastPauseReason()

PauseReason eve::dev::Debugger::lastPauseReason ( ) const
inline

在文件 Debugger.hpp 第 135 行定义.

◆ locals()

std::vector< VariableInfo > eve::dev::Debugger::locals ( int  stackLevel = 0) const

Locals of the given call-stack level (0 = current script frame).

在文件 Debugger.cpp 第 1015 行定义.

引用了 info, level, n, name, top , 以及 vm().

被这些函数引用 containerChildren().

◆ mode()

RunMode eve::dev::Debugger::mode ( ) const
inline

在文件 Debugger.hpp 第 134 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ normalizeSource()

std::string eve::dev::Debugger::normalizeSource ( std::string  source)
static

Normalize source paths for breakpoint matching (basename fallback).

在文件 Debugger.cpp 第 392 行定义.

引用了 c , 以及 source.

被这些函数引用 eve::dev::DebugAdapter::registerSource(), setBreakpoint(), setVirtualSource(), sourceBasename() , 以及 sourcesMatch().

◆ notifyFrameDone()

void eve::dev::Debugger::notifyFrameDone ( )

After a frame when StepFrame was active → return to Paused.

在文件 Debugger.cpp 第 655 行定义.

引用了 eve::dev::Paused, eve::dev::Step, eve::dev::StepFrame , 以及 stepFrame().

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ onCall()

std::string eve::dev::Debugger::onCall ( SourceLoc  loc)

Squirrel call debug hook ('c'). Records a frame on the active CallGraph.

参数
locHook location (function name may be unknown for anonymous closures).
返回
Display name stored on the new frame (binding name when the closure is anonymous).

在文件 Debugger.cpp 第 500 行定义.

引用了 eve::dev::SourceLoc::function, name , 以及 eve::dev::CallGraph::onCall().

被这些函数引用 eve::dev::DevTool::handleDebugEvent().

◆ onReturn()

void eve::dev::Debugger::onReturn ( const SourceLoc &  loc)

Squirrel return debug hook ('r'). Pops the active CallGraph frame.

参数
locHook location of the returning function.

在文件 Debugger.cpp 第 507 行定义.

引用了 eve::dev::SourceLoc::function , 以及 eve::dev::CallGraph::onReturn().

被这些函数引用 eve::dev::DevTool::handleDebugEvent().

◆ onScriptLine()

bool eve::dev::Debugger::onScriptLine ( const SourceLoc &  loc)

◆ operator=()

Debugger & eve::dev::Debugger::operator= ( const Debugger &  )
delete

◆ pause()

void eve::dev::Debugger::pause ( PauseReason  reason = PauseReason::PauseKey)

Frame-level pause without a script site (PauseKey clears pauseLocation). For Exception / Snapshot, prefer pauseAt so DAP/MCP keep a source location.

参数
reasonPause cause stored in lastPauseReason().

在文件 Debugger.cpp 第 553 行定义.

引用了 pauseAt() , 以及 eve::dev::PauseKey.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ pauseAt()

void eve::dev::Debugger::pauseAt ( PauseReason  reason,
SourceLoc  loc 
)

Pause and record the script site (copied; Observed until the next pause/resume). Thread: VM / game loop that owns waitWhilePaused.

参数
reasonPause cause (Exception, Snapshot, Breakpoint, …).
locSource location shown to DAP/MCP; empty clears pauseLocation.

在文件 Debugger.cpp 第 564 行定义.

引用了 eve::dev::Paused.

被这些函数引用 eve::dev::DevTool::exposeScriptApi(), eve::dev::DevTool::notifyError() , 以及 pause().

◆ pauseLocation()

const SourceLoc & eve::dev::Debugger::pauseLocation ( ) const
inline

在文件 Debugger.hpp 第 136 行定义.

◆ refreshWatches()

void eve::dev::Debugger::refreshWatches ( )

Re-evaluate all watches against current VM (paused preferred).

在文件 Debugger.cpp 第 897 行定义.

引用了 evaluate(), eve::dev::WatchEntry::expression, info , 以及 w.

被这些函数引用 eve::dev::DevTool::exposeScriptApi() , 以及 eve::dev::DevTool::handleDebugEvent().

◆ removeWatch()

bool eve::dev::Debugger::removeWatch ( const std::string &  expression)

在文件 Debugger.cpp 第 878 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ resume()

void eve::dev::Debugger::resume ( )

在文件 Debugger.cpp 第 571 行定义.

引用了 eve::dev::None , 以及 eve::dev::Running.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ scriptStackDepth()

int eve::dev::Debugger::scriptStackDepth ( ) const

Current Squirrel call depth (1 = topmost script frame). 0 if none.

在文件 Debugger.cpp 第 592 行定义.

引用了 depth, level , 以及 vm().

被这些函数引用 onScriptLine() , 以及 stepOut().

◆ setBreakOnError()

void eve::dev::Debugger::setBreakOnError ( bool  on)
inline

Break on script errors (Godot "Break on Error"). Default off.

在文件 Debugger.hpp 第 226 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ setBreakpoint()

int eve::dev::Debugger::setBreakpoint ( std::string  source,
int  line,
bool  enabled = true,
std::string  condition = {} 
)

Add or update a line breakpoint. A later call with the same source+line replaces enabled and condition (empty condition clears a previous one).

返回
Breakpoint id, or 0 if source is empty / line is not positive.

在文件 Debugger.cpp 第 805 行定义.

引用了 eve::dev::Breakpoint::condition, condition, eve::dev::Breakpoint::enabled, enabled, eve::dev::Breakpoint::id, eve::dev::Breakpoint::line, line, normalizeSource(), eve::dev::Breakpoint::source , 以及 source.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ setBreakpointEnabled()

bool eve::dev::Debugger::setBreakpointEnabled ( int  id,
bool  enabled 
)

Enable or disable by id.

返回
false if id is unknown.

在文件 Debugger.cpp 第 849 行定义.

引用了 enabled.

◆ setBreakpointEventFn()

void eve::dev::Debugger::setBreakpointEventFn ( BreakpointEventFn  fn)
inline

在文件 Debugger.hpp 第 234 行定义.

引用了 fn.

被这些函数引用 eve::dev::DebugAdapter::listen() , 以及 eve::dev::DebugAdapter::stop().

◆ setBreakpointsEnabled()

void eve::dev::Debugger::setBreakpointsEnabled ( bool  on)
inline

Master switch for all breakpoints ("skip all breakpoints").

在文件 Debugger.hpp 第 229 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ setCallGraph()

void eve::dev::Debugger::setCallGraph ( CallGraph *  graph)

Use DevTool's CallGraph for stack names (same object the slicer sees). Pass nullptr to record calls on the debugger's own graph (unit tests).

参数
graphShared CallGraph, or nullptr for the debugger-owned graph.

在文件 Debugger.cpp 第 462 行定义.

引用了 graph.

被这些函数引用 eve::dev::DevTool::attach() , 以及 eve::dev::DevTool::detach().

◆ setPump()

void eve::dev::Debugger::setPump ( PumpFn  pump)
inline

在文件 Debugger.hpp 第 237 行定义.

被这些函数引用 eve::dev::DevTool::attach().

◆ setVirtualSource()

void eve::dev::Debugger::setVirtualSource ( std::string  source,
std::string  text 
)

In-memory script text used to name anonymous name = function() bindings when the hook source is a compile buffer, not a file.

参数
sourceCompile name / path as reported by the Squirrel debug hook.
textFull source of that buffer.

在文件 Debugger.cpp 第 467 行定义.

引用了 normalizeSource(), source , 以及 text.

◆ shouldRunUpdate()

bool eve::dev::Debugger::shouldRunUpdate ( )

Frame loop: true ⇒ call eve_update this frame. Consumes StepFrame.

在文件 Debugger.cpp 第 645 行定义.

引用了 m, eve::dev::Running, eve::dev::StepFrame, eve::dev::StepInto, eve::dev::StepOut , 以及 eve::dev::StepOver.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ sourceBasename()

std::string eve::dev::Debugger::sourceBasename ( const std::string &  source)
static

Basename of a normalized path (empty-safe).

在文件 Debugger.cpp 第 409 行定义.

引用了 normalizeSource() , 以及 source.

被这些函数引用 sourcesMatch().

◆ sourcesMatch()

bool eve::dev::Debugger::sourcesMatch ( const std::string &  a,
const std::string &  b 
)
static

True when two source paths refer to the same script file. Matches exact path, or one path as a directory-bounded suffix of the other. A bare filename (no /) also matches any path with the same basename. Two directory-qualified paths that only share a basename do not match.

在文件 Debugger.cpp 第 415 行定义.

引用了 a, b, idx, normalizeSource() , 以及 sourceBasename().

被这些函数引用 onScriptLine().

◆ stackTrace()

std::vector< StackFrameInfo > eve::dev::Debugger::stackTrace ( int  maxFrames = 32) const

在文件 Debugger.cpp 第 1170 行定义.

引用了 f, eve::dev::StackFrameInfo::id, level , 以及 vm().

◆ step()

void eve::dev::Debugger::step ( )

Convenience: script stepOver when mid-hook; otherwise one game frame. Prefer stepInto/stepOver/stepOut from DAP / UI.

在文件 Debugger.cpp 第 633 行定义.

引用了 eve::dev::Breakpoint, eve::dev::SourceLoc::empty(), eve::dev::Exception, r, eve::dev::Snapshot, eve::dev::Step, stepFrame() , 以及 stepOver().

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ stepFrame()

void eve::dev::Debugger::stepFrame ( )

在文件 Debugger.cpp 第 581 行定义.

引用了 eve::dev::Step , 以及 eve::dev::StepFrame.

被这些函数引用 eve::dev::DevTool::exposeScriptApi(), notifyFrameDone(), step() , 以及 stepFrames().

◆ stepFrames()

void eve::dev::Debugger::stepFrames ( int  count)

Run count game frames then pause. Each frame is consumed by shouldRunUpdate / notifyFrameDone on the game loop.

参数
countHost frames to execute; must be >= 1.

在文件 Debugger.cpp 第 587 行定义.

引用了 count , 以及 stepFrame().

◆ stepInto()

void eve::dev::Debugger::stepInto ( )

Enter calls: stop on the next script line at any depth.

在文件 Debugger.cpp 第 620 行定义.

引用了 eve::dev::StepInto.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ stepLine()

void eve::dev::Debugger::stepLine ( )
inline

Alias for stepInto (historical name).

在文件 Debugger.hpp 第 127 行定义.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ stepOut()

void eve::dev::Debugger::stepOut ( )

Finish current function: stop when stack depth drops.

在文件 Debugger.cpp 第 624 行定义.

引用了 scriptStackDepth(), eve::dev::StepOut , 以及 eve::dev::StepOver.

被这些函数引用 eve::dev::DevTool::exposeScriptApi().

◆ stepOver()

void eve::dev::Debugger::stepOver ( )

Skip calls: stop on the next line at ≤ current stack depth.

在文件 Debugger.cpp 第 622 行定义.

引用了 eve::dev::StepOver.

被这些函数引用 eve::dev::DevTool::exposeScriptApi() , 以及 step().

◆ vm()

HSQUIRRELVM eve::dev::Debugger::vm ( ) const
inline

在文件 Debugger.hpp 第 96 行定义.

被这些函数引用 attach(), containerChildren(), evaluate(), globals(), locals(), scriptStackDepth() , 以及 stackTrace().

◆ waitWhilePaused()

void eve::dev::Debugger::waitWhilePaused ( const std::function< void()> &  pump = {})

Block until resume/step/detach (processes external poll callbacks).

在文件 Debugger.cpp 第 780 行定义.

引用了 eve::dev::Paused.

被这些函数引用 eve::dev::DevTool::handleDebugEvent() , 以及 eve::dev::DevTool::notifyError().

◆ watches()

std::vector< WatchEntry > eve::dev::Debugger::watches ( ) const

在文件 Debugger.cpp 第 892 行定义.


该类的文档由以下文件生成: