OpenWebGAL

https://docs.openwebgal.com/
Admin
OpenWebGAL is a development platform and engine that provides tools and guides for creating,...
Tokens:9,524
Snippets:77
Trust Score:6.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get User Input with Options

Source: https://docs.openwebgal.com/script-reference/commands/getUserInput

Demonstrates how to use the getUserInput function to prompt the user for input, specifying the variable to store the input, the title of the input prompt, the text for the confirmation button, and a default value.

```N/A
角色B:真的是太感谢您了，能告诉我您的名字吗？;
getUserInput:player_name -title=您的名字 -buttonText=确认 -defaultValue=Bob;
角色B:{player_name}，我记住了。;
```

--------------------------------

### Change Scene Example

Source: https://docs.openwebgal.com/script-reference/commands/changeScene

This snippet demonstrates the usage of the changeScene command to switch to a new scene. It also includes commands to change backgrounds, character figures, and dialogue, followed by explicit instructions to clear the previous scene elements.

```Project Script
changeBg:home/character_a/bedroom.png;
changeFigure:main_character/character_a/thinking.png -next;
角色A:今天去她家里吧！;
changeBg:none -next; 手动关闭背景
changeFigure:none -next; 手动关闭立绘
:; 手动关闭对话框
changeScene:chapter_01/part_02.txt;
```

--------------------------------

### OpenWebGAL 'next' Parameter Example

Source: https://docs.openwebgal.com/script-reference/commands/global

Demonstrates the use of the 'next' parameter to synchronize statement execution. When 'next' is true, subsequent statements are executed simultaneously until a 'next' false statement is encountered. Some commands support 'next' by default, while others like 'wait' are incompatible.

```OpenWebGAL
label:loop;
;
changeBg:bg.png -next;
changeFigure:1/open_eyes.png -next -id=aaa;
角色名:背景，角色与这段话同时出现;
;
changeBg:none -next;
changeFigure:none -next -id=aaa;
角色名:背景，角色同时退场;
;
jumpLabel:loop;

```

--------------------------------

### OpenWebGAL 'continue' Parameter Example

Source: https://docs.openwebgal.com/script-reference/commands/global

Shows the 'continue' parameter, which automatically executes the next statement after the current one finishes, even if auto-play is not enabled. This is useful for creating continuous animations or timed events. Some commands support 'continue' natively.

```OpenWebGAL
changeBg:bg.png -next;
changeFigure:1/open_eyes.png -transform={"position":{"x":-500}} -id=aaa -next;
changeFigure:2/open_eyes.png -transform={"position":{"x":500}} -id=bbb;
;
label:loop;
;
setTransform:{"position":{"x":500}} -target=aaa -continue;
setTransform:{"position":{"x":-500}} -target=bbb -continue;
setTransform:{"position":{"x":-500}} -target=aaa -continue;
setTransform:{"position":{"x":500}} -target=bbb -continue;
;
jumpLabel:loop;

```

--------------------------------

### setTransform: Controlling Brightness and Duration

Source: https://docs.openwebgal.com/script-reference/commands/setTransform

Demonstrates how to use setTransform to adjust the brightness of a character and set the animation duration. This example also shows the initial figure change command.

```script
changeFigure:1/open_eyes.png -id=aaa;
setTransform:{"brightness":0.5} -target=aaa -duration=500;
```

--------------------------------

### OpenWebGAL 'when' Parameter Example

Source: https://docs.openwebgal.com/script-reference/commands/global

Illustrates the 'when' parameter for conditional execution based on string expressions. A statement is executed only if its 'when' condition evaluates to true. This is used for controlling game logic and dialogue progression.

```OpenWebGAL
label:start;
;
setVar:coin=10;
角色名:我现在有 {coin} 块钱。
;
label:buy;
;
setVar:coin=coin-3 -when=coin>=3;
角色名:花 3 块钱买汽水，剩下 {coin} 块。
;
角色名:没钱买 3 块钱的汽水了，只剩下 {coin} 块。 -when=coin<3;
jumpLabel:start -when=coin<3;
;
jumpLabel:buy;

```

--------------------------------

### setTransition: Specify Target for Animation

Source: https://docs.openwebgal.com/script-reference/commands/setTransition

This example illustrates how to set the target for a transition animation. The 'target' parameter can refer to predefined stage elements like 'fig-center', 'fig-left', 'fig-right', or custom IDs assigned to figures.

```Mahiru Script
changeFigure:1/open_eyes.png -id=aaa -next;
setTransition: -target=aaa -enter=enter-from-left;
角色A: 你好！
```

--------------------------------

### Set Global and Local Variables with setVar -global in WebGAL

Source: https://docs.openwebgal.com/script-reference/commands/setVar

This example illustrates how to use the '-global' parameter with the setVar command to define persistent variables that affect the entire game session, as opposed to temporary variables scoped to the current scene. It shows setting a global flag to differentiate playthroughs.

```WebGAL
; 假设这是新游戏的开头
jumpLabel:another_life -when=multiple_playthroughs;
;
setVar:multiple_playthroughs=false -global; 是否为多周目游戏
changeScene:chapter_01/part_01.txt;
;
label:another_life;
神秘的声音:如果有机会，你会选择过另一种人生吗？;
changeScene:chapter_01/part_01_extra.txt;
;
; 假设这是最后一章的结束部分
setVar:multiple_playthroughs=true -global; 设置为多周目游戏

```

--------------------------------

### Set and Modify Variables with setVar in WebGAL

Source: https://docs.openwebgal.com/script-reference/commands/setVar

This snippet demonstrates the core functionality of the setVar command, allowing for the assignment of values or expressions to variables. It supports numeric, boolean, and string types, with automatic conversion for unrecognized types. The example shows conditional logic based on variable values.

```WebGAL
setVar:char_b_fav=15; 角色 B 初始好感度
角色B:呐呐，看不看得出来我今天哪里不一样？;
choose:缎带:add|你变胖了:minus;
;
label:add;
角色A:是换了缎带吧。;
setVar:char_b_fav=char_b_fav+10; 角色 B 好感度 +10;
角色B:答对了，怎么样，你觉得好看吗？;
角色A:嗯，很适合你。;
jumpLabel:go_out;
;
label:minus;
角色A:你变胖了。;
setVar:char_b_fav=char_b_fav-10; 角色 B 好感度 -10;
角色B:你这人好无趣唉......;
;
label:go_out;
角色A:对了，今天晚上你有空吗？;
;
角色B:今晚没有安排，怎么了？ -when=char_b_fav>10;
changeScene:chapter_01/part_02.txt -when=char_b_fav>10;
;
角色B:没有。不好意思我先走了。;
:角色 B 离开了。;
;
```

--------------------------------

### 克隆 WebGAL 源代码

Source: https://docs.openwebgal.com/getting-started

使用 Git 克隆 OpenWebGAL 项目的源代码仓库，这是从源代码开始开发的第一步。

```bash
git clone https://github.com/OpenWebGAL/WebGAL.git
```

--------------------------------

### Display Full-Screen Text

Source: https://docs.openwebgal.com/script-reference/commands/intro

The basic 'intro' command displays provided text in full-screen. Multiple lines can be separated by '|'.

```OpenWebGal Commands
intro:这是第一行文字|这是第二行文字|这是第三行文字;
```

--------------------------------

### 打包 WebGAL 项目

Source: https://docs.openwebgal.com/getting-started

使用 Yarn 打包 WebGAL 项目以生成生产环境所需的构建文件。

```bash
yarn build
```

--------------------------------

### 安装依赖和启动开发服务器

Source: https://docs.openwebgal.com/getting-started

安装项目依赖并启动 Vite 开发服务器以进行本地调试和开发。

```bash
npm install yarn -g
yarn
yarn dev
```

--------------------------------

### Apply Animation to Full-Screen Text

Source: https://docs.openwebgal.com/script-reference/commands/intro

Choose from various animation effects like 'fadeIn', 'slideIn', 'typingEffect', 'pixelateEffect', or 'revealAnimation' for displaying text.

```OpenWebGal Commands
intro:这是第一行文字|这是第二行文字|这是第三行文字 -animation=slideIn;
```

--------------------------------

### Forward Text Display with User Interaction

Source: https://docs.openwebgal.com/script-reference/commands/intro

When 'true', the next line of text is displayed only after manual player clicks, automatically setting 'hold' to 'true'.

```OpenWebGal Commands
intro:这是一段话 -useForward;
```

--------------------------------

### Set Background Image for Full-Screen Text

Source: https://docs.openwebgal.com/script-reference/commands/intro

Use a specified image path as the background for the full-screen text. If not set, 'backgroundColor' is used.

```OpenWebGal Commands
intro:这是一段话 -backgroundImage=bg.png;
```

--------------------------------

### Hold Full-Screen Text Until Player Input

Source: https://docs.openwebgal.com/script-reference/commands/intro

When set to 'true', the text display pauses after completion, requiring player interaction to proceed.

```OpenWebGal Commands
intro:这是一段话 -hold;
```

--------------------------------

### Play, Replace, or Stop Sound Effects

Source: https://docs.openwebgal.com/script-reference/commands/playEffect

Demonstrates the basic usage of the playEffect command. It shows how to play a sound effect, replace an existing one with a new file, and stop playback by setting the path to 'none' or leaving it empty.

```text
; If no sound effect is present, this line plays a sound effect.
playEffect:rain.wav;
; If a sound effect is already present, this line replaces the sound effect.
playEffect:heavy_rain.wav;
; If 'none' is specified or the field is left empty, this line stops playing the sound effect.
playEffect:none;
```

--------------------------------

### Play Background Music (BGM)

Source: https://docs.openwebgal.com/webgal-script/audio

Plays background music by placing MP3 files in the 'bgm' folder and using the 'bgm' command. Supports optional '-volume' for loudness (0-100, default 100) and '-enter' for fade-in duration in milliseconds (default 0).

```text
bgm:夏影.mp3;

```

```text
bgm:夏影.mp3 -volume=30;

```

```text
bgm:夏影.mp3 -enter=3000;

```

```text
bgm:none -enter=3000;

```

--------------------------------

### Set Delay Between Lines of Full-Screen Text

Source: https://docs.openwebgal.com/script-reference/commands/intro

Control the delay in milliseconds between the display of each line of text.

```OpenWebGal Commands
intro:这是第一行文字|这是第二行文字|这是第三行文字 -delay=1000;
```

--------------------------------

### Set Font Size for Full-Screen Text

Source: https://docs.openwebgal.com/script-reference/commands/intro

Customize the font size of the full-screen text using predefined values like 'small', 'medium', or 'large'.

```OpenWebGal Commands
intro:这是一段话 -fontSize=large;
```

--------------------------------

### Play, Switch, Stop Background Music

Source: https://docs.openwebgal.com/script-reference/commands/bgm

Demonstrates the basic usage of the 'bgm' command to play, switch, or stop background music by specifying the audio file path. An empty path or 'none' stops playback.

```N/A
; If there is no background music, this statement means to play background music.
bgm:01.wav;
; If background music already exists, this statement means to switch background music.
bgm:02.wav;
; If none is filled in or not filled in, this statement means to stop playing background music.
bgm:;
```

--------------------------------

### Set Background Color for Full-Screen Text

Source: https://docs.openwebgal.com/script-reference/commands/intro

Set the background color for the full-screen text using RGBA format. The default is black.

```OpenWebGal Commands
intro:这是一段话 -backgroundColor=rgba(22,22,22,0.8);
```

--------------------------------

### Apply UI Styles

Source: https://docs.openwebgal.com/script-reference/commands/applyStyle

Replaces existing UI styles with new ones defined in the UI template. Supports replacing single or multiple styles at once using the format 'oldStyle->newStyle'.

```OpenWebGal Command Language
; 将角色名背景替换为红色，前提是在 UI 模板里写了新样式
applyStyle:TextBox_ShowName_Background->TextBox_ShowName_Background_Red;
角色名:这是一句话;
; 同时替换多个样式
applyStyle:TextBox_ShowName_Background->TextBox_ShowName_Background_Green,TextBox_main->TextBox_main_Black;
```

--------------------------------

### Set Button Text for getUserInput

Source: https://docs.openwebgal.com/script-reference/commands/getUserInput

Illustrates how to customize the text displayed on the confirmation button for the getUserInput prompt using the '-buttonText' parameter.

```N/A
getUserInput:player_name -buttonText=确认;
```

--------------------------------

### Incorrect Style Replacement Pattern

Source: https://docs.openwebgal.com/script-reference/commands/applyStyle

Demonstrates an incorrect pattern for applying styles where a style is replaced multiple times sequentially. The command should always refer to the original style name for replacement.

```OpenWebGal Command Language
applyStyle:原样式名->新样式名1;
applyStyle:新样式名1->新样式名2; 错误
applyStyle:原样式名->新样式名2;
```

--------------------------------

### Set Default Value for getUserInput

Source: https://docs.openwebgal.com/script-reference/commands/getUserInput

Explains how to pre-fill the input field with a default value using the '-defaultValue' parameter in the getUserInput function.

```N/A
getUserInput:player_name -defaultValue=Bob;
```

--------------------------------

### 定制引擎目录结构

Source: https://docs.openwebgal.com/derivative

展示了定制引擎的标准文件组织方式。解压后的定制引擎目录应包含 assets、game、icons、index.html、manifest.json 和 webgal-serviceworker.js 文件。

```text
name
├── assets
├── game
├── icons
├── index.html
├── manifest.json
└── webgal-serviceworker.js
```

--------------------------------

### WebGAL 问题报告模板

Source: https://docs.openwebgal.com/info

用于报告 WebGAL 引擎或编辑器缺陷的说明模板。它包含占位符，用于描述问题、附带截图，并展示出现问题的具体代码。

```markdown
你好，我是[名称或昵称]，在使用 WebGAL [引擎/编辑器] 时，出现了以下问题：
[在此处简单描述问题表现]
[如果有相关截图，附上相关截图]
出现问题的具体代码是这样的：
```
在这里展示具体出现故障的代码或编辑器编辑页面的截图

```
```

--------------------------------

### Apply Parameters Without Interrupting Music

Source: https://docs.openwebgal.com/script-reference/commands/bgm

Shows how to apply new parameters, such as volume, to the currently playing background music without interrupting the playback. This allows for dynamic adjustments.

```N/A
bgm:morning.wav;
; Adjust volume without interrupting background music
bgm:morning.wav -volume=50;
```

--------------------------------

### Looping and Layering Sound Effects with IDs

Source: https://docs.openwebgal.com/script-reference/commands/playEffect

Illustrates how to use the '-id' parameter with the playEffect command. Assigning an ID allows sound effects to loop, and different IDs enable the layering of multiple sound effects simultaneously.

```text
; Loop the footsteps sound effect
playEffect:footsteps.wav -id=footsteps;
; Loop the rain sound effect
playEffect:rain.wav -id=rain;
; Play thunder sound effect once
playEffect:thunder.wav;
```

--------------------------------

### Play Voice Lines

Source: https://docs.openwebgal.com/webgal-script/audio

Plays voice lines by placing OGG files in the 'vocal' folder and referencing them with a '-VoiceFilename' parameter in dialogue. Supports an optional '-volume' parameter for adjusting loudness (0-100, default 100).

```text
比企谷八幡:刚到而已 -V3.ogg;

```

```text
雪之下雪乃:你到得真早 -V1.ogg;
对不起，等很久了吗？ -V2.ogg;

```

```text
比企谷八幡:刚到而已 -V3.ogg -volume=30;

```

--------------------------------

### Set Font Color for Full-Screen Text

Source: https://docs.openwebgal.com/script-reference/commands/intro

Specify the font color using RGBA format. The default color is black.

```OpenWebGal Commands
intro:这是一段话 -fontColor=rgba(48, 135, 206, 1);
```

--------------------------------

### Play Sound Effects

Source: https://docs.openwebgal.com/webgal-script/audio

Plays sound effects using the 'playEffect' command, typically with MP3 files. An optional '-volume' parameter can adjust the sound's loudness (0-100, default 100).

```text
playEffect:xxx.mp3;

```

```text
playEffect:xxx.mp3 -volume=30;

```

--------------------------------

### Unlock Audio for Gallery

Source: https://docs.openwebgal.com/webgal-script/audio

Unlocks audio files for in-game gallery viewing using the 'unlockBgm' command. It can be used without arguments to unlock all BGM, or with a filename and an optional '-name' parameter to assign a specific display name.

```text
; // 解锁bgm并赋予名称

```

```text
unlockBgm:s_Title.mp3 -name=Smiling-Swinging!!!;

```

--------------------------------

### Change Background Image (Entry, Replace, Exit)

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Demonstrates the basic usage of the 'changeBg' command for entering, replacing, or exiting background images. If the path is empty or 'none', the background exits. If no background exists, it enters.

```WebGAL Script
; If no background exists, this command indicates background entry.
changeBg:bg.png;
; If a background already exists, this command indicates background replacement.
changeBg:WebGAL_New_Enter_Image.png;
; If 'none' is specified or the path is empty, this command indicates background exit.
changeBg:none;
```

--------------------------------

### Place Mini Avatars

Source: https://docs.openwebgal.com/webgal-script/bg-and-figure

Syntax for displaying small avatars in the bottom-left corner of the text box. Avatars can be shown using 'miniAvatar' and removed by setting it to 'none'.

```WebGAL Script
miniAvatar:minipic_test.png;
miniAvatar:none;
```

--------------------------------

### WebGAL Terre 模板目录结构

Source: https://docs.openwebgal.com/derivative

说明了如何将定制引擎目录放置在 WebGAL Terre 的 assets/templates/Derivative_Engine 目录下，以使其在创建游戏时可用。正确的结构是 Derivative_Engine 下的 name 目录。

```text
Derivative_Engine
└── name
    ├── assets
    ├── game
    ├── icons
    ├── index.html
    ├── manifest.json
    └── webgal-serviceworker.js
```

--------------------------------

### changeBg: Background Management

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Manages background images for entry, replacement, and exit. You can specify the image path, set it to 'none' for exit, or omit the path if no background exists.

```APIDOC
## POST /websites/openwebgal/changeBg

### Description
Manages background images for entry, replacement, and exit. You can specify the image path, set it to 'none' for exit, or omit the path if no background exists.

### Method
POST

### Endpoint
/websites/openwebgal/changeBg

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **bg_path** (string) - Required - The path to the background image. Use 'none' or omit for background exit.
- **transform** (string) - Optional - JSON string to control transform and effects. Only applies during entry or replacement.
- **enter** (string) - Optional - Animation name for entry, overrides default fade-in.
- **exit** (string) - Optional - Animation name for exit, overrides default fade-out.
- **duration** (number) - Optional - Duration of the animation in milliseconds. Defaults to 1000.
- **ease** (string) - Optional - Easing type for animations. Defaults to 'easeInOut'.
- **unlockname** (string) - Optional - Name for CG gallery inclusion.
- **series** (string) - Optional - Name of the series for CG gallery inclusion. Requires `unlockname`.

### Request Example
```json
{
  "bg_path": "bg.png",
  "transform": "{\"position\":{\"x\":-50,\"y\":-20},\"rotation\":0.1,\"scale\":{\"x\":1.2,\"y\":1.2},\"brightness\":0.5,\"blur\":10}",
  "enter": "enter-from-left",
  "exit": "exit-to-right",
  "duration": 200,
  "ease": "easeOut",
  "unlockname": "MyCg01",
  "series": "MySeries01"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "message": "Background changed successfully."
}
```
```

--------------------------------

### Include Image in CG Gallery with Series - unlockCg Command

Source: https://docs.openwebgal.com/script-reference/commands/unlockCg

This command adds an image to the CG gallery, assigning it a display name and organizing it into a specified series. If the 'series' parameter is omitted or empty, the image is added to the default series. An image can only belong to one series; if included in multiple series, it will remain in the last series specified. The command demonstrates adding an image with both a name and a series.

```OpenWebGAL Command
unlockCg:chapter_03/date.png -name=第一次约会 -series=角色B;
```

--------------------------------

### Set Input Title for getUserInput

Source: https://docs.openwebgal.com/script-reference/commands/getUserInput

Shows how to set a custom title for the user input prompt using the '-title' parameter in the getUserInput function.

```N/A
getUserInput:player_name -title=您的名字;
```

--------------------------------

### Register Music with Unlock Name

Source: https://docs.openwebgal.com/script-reference/commands/bgm

Shows how to register background music with a specific name for the BGM Appreciation feature using the '-unlockname' parameter. This allows the music to be displayed with a custom title.

```N/A
bgm:01.wav -unlockname=MyBgm01;
```

--------------------------------

### Set Background Music Fade-In Time

Source: https://docs.openwebgal.com/script-reference/commands/bgm

Demonstrates setting the fade-in duration for background music using the '-enter' parameter. The time is specified in milliseconds, with a default of 0.

```N/A
bgm:01.wav -enter=1500;
bgm:02.wav -enter=1500;
```

--------------------------------

### Categorize Music into Series

Source: https://docs.openwebgal.com/script-reference/commands/bgm

Illustrates how to categorize background music into specific series for the BGM Appreciation feature using the '-series' and '-unlockname' parameters. Music is added to the default series if '-series' is omitted.

```N/A
bgm:01.wav -unlockname=MyBgm01 -series=MySeries01;
```

--------------------------------

### Change Background and Character Sprites

Source: https://docs.openwebgal.com/webgal-script/bg-and-figure

Commands to change the current background and character sprites. 'changeBg' and 'changeFigure' are used, with 'none' to remove them. The '-next' parameter can be used to immediately execute the next command after the change.

```WebGAL Script
changeBg:testBG03.jpg;
changeFigure:testFigure02.png;
changeBg:none;
changeFigure:none;
```

```WebGAL Script
changeBg:testBG03.jpg -next;
changeFigure:testFigure02.png -next;
一色:谢谢学姐！;
```

--------------------------------

### Set Background Music Volume

Source: https://docs.openwebgal.com/script-reference/commands/bgm

Illustrates how to set the volume for background music using the '-volume' parameter. The value ranges from 0 to 100, with a default of 100.

```N/A
bgm:01.wav -volume=100;
bgm:01.wav -volume=50; Adjust volume
```

--------------------------------

### Free Character Sprites with IDs

Source: https://docs.openwebgal.com/webgal-script/bg-and-figure

Enables precise control over character sprites, including using IDs for more than three sprites or for specific management. Sprites can be closed using their ID.

```WebGAL Script
changeFigure:testFigure03.png -left -id=test1;
changeFigure:none -id=test1;
```

--------------------------------

### Add Music to BGM Appreciation

Source: https://docs.openwebgal.com/script-reference/commands/unlockBgm

This command adds a music file to the BGM appreciation feature. It requires the path to the music file. Optionally, a name can be provided for display in the appreciation list.

```command
unlockBgm:school/morning.mp3 -name=学校的早晨;
```

--------------------------------

### Set Custom Animation using setAnimation

Source: https://docs.openwebgal.com/script-reference/commands/setAnimation

Applies a custom animation (e.g., 'shake') to a specified target object (e.g., 'aaa'). This is the primary method for setting predefined animations.

```OpenWebGal Script
setAnimation:shake -target=aaa;
```

--------------------------------

### Include Image in CG Gallery with Name - unlockCg Command

Source: https://docs.openwebgal.com/script-reference/commands/unlockCg

This command adds an image to the CG gallery and assigns it a specific display name. If the 'name' parameter is omitted or empty, the image will not be included in the gallery. Each image can only have one display name; subsequent attempts to name the same image will overwrite the previous one. If no name is provided, the image path will be used as the name.

```OpenWebGAL Command
unlockCg:chapter_03/date.png -name=第一次约会;
```

--------------------------------

### setTransform: Using writeDefault Parameter

Source: https://docs.openwebgal.com/script-reference/commands/setTransform

Illustrates the use of the `writeDefault` parameter in setTransform. When true, unassigned properties are reset to their default values; when false, they retain their current values.

```script
changeFigure:1/open_eyes.png -id=aaa;
setTransform:{"brightness":0.5} -target=aaa -duration=500 -writeDefault;
```

--------------------------------

### setTransform: Creating Persistent Animations with 'keep'

Source: https://docs.openwebgal.com/script-reference/commands/setTransform

Shows how to use the 'keep' parameter with setTransform to create animations that persist across multiple script statements. The animation continues until it naturally ends, is interrupted by another setTransform, setAnimation, or setTempAnimation on the same target, or if the 'next' parameter is used.

```script
; 假设这是一个特别长的动画
setTransform:{"scale":{"x":2,"y":2}} -target=aaa -duration=10000;
角色A: 第一句话;
角色A: 第二句话;
角色A: 第三句话;
; 这会打断 aaa 的跨语句动画，并播放新动画
setTransform:{"scale":{"x":1,"y":1}} -target=aaa -duration=10000;
```

--------------------------------

### Loop Sound Effects

Source: https://docs.openwebgal.com/webgal-script/audio

Enables sound effect looping by assigning an 'id' to the 'playEffect' command. The same 'id' can be used with 'playEffect:none' to stop the looping sound.

```text
playEffect:xxx.mp3 -id=xxx;
playEffect:none -id=xxx; // 停止这个循环的效果音

```

--------------------------------

### Set Transformations on Existing Sprites

Source: https://docs.openwebgal.com/webgal-script/bg-and-figure

Applies transformation effects to already displayed sprites using the 'setTransform' command. The '-target' specifies the sprite (e.g., 'fig-center') and '-duration' controls the animation time.

```WebGAL Script
setTransform:{"position":{"x":100,"y":0}} -target=fig-center -duration=0;
```

--------------------------------

### setTransition: Define Entry and Exit Animations

Source: https://docs.openwebgal.com/script-reference/commands/setTransition

This snippet demonstrates how to use the setTransition function to apply entry and exit animations to specified targets. It requires a target ID and can specify either an 'enter' or 'exit' animation.

```Mahiru Script
changeFigure:1/open_eyes.png -id=aaa -next;
setTransition: -target=aaa -enter=enter-from-left;
角色A: 你好！
setTransition: -target=aaa -exit=exit-to-right;
changeFigure:none -id=aaa -next;
角色A: 再见！
```

--------------------------------

### Set Custom Entry Animation for Background

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Specifies a custom animation to be played when the background enters, overriding the default fade-in effect. The animation name is provided as a string.

```WebGAL Script
changeBg:bg.png -enter=enter-from-left;
```

--------------------------------

### Add Music with Series to BGM Appreciation

Source: https://docs.openwebgal.com/script-reference/commands/unlockBgm

This command adds a music file to the BGM appreciation feature and assigns it to a specific series. If no series is specified, the music is added to the default series. It also allows for a custom display name.

```command
unlockBgm:school/morning.mp3 -name=早晨 -series=学校;
```

--------------------------------

### Apply Transformations and Effects with setTransform

Source: https://docs.openwebgal.com/script-reference/commands/setTransform

Applies transformations and effects to a target element. It takes a JSON string for the transformation properties and can specify the target, duration, and behavior for unassigned properties. This command creates a single animation segment.

```script
changeFigure:character_a/normal.png -id=aaa;
; 向左移动
setTransform:{"position":{"x":-500},"saturation":0.8} -target=aaa -duration=500;
; 降低亮度
setTransform:{"brightness":0.5,"contrast":1.2} -target=aaa -duration=500;
```

--------------------------------

### Set Complex Animation: universalSoftIn

Source: https://docs.openwebgal.com/script-reference/commands/setComplexAnimation

Sets the 'universalSoftIn' complex animation, which provides a general transparency fade-in effect. This animation requires a target element and a duration in milliseconds.

```OpenWebGAL Script
setComplexAnimation:universalSoftIn -target=aaa -duration=1000;
```

```OpenWebGAL Script
setComplexAnimation:universalSoftIn -target=fig-center -duration=1000;
```

--------------------------------

### Set Easing Function for Background Animations

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Defines the easing function used for background entry and exit animations. This controls the acceleration and deceleration of the animation. The default is 'easeInOut'.

```WebGAL Script
changeBg:bg.png -ease=easeOut;
```

--------------------------------

### Position Character Sprites

Source: https://docs.openwebgal.com/webgal-script/bg-and-figure

Allows positioning character sprites in left, center, or right locations. Each position is independent and must be cleared separately if needed. The '-next' parameter can also be applied here.

```WebGAL Script
changeFigure:testFigure03.png -left;
changeFigure:testFigure04.png;
changeFigure:testFigure03.png -right;

changeFigure:none -left;
changeFigure:none;
changeFigure:none -right;
```

```WebGAL Script
changeFigure:testFigure03.png -left -next;
changeFigure:testFigure04.png -next;
changeFigure:testFigure03.png -right -next;
```

--------------------------------

### setTransition: Apply Exit Animation

Source: https://docs.openwebgal.com/script-reference/commands/setTransition

This snippet demonstrates the use of the 'exit' parameter in setTransition to specify a custom animation for an object's disappearance, replacing the default fade-out.

```Mahiru Script
changeFigure:1/open_eyes.png -id=aaa -next;
角色A: 你好！
setTransition: -target=aaa -exit=exit-to-right;
changeFigure:none -id=aaa -next;
角色A: 再见！
```

--------------------------------

### Apply Transform Effects to Background

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Applies various transform effects such as position, rotation, scale, brightness, and blur to the background image during entry or replacement. This parameter is ignored if the background is already on screen and only being modified.

```WebGAL Script
changeBg:bg.png -transform={"position":{"x":-50,"y":-20},"rotation":0.1,"scale":{"x":1.2,"y":1.2},"brightness":0.5,"blur":10};
```

--------------------------------

### Set Animation to Persist Across Statements (keep)

Source: https://docs.openwebgal.com/script-reference/commands/setAnimation

Applies an animation to a target and keeps it playing alongside subsequent script statements until the animation ends or is interrupted by another animation command for the same target. Often used with the 'next' parameter.

```OpenWebGal Script
; 假设这是一个特别长的动画
setAnimation:shake -target=aaa -keep;
角色A: 第一句话;
角色A: 第二句话;
角色A: 第三句话;
; 这会打断 aaa 的跨语句动画，并播放新动画
setAnimation:rotate -target=aaa -keep;
```

--------------------------------

### Define Multi-stage Animation with setTempAnimation

Source: https://docs.openwebgal.com/script-reference/commands/setTempAnimation

Sets a temporary animation by defining stages directly in the code. This is useful for creating custom animations without relying on external files. The animation stages are defined as a JSON array.

```script
changeFigure:1/open_eyes.png -id=aaa;
; 闪光弹动画
setTempAnimation:[{"duration":0},{"brightness":2,"contrast":0,"duration":200,"ease":"circIn"},{"brightness":1,"contrast":1,"duration":200},{"brightness":2,"contrast":0,"duration":200,"ease":"circIn"},{"brightness":1,"contrast":1,"duration":2500}] -target=aaa;
```

--------------------------------

### Set Temporary Animation

Source: https://docs.openwebgal.com/script-reference/commands/setTempAnimation

Sets a temporary animation for a specified target. Animations are defined as an array of keyframes, each with properties like duration, brightness, contrast, and easing functions.

```APIDOC
## POST /api/setTempAnimation

### Description
Sets a temporary animation for a specified target. Animations are defined as an array of keyframes, each with properties like duration, brightness, contrast, and easing functions.

### Method
POST

### Endpoint
/api/setTempAnimation

### Parameters
#### Query Parameters
- **target** (string) - Required - The target element for the animation. Can be 'fig-center', 'fig-left', 'fig-right', a free figure ID, 'bg-main', or 'stage-main'.
- **writeDefault** (boolean) - Optional - If true, unassigned transformation and effect properties will be written with default values. If false, unassigned properties inherit existing values.
- **keep** (boolean) - Optional - Converts the animation to a cross-statement animation, maintaining playback alongside subsequent statements until interrupted.

#### Request Body
- **animationData** (array) - Required - An array of animation keyframes. Each keyframe is an object that can include:
  - **duration** (integer) - The duration of the keyframe in milliseconds.
  - **brightness** (float) - The brightness value (e.g., 1 for normal, 2 for brighter).
  - **contrast** (float) - The contrast value.
  - **ease** (string) - The easing function for the keyframe (e.g., 'circIn').
  - **scale** (object) - An object defining scale: {"x": float, "y": float}.

### Request Example
```json
{
  "animationData": [
    {"duration": 0},
    {"brightness": 2, "contrast": 0, "duration": 200, "ease": "circIn"},
    {"brightness": 1, "contrast": 1, "duration": 200},
    {"brightness": 2, "contrast": 0, "duration": 200, "ease": "circIn"},
    {"brightness": 1, "contrast": 1, "duration": 2500}
  ],
  "target": "aaa",
  "writeDefault": false,
  "keep": false
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., 'success').

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### setTransform API

Source: https://docs.openwebgal.com/script-reference/commands/setTransform

This endpoint is used to set transformations and effects on a specified target with a given duration.

```APIDOC
## POST /setTransform

### Description
Sets transformations and effects on a target element. This command generates a single animation. For multiple animations, use `setAnimation` or `setTempAnimation`.

### Method
POST

### Endpoint
/setTransform

### Parameters
#### Query Parameters
- **target** (string) - Required - The target element for the animation. Can be `fig-center`, `fig-left`, `fig-right`, a custom figure ID, `bg-main`, or `stage-main`.
- **duration** (number) - Optional - The duration of the animation in milliseconds. Defaults to milliseconds if not specified. Range: 0 to infinity.
- **writeDefault** (boolean) - Optional - If true, unassigned transform and effect properties will be written with default values. If false, unassigned properties inherit existing values.
- **keep** (boolean) - Optional - Converts the animation to a cross-statement animation. It keeps playing the current animation while executing subsequent statements until the animation ends or is interrupted by another `setTransform`, `setAnimation`, or `setTempAnimation` for the same target. Often used with the `next` parameter.

#### Request Body
- **transform_data** (JSON string) - Required - A single-line JSON string containing the transformations and effects to apply. Examples include `{"position":{"x":-500},"saturation":0.8}` or `{"brightness":0.5,"contrast":1.2}`.

### Request Example
```json
{
  "transform_data": "{\"position\":{\"x\":-500},\"saturation\":0.8}"
}
```

### Response
#### Success Response (200)
This endpoint typically returns no specific JSON response body, but the action is applied to the target.

#### Response Example
(No specific response body for success)
```

--------------------------------

### Set Animation with Default Values (writeDefault)

Source: https://docs.openwebgal.com/script-reference/commands/setAnimation

Sets a custom animation on a target, with the 'writeDefault' parameter ensuring that any unassigned transformation or effect properties are set to their default values. If false, unassigned properties inherit existing values.

```OpenWebGal Script
changeFigure:1/open_eyes.png -id=aaa;
setAnimation:shake -target=aaa -writeDefault;
```

--------------------------------

### Unlock CG for Gallery

Source: https://docs.openwebgal.com/webgal-script/bg-and-figure

Command to unlock CGs for the gallery. 'unlockCg' is used with the filename and an optional '-name' for display and '-series' to group related CGs.

```WebGAL Script
unlockCg:xgmain.jpeg -name=星光咖啡馆与死神之蝶 -series=1;
```

--------------------------------

### Apply Temporary Animation with writeDefault

Source: https://docs.openwebgal.com/script-reference/commands/setTempAnimation

Applies a temporary animation to a target element, using the -writeDefault flag. When true, unspecified transform and effect properties are set to their default values. Otherwise, they inherit existing values.

```script
changeFigure:1/open_eyes.png -id=aaa;
setTempAnimation:[{"duration":0},{"brightness":2,"contrast":0,"duration":200,"ease":"circIn"},{"brightness":1,"contrast":1,"duration":200},{"brightness":2,"contrast":0,"duration":200,"ease":"circIn"},{"brightness":1,"contrast":1,"duration":2500}] -target=aaa -writeDefault;
```

--------------------------------

### Create Cross-Statement Animation with setTempAnimation and keep

Source: https://docs.openwebgal.com/script-reference/commands/setTempAnimation

Creates a temporary animation that persists across subsequent script statements using the -keep flag. The animation continues until explicitly interrupted by another animation command targeting the same element. It typically requires the -next parameter.

```script
changeFigure:1/open_eyes.png -id=aaa;
setTempAnimation:[{"duration":0},{"scale":{"x":2,"y":2},"duration":10000}] -target=aaa -keep -next;
角色A: 第一句话;
角色A: 第二句话;
角色A: 第三句话;
; 这会打断 aaa 的跨语句动画，并播放新动画
setTempAnimation:[{"duration":0},{"scale":{"x":1,"y":1},"duration":10000}] -target=aaa -keep -next;
```

--------------------------------

### Set Animation Duration for Background Transitions

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Controls the duration of the entry or exit animations for the background. The duration is specified in milliseconds. The default duration is 1000ms.

```WebGAL Script
changeBg:bg.png -duration=200;
```

--------------------------------

### Categorize CGs into Series

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Organizes collected CGs into named series within the CG gallery. This requires 'unlockname' to be set. An image can only belong to one series, and the last specified series takes precedence.

```WebGAL Script
changeBg:bg.png -unlockname=MyCg01 -series=MySeries01;
```

--------------------------------

### Set Custom Exit Animation for Background

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Specifies a custom animation to be played when the background exits, overriding the default fade-out effect. The animation name is provided as a string.

```WebGAL Script
changeBg:bg.png -exit=exit-to-right;
```

--------------------------------

### Set Transformations on Character Sprites

Source: https://docs.openwebgal.com/webgal-script/bg-and-figure

Applies transformation and filter effects when setting a character sprite. The '-transform' parameter accepts a JSON object with various properties like alpha, position, scale, rotation, and color adjustments.

```WebGAL Script
changeFigure:stand.png -transform={"alpha":1,"position":{"x":0,"y":500},"scale":{"x":1,"y":1},"rotation":0,"blur":0,"brightness":1,"contrast":1,"saturation":1,"gamma":1,"colorRed":255,"colorGreen":255,"colorBlue":255,"oldFilm":0,"dotFilm":0,"reflectionFilm":0,"glitchFilm":0,"rgbFilm":0,"godrayFilm":0} -next;
```

--------------------------------

### Assign Name for CG Collection

Source: https://docs.openwebgal.com/script-reference/commands/changeBg

Assigns a specific name to the background image for collection in the CG gallery. If not provided or empty, the image is not collected. Each unique image path can only have one collection name.

```WebGAL Script
changeBg:bg.png -unlockname=MyCg01;
```
Tokens:
Raw