Any examples to get me started

[tombomb]

Hey do you have any examples on how to get me started with this, what do I need to pass to it.

[symposion]

Oh man, I'm sorry but this was really just something I split out to clean up some of my own projects. You're welcome to use it but it's actually a pretty involved setup because in order to be able to use a node modules in roll20 you need to compile everything together with webpack or browserify.

If you know your way around node, fulp, npm, etc, then you could check out https://github.com/symposion/roll20-shaped-scripts for examples of how I put everything together. In particular you want to look at the browserify stuff in the gulpfile and entry-point.js.

Unless you're intending to start a really big project in Roll20, it may not be worthwhile investing the time; the Shaped Sheet support script is 6.5k lines now and has unit tests and a CI system - if you're just doing a little light hacking to support your games you're going to spend more time understanding the code and getting it working than you will save by using it!

The other alternative would be to just take logger.js and copy-paste into your own script. You'll need to strip out the module.exports = so that you can access the class directly. You'll also need to do the same for my Roll20 Wrapper, which you need to pass as a constructor parameter to the Logger class.

You instantiate a Logger instance with a name, which is used subsequently to identify it for control from the chat window. The only command that it responds to is:

!logLevel MyLoggerName TRACE

Where TRACE can be one of ERROR, WARN, INFO, DEBUG, TRACE.

You put logging statements into your code by calling the relevant methods on your logger instance - e.g. logger.debug('This is a debug statement'); . It also supports very simple variable interpolation. If you include the string '$$$' in your log text, it will interpolate additional variables into the string in order, e.g. logger.debug('Output my $$$ value and my other $$$ value', value1, value2);

The only exception is TRACE level, which isn't intended for direct usage, but instead is used as part of a call-tracing system. If you call logger.wrapModule(obj) on any object it will replace all of the methods on that object with wrappers that output a log statement at level TRACE whenever they are called. In addition, the wrapper methods will wrap any objects which have the property logWrap that are returned from the original functions, so if you wrap your main module object it should propagate automatically down through your code. The value of the logWrap property is used as a name to identify the object in the log output - if you want to use TRACE logging, most of your objects should have this property set to a readily-identifiable name. The return value propagation obviously falls down when you get to chains of callbacks - there you'll have to do a bit more work manually if you want a complete call chain in the logs.

One other thing to be aware of is that the logger tries to indent the TRACE output according to the call stack. This works fine until you throw an exception. You should ensure that all of your main entry points (i.e. any event handlers that will be called directly by Roll20) set logger.prefixString to the empty string to ensure that indenting starts at zero even if the previous call didn't end normally.

If none of the above makes any sense, I'm afraid this probably isn't the tool for you; it was written basically for my own use, the only reason it's published on npm is because it made it easier for me to modularise my code, and there were a couple of other advanced Roll20 scripters who were considering using a similar module structure. Although I'm happy to give you some pointers/clarify a few things occasionally, I don't have the time to lead you through using it step-by-step; from here you'll need to read the code yourself and try to understand roughly how it works if you want to use it.

Good luck!