Skip to content

Home

Jump to bottom
baris edited this page Jun 19, 2022 · 7 revisions

Introduction

  • The main class you need to use for console is Cc, (com.junkbyte.console.Cc).
  • Cc stands for Console controller which acts as singleton adapter for Console (com.junkbyte.console.Console).
  • When you no longer need console in your project, you can remove Cc.startOnStage(..) and all other calls through Cc will stop working silently.

Basics

For reference, please see samples/haxe/SampleAdvanced.hx for working sample.

Start on stage

import com.junkbyte.console.Cc;
Cc.startOnStage("");

If you want to set a keyword for console to start, assign at first parameter.

  • You will need to type the keyword in correct sequence to show the console.
  • Recommended keyword: ``` or ~ or debug. Use letters and numbers only.
  • Console will start hidden if you set a password (you can set Cc.visible = true; to force display console).
  • Entering the keyword while console is visible will hide it
  • Password will not trigger if user have focus on an input TextField

Logging

Cc.log("Hello world.");
Cc.info("An info message.", "Optionally there", "can be", "multiple arguments.");
Cc.debug("A debug level log.", "You can also pass an object and it'll become a link to inspect:", this);
Cc.warn("This is a warning log.", "Lets try the object linking again:", stage, " <- click it! (press 'exit' when done)");
Cc.error("This is an error log.", "This link might not work because it can get garbage collected:", new Sprite());
Cc.fatal("This is a fatal error log with high visibility.", "You will get a short stack trace of where it's called from (configurable)");
//
// Basic channel logging
//
Cc.infoch("myChannel", "Hello myChannel.");
Cc.debugch("myChannel", "A debug level log.", "There is also Cc.errorch() and Cc.fatalch(). Skipping that for demo.");
// You can also use Cc.errorch() and Cc.fatalch().
//
// Instanced channel
//
var ch:ConsoleChannel = new ConsoleChannel('myCh');
ch.info("Hello!", "Works just like other logging methods but this way you keep the channel as an instance.");

UI

console_controls
(The image is taken from Junkbyte's original site and shows the Flash version.)

Configuration

You will need to use Cc.config to enable or disable some features. It is recommended to set them before starting console. Example:

Cc.config.commandLineAllowed = true // Enables full commandLine features
Cc.config.tracing = true; // also send traces to flash's normal trace()
Cc.config.maxLines = 2000; // change maximum log lines to 2000, default is 1000

Cc.startOnStage(""); // finally start with these config

Useful Features (Advanced)

For easy reference, please see samples/haxe/SampleAdvanced.hx for working sample.

Object inspection

  • When you log an object in console, it will keep a weak reference to the object
  • Example: Cc.info("Stage is:", stage) will show up in console as Stage is: {Stage}
  • Clicking on the link {Stage} will reveal detailed info about stage
  • Details shows up in an 'inspection' channel. When you are done, click 'Exit' to return to normal logging view
  • As references are stored as weak link, some objects may get garbage collected before you click
  • To avoid early garbage collection issue, see Cc.config.objectHardReferenceTimer.
  • You can click on [set scope] to set scope in commandLine (explained later)
  • You can manually print detailed info about an object by calling Cc.inspect(...);

Keyboard Binding

  • Key binding lets you bind keyboard keys to your own function
  • Example usages: open a specific panel, give special items/cheats in a game
  • The function you pass get STRONG referenced
  • Key Binding will not trigger if user have focus on an input TextField
  • If triggering something by keyboard is part of the actual project behaviour, it is recommended you write your own to avoid depending on console
  • Example below logs "Hello!" in console when user press the key H in keyboard.
import com.junkbyte.console.Cc;
import com.junkbyte.console.KeyBind;
Cc.bindKey(new KeyBind("h"), Cc.log, ["Hello!"]);
//Callbacks like Cc.log on cpp do not work due to rest arguments limitation.

Command line

  • CommandLine let you execute actionscript 3 code at run time

  • You must set Cc.config.commandLineAllowed = true; to be able to run full features.

  • Command line appears at the bottom of main panel (press CL at top menu)

  • Slash commands run special functions on demand

  • An example of built-in slash command: '/filter log'

  • Typing this will filter to logs that match the string 'log'

  • You will also get underline under the exact match

  • When you are done, change the channel at top OR type '/filter'

  • You can also add your own custom slash commands

// Slash command example 1
Cc.addSlashCommand("test", function():void{ Cc.log("Do the test!");} );
//When user type "/test" in commandLine, it will call function with no params.

// Slash command example 2
Cc.addSlashCommand("test2", function(param:String = ""):void{Cc.log("Do the test2 with param string:", param);} );
//User type "/test2 abc 123" in commandLine to call Cc.log with one param: "abc 123".
  • Functions and arguments you pass get STRONG referenced
  • If you are planning to use complex params, consider using Cc.store instead
  • You can store references for use in commandline
//Example 1 (storing functions)
Cc.store("load", function(id:uint){Cc.log("Do some loading with id", id)});
//User call this function by typing '$load(123);' to load with id 123.
//
//Example 2 (storing anything)
Cc.store("mc", myMC); // assuming myMC is a MovieClip somewhere or could be anything, class, object, etc...
//User manipulate the mc by typing `$mc.x = 100;`, `$mc.alpha = 0.5`, `$mc.parent.removeChild($mc);` etc...
  • NOTE: Cc.store(...) use weak reference by default but you can specify to be strong
  • You can go crazy with commandline. Example:
  • stage.getChildByName("Console").filters = new Array(new flash.filters.GlowFilter());
  • Adds glow filter on Console.
  • CommandLine have limitations. For better understanding, see CommandLineHelp

Display Roller

  • Display roller shows the display tree of objects under your mouse
  • Start Display roller by pressing RL at the top menu
  • You can capture the display map to console for use in commandLine or for detail inspection
  • To do this, click on 'Capture key: unassigned' in the RL panel
  • Press C on keyboard to bind the capture key to that key
  • Roll over to anything you want to capture and press the keyboard C key
  • You will get the display map printed on console
  • Clicking on the name will set that display (Sprite/MovieClip etc) as commandLine's scope
  • Clicking on the link inside the {..} will inspect the object showing you the detailed info
  • NOTE: You can also use Cc.setRollerCaptureKey(...) to assign the capture key
  • Example use: You got an item thats behaving weirdly on screen...
  • Use the Roller tool to get reference to that object
  • Use link inspection to find out whats wrong with the values
  • Use commandline to change and experiment with different property values on the fly

Advanced Logging

Yes, lets go back to logging... here are some extra features:

  • Cc.stack() Gives you a stack trace under your string to show where this method is called from (requires debug player)
  • Example if you need to clearify from which call to a specific function is causing the bug
Cc.stack("Stack trace called from...");
/* //If you have debug player, it'll show up in console as:
   Stack trace called from...
    @ Sample/demoBasics()
    @ Sample()
*/

  • Use Cc.stackch(ch:String, str:*, depth:int = -1, priority:int = 5) to have channel name.

  • Cc.explode() is similar to JSON where it explodes an object's value to bits so that you can see all in one line

Cc.explode(stage);
// logs: {Stage quality:"HIGH", fullScreenWidth:1920, alpha:1, numChildren:2, width:700, height:303, etc...

  • The explosion also give you links to the sub objects

  • Non-repetitive logging

  • Keeps replacing the previous line that has repeat turned on until certain count is passed

  • For example, if you are tracing download progress and you don't want to flood console with it

Cc.add("My advanced log in priority 2, 1st call", 2, true);
Cc.add("My advanced log in priority 2, 2nd call", 2, true);
Cc.add("My advanced log in priority 2, 3rd call", 2, true);
Cc.add("My advanced log in priority 2, 4th call", 2, true);
Cc.add("My advanced log in priority 2, 5th call", 2, true);
// You will only see the last line in console.
// If you want to specify the channel, use:
// Cc.ch(channel:*, str:*, priority:int, isRepeating:Boolean)

Graphing

  • Graphing lets you view number graphs similar to the FPS and memory monitor. (F and M buttons on top menu)
  • Example as seen in samples/haxe/SampleAdvanced.hx:

Flash

//Graph the current mouseX and mouseY values
Cc.addGraph("mouse", this, "mouseX", 0xff3333,"X", new Rectangle(380,180,80,80), true);
Cc.addGraph("mouse", this, "mouseY", 0x3333ff,"Y");
// Sine wave graph generated by commandline execution, very expensive way to graph but it works :)
Cc.addGraph("mouse", this, "(Math.sin(flash.utils.getTimer()/1000)*300)+300", 0x119911, "sine");

Non-Flash

//Graph the current mouseX and mouseY values
Cc.addGraph("mouse", this,"get_mouseX()", 0xff3333,"X", new Rectangle(560,180,80,80), true);
Cc.addGraph("mouse", this,"get_mouseY()", 0x3333ff,"Y");
// Sine wave graph generated by commandline execution, very expensive way to graph but it works :)
Cc.addGraph("mouse", this,"(Math.sin(openfl.Lib.getTimer()/1000)*300)+300", 0x119911,"sine");

Extra menu links

  • You can add your own menu link at the top along with other console built-in links.
Cc.addMenu("hi", Cc.log, ["Hello from top menu"], "Says hello!");
//Callbacks like Cc.log on cpp do not work due to rest arguments limitation.
  • This adds a link 'hi' on top menu. Rolling over the link will show the tooltip "Says hello!"
  • Clicking on the link will print in console "Hello from top menu".

Ruler tool

  • Start ruler tool by pressing on RL at the top menu
  • Ruler tool let you measure the distance and angle between two points

Garbage collection monitor

import flash.display.Sprite;
var aSprite = new Sprite();
Cc.watch(aSprite, "aSprite");
aSprite = null;
  • Above example creates a Sprite and then remove its reference.
  • This marks the Sprite to be garbage collected, but it might not get collected straight away.
  • If you have a debugger version of flash player installed, you can open memory monitor (press M in console menu) and then press G in that panel to force garbage collect.
  • You will see that objects you are watching will get notified in console when they are garbage collected.

Custom Style

You must set them before starting console. Example:

Cc.config.style.big(); // BIGGER text.
Cc.config.style.whiteBase(); // Black on white. - NOT the way for stealth coders!
Cc.config.style.backgroundAlpha = 1; // opaque background.

Cc.startOnStage(this); // finally start with these styles

Addons

There are a few addons available for console. See Addons

Clone this wiki locally