Wiki

Clone wiki

asPEEK / Home

What is this?

asPEEK is a remote debugger with an HTML client for AngelScript

How does it work ?

  1. Integrate asPEEK in your application.
  2. Use HTML client to start debugging.

Features

  • Stop/Resume/StepOut/StepIn/StepOver any script
  • See Stack and Jump to functions.
  • Easy breakpoint control.
  • Hover over any variable to see its value. Classes, primitives, arrays even C++ registered objects.
  • Real-time value visualization for globals Local variables and member variables are visualized when execution is halted.
  • Add global variable to watch variables in real-time
  • Built-in execution console, doubles as console output if you need one.
  • Unblocking multithreaded design
  • Supports multiple users at the same time
  • Able to debug multiple contexts at the same time
  • Capable text editor
  • Works in Firefox and Chrome. Opera and IE is not supported.
  • Load/Save script sections
  • Optional Restart application functionality

Build

  1. Build Boost
  2. Build AngelScript
  3. Build asPEEK using CMAKE
  4. Add ./include directory to your project
  5. Add asPEEK.h to your project

Integration

Integration is simple, only takes a few lines.

// create asPEEK, with a port and a pointer to script engine
asPEEK *peek = new asPEEK(engine, 9002);
// function that loads a section, asPEEK does not assume anything about how you load script sections
peek->LoadSectionFunction = &LoadScriptFile;
// function that saves a section, optional
peek->SaveSectionFunction = &SaveScriptFile;
// add modules to peek so that we can lookup global variables in them
peek->AddModule(mod);
// only the contexts you add will be debugged and paused when debugging starts.
peek->AddContext(ctx);
// add section to asPEEK, if you don't add sections you won't be able to see where current line is and step trough that section seeing the actual code
peek->AddScriptSection("sectionname", "moduleName");

 // listen incoming connection. Creates its own threads.
peek->Listen();
// when you are done with it
delete peek;

A simple LoadSection function

Since asPEEK does do any loading/saving itself, you need to supply it with a function pointer (or a member method with boost::bind). This example straight up loads a file to 2nd parameter.

void LoadScriptFile(const std::string &filename, string &script)
{
  ifstream ifs;
  ifs.open(filename.c_str(), ifstream::in);

  int ch = ifs.get();
  while (ifs.good())
  {
    script += (char) ch;
    ch = ifs.get();
  }

  ifs.close();
}

Can i visualize application registered types?

Yes. You need add a function to convert type to a string. It is not possible in C++ to determine object type from just void*.

Here is an example:

std::string Vector3ToString(void *vec)
{
  Vector3 *v = (Vector3*) vec;
  std::stringstream ss;
  ss << "{\"_\":\"Vector3\",";
  ss << "\"x\":" << v->x << ",\"y\":" << v->y << ",\"z\":" << v->z << "}";
  return ss.str();
}
// add type id and function to lookup table.
peek->AddSpecialTypeConversion(engine->GetTypeIdByDecl("Vector3"), &Vector3ToString);

This function converts a Vector3 POD type to JSON format. String returned should be valid JSON. "_" member is object type as a string. It is optional, but if you like to see object type in debugger include it.

It is better not to include any space/tab/newline in this, since string is sent over sockets.

Is there an example/demo?

Yes. Look at the "example" folder for a simple integration sample. Built version of this example available as Windows binary in the Downloads section. Binary demo is most likely outdated.

Updated