Control characters

A “control character” is a character which makes gb-vwf perform some kind of special action.

There are two ways to use a control character, let's take END as an example:

• There is a VWF_END constant, which is also exported outside of vwf.asm itself.
• The charmap also makes "<END>" emit the control character.

Some control characters expect one or more arguments. They must immediately follow the control character, and be contiguous (unless otherwise specified).

Here is a list of the control characters that are built into gb-vwf. Unless otherwise mentioned, none of these end the current tick.

END

This control character ends the current string, popping one entry off the “source stack”.

This can be monitored by examining wSourceStack.len, which will decrease by 1. As mentioned in the How-to, if that variable reaches 0, that means the engine is done printing.

(This control char could have been called RET.)

CALL

This control char enables one to “reuse” some strings. As mentioned in the demo, this is intended for something like the player's name, an attack's target, etc.

This control character expects one argument, a pointer to the “sub-string”. The pointer must be little-endian, so you should use one of the following:

• db VWF_CALL ; or `db "<CALL>"`, both work the same.
  dw TheSubString

• db VWF_CALL, LOW(TheSubString), HIGH(TheSubString)

Caution

The argument is only a pointer, it does not include a ROM bank number! Therefore, the engine does not provide a way to do cross-bank CALLs. Sub-strings should be placed in RAM or ROM0, or else in the same ROMX bank as their caller.

1. First, the address of the byte after the VWF_CALL's argument is pushed onto the “source stack”. (This means that the next END will resume printing there.) This increases wSourceStack.len by 1.
2. Then, text printing continues at the specified address (TheSubString in the example above).

JUMP

This control char simply “redirects” the engine's input. Unlike CALL, nothing is pushed to the “source stack”.

It is preferable to use a JUMP rather than a CALL immediately followed by a END, because the latter consumes one entry in the “source stack” (and is significantly more expensive to process for that reason).

SET_FONT

This takes a one-byte argument, the new font ID.

SET_VARIANT

This is like SET_FONT; except that only the NB_VARIANT_BITS least significant (“rightmost”) bits of wFontID are updated.

This is useful, for example, if you use bold and/or italic fonts: if all your even-numbered fonts are “base”, and all your odd-numbered fonts are bold, then you can db VWF_SET_VARIANT, 1 to switch to a bold font, regardless of which one is currently active. And then db VWF_SET_VARIANT, 0 to switch back to the “base” font.

This makes custom fonts and sub-strings play nicer with each other.

Note

If not defined in the config file, NB_VARIANT_BITS defaults to 2 (for base, bold, italic, bold+italic).

ZWS

This is a control char that, by itself, does nothing (so the tick continues). However, it is a line break opportunity; and if a line break is automatically inserted at that point (which ends the tick), it will be printed as a hyphen (-).

This is useful to insert inside of long words, to avoid the line before that word being awkwardly short.

NEWLINE

This will end the tick, and signal PrintVWFChars to move to the next line.

Neither this, nor automatically-inserted newlines, will ever overflow the textbox, acting like SCROLL and/or WAIT as necessary.

SET_COLOR

This takes a one-byte argument, which should be either 0 or 1. 0 makes glyphs be printed to colour index #3, 1 makes glyphs be printed to colour index #1.

The engine will never print glyphs to colour indices #0 or #2.

DELAY

This takes a one-byte argument, N. Makes the engine pause for N ticks (and immediately ends the current tick, which counts as 1).

Important

N = 1 will make printing resume on the next tick, and N = 0 will make the engine pause for 256 ticks!

SYNC

This will simply set the SYNC flag in wFlags, and continue the tick. This is so that SYNC doesn't create a 1-tick pause.

If you do want a pause, you can insert "<DELAY>", 1 (or "<WAIT>", or...) afterwards.

WAIT

This will simply set the WAITING flag in wFlags, and then end the tick.

TickVWFEngine will do nothing if called while this flag is set. The WAITING flag must be reset externally, which lets you use whatever logic you want for that purpose!

SCROLL

This will end the tick, and signal PrintVWFChars to scroll the entire textbox tilemap up by one row, and fill the bottommost row with VWF_BLANK_TILE.

Note that 1-tall textboxes are supported, and will simply be cleared.

No animation is performed, the tilemap is simply modified. Here are a few ways to change that:

• After TickVWFEngine returns, check if the SCROLL flag is set in wFlags but not WAITING (because auto-newlines can set both). If so, set the WAITING flag before calling PrintVWFChars (this inhibits the scrolling logic), and perform your animation.

  Once the animation is finished, reset the WAITING flag and call PrintVWFChars again, which will shift the tilemap and perform some internal updates. It is inadvisable to shift the tilemap yourself and/or reset the SCROLL flag manually, because of that last part.

• Modify vwf.asm to perform your desired animation; look above PrintVWFChars.notScrolling.

  This is not recommended, as then updating vwf.asm (to get bugfixes, for example) will be more difficult.