CHARML English

CHARML (Character Markup Language; reads as caramel) is an XML used to create characters for Apricot. It's described in the following specification.

It should be noted that this specification limited to platforms and versions of Apricot listed below:

• Apricot for Windows (6.8 or higher)
• Apricot for Windows Store (1.7 or higher)
• Apricot for iOS (2.1.1 or higher)

Currently following elements are availible for use:

• script
• character
• sequence
• message
• break
• motion
• image
• sound

script element

<script>
...(content)...
</script>

The script element represents the root of a CHARML document.

character element

<script>
  <character name="charname" width="240" height="320">
  ...(content)...
  </character>
</script>

The character element represents a character labeled by its name. The parent element is script element. There can be multiple character elements with unique names within a single file.

Attributes:

name: name of the character.
x: X coordinate of the character. (optional)
y: Y coordinate of the character. (optional)
width: Width of the character.
height: Height of the character.
origin-x: Origin X coordinate of the character. (optional) (default: 0)
origin-y: Origin Y coordinate of the character. (optional) (default: 0)

All coordinates and dimensions are in display pixels. Coordinates are relative to the application's coordinate frame.

Adjusting display position of the balloon:

x-coordinate of the balloon = (width attribute + origin-x attribute) / 2.
y-coordinate of the balloon is determined from value of the y attribute of image element, which will be described later, plus value of origin-y attribute.
If you want to shift y coordinate of the balloon by 50, set origin-y attribute to 50, and then set to -50 y attributes for all image elements.

sequence element

<script>
  <character name="charname" width="240" height="320">
    <sequence name="Blink>
      ...(content)...
    </sequence>
    <sequence name="Idle">
      <sequence name="Blink" />
    </sequence>
  <character>
</script>

The sequence element represents a subset of the character movements labeled by name.

The state attribute represents character state. Value that represents this state is not limited to the place from which function was called. Sequence with the state that matches given state will run. If they do not match, state attribute runs unspecified sequence. Containing element of a sequence element can be either character or sequence element. It's possible to nest sequence elements. When a sequence element have empty state by tame nesting is finished, a designated sequence element is called. When the state attribute is specified, state transition is done to the defined state. When it is not specified, the present state is maintained. In the above example, at the time of the Idle state the sequence of Blink is called.

Attributes:

name: name of the sequence. Identifies sequence within the element. For values of the name attribute that are reserved by Apricot refer to events section. If the element is an empty element specifies the name of the sequence to call. When there is more than one of the same name the sequences are called at random.

state: if the element is an empty element, and set the state. If you include a element to the sequence within the element, the element is sequence is executed in the case that matches the string of state, which was set at the time of the call at the time of empty element. If you do not want to match, state will be performed include the top. The state attribute can include regular expressions.

<sequence name="Activate">
  <sequence name="Apricotan.Talk" state="dere\d">
    <sequence name="Apricotan.Talk" state="tsun1">
      <message>Maybe I don't like {character}!</message>
      <sequence name="Apricotan.Shy" />
    </sequence>
    <sequence name="Apricotan.Talk" state="tsun1" />
  </sequence>
  <sequence name="Apricotan.Talk" state="tsun1">
    <sequence name="Apricotan.Talk" state="tsun2">
      <message>I don't like {character} very much!</message>
      <sequence name="Apricotan.Anger" />
    </sequence>
    <sequence name="Apricotan.Talk" state="tsun2" />
  </sequence>
  <sequence name="Apricotan.Talk" state="tsun2">
    <message>I don't particularly like {character}!</message>
    <sequence name="Apricotan.Anger" />
  </sequence>
  <sequence name="Apricotan.Talk" />
</sequence>

In the above example, the state is "dere1" of Apricotan.Talk sequence, "dere2", "tsun1", it is assumed the case in which four of "tsun2". If Apricotan.Talk state of the sequence is "dere1" or "dere2", after this sequence element is executed a sequence of "dere\d" run, state will transition to "tsun1". In the case of "tsun1", after executing a sequence of "tsun1", the state will transition to "tsun2". In the case of "tsun2" it will maintain the state of "tsun2".

Events

When an event occurs in the Apricot it searches for corresponding sequence element from the character markup. The element is then matched by the name attribute to the following system events:

Start

<sequence name="Start">
...(content)...
</script>

Called at the application's start and at character switching.

Stop

<sequence name="Stop">
...(content)...
</script>

Called at the application's exit.

Idle

Called at the beginning of Idle state.

Tick

Called when each second passed.

DoubleClick

<sequence name="DoubleClick">
...(content)...
</script>

Called when character is double-clicked.

DrawClipboard

Called when text has been copied to the clipboard.

Learn

Called when when caracter learned a word.

Alert

<sequence name="Alert">
  <message>There is a new entry.</message>
</script>

Called after getting RSS/Atom feed if there is a new entry.

Trend

Called after finding a keyword that has become hot topic.

Search

Called when the search is performed.

Suggest

Called when you open related entry.

Activate

<sequence name="Activate">
  <message>It's not that I like {name|character} or anything.</message>
</sequence>

Called when the caracter is prompted to speak spontaneously.

When you use the {character} template it will be replaced by name of a random character. | separator can be used to specify more than one template. For example if you use {name|character} it will be replaced by either character's or person's name. Following values can be specified instead of character for the default words database:

• activity
• audial
• character
• creature
• drink
• food
• knowledge
• name
• occupation
• organization
• person
• phenomenon
• place
• problem
• state
• symptom
• technology
• thing
• time
• visual
• wearable

Extended Events

Extended events provide additional responsiveness for characters.

Talk feature

The name attribute of the sequence elements talk can be set to five values: Ignore/Greet/Hate/Interest/Thank. Talk feature analyzes the classified content. If text is classified Hate/Interest/Thank called. If it's not then Ignore called. If the state is set text entered by the user is filtered using a regular expression from the attribute.

Ignore

Called if the text that user entered could not be classified.

Greet

Called when text entered by the user is classified as a greeting.

Hate

Called when text entered by the user is classified as disliking (reverse of Interest).

Interest

Called when text entered by the user is classified as interest (reverse of Hate).

Thank

Called when text entered by the user is classified as showing appreciation.

Function of likeability

The name attribute of the sequence element required for compliance with likeability is Like. If the state for likeability is set (numerical value) then regular expressions using the state attributes wil be applied. It should be noted that likeability may not be set from the start.

Like

<sequence name="Like" state="^[1-9]$">
  <sequence name="Additional expression">
    <!-- The 1 state is set for Apricotan.TryUnlock sequence -->
    <sequence name="Apricotan.TryUnlock" state="1">
      <sequence name="Apricotan.NOP" />
    </sequence>
    <sequence name="Apricotan.TryUnlock" state="1" />
  </sequence>
  <sequence name="Additional expression" />
</sequence>

Called when the likeability has been updated. To view the performance name that can be released by increasing the likeability rating in such a dashboard, name attribute inserts a sequence element to the child element of the sequence element of Like, you put the proven name in the name attribute.

Functions related to weather

The name attribute of the sequence elements necessary to correspond to the current weather is Weather. In state is the current state of the weather is set, and then filtering regular expressions using the state attributes. It should be noted that it may not be set from the start.

state list

• Thunderstorm
• Drizzle
• Rain
• Snow
• Mist
• Smoke
• Haze
• Dust
• Fog
• Sunny
• Clear
• Cloudy
• Overcast
• Tornado
• Windy
• Hail

message element

<message speed="50" duration="00:00:03">This is a message!</message>

The message element represents a text to be displayed inside the balloon.

Attributes:

speed: sets the message speed. The unit is the number of characters per sec. (default: 50)
duration: appearance time of the balloon in hh:mm:ss format. (default: 00:00:05, i.e. 5 seconds)

break element

<message speed="50" duration="00:00:03">This<break />is a message!</message>

The break element represents a new line in the text that appears in the balloon.

motion element

<motion fps="10" z-index="1" iterations="30">
  <image x="10" y="20">Images\Apricotan-Face-02.png</image>
</motion>

The motion element represents a movement of the character. The elements are set in order of image appearance and are similar to a collection of flip-book frames. If values of z-index attribute are the same, motion elements processed from top to bottom. Uses image elements as children. The parent element is sequence element. To use dress-up option set the type attribute.

Attributes:

loop: If True then loop until the layer (z-index) is overwritten. (optional) (default: False)
type: If you want to use the dress-up option set the name that you want to appear in the dress menu. (optional)
fps: Sets the FPS value.
z-index: Sets the visibility layer. (integer value)
iterations: Sets the number of times the animation is repeated.

<sequence name="Sample">
  <motion fps="30" z-index="1" iterations="2">
    <image>Animation01.png</image>
    <image>Animation02.png</image>
  </motion>
</sequence>

Equals to:

<sequence name="Sample">
  <motion fps="30" z-index="1">
    <image>Animation01.png</image>
    <image>Animation02.png</image>
    <image>Animation01.png</image>
    <image>Animation02.png</image>
  </motion>
</sequence>

This will give the same result:

<sequence name="Sample">
  <motion fps=>"30" z-index="1" iterations="2">
    <image>Animation01.png</image>
    <image>Animation02.png</image>
  </motion>
  <motion fps="10" z-index="1" iterations="3">
    <image>Animation02.png</image>
  </motion>
</sequence>

The sequence above shows how fps and iterations attributes can be manipulated to produce a single motion.

image element

<image x="10" y="20">Images\Apricotan-Face-02.png</image>

The image element represents an image. Its content equals path to the image. The parent element is motion element.It is recommended to use PNG image format. The path format depends on the environment. In case of ZIP format, that is supported by the Windows version 7.0 or higher or Windows Store app, directory is represented by a slash /.

Attributes:

x: X coordinate of the image. (optional)
y: Y coordinate of the image. (optional)
width: width of the image. (optional)
height: height of the image. (optional)
opacity: alpha value of the image in 0..1 range where 0 = transparent and 1 = opaque. (optional)

All coordinates and dimensions are in display pixels. Coordinates are relative to the application's coordinate frame.

sound element

<sound>Sounds\alert\alert_001.wav</sound>

The sound element represents a sound. Its content equals path to the sound. The parent element is sequence element. It is recommended to use WAVE format. The path format depends on the environment. In case of ZIP format, that is supported by the Windows version 7.0 or higher or Windows Store app, directory is represented by a slash /.