Kawari- Getting Started

Index

0. Introduction
1. Installation
2. About files
3. kawarirc.kis
3.1. How to Write kawarirc.kis
3.2. Operation Mode Specification
4. Dictionary
4.1. How to Write a Dictionary File
4.2. Quoting Notation
4.3. Entry Calls
4.4. History Reference
4.5. System Entries
5. Inline Script
6. Miscellaneous

0. Introduction

You don't need to understand everything about Kawari.

Kawari intentionally provides a versatile and flexible platform so that the roles of the "framework creator" and the "ghost creator" can be shared. If you just want to put a ghost on your desktop, you only need to know 10% of Kawari's functionality.

If you don't know anything about Kawari but just want to create a ghost, we recommend that you start by obtaining middleware、that provides a "framework" such as、OpenKEEPS, KLAFT, or FUDS and then rewrite the sample messages.

1. Installation

Place the following files in the ghost directory.

2. About Files

All ghost setting files read by Kawari are in the "Kawari Dictionary" file format. Kawari reads the "kawarirc.kis" file first, so normally, several option dictionary files are read sequentially from here.

To avoid conflicts with other files, it is recommended that the dictionary file used for the actual ghost description be named "dict-*.txt", for the main word data and "ghost-*.txt" for the main conversation data.

3. kawarirc.kis

The kawarirc.kis file is the first dictionary file to be read by Kawari, and must be prepared. It is grammatically the same as other dictionary files, but until you get used to it, you should use it as follows.

3.1. How to Write kawarirc.kis

First, surround the entire file with a line with just "=kis"and a line with just "=end".

Next, specify the name of the dictionary file you want to load in the form of "load file name;" between =kis and =end=end. Please note that ";" (semicolon) cannot be omitted for each load. Blank lines are allowed, too. Also, as long as you have a semicolon, you can write multiple commands on the same line.

Also, the entire line starting with "#" is a comment. Comments do not affect Kawari's behavior at all. Kawari skips comments when reading a dictionary.

3.2. Operation Mode Specification for Debugging

During the development of ghosts, it is often done to make Kawari output information during operation for debugging purposes. Within =kis ～ =end, you can change the debug operation by the following description. For more detailed settings, please refer to the User's Manual.

logfile filename;

Creates a log file with the specified file name in the same folder as shiori.dll.

loglevel [ operation information event type ... ];

Specifies what should be logged. By default, nothing is logged. loglevel quiet; allows you to explicitly disable the logging activity.

Be sure to delete or comment out the loglevel and logfile specifications at the time of release (actually providing the created ghost to users).

4. Dictionary

In Kawari, the content of the ghost's speech and each word, such as nouns and verbs, is called a "definition". Kawari has a "dictionary" that categorizes and collects these "definitions". The dictionary is read from a dictionary file at startup. Dictionaries can also be rewritten using scripts during execution.

Usually, the dictionary file is loaded from kawarirc.kis by the "load" command described earlier.

4.1. How to Write a Dictionary File

The basic dictionary file description format is as follows:

Definitions arranged in a comma-separated list are classified into a single entry. A colon separates the entry name from the sequence of definitions. A line break terminates the registration of an entry. Lines beginning with a pound sign/hash ('#') character are ignored as comments.

Spaces and tabs around commas and colons are automatically removed.

Entry names may be separated by commas, and definitions may be registered to multiple entries at once.

The following characters can be used for entry names:

However、the At Symbol '@' is used for a specific purpose, and shouldn't be used normally.

There are no restrictions on the length of entry names, the number of entries, or the length of the dictionary file.

Characters that cannotbe used in entry definitions are as follows:

Whitespace (Spaces "' '", tabs, etc.) can also be used. However, since whitespace around commas and colons (as well as at the beginning and end of each line) is automatically deleted, use the quoting notation described below to insert whitespace in these places.

Long sentences may be written on multiple lines. Within a statement, line breaks may be inserted freely within the area enclosed by parenthesis "'(' ～ ')'". The newline character is treated as a type of whitespace and will not appear in the output. Within the parentheses, additional commas ",", and semicolons ";" can be used in a sentence. On the other hand, it is not possible to put several sentences in a row to register an entry within the parenthesis.

4.2. Quoting Notation

Strings enclosed in single quotes, "'", or double quotes, """, are always output as is. Entry calls, etc., described below, are not substituted even if they are inside quotes. Use quotes if you want to write strings with special meaning in Kawari such as ",", "${}", and "$()", or if you want to write spaces in a sentence.

In a string enclosed in quotes, only "\<character used for quoting>" and "\\" are treated specially. They output the character used for quoting and "\" respectively. If there is a character other than the two listed after "\", the \will be printed as is.

Note that single quotes can be used normally within double quotes, and double quotes can be used normally within single quotes.

sentence : Good morning, U.S.A.

In the above example, the two words are registered as "Good morning" and "U.S.A.". If you want to register "Good morning, U.S.A.", do the following

sentence : "Good morning, U.S.A."
    or
sentence : Good morning", "U.S.A.

Other examples of quoting notation.

sentence : "I can't help fallin' love"
sentence : "We scream \"Ice cream\" !"

4.3. Entry Calls

The format "${entryname}" is called an "entry call".

When "${entryname}" is specified in a sentence, one of the sentences registered for that entry is randomly selected and replaced. If no corresponding sentence is found, it is replaced with an empty string. If the replaced sentence also contains an entry call, it is replaced again.

This is the core of creating of Kawari Ghosts.

npw : Ichiro Suzuki,Mr. Taro Yamamoto
sentence : Mr. ${npw}

In the above example, when you call the definition, it becomes "Mr. Ichiro Suzuki" or "Mr. Taro Yamamoto".

"Replacement" is not performed when the dictionary is loaded into Kawari, but when it is called from the outside (main body) and the word in the entry is actually selected. So calling the same entry multiple times will give different results each time.

4.4. History Reference

The special entry call "${num}" is called the "history reference". History referencing is used to refer back to replaced words in the same context.

n : stone
food : pear
sentence : ${n}like ${food}、${1}like ${0}.

In the example above, ${0} is the result of replacing ${n}, ${1} is the result of replacing ${food}, and the definition is "Pear like a stone, stone like a pear" .

4.5. System Entries

The number of entries specifically used by Kawari has been greatly reduced.

The "System.Callback.*" format entry is called when various events, such as OnClose, occur. At that time, all requests from the main unit are stored in "System.Request.*" format entries. By registering information in the "System.Response.*" format entry and terminating the operation, the response to the main unit can be freely configured. If a sentence is generated and returned normally, it is treated as a conversational sentence (content of the Sentence header).

The "System.Resource.resourcename" format entry is called when a SHIORI/3.0-unsupported main unit requests a network update destination URL, recommended menu, or other information. For details on resources, please refer to the SHIORI specification on the official Ukagaka page.

Now, as it is, you cannot make the ghost work. For example, if you write a conversation directly in System.Callback.OnEvent, it will probably not work. OnEvent, for example, it will not work. In order for the Kawari Ghost to work, it is necessary to use the inline script "KIS," which is described later in this article. This is both an advantage and a disadvantage of Kawari. In order to write ghosts in Kawari, layering software or middleware written in KIS is indispensable. Once you understand the grammar of Kawari, we strongly recommend that you search for Kawari middleware on the web and use one of them. Using them to create ghosts is a very easy and enjoyable process.

Anyway, to make the ghost work with a minimum of description, please make the following description in kawarirc.kis, or in the dictionary file that is always loaded. However, the beginning of the sentence must start outside the =kis ~ =end region.

# Before period 565 Event handler
System.Callback.OnEvent: ${event.${System.Request.Event}}
System.Callback.OnResource: ${resource.${System.Request.ID}}

# period 568 or later (SHIORI/3.0) event handler
System.Callback.OnGET: $(
    if $(match_at ${System.Request.ID} On)
        ${event.${System.Request.ID}}
    else
        ${resource.${System.Request.ID}} )

# Minimum event processing description
event.OnFirstBoot: \0\s[0]\1\s[10]\e
event.OnBoot: \0\s[0]\1\s[10]\e
event.OnGhostChanged: \0\s[0]\1\s[10]\e
event.OnShellChanged: \0\s[0]\1\s[10]\e
event.OnWindowStateRestore: \0\s[0]\1\s[10]\e
event.OnClose: \-

# 一Call sentence every minute.
event.OnMinuteChange: ${sentence}

# 一Sentence is called every minute.
sentence : \0\s[0]Hello.\e
sentence : \1\s[10]I have to move it.\0\s[0]Yeah.\e

5. Inline Script

The "Kawari Inline Script" can be used for event processing, dynamic modification of dictionary contents, conditional branching based on entry contents, etc. The basic format of the script is "$(commandname, argument1, argument2...)". (Simply put, it is a subset of Bash (Bourne Again SHell). For details of the language specification, please refer to the attached Kawari Inline Script Reference Manual.)

In the "Kawari Ghost" conversation data (ghost-kawari.txt) you will find an example of inline scripting. It is easy to call the script from the Communicate Box, so you can play around with it and see how it works.

6.Miscellaneous

Kawari has many functions, but you don't need to use all of them from the beginning. At first, you should look for and use something like a collection of scripts called "layer software" or "middleware". You can also find middleware at"KawaLinks", a collection of links on Kawari. If you want to write ghosts on top of that, the knowledge of what is written in this document should be enough. One of our goals is "Ghost writing should be easy".

However, there are times when you want to display information obtained from SAORI or information sent from the main unit with some modification. Or, what if you want to save the information gathered by the ghost, such as the time it has been activated, the number of times it has been activated, the number of times a certain event has occurred, a line sent by an acquaintance's ghost in a communique, or a recent topic of conversation? What if you want to change the ghost's behavior based on the information you have saved? What if you want to create a Ghost with different personalities the user can change to?

One thing you can do is to look for middleware that also provides such functions. However, if you cannot find what you want, you will have to create it yourself. In that case, you will have to make full use of the functions of Kawari. Please read the User Reference, and the KIS Reference Manual and try to realize the functions in your own way. If you are interested in more details, please refer to the KIS Programming Manual. It contains everything you need to know about Kawari. If you have any questions, please ask on the Official Kawari BBS. I am sure someone will be able to answer your question. With Kawari's scripting language, KIS, you should be able to do quite a bit. "Ghosts must be diverse" is another goal of Kawari.