MoonSharp offers, out of the box, two debuggers.
99.9% of the time, if you want to offer a debugger to your users, you can just go with using one of those two.
Overall, the VSCode debugger is friendlier and easier to use, but it requires the application running MoonSharp to be running on the same machine where the VSCode editor is running, so it’s limited to desktop, local platforms.
To use it, you have to reference
MoonSharp.VsCodeDebugger.dll either manually or through NuGet.
If you use the Unity package, it’s already included.
Once you have the DLLs referenced, setting it up for a first use is very very simple. As simple as:
You can attach multiple scripts to the VSCode debugger without any constraints - although, the more you add, the more you should use meaningful names to avoid confusing your users.
You can switch the script which will be debugged first when a new debugger client is attached by setting the
Current property on the
MoonSharpVsCodeDebugServer object; users can switch the script from the VsCode Debug Console, in any case, using the
If a script becomes obsolete and there is no reason to debug it anymore, call the
Detach method on the
MoonSharpVsCodeDebugServer object; this will disconnect any debugger currently debugging that obsolete script object, allowing memory to be freed up and avoiding polluting the script list.
VSCode debugging relies on the usage of files on the filesystem. If a source file cannot be found, a temporary file is saved on the fly on the local machine with the contents of the script. This for examples happens if the directory where the files are located is different from the relative path used by the application to load, or if the scripts are embedded resources of some kind, or if they are loaded using
LoadString even if they are files.
MoonSharpVsCodeDebugServer accepts a third parameter in the
AttachToScript method, which is a function mapping a
SourceCode object to a filename. For example, this piece of code uses
LoadFile to load relative source code, but is still compatible with the debugger:
Another example, this uses the friendlyName parameter of LoadString to avoid the problem altogether:
To use it, you have to reference
MoonSharp.RemoteDebugger.dll either manually or through NuGet.
After that, setting it up for a first use is very very simple. Simple as:
The remote debugger uses Flash, which is very picky on how the domain name is expressed in the URL bar. For example,
127.0.0.1are considered different things for Flash security. If something doesn’t work, try to express the host name part of the URL in a different way.
Some simple customizations are available with the remote debugger. They are passed to the RemoteDebuggerService constructor, through a RemoteDebuggerOptions object.
The following are available:
Utf8TcpServerOptions.LocalHostOnly, specifies that only connections from the local host are accepted.
Utf8TcpServerOptions.SingleClientOnlyspecifies that at most one client can be connected (at a connection, all previous clients are force disconnected).
Scriptobject is instantiated at a time.
Scriptobjects are received. Every other script increments from this number.
The defaults are:
This is a very advanced topic.
It’s also possible to implement your own debugger. We won’t dig it here too much but: