3.6 Commands for avatarsay

The program avatarsay understands a small set of commands. So you can spice up your “executable texts” even further.

A line starting with a hash sign (#, U+0023) is a comment. Those lines are simply ignored by the program. Attention: unlike in other scripting languages there may even be no whitespace in front of the hash sign.

You can structure your text by including a stripline. A stripline is a line like this: ‘---------’. The line must start at the very first column and there must be at least three successive hypens (U+002D). Of course you can use more than three ones.

A command for avatarsay starts with a dot (U+002E) in the very first position of a new line.

.datadir directory

with this command you can set the directory, where images and sound files are located

The data directory can also be set with the environment variable AVATARDATADIR. The command has precedence over the environment variable.

.avatarimage imagefile

with this command you can use a different image for the avatar.

Attention: This command has to be used before the text starts

The avatar image can also be set with the environment variable AVATARIMAGE. The command has precedence over the environment variable.

Which file-formats AKFAvatar supports depends on which libraries you have installed. Uncompressed BMP images are always supported.

.encoding encodingname

sets the encoding of the text; such as ‘ISO-8859-1’ or ‘UTF-8’

Attention: This command has to be used at the beginning of the file. You can no longer change the encoding inside of the text (which was possible in previous versions).

This command can only be used with ASCII compatible encodings, such as the ISO-8859-series or UTF-8. The encodings UTF-16 (UCS2) and UTF-32 (UCS4) can not be set with this command. But these encodings are in most cases detected automatically. (Earlier versions of avatarsay could not handle these encodings at all.)

It depends on your systems iconv implementation, which encodings are supported. On some systems you can get a list with the command iconv -l.

.backgroundcolor #color-definition

set a different background color

The color-definition has to be given as six hexadecimal characters; with two digits each for red, green and blue. The default value is ‘#CCCCCC’.

Attention: This command has to be used before the text starts

.left-to-right

.right-to-left

changes the text direction; this is useful if you have text written in Hebrew or Yiddish (Arabic is not supported)

You can only switch the text-direction on a line by line basis. Different text directions inside of one line is not supported.

.flip

flip the page; the same effect as with a stripline

.clear

clears the text-area; unlike .flip it doesn't wait, but clears it immediately

.pause

a longer pause; the avatar is shown without the balloon for some time

.image imagefile

shows an image for a while (without the avatar)

The image is centered on the screen. If the image is larger than the screen, the screen is centered on the image.

You can use a stripline after this command if you wish. The stripline doesn't have any effect then.

Which file-formats AKFAvatar supports depends on which libraries you have installed. Uncompressed BMP images are always supported.

.audio audiofile

plays an audio file

The text continues to be shown, so you can play an audio file with the recorded words of the following text.

Currently only WAV-files with PCM or ADPCM encoding are supported.

.waitaudio

wait until the audio output ends

This can be used to synchronize the recorded and the written text to some extend.

.effectpause

short pause while the text stays visible

If you want to make an effect-pause within a line, you can end the previous line with a backslash (\, U+005C), so the line-ending has no effect for the output.

.back number

delete the last number of characters

The previous line has to be ended with a backslash (\, U+005C). You could use this command after an .effectpause-command for a nice effect.

.read

reserved for later versions

.end

end of the text

The avatar moves out.

Anything behind the .end command is ignored.

.stop

stops the output immediately

The avatar is not moved out, but the text ends immediately.

Anything behind the .stop command is ignored.