Translated Document

This document has been translated from the original Japanese by members of the Ukagaka Dream Team community.
To see the original document, click here.
To submit corrections/updates, see our repository to open an issue or find where to contact us.

surfaces.txt

Summary

A file that contains the individual definitions for a shell. Fundamentally most of it is omissible and only certain parts are necessary to function.
This file includes image synthesis, the collisions, and the animations (frames, expressions, parts, dressup parts) for each surface.
It is also used to give surface IDs separate names, known as surface aliases.
In SSP, in addition to the above, tooltips and special cursors when hovering over collisions can also be set up.

On the other hand, settings related to information such as the names of the shell and shell creator or the display settings for the dressup section of the owner draw menu (right-click menu) are written in descript.txt, not this file.

Basic format

Almost all of the settings are omissible, and need only be added if deemed necessary.

When it comes to writing the settings, the charset must be in the first line, and everything else must be written inside each brace, between { and } (refer to each entry on this page for details on each brace).

{ and } must be written on individual lines, and cannot be written as "surface1 {" on the same line as the brace name, for example.

Brace name
{
// Settings contents
}

All lines that are not recognised as either a brace name, {}, or settings will be treated as comments. Comments are customarily started with //.

Any line may be indented.

In SSP only, any text file named surfaces***.txt will be read (where *** is any string) and treated in the same way as surfaces.txt. When there are multiple files, they are read in the order of the file names.

When multiple surfaces***.txt files exist, they must all have descript braces (including charset). In other words, each file may have different settings.

Usage example

charset,UTF-8

descript
{
version,1
}

surface0
{
animation0.interval,sometimes
animation0.pattern0,overlay,101,100,168,67
animation0.pattern1,overlay,100,100,168,67
animation0.pattern2,overlay,101,100,168,67
animation0.pattern3,overlay,-1,100,168,67
}

surface1
{
element0,overlay,body0.png,0,0
element1,overlay,face1.png,0,0
}

surface10
{
collision0,40,56,95,90,Head

sakura.balloon.offsetx,80
sakura.balloon.offsety,-100
kero.balloon.offsetx,-30
kero.balloon.offsety,20
}

// This definition method only works in SSP ← As this line does, comments start with //
surface.append0-9
{
collision0,188,25,252,63,Head
collision1,190,92,236,118,Face
collision2,180,191,220,222,Bust
collision3,154,311,248,362,Skirt
}

surfaces.txt or surfaces**.txt (SSP only)

charset,(character encoding)

Character encoding to be used. Shift_JIS is recommended for compatibility with older environments, otherwise UTF-8 is recommended.

In SSP, if multiple surfaces***.txt files are used, each file must have it's own configuration. (Conversely, each file may have different settings.)

(OS standard setting or SSP -> Internationalization -> Default character encoding -> Text definition)

Descript brace

Descript brace example

In SSP, if multiple surfaces***.txt files are used, each file must have it's own configuration. (Conversely, each file may have different settings.)

descript
{
version,1
collision-sort,ascend
animation-sort,ascend
}

version,*

Specify which version of SERIKO definition format to use. 0 for SERIKO/1.x format (old definition), 1 for SERIKO/2.0 format.

maxwidth,(pixels)

※SSP does not use this information as it is detected automatically.
Maximum width of the surface, in pixels. This information is used for overlap determination, etc.

No definition / In SSP, maximum width in actual surface definition

collision-sort,(sort order)

Sorting order of the collisions. In which order should they be displayed from the front to the back?
ascend for ascending order (1,2,3...), descend for descending order (10,9,8...).

none (the one written first, regardless of ID, is in the foreground)

animation-sort,(sort order)

Sorting order of animations by ID number. In which order should they be displayed from the front to the back?
ascend for ascending order (1,2,3...), descend for descending order (10,9,8...).

descend

Surface brace

Surface brace examples

surface1
{
element0,overlay,body0.png,0,0
element1,overlay,face0.png,0,0

collision0,188,25,252,63,Head
collision1,190,92,236,118,Face
collision2,180,191,220,222,Bust
collision3,154,311,248,362,Skirt

animation0.interval,sometimes
animation0.pattern0,overlay,101,100,168,67
animation0.pattern1,overlay,100,100,168,67
animation0.pattern2,overlay,101,100,168,67
animation0.pattern3,overlay,-1,100,168,67
}

In SSP only, there is a notation surface.append which is used to specify additional definitions (i.e., to append more definitions to those already defined).
See below for details.

surface.append1-9,20-29
{
// Truncated (Same as normal surface brace)
}

Specify a number that is the surface ID in the * part of surface(.append)*. Multiple specifications and range specifications are possible (See below).

For the rest of the numbers in this section, please refer to the explanation of each definition.

Animations (SERIKO)

Summary

Ukagaka shells have animation functions. Animation is represented by continuously drawing frames that are still images.

The animation is set for each surface. The image used as each frame of the animation is also another surface. If the surface referred to as the frame has additional animation definitions, they are usually ignored. (However, in SSP only, there is a mechanism called "multiple dressups" dressups).

In the settings for each surface, it is necessary to define when the animation itself will start, which surface to use for each frame, and what method and time interval it will be drawn using.

This specification for a series of animations in surfaces.txt is given the name SERIKO.

Basic format and description examples


surface0
{
// Blink
animation0.interval,rarely
animation0.pattern0,overlay,101,700,200,100
animation0.pattern1,overlay,102,700,200,100
animation0.pattern2,overlay,101,700,200,100
animation0.pattern3,overlay,-1,700,0,0

// Move the mouth when talking
animation10.interval,talk,2
animation10.pattern0,overlay,200,700,200,120
animation10.pattern1,overlay,201,700,200,120
animation10.pattern2,overlay,202,700,200,120
animation10.pattern3,overlay,-1,700,0,0
}

An example animation definition in surfaces.txt is as follows.

In the above example, two animations are defined for surface0: "Blink" and "Move the mouth when talking".

All animation definitions include an interval definition and pattern definitions. There are also option definitions, and, in the case of SSP, animation-specific collision definitions. But while these are optional, interval definitions are not optional and must appear at the beginning of an animation definition.

The interval definition is the setting for when the animation will play. In the example above, there are three types of designations: "rarely", "talk", and "never". For details, see the animation interval section. Generally speaking, the "Blink" animation is played occasionally, and the "Move the mouth when talking" animation is played every time the character speaks two letters.

The pattern definition is the setting for each "frame" of the animation. Set the drawing method of the frame (See the drawing methods section), the waiting time until the frame is displayed, and how much the position of the frame should be shifted relative to the frame below it. The * in pattern* is a sequential number, starting from 0.

Relationship between each animation

All animations are given an ID (see animation*.interval section for specifics).

IDs cannot be duplicated within a single surface, and animations with the same ID across different surfaces are expected to have the same meaning. For example, suppose there are two surfaces; surface0 with the character facing forward, and surface1 with the character facing sideways; and we want to create a "blink" animation for both surfaces. In this case, the images corresponding to the frame that actually expresses the blink should be different due to the difference in the character's position, but the same animation ID should be given to both surfaces regardless. This is particularly important with dressup, which is described below.

All different animations are essentially independent, and start and end asynchronously.
For example, an animation that blinks and an animation that moves the mouth when talking would start and end regardless of whether the other is running or not. In fact, as long as two animations are defined as different animations with different IDs, they will behave that way.

On the other hand, however, there is also a mechanism that allows animations themselves to trigger the execution of other animations. This is done by means of special drawing methods, such as start and alternativestart.
It is also possible to execute exclusive animation by specifying the exclusive option.

Dressups (MAYUNA)

Summary

Ukagaka shells have a mechanism called "dressup". This is used for displaying/hiding parts, such as additional outfits, and switching between different kinds of outfits within a single shell.

Dressup in an ukagaka shell is considered a type of animation.
However, unlike other animations it does not move frame by frame, and instead all frames (patterns) and the base surface are immediately composited when the animation is started, and are treated as a single image thereafter (thus, the "wait" parameter in in the pattern definition is ignored).
This property of "the drawing behaves as if it were integrated with the base surface" is well suited for the purpose of expressing things like clothing.

The start and end of dressup animations is mainly controlled by switching in the "dressup" section of the owner draw menu. In SSP, it can additionally be controlled from the ghost side using the \![bind] SakuraScript tag.
The settings on the owner draw menu side are done in descript.txt, not surfaces.txt, so refer to that page.

This specification for a series of animations in surfaces.txt is given the name MAYUNA.

Basic format and description examples


surface0
{
// Clothing 1 has an animation ID of 0
animation0.interval,bind
animation0.pattern0,add,500,0,50,100

// Clothing 2 has an animation ID of 1
animation1.interval,bind
animation1.pattern0,add,501,0,50,100
}

//--- Definition of the above dressup parts ---
// Clothing 1
surface500
{
element0,overlay,dress1.png,0,0
}

// Clothing 2
surface501
{
element0,overlay,dress2.png,0,0
}

An example dressup definition in surfaces.txt is as follows.

The above example defines two dressups for surface0, "Clothing 1" and "Clothing 2".

As with normal animation definitions, an interval definition and a pattern definition are required. By specifying bind in the interval definition, it indicates that the animation is a dressup definition.

In the case of animation, the pattern definitions are used as the number of frames. But in the case of dressup, since this is a static image specification, the patterns are combined as a whole rather than as frames. If you only need one piece to make up the dressup, as in the example above, then only one pattern line is needed. Also, in the case of dressup, each piece is composited immediately, so the wait parameter is ignored.

The drawing methods of pattern definitions are described below.

Available drawing methods

In MATERIA (original ukagaka), four methods were available for dressup: "bind", "add", "reduce", and "insert". Of these, bind is the old specification, and add is upward compatible.

In SSP, some of the methods used for normal animation drawing methods can also be used for dressup.

See the section on drawing methods for the specific drawing methods available for dressup.

Specification of bind combination intervals

In SSP, it is possible to specify a combination of intervals, as mentioned in the animation interval section.

When bind is used in a combination specification, the animation loses the static image specification that it would have if bind was used alone (the wait parameter in the pattern definition is no longer ignored). However, the lifespan of the animation is unchanged. For example, in the case of a combination specification such as bind + runonce, the animation will continue to display after all patterns have been drawn until the base surface is changed or the dressup is changed.

Therefore, in an interval combination that includes bind, the animation should not be terminated at the final line of the pattern definition, but instead should be the drawing that you want to be composited as a static image.

Multiple dressups definition (SSP only)

If the surface referenced as an animation frame has animations defined for that surface, they are usually ignored.

However, in SSP, bind animations in particular (i.e. dressups) will be displayed instead of being ignored.

As a result, for animations that are affected by dressups, it is possible to define dressups on the frame side of the animation.

Note that it is possible to nest multiple dressups, but circular references are ignored.

Regarding the old and new SERIKO definitions

What are the old and new definitions of SERIKO?

In a late development version of MATERIA (original ukagaka), there was a change in the format of settings related to SERIKO (animation) in surfaces.txt.
The old definition is the conventional SERIKO/1.x format found in the original specification, while the new definition is the new format (SERIKO/2.0) which has not been officially documented.

In addition, and separately from this, after the development of MATERIA was discontinued, SSP and others added their own notation to the format of surfaces.txt (e.g., surface.append, surface1-9, etc.).
Some people and documents may refer to these additions as the new definition, but please note that the old and new definitions—at least in Ukadoc—are only about the SERIKO format, not that kind of usage.

Differences between new and old definitions

There are four formatting changes in the new definition:

Changed all SERIKO-related definition lines to begin with the word "animation".
The order of parameters in pattern definitions has been changed (drawing method was moved and is now written first).
The unit of the wait parameter in pattern definitions has been changed from 10 milliseconds to 1 millisecond.
For the drawing method alternativestart, the brackets for specifying IDs have been changed from [] to ().

In addition to this, it is necessary to have a description brace, in which "version,1" is defined.

Below is an example of the old definition and the new definition with the same definition content.

// Old definition
surface1
{
0interval,rarely
0pattern0,0,0,alternativestart,[1,2]

1interval,never
1pattern0,101,70,overlay,200,100
1pattern1,102,70,overlay,200,100
1pattern2,101,70,overlay,200,100
1pattern3,-1,70,overlay,0,0

2interval,never
2pattern0,101,70,overlay,200,100
2pattern1,102,70,overlay,200,100
2pattern2,101,70,overlay,200,100
2pattern3,-1,70,overlay,0,0
2pattern4,101,70,overlay,200,100
2pattern5,102,70,overlay,200,100
2pattern6,101,70,overlay,0,0
2pattern7,-1,70,overlay,0,0
}

// New definition
surface1
{
animation0.interval,rarely
animation0.pattern0,alternativestart,(1,2)

animation1.interval,never
animation1.pattern0,overlay,101,700,200,100
animation1.pattern1,overlay,102,700,200,100
animation1.pattern2,overlay,101,700,200,100
animation1.pattern3,overlay,-1,700,0,0

animation2.interval,never
animation2.pattern0,overlay,101,700,200,100
animation2.pattern1,overlay,102,700,200,100
animation2.pattern2,overlay,101,700,200,100
animation2.pattern3,overlay,-1,700,0,0
animation2.pattern4,overlay,101,700,200,100
animation2.pattern5,overlay,102,700,200,100
animation2.pattern6,overlay,101,700,200,100
animation2.pattern7,overlay,-1,700,0,0
}

Animation ID
Pattern ID
Surface ID
Drawing method
Wait
x-coordinate
y-coordinate

Note that each line now begins with "animation", the number of the wait parameter has been multiplied by 10, and the drawing method specification has been moved to the beginning of the parameters.
In addition, for the alternativestart drawing method, [] has been changed to (). In the old definition, the dummy value 0 was written for the "surface ID" and "wait" parameters, because these parameters are ignored by alternativestart. Whereas in the new definition, the drawing method has been moved to the start, so these values—including the x and y-coordinates—can be omitted entirely.

Advantages of using the new definition

Settings that SSP has added on its own (Those that do not display , and only display ) may not be expected to be written in the old definition.
The same can be said for any additional settings that will be added in the future.
When using such settings, it is advisable to use the new definition (the old definition may not work properly).
In such cases, mixing the old and new definitions will result in an error, so the definitions must be unified.
The wait unit is changed from 10 ms to 1 ms, allowing for more detailed control.
As seen in the example above, the advantage of moving the drawing method to the beginning of the parameters is that parameters which are ignored by special drawing methods—such as start and alternativestart—are neatly omitted.
In addition, by clearly specifying the word "animation", the cohesiveness of the definition of SERIKO may be emphasized and make the meaning of the line easier to understand. Although, the ease of reading depends largely on familiarity and personal differences, and it is natural to feel that the old definition is more familiar and easier to read.

If you do not feel that the above points are beneficial, it may not necessarily make sense to migrate if you are considering using SSP only.

In addition, UKADOC describes SERIKO with the new definition, so if you want to use the old definition, please refer to the above and change the definitions accordingly.

ID specifications possible for surface* braces

All of the following notations can be used together. They are all for SSP only.

Enumeration specification ","

surface1,3,4,6,12
{
// Content omitted
}

The same content can be defined for multiple surfaces by specifying IDs separated by "," like this.

Range specification "-"

surface1-12
{
// Content omitted
}

By specifying IDs using "-" like this, it is possible to define the same content for multiple surfaces in a consecutive range of numbers (from surface1 to surface12 in this example).

Range exclusion specification "!"

surface1-30,!15,!20-25
{
// Content omitted
}

Writing "!" before a single ID or a range of IDs excludes those IDs from the definition (in this example, it is synonymous with writing surface1-14,16-19,26-30).
Note that exclusion with ! takes precedence over other specifications, regardless of its position (for example, if you write surface1-10,!2-4,3, 3 will be excluded even though it is written after the excluded range).

In the original specification of Materia, only enumeration specification as shown below is allowed with surfaces.

surface1,surface3,surface4
{
// Content omitted
}

surface* braces and surface.append* braces

Definitions in surface.append are only appended to "definitions that already exist (either by surface braces or by the existence of surface*.png)".

So for example:

surface1,3
{
collision0,188,25,252,63,Head
collision1,180,191,220,222,Bust
}

And later, intended as an additional definition:

surface1-3
{
animation0.interval,sometimes
animation0.pattern0,overlay,101,100,168,67
animation0.pattern1,overlay,100,100,168,67
animation0.pattern2,overlay,101,100,168,67
animation0.pattern3,overlay,-1,100,168,67
}

With this, a new "surface2" will be created and defined, even though it was not originally intended to be defined.

Therefore, additional definitions with range specification without using append may cause "unknown duplicate definition errors". But if you write like so:

surface.append1-3
{
// Content omitted
}

In this case, the definition added by append is only added to "surface1" and "surface3" since they already have definitions, and "surface2", which does not exist beforehand, is not newly created, even internally.

Note that due to this relationship, surface braces must be written before the surface.append brace in the definition file (surfaces.txt, etc.).

Base surfaces

An image that is the basic state of each surface before animations are added is called the base surface.

Animations are usually drawn above the base surface (at the front of the screen).

Base surface entity

A surface's base surface is defined by the surface*.png corresponding to the ID and the element specification in the surface brace corresponding to the ID.

For surfaces with surface*.png, that image becomes the base surface of surface*. However, if element0 is also defined, the content of surface*.png is discarded, and is replaced with the content of element0 (this is a specification to ensure compatibility).

If there are definitions for element1 and after, they are composited sequentially, stacking on top of each other, and the final composited image is treated as the base surface.

Position and order of components

Upper and lower

The front of the screen is referred to as the upper side, and the back of the screen is referred to as the lower side.

Vertical structure of different parts

For elements and dressups (animations with the bind interval), smaller element IDs and pattern IDs are lower, and larger IDs are higher.

Vertical structure of the base surface and each animation

The base surface is generally the image that is placed at the bottom of all composites, but in SSP, animations with the background option are composited below (behind) the base surface.

The upper and lower structure between animations, including dressup animations, is usually in descending order from the one with the highest animation ID (the one with the highest number is placed at the front of the screen). However, in SSP, if animation-sort is defined in the descript brace, it can be in ascending order.

Vertical structure of collisions

Generally, collision definitions that appear earlier in surfaces.txt are higher. However, in SSP, if collision-sort is defined in the descript brace, it can be set in ascending or descending order based on the collisionID.

In SSP, animation*.collision can be used to set a collision area that is valid only when a specific animation is displayed. In this case, the vertical structure of each animation is first taken into account, and then the collision detection for each animation and the base surface is evaluated in the usual order.

For example, when animation-sort is set to descend, the following is the order from top to bottom.

Higher hitboxes for regular animations with higher IDs
Lower hitboxes for regular animations with higher IDs
Higher hitboxes for regular animations with lower IDs
Lower hitboxes for regular animations with lower IDs
Higher hitboxes for the base surface
Lower hitboxes for the base surface
Higher hitboxes for animations with the background option with higher IDs
Lower hitboxes for animations with the background option with higher IDs
Higher hitboxes for animations with the background option with lower IDs
Lower hitboxes for animations with the background option with lower IDs

(Animation here includes dressup.)

Allocation of surface IDs

You are generally free to assign any surface ID to any expression or content.

However, surface0 and surface10 are required as default surfaces. If the ghost has no partner, it is necessary to prepare a transparent image as surface10. (In SSP only, the default surface can be changed in the descript settings.)

In addition, there are some "de facto standards". The following assignments (other than 0 and 10) are for reference only. They are not required and can be assigned freely.

sakura side

00 Normal
01 Embarrassment
02 Surprise
03 Anxiety
04 Discourage
05 Smile
06 Closing Eyes
07 Anger
08 Sneer
09 Embarrassed anger
25 Singing

kero side

10 Normal
11 Opening Eyes
19 Singing

Note that in MATERIA, the range of numbers that can be used for surfaceIDs is limited to 0–8192.

element*,(drawing method),(filename),(X coordinate),(Y coordinate)

Base surface composite.
A system that composites multiple images and treats the composite result as the base surface, as though it were a single image.
If there is an image called surface*.png that corresponds to the surface, and element0 is defined, the content of the original surface*.png is discarded and replaced with the content of element0.
element1 and onward are sequentially composited on top of it.
Starting with SSP 2.3.53, surfaces defined as elements behave as if they were a single image, even if used as an animation part (previously undefined).
The * part (elementID) is a serial number, starting with 0, that is consistent within the same surface.
For drawing methods, see drawing methods below.

No behavior

animation*.interval,(interval)

Definition of the timing (cycle) at which the animation starts.
For interval, see animation intervals below. In SSP only, combinations can be specified by listing multiple with + as a delimiter.
The * part (animationID) is an arbitrary number. For all surfaces within the same scope (\0, \1, ...), animations with the same ID in common should have the same meaning (e.g., "blink", "talking", "same clothes", etc.).
The interval definition indicates the starting point of the entire animation definition for that ID, and must always be first in a series of animation definitions.
See animation-sort for the relationship between how animations overlap and the order of IDs.
Old definition: *interval,(interval)

No behavior

animation*.pattern*,(drawing method),(surface ID),(wait),(X coordinate),(Y coordinate)

Definition of each frame of the animation. Each frame is usually drawn by resetting the previous frame and compositing a new one on the base surface (strictly speaking, it depends on the drawing method).
The * following animation is the animationID (the same * as in animation*.interval).
The * (patternID) following pattern is a serial number starting from 0 in a series of animation*.pattern definitions. In materia, the upper limit is 127. The patterns are drawn in a stacked manner, starting with the one with the lowest number.
For drawing methods, see drawing methods below.
wait is the waiting time until the frame is drawn, in milliseconds. In SSP only, it can be written as "minimum wait-maximum wait" separated by a dash, in which case a value is randomly chosen between the minimum and maximum.
The X and Y coordinates specify how much the frame should be shifted relative to the base (the result of drawing up to that frame).
The surface ID can be set to -1 to stop the current animation, or -2 to stop all other animations currently running. In both cases, the drawing method and X and Y coordinates are ignored.
Old definition:*pattern*,(surface ID),(wait),(drawing method),(X coordinate),(Y coordinate)

No behavior

animation*.option,exclusive

Exclusive execution option for animations.
That is, when an animation with the exclusive option is executed, all other animations are stopped, and no other animations are started until the animation with the exclusive option ends.
The * following animation is the animationID (The same as * in animation*.interval).
Note that this specification is undefined for animations whose interval is bind.
For SSP only, if you use animation*.option,exclusive,(1,3,5) you can restrict the exclusitivy to only animations with the specified IDs.
Old definition:*option,exclusive

No behavior

animation*.option,background

Background option for animations.
Animations with the background option run behind the base surface (at the back of the screen).
The * following animation is the animationID (The same as * in animation*.interval).

No behavior

animation*.option,shared-index

When switching surfaces with the \s tag, continue the animation of the same ID from part way through.
Specifically, assuming that the animation was executed up to pattern4 before executing the \s tag, it will start again from pattern4 after executing the \s tag.
This option must be specified both in the current surface before the \s tag, and in the surface that is switched to. If only one of them is specified, it will be reset.
It will also be reset if the pattern ID is not found in the target animation.

No behavior

2.6.02

animation*.option,(option)

The exclusive, background, and shared-index options can be specified simultaneously, and multiple options can be specified by separating them with +. For example: exclusive+background.
The * following animation is the animationID (The same as * in animation*.interval).
If you write animation*.option,exclusive+background,(1,3,5), the IDs in specified in () will only be affected by the exclusive option.
For animations whose interval is bind, the exclusive specification is undefined.

No behavior

animation*.collision*,(collision definition) animation*.collisionex*,(collision definition(ex))

Definition of a collision or collisionex that is only available while the animation is running. Also valid for animations whose interval is bind.
The * following animation is the animationID (The same as * in animation*.interval).
The * following collision should be a unique number in a series of animation*.collision definitions.

No behavior

collision*,(origin X coordinate),(origin Y coordinate),(end X coordinate),(end Y coordinate),(ID)

Collision detection. The area enclosed by the coordinates will be the area of the collision with the specified ID.
The * part (collisionID) is a serial number that should not match any other ID within the same surface.
See collision-sort for the relationship between how collision areas overlap and the order of the IDs.

No behavior

collisionex*,(ID),(type),(coordinate 1),(coordinate 2)...

Irregularly shaped collision detection.
The * part (collisionID) is a serial number that should not match any other ID within the same surface.
The types are as follows:

rect: Rectangle. There are four coordinates: the start point X and Y, and the end point X and Y.
Example: collisionex0,Head,rect,100,100,200,300
ellipse: Ellipse. The four coordinates are the rectangle surrounding the ellipse: the start point X and Y, and the end point X and Y.
Example: collisionex0,Head,ellipse,100,100,200,300
circle: Circle. Describe the X and Y value of the center point, followed by the radius.
Example: collisionex0,Head,circle,100,200,20
polygon: Polygon. Pairs of coordinates for each vertex. Crossing is allowed.
Example: collisionex0,Head,polygon,100,100,200,300,50,200
region: [SSP 2.5.19~] Treat the area of the specified color in the specified image file as a collision area.
Note that using a large amount (~100) will slow down the overall operation.
If "Invert area" is set to true, it means "area not of the specified color". This option can be omitted.
Specification format: (Filename),(R),(G),(B),(Invert area (false or true))
Example 1: collisionex0,Head,region,atari.png,255,0,0
Example 2: collisionex1,Head,region,atari.png,0,255,0,true

No behavior

sakura.balloon.offsetx,(coordinate)

X coordinate of the balloon position for the main character, for this surface only.

Normal: The left/right edges of the balloon are aligned with the right/left edges of the surface.
align=top/bottom: Center of the surface.

sakura.balloon.offsety,(coordinate)

Y coordinate of the balloon position for the main character, for this surface only.

Normal: The top edge of the balloon is aligned with the top edge of the surface.
align=top/bottom: The upper/lower edge of the balloon is aligned with the bottom/top edge of the surface.

kero.balloon.offsetx,(coordinate)

X coordinate of the balloon position for the side character, for this surface only.

Normal: The left/right edges of the balloon are aligned with the right/left edges of the surface.
align=top/bottom: Center of the surface.

kero.balloon.offsety,(coordinate)

Y coordinate of the balloon position for the side character, for this surface only.

Normal: The top edge of the balloon is aligned with the top edge of the surface.
align=top/bottom: The upper/lower edge of the balloon is aligned with the bottom/top edge of the surface.

balloon.offsetx,(coordinate)

X coordinate of the balloon position for this surface only (regardless of main character or side character).
Can also be written as offset.x

Normal: The left/right edges of the balloon are aligned with the right/left edges of the surface.
align=top/bottom: Center of the surface.

balloon.offsety,(coordinate)

Y coordinate of the balloon position for this surface only (regardless of main character or side character).
Can also be written as offset.y

Normal: The top edge of the balloon is aligned with the top edge of the surface.
align=top/bottom: The upper/lower edge of the balloon is aligned with the bottom/top edge of the surface.

point.centerx,(coordinate)

X coordinate of the surface center.
Not normally used, but can be obtained from external sources such as the Sakura API.

Center of surface (width ÷ 2)

point.centery,(coordinate)

Y coordinate of the surface center.
Not normally used, but can be obtained from external sources such as the Sakura API.

Center of surface (height ÷ 2)

point.kinoko.centerx,(coordinate)

X coordinate where mushrooms grow.

Center of surface (width ÷ 2)

point.kinoko.centery,(coordinate)

Y coordinate where mushrooms grow.

20 pixels below the top of the surface (SSP).

point.basepos.x,(coordinate)

X coordinate of the base position for initial placement and saving the position of the window.
It is possible to adjust for misalignment, etc. when switching to images with different surface sizes.

Center of surface (width ÷ 2)

point.basepos.y,(coordinate)

Y coordinate of the base position for initial placement and saving the position of the window.
It is possible to adjust for misalignment, etc. when switching to images with different surface sizes.

Lower edge of surface.

Animation Intervals

Animation intervals

Summary

animation*.interval specifies the cycle and timing (trigger) at which the animation runs.

Combination specification (SSP extension)

In the case of SSP, animation intervals can combine specifications by listing multiple of them separated by "+". Since this specification was originally intended to be used for bind, be careful when specifying without bind, even if it is working.

Examples of combinations are listed below.

bind+always: An animation that executes continually when the dressup is on.
bind+runonce: An animation that is executed only once when switching to a surface with that dressup definition when the dressup is ON, or conversely, if the dressup is turned ON during the display of that surface.
bind+random,(numeric interval): An animation that occurs with a probability of (1/numeric interval) per second when that dressup is ON.
bind+periodic,(numeric interval): An animation that occurs every (numeric interval) seconds when the dressup is ON.
bind+runonce+random,5: An animation that is executed once when switching to a surface with that dressup definition when the dressup is ON, or conversely, if the dressup is turned ON during the display of that surface. After that, it will be executed with a probability of 1/5 each second.

If other specifications are added to bind with the "+" delimiter, the bind interval loses its original property that the wait parameter of the pattern definition is ignored and the image is composited with the base surface as a still image.

In specifications that require parameters, such as random, periodic, and talk, the parameters should be written at the end of the combination specification.

The following is incorrect.

animation0.interval,random,5+bind

The following is correct.

animation1.interval,bind+random,5

Inteval specifications with parameters cannot be combined with each other.

sometimes

Play with a probability of 1 in 2 per second while on that surface.

rarely

Play with a probability of 1 in 4 per second while on that surface.

random,(numeric interval)

Play with a probability of 1 in (numeric interval) per second while on that surface.

periodic,(numeric interval)

Play regularly every (numeric interval) seconds while on that surface.

always

Loop playback while on that surface.

runonce

Play only once when the surface is switched to.

never

Will not execute automatically. Specify this for animations that should not play except when called by start or alternativestart methods from other animations, or by commands such as SakuraScript's \i[*] tag.

yen-e

Play when the \e tag is executed while on that surface.

talk,(numeric interval)

Play when text is displayed in a balloon while on that surface.
The animation is run every (number) characters.

bind

The animation is defined as a dressup for that surface.

Drawing Methods

Drawing methods

Summary

Methods for compositing and drawing each frame (part) in animation pattern definitions and element definitions.

In addition to compositing images, there are methods for various roles such as replacing the base surface (base), moving the base surface (move), and inserting and executing other animations (insert, start, stop, alternativestart, alternativestop).

Handling of drawing methods in dressup

In dressup definitions, methods that are not image composition (move, insert, start, stop, alternativestart, alternativestop) are invalid (treated as overlay). However, base is valid if and only if it is used as the first pattern, allowing a mechanism such as replacing the base surface only when that dressup is turned on.

The add and bind methods, which are implemented as methods for dressup, are synonymous with overlay in terms of implementation. In the case of dressup, the effect is the same no matter which of these three methods is specified.

Handling of drawing methods in element definitions

In element definitions, methods that are not image composition (move, insert, start, stop, alternativestart, alternativestop) are invalid (treated as overlay).

The add and bind methods used for dressups are also invalid. (However, in the current implementation of SSP, invalid specifications are replaced with overlay, so it will render as specified.)

It is obvious that most drawing methods specified in the first element (element0, or later if surface*.png does not exist) are synonymous with base. However, the asis method is useful in that it displays the transparency of the colors as they are.

Note that when an element-composited surface is used as an animation part, the result of the element compositing is treated as if it were a single image. Note that this implementation is from SSP2.3.53, and was undefined prior to that.

Differences and similarities between the compositing of elements, animations, and dressups

The meaning of compositing differs between elements, animations, and dressups.

The purpose of the element definition is to obtain a single still image that will serve as the base surface. In the element definition, each image is composited on the previous, and a single still image is obtained as a result of the compositing.

Like the element definition, the dressup definition's purpose is also to obtain a still image, so the flow of the compositing is similar to that of the element definition. In the pattern definition of a dressup, the first pattern is composited on the base surface, and then the next pattern is composited on the previous pattern, and so on, until a still image is obtained as the final result. Thus, the dressup behaves as if it were integrated with the base surface.

On the other hand, a normal animation that is not a dressup expresses a moving image, and its flow is very different from the previous two. Each pattern definition of an animation is a definition of each frame that makes up the animation, and is independent of the others. Since each pattern definition creates a new frame by compositing the base surface and a new image, the compositing result of the previous pattern definition (previous frame) does not affect the next frame. In this way, new frames are drawn one after another to express a moving image.

In both cases, however, the compositing method has the function of compositing the "original image" and the "new image". In ukadoc, for convenience, the "original image" is called the base layer, and the "new image" is called the new layer in the description of drawing methods.

In other words, each pattern definition in an animation creates a frame by compositing a new layer using the base surface as the base layer. On the other hand, in dressup and element composition, one still image is obtained as a result of the process of repeatedly compositing

Drawing methods and transparency colors

The color of the first pixel in the upper left corner of the image is treated as the transparency color, and that color will be rendered as transparency in the actual display. This is also the case for surfaces used in pattern definitions and images used in element defitnitions.

The RGB values of the transparency color of each image to be composited do not need to be uniform.

Each drawing method has its own characteristics regarding the handling of transparency colors, so please refer to each item.

Misalignment/overlap between the base layer and new layer

The behavior when compositing the new layer into an area outside the base layer (because of image size or position) is left to the baseware implementation.

In MATERIA, areas that extend outside of the base layer are simply not displayed.

In CROW, a composition that extends outside of the base layer will not be rendered correctly.

In SSP, the new layer is allowed to extend beyond the base layer, and the behavior is such that the base layer compensates by adding transparent area for as far as the new layer extends beyond the base layer.

Conversely, the area outside the new layer is an empty area that is different from the transparent area, and nothing happens during compositing, leaving the contents of the base layer intact. This is a particularly important point to note, especially for understanding the replace and reduce methods, where all transparent areas of the new layer affect the compositing result.

base

The base surface is completely replaced with the new layer. Collisions are also replaced with the ones defined on the new layer's surface.
By layering patterns of this method, the result is an animation created by redrawing the entire surface (like a flipbook).
X and Y coordinates are ignored in pattern definitions that specify this drawing method.
For dressups and elements, the base method can only be used at the beginning (element0, pattern0). Otherwise, it is read as overlay.

overlay

Simply overlay the new layer on top of the base layer.
It can also be used for dressup and elements (In the case of dressup, add and bind have this same effect).

overlayfast

Overlay the new layer based on the opacity of the base layer.
In semi-transparent areas of the base layer, the less transparent the area is, the more fully the new layer is composited. If the area is opaque, the new layer is composited completely. If the area is fully transparent, the new layer is not composited at all.
This is the opposite of the interpolate method.
Can also be used in dressup and elements.

overlaymultiply

Multiply and overlay the new layer based on the opacity of the base layer.
The behavior is the same as overlayfast and the outline remains the same, but instead of overwriting, a multiplicative composite operation is applied to the current surface.
Can also be used in dressup and elements.

2.5.91

replace

Replace part of the base layer with the new layer.
Areas with transparency color and areas that are semi-transparent with transparency information are also overwritten, leaving no information from the base layer.
The area outside of the new layer is an empty area and is not treated as an area with 100% transparency. Nothing is composited in this area, and the drawing of the base layer simply remains as it is.
Can also be used in dressup and elements.

interpolate

Overlay the new layer based on the transparency of the new layer.
In semi-transparent areas of the base layer, the more transparent the area is, the more fully the new layer is composited. If the area is fully transparent, the new layer is composited completely. If the area is opaque, the new layer is not composited at all.
This is the opposite of the overlayfast method.
Can also be used in dressup and elements.

asis

Similar to overlay but it ignores the transparency of the new layer (transparency color and the alpha channel of the image itself if pna or seriko.use_self_alpha is used).
Can also be used in dressup and elements.
The display is undefined when an element-composited surface is used with the asis method as a part of an animation, but on Windows, transparent areas will usually be displayed as black (#000000) regardless of the original transparency color of the image.

move

The display position of the base layer is shifted by the specified coordinates from its original position.
The change in display position with the move method is instantaneous, not continuous.
Positive X values move to the right side, and positive Y values move downwards.
Surface IDs are ignored in pattern definitions that specify this drawing method.
Cannot be used in dressup or elements.

bind

Use the new layer as a dressup part.
It was the only method available when the only way to create dressup parts was to simply stack one surface on top of another. It is now used interchangeably with the add method.
It is processed in the same way as overlay.
Usage in non-dressup animations and elements is undefined.

add

The new layer is overlaid on the base layer as a dressup part.
It is processed in the same way as overlay.
Usage in non-dressup animations and elements is undefined.

reduce

Composite the transparency of the base layer and new layer. This has the effect of "cropping" the base layer using the transparency information of the new layer.
The opacity of the base layer and the new layer are multiplied (the transparency color is treated as a fully transparent area).
For example, an area where the base layer has 40% opacity and the new layerhas 60% opacity becomes an area with 24% opacity / 76% transparency after compositing.
Information other than transparency (RGB values) is simply ignored.
The area outside the range of the new layer is treated as transparency.
This method is provided for dressup, but can also be used for animations and elements that are not dressup.

insert,ID

Inserts the dressup group (animation with a bind interval) of the specified ID (the number of the * in animation*) at this position.
This method is provided for dressup, and is undefined for use with animations and elements that are not dressup.
For example, if dressup A has is positioned so that it is partially in front of and partially behind dressup B, a natural display of the front-back structure can be achieved by inserting dressup B between the back part and front part of dressup A. In this way, the integrity of the display is maintained regardless whether dressup B is displayed or not.
It is also possible to use insert in the target surface (nesting).
Note that this only reserves the display order of dressup A and B, and does not force dressup B to be displayed.
Whether or not dressup B is actually displayed depends on the enable/disable status of dressup B.

start,ID

Play the animation with the specified ID (the number of the * in animation*).
Surface ID, wait, and X and Y coordinates are ignored in pattern definitions that specify this drawing method.
Cannot be used in dressup or elements.

stop,ID

Stop the animation with the specified ID (the number of the * in animation*).
Surface ID, wait, and X and Y coordinates are ignored in pattern definitions that specify this drawing method.
Cannot be used in dressup or elements.

alternativestart,(ID1,ID2...)

Play the animation of one of the specified ID numbers (the number of the * in animation*).
Surface ID, wait, and X and Y coordinates are ignored in pattern definitions that specify this drawing method.
In SSP, it is valid even if [] is used instead of parenthesis, or the delimiter "." is used instead of ",".
Cannot be used in dressup or elements.
Old definition:alternativestart,[ID1,ID2...]

alternativestop,(ID1,ID2...)

Stop the animation of one of the specified ID numbers (the number of the * in animation*).
Surface ID, wait, and X and Y coordinates are ignored in pattern definitions that specify this drawing method.
In SSP, it is valid even if [] is used instead of parenthesis, or the delimiter "." is used instead of ",".
Cannot be used in dressup or elements.

parallelstart,(ID1,ID2...)

Play animations of all specified ID numbers (the number of the * in animation*).
Surface ID, wait, and X and Y coordinates are ignored in pattern definitions that specify this drawing method.
In SSP, it is valid even if [] is used instead of parenthesis, or the delimiter "." is used instead of ",".
Cannot be used in dressup or elements.

parallelstop,(ID1,ID2...)

Stop animations of all specified ID numbers (the number of the * in animation*).
Surface ID, wait, and X and Y coordinates are ignored in pattern definitions that specify this drawing method.
In SSP, it is valid even if [] is used instead of parenthesis, or the delimiter "." is used instead of ",".
Cannot be used in dressup or elements.

surface.alias Brace

surface.alias brace examples

sakura.surface.alias
{
Default,[0]
Shy,[1,101,201]
Surprised,[2]
}

The settings for side characters are written as kero.surface.alias and char*.surface.alias (char* is for SSP only).

alias.txt

Until MATERIA period453, the alias brace specification was written in a dedicated file called alias.txt instead of surfaces.txt.

Today the description is integrated into surfaces.txt, but CROW and SSP both maintain compatibility, it is possible to create a separate alias.txt file.

*,[*]

Set an arbitrary alias ID for the surface ID.
For example, surprise,[2] means that \s[surprise] has the same meaning as \s[2].
You can also specify multiple surfaces separated by commas, e.g., 1,[1,11,21].
In this case, \s[1] will randomly select from 1,11,21.

No behavior

Cursor Brace

Cursor brace examples

sakura.cursor
{
mouseup0,Head,system:hand
mousedown0,Head,system:finger

mouseup1,Bust,system:hand
mousedown1,Bust,system:grip
}

The settings for side characters are written as kero.cursor and char*.cursor

mouseup*,(collision ID),(filename)

Set the cursor file to be displayed when on top of a collision.
The * part is a number that must be unique in the mouseup definitions for this scope.
The name of the collision is the name set in the collision definition.
The filename is the cursor filename (cur/ani). Instead of a filename, the system cursor specification described below can also be used.

system:finger (when the collision name is bust, system:hand)

mousedown*,(collision ID),(filename)

Set the cursor file to be displayed when a mouse button is pressed on a collision.
The * part is a number that must be unique in the mousedown definitions for this scope.
The name of the collision is the name set in the collision definition.
The filename is the cursor filename (cur/ani). Instead of a filename, the system cursor specification described below can also be used.

system:finger (when the collision name is bust, system:grip)

mouserightdown*,(collision ID),(filename)

Set the cursor file to be displayed when the right mouse button is pressed on a collision.
The * part is a number that must be unique in the mouserightdown definitions for this scope.
The name of the collision is the name set in the collision definition.
The filename is the cursor filename (cur/ani). Instead of a filename, the system cursor specification described below can also be used.

system:finger

2.6.14

mousewheel*,(collision ID),(filename)

Set the cursor file to be displayed when the mouse wheel is scrolled on a collision.
The * part is a number that must be unique in the mousewheel definitions for this scope.
The name of the collision is the name set in the collision definition.
The filename is the cursor filename (cur/ani). Instead of a filename, the system cursor specification described below can also be used.

system:arrow

mousehover*,(collision ID),(filename)

Set the cursor file to be displayed when the mouse is on a collision and is not moved for a while.
The * part is a number that must be unique in the mousehover definitions for this scope
The name of the collision is the name set in the collision definition.
The filename is the cursor filename (cur/ani). Instead of a filename, the system cursor specification described below can also be used.

system:arrow

System Cursors

If you specify one of these instead of a cursor file, you can display a variant of the currently used cursor.

system:arrow

Arrow

system:cross

Cross

system:no

Prohibited symbol

system:hand

Hand

system:grip

Grabbing hand

system:finger

Pointing finger

system:wait

system:text

system:move

Movement arrow

system:help

Tooltip Brace

Tooltip brace examples

sakura.tooltips
{
Bust,I'll be angry.
Head,It hurts when it is poked.
Shoulder,Click and hold to display the communicate box.
}

The settings for side characters are written as kero.tooltips and char*.tooltips

(Collision name),(Display contents)

Set the text of the tooltip to be displayed when hovering over the collision.

No behavior

Shell Settings - surfaces.txt

Shell - surfaces.txt

Descript Brace

Surface Brace

Animation Intervals

Drawing Methods

surface.alias Brace

Cursor Brace

System Cursors

Tooltip Brace

Translated Document

surfaces.txt

Summary

Basic format

Usage example

surfaces.txt or surfaces**.txt (SSP only)

Descript brace

Descript brace example

Surface brace

Surface brace examples

Animations (SERIKO)

Summary

Basic format and description examples

Relationship between each animation

Dressups (MAYUNA)

Summary

Basic format and description examples

Available drawing methods

Specification of bind combination intervals

Multiple dressups definition (SSP only)

Regarding the old and new SERIKO definitions

What are the old and new definitions of SERIKO?

Differences between new and old definitions

Advantages of using the new definition

ID specifications possible for surface* braces

surface* braces and surface.append* braces

Base surfaces

Base surfaces

Base surface entity

Position and order of components

Upper and lower

Vertical structure of different parts

Vertical structure of the base surface and each animation

Vertical structure of collisions

Allocation of surface IDs

Animation Intervals

Animation intervals

Summary

Combination specification (SSP extension)

Drawing Methods

Drawing methods

Summary

Handling of drawing methods in dressup

Handling of drawing methods in element definitions

Differences and similarities between the compositing of elements, animations, and dressups

Drawing methods and transparency colors

Misalignment/overlap between the base layer and new layer

surface.alias Brace

surface.alias brace examples

alias.txt

Cursor Brace

Cursor brace examples

System Cursors

Tooltip Brace

Tooltip brace examples