Libdragon Console
The Libdragon console is what is used to display plain text in an easy and safe manner onto the N64 display. It is mainly used for debugging, but it can be also used as an engine for a simple text-based game.
Starting up the console
Starting up the console is fairly easy, all you need is this following line of code. It will start the console up and allow you to start printing text to it.
console_init();The console has 28 rows with 64 characters each, and is padded vertically by 8 pixels and horizontally by 64 pixels. These values can be referenced with these macros:
#define CONSOLE_WIDTH 64
#define CONSOLE_HEIGHT 28
#define HORIZONTAL_PADDING 64
#define VERTICAL_PADDING 8Optional: set the mode
There are two modes for printing to the console:
RENDER_MANUAL– Keeps the printed statements in a buffer and waits for them to be manually summoned byconsole_render().RENDER_AUTOMATIC– Renders each console print command as it is printed
These options are set like this (pick one line only):
console_set_render_mode(RENDER_MANUAL);
console_set_render_mode(RENDER_AUTOMATIC);By default, it will be set to automatic mode, so this can be ignored completely if you plan on sticking to printing out text as you go.
Printing text
Once the console has been activated, it’s time to start printing some text to it. This can be achieved by using functions that print to stdout, primarily the following:
printf()– Print a formatted stringputs()– Print an unformatted string with a newline (\n) at the endputchar()– Print a single character
These functions come in the standard library <stdio.h>, so they should be fairly familiar. Try something out like this:
printf("Hello world %i!\n", 1234);
puts("Hello to you too!");
for (char i=0; i<26; i++) {
putchar(65+i);
}
putchar('\n');This snippet will output something like this:
Notes
It is important to add a newline to the end or else the previous text will not be printed. It is possible to print multiple print statements to a line without a newline (like the putchar() above) as long as it eventually has a \n somewhere afterwards.
Carriage returns (\r) do not work on the Libdragon console, nor is there any way of modifying already-printed text without deleting and rewriting the whole thing.
ASCII table
Here is the ASCII table of printable characters. The main ASCII set (32-127) is more or less what you’d expect, but some of the non-printing characters (1-31) do output some symbols. The extended ASCII characters (128-255) are mostly gibberish or slightly corrupted versions of other characters so they should be avoided – unless you’re trying to make some kind of ASCII art.
And yes, it works.
Clearing the screen
If your console prints reach the bottom of the screen, it will scroll the console down automatically. Once you reach the bottom of the screen there’s just two ways to amend what lies above: clearing and overwriting.
Overwriting means that you just keep on printing text to shift the console back up until you get it to where you want. It can be a bit tedious to keep track of all the lines so it’s not recommended unless you want to keep a chunk of the previous prints.
Clearing involves clearing the console buffer and placing the cursor back in the top left of the array as if nothing had been written. This can be done by using the following function. This is best used when you want to write a multi-line output to the console, such as emulating a GUI in a text-only way.
console_clear();Customising the console
You can use the standard white text on black background, but you can also customise the colour of the console as you see fit. To do this you need to use the graphics_set_color() function, which takes two unsigned 32-bit ints as input; the first for the text colour and the second for the background. Here is the function prototype:
void graphics_set_color (uint32_t forecolor, uint32_t backcolor);So you can set your colour by using a RGBA hex number or by using the graphics_make_color() function like this (both methods do the same thing):
// Prototype for syntax purposes only, not needed in actual code
uint32_t graphics_make_color (int r, int g, int b, int a);
graphics_set_color(
graphics_make_color(255,0,0,255),
graphics_make_color(0,255,0,255)
);
graphics_set_color(
0xF801F801,
0x07C107C1
);Note that the hex number is 32-bit but the value within it is two repeated 16-bit colours. Read the page on N64 colour encoding for more on how 16-bit colours work. Also, the colour is set for the entire console at once, you can’t specifically colour-code certain characters or rows at a time.
#include <stdio.h>
#include <libdragon.h>
int main(void)
{
console_init();
graphics_set_color(
0xF801F801,
0x07C107C1
);
printf(" o\n");
printf(" o /\n");
printf(" \\ /\n");
printf(" \\ /\n");
printf(" \\ /\n");
printf(" ______V_______\n");
printf(" |.------------.|\n");
printf(" || ||\n");
printf(" || ||\n");
printf(" || ||\n");
printf(" || ||\n");
printf(" ||____________||_\n");
printf(" |OO ....... OO | `-.\n");
printf(" '------_.-._---' _.'\n");
printf(" _____|| ||___/_\n");
printf(" / _.-|| N ||-._ \\ .-._\n");
printf(" / -'_.---------._'- \\ ,'___i--i___\n");
printf(" /_.-'_ NINTENDO _'-._\\ ' /_+ o :::_\\\n");
printf(" |`-i /m\\/m\\|\\|/=,/m\\i-'| | || \\ O / ||\n");
printf(" akg | |_\\_/\\_/___\\_/'./| | | \\/ \\ / \\/\n");
printf(" `-' '-.`-' , V\n");
printf(" `---' \n");
while(1) {
}
}Cleaning things up
Once you’re done with the console, you can summon the following function to close the console and free any memory that it was using:
console_close();Note that the text will remain on screen unless you use console_clear(); before you close the console.
Debug
If you’re using a flash cart with USB debugging, you can use the following to enable debugging using this method:
// Enable it
console_set_debug(true);
// Disable it
console_set_debug(false);I don’t have one so I can’t demonstrate the use of this functionality here.
