diff --git a/src/.vuepress/sidebar/en.ts b/src/.vuepress/sidebar/en.ts index 527e213c6..80a863373 100644 --- a/src/.vuepress/sidebar/en.ts +++ b/src/.vuepress/sidebar/en.ts @@ -9,9 +9,20 @@ export const enSidebar = sidebar({ "getting-started", "resources", "config", - "publish", + { + text: "Deploy or Publish My Visual Novel?", + link: "publish/", + collapsible: true, + prefix: "publish/", + children: [ + "web", + "desktop", + "android", + ] + }, "faq", "live2D", + "spine", "migration", "derivative", ], @@ -20,15 +31,47 @@ export const enSidebar = sidebar({ text: "WebGAL Script Tutorial", prefix: "webgal-script/", children: [ - "base", - "dialogue", - "bg-and-figure", - "audio", - "video", - "scenes", - "variable", - "animation", - "special-effect", + { + text: "Basic Features", + collapsible: true, + children: [ + "base", + "dialogue", + ] + }, + { + text: "Visual Content", + collapsible: true, + children: [ + "bg-and-figure", + "animation", + "special-effect", + ] + }, + { + text: "Audio & Video", + collapsible: true, + children: [ + "audio", + "video", + ] + }, + { + text: "Interaction & Flow", + collapsible: true, + children: [ + "scenes", + "variable", + ] + }, + { + text: "Advanced Features", + collapsible: true, + children: [ + "intro", + "other-features", + ] + }, ] }, { diff --git a/src/.vuepress/sidebar/ja.ts b/src/.vuepress/sidebar/ja.ts index 45c95f46b..1db91438b 100644 --- a/src/.vuepress/sidebar/ja.ts +++ b/src/.vuepress/sidebar/ja.ts @@ -9,9 +9,20 @@ export const jaSidebar = sidebar({ "getting-started", "resources", "config", - "publish", + { + text: "ビジュアルノベルをデプロイまたは公開する？", + link: "publish/", + collapsible: true, + prefix: "publish/", + children: [ + "web", + "desktop", + "android", + ] + }, "faq", "live2D", + "spine", "migration", "derivative", ], @@ -20,15 +31,47 @@ export const jaSidebar = sidebar({ text: "WebGAL Script チュートリアル", prefix: "webgal-script/", children: [ - "base", - "dialogue", - "bg-and-figure", - "audio", - "video", - "scenes", - "variable", - "animation", - "special-effect", + { + text: "基本機能", + collapsible: true, + children: [ + "base", + "dialogue", + ] + }, + { + text: "視覚コンテンツ", + collapsible: true, + children: [ + "bg-and-figure", + "animation", + "special-effect", + ] + }, + { + text: "音声・映像", + collapsible: true, + children: [ + "audio", + "video", + ] + }, + { + text: "インタラクション・フロー", + collapsible: true, + children: [ + "scenes", + "variable", + ] + }, + { + text: "高度な機能", + collapsible: true, + children: [ + "intro", + "other-features", + ] + }, ] }, { diff --git a/src/.vuepress/sidebar/zh.ts b/src/.vuepress/sidebar/zh.ts index 54762b4ad..f8ea9b5cf 100644 --- a/src/.vuepress/sidebar/zh.ts +++ b/src/.vuepress/sidebar/zh.ts @@ -22,6 +22,7 @@ export const zhSidebar = sidebar({ }, "faq", "live2D", + "spine", "migration", "derivative", ], @@ -30,15 +31,47 @@ export const zhSidebar = sidebar({ text: "WebGAL 脚本教程", prefix: "webgal-script/", children: [ - "base", - "dialogue", - "bg-and-figure", - "audio", - "video", - "scenes", - "variable", - "animation", - "special-effect", + { + text: "基础功能", + collapsible: true, + children: [ + "base", + "dialogue", + ] + }, + { + text: "视觉内容", + collapsible: true, + children: [ + "bg-and-figure", + "animation", + "special-effect", + ] + }, + { + text: "音视频", + collapsible: true, + children: [ + "audio", + "video", + ] + }, + { + text: "交互与流程", + collapsible: true, + children: [ + "scenes", + "variable", + ] + }, + { + text: "高级功能", + collapsible: true, + children: [ + "intro", + "other-features", + ] + }, ] }, { diff --git a/src/en/spine.md b/src/en/spine.md index a4382d7f4..afce65c51 100644 --- a/src/en/spine.md +++ b/src/en/spine.md @@ -98,3 +98,129 @@ Furthermore, the WebGAL project team expressly disclaims any responsibility for In summary, if you choose to integrate or use Spine functionality in WebGAL, you must ensure that you have legally obtained a Spine Editor license and commit to complying with all relevant license terms and regulations. Otherwise, all risks, liabilities, and consequences arising therefrom shall be borne by you or your organization and are unrelated to the WebGAL project team. By using this software, you acknowledge that you have read, understood, and agreed to all contents of the above disclaimer. If you do not agree to these terms, please immediately cease using the WebGAL version integrated with Spine functionality. + +## Spine Animation Usage Guide + +After completing the above license requirements and technical integration, you can follow the instructions below to use Spine animation functionality in WebGAL. + +### File Format + +Spine animations typically include the following files: +- `.skel` - Skeleton data file (binary format) +- `.json` - Skeleton data file (JSON format) +- `.atlas` - Texture atlas description file +- `.png` - Texture image files + +### Basic Usage + +#### Setting Spine Figures + +Use the `.skel` file extension or `type=spine` parameter to specify Spine animation: + +``` ws +changeFigure:character.skel; +changeFigure:character.json?type=spine; +``` + +#### Setting Spine Backgrounds + +Spine animations can also be used as backgrounds: + +``` ws +changeBg:background.skel; +changeBg:background.json?type=spine; +``` + +#### Figure Position Settings + +Spine figures support preset positions, same as regular figures: + +``` ws +changeFigure:character.skel -left; +changeFigure:character.skel -right; +changeFigure:character.skel; // Default is center position +``` + +### Animation Control + +#### Switching Actions + +You can use the `-motion` parameter to switch Spine animations, just like Live2D: + +``` ws +changeFigure:character.skel -motion=idle; +changeFigure:character.skel -motion=walk -left; +``` + +#### Custom ID Spine Figures + +You can specify custom IDs for Spine figures and then use the `-motion` parameter to control animations: + +``` ws +changeFigure:character.skel -id=mainCharacter -left; +changeFigure:character.skel -id=mainCharacter -motion=happy; +``` + +### Animation Behavior + +- When Spine animation loads, it automatically plays the first available animation +- If a specific animation is specified in the state, it will be played preferentially +- Spine animations automatically scale to fit the screen + +### Usage Examples + +``` ws +; Set main character figure +changeFigure:mainCharacter.skel -id=hero -center; + +; Play walking animation +changeFigure:hero.skel -motion=walk -id=hero; + +; Set side character figure +changeFigure:sidekick.skel -left; + +; Set dynamic background +changeBg:forest.skel; +``` + +### Integration with Other Features + +Spine animations can be combined with other WebGAL features: + +``` ws +; Combined with voice playback +Character Name:Hello! -V1.ogg -figureId=hero; +changeFigure:character.skel -id=hero -motion=speaking; + +; Combined with scene switching +changeFigure:character.skel -id=hero; +changeFigure:character.skel -id=hero -motion=idle; +changeScene:next_scene.txt; +``` + +### Performance Considerations + +1. **Memory Usage**: Spine animations use more memory than static images +2. **Loading Time**: Initial loading may take longer +3. **Compatibility**: Requires browser WebGL support + +### Troubleshooting + +#### Common Issues + +1. **Animation not playing**: Check if animation name matches the name defined in the Spine file +2. **File loading failed**: Ensure `.skel`, `.atlas`, and texture files are in the same directory +3. **Display abnormalities**: Check Spine version compatibility + +#### Debug Tips + +- Use browser developer tools to check console logs +- Check network panel to confirm all files are loaded correctly +- Verify Spine file export settings are correct + +### Important Notes + +- Animation names must match the animation names defined in the Spine file +- Figures maintain aspect ratio and scale to fit the screen +- Backgrounds stretch or scale to fill the entire screen +- Please ensure compliance with all Spine license requirements diff --git a/src/en/webgal-script/README.md b/src/en/webgal-script/README.md index fb72a8804..c69fc54f5 100644 --- a/src/en/webgal-script/README.md +++ b/src/en/webgal-script/README.md @@ -2,20 +2,23 @@ ## Table of Contents +### Basic Features - [Base](base.md) - - [Dialogue](dialogue.md) +### Visual Content - [Background and Figure](bg-and-figure.md) +- [Animation Effects](animation.md) +- [Special Effects](special-effect.md) +### Audio & Video - [Audio](audio.md) - - [Video](video.md) +### Interaction & Flow - [Scenes and Branches](scenes.md) - - [Variables](variable.md) -- [Animation Effects](animation.md) - -- [Special Effects](special-effect.md) \ No newline at end of file +### Advanced Features +- [Intro Presentation](intro.md) +- [Other Features](other-features.md) \ No newline at end of file diff --git a/src/en/webgal-script/animation.md b/src/en/webgal-script/animation.md index b175582c2..97ee6b6ae 100644 --- a/src/en/webgal-script/animation.md +++ b/src/en/webgal-script/animation.md @@ -9,6 +9,8 @@ Use the statement `setAnimation:animation name -target=target;` ``` ws ; // Set an animation for the center sprite to enter from the bottom, and proceed to the next line setAnimation:enter-from-bottom -target=fig-center -next; +; // Continuously play animation +setAnimation:shake -target=bg-main -keep; ``` Currently, the following preset animations are available: @@ -19,7 +21,7 @@ Currently, the following preset animations are available: | Fade Out | exit | 300 | | Shake Once | shake | 1000 | | Enter from Bottom | enter-from-bottom | 500 | -| Enter from Left | enter-from-right | 500 | +| Enter from Left | enter-from-left | 500 | | Enter from Right | enter-from-right | 500 | | Move Front and Back Once | move-front-and-back | 1000 | @@ -89,6 +91,26 @@ The following table explains each property: | rotation | Rotation angle, in radians | | blur | Gaussian blur radius | | duration | Duration of this time slice, in milliseconds (ms) | +| brightness | Brightness adjustment | +| contrast | Contrast adjustment | +| saturation | Saturation adjustment | +| gamma | Gamma adjustment | +| colorRed | Red channel adjustment (0-255) | +| colorGreen | Green channel adjustment (0-255) | +| colorBlue | Blue channel adjustment (0-255) | +| bevel | Bevel effect intensity | +| bevelThickness | Bevel thickness | +| bevelRotation | Bevel rotation | +| bevelSoftness | Bevel softness | +| bevelRed | Bevel red channel (0-255) | +| bevelGreen | Bevel green channel (0-255) | +| bevelBlue | Bevel blue channel (0-255) | +| bloom | Bloom effect | +| bloomBrightness | Bloom brightness | +| bloomBlur | Bloom blur | +| bloomThreshold | Bloom threshold | +| shockwaveFilter | Shockwave effect | +| radiusAlphaFilter | Radial alpha | | oldFilm | Old film effect, 0 to disable, 1 to enable | | dotFilm | Dot film effect, 0 to disable, 1 to enable | | reflectionFilm | Reflection film effect, 0 to disable, 1 to enable | @@ -162,5 +184,58 @@ When setting a sprite or background, an entrance and exit animation will be set If you execute the statement for setting entrance and exit effects immediately after setting the sprite or background, you can override the default entrance and exit animations, thus achieving custom entrance and exit effects. If you do not set them, the default animations will be executed when entering or exiting. -If you do not execute the statement for setting entrance and exit effects immediately after setting the sprite or background, it will be meaningless to override the entrance animation after the image has already entered. However, if the image has not yet entered at this time, the set entrance animation will still be meaningful. It will be applied correctly when the sprite or background enters. -::: \ No newline at end of file +If you do not execute the statement for setting entrance and exit effects immediately after setting the sprite or background, it will be meaningless to override the entrance animation after the image has already entered. However, if the image has not yet exited at this time, the set exit animation will still be meaningful. It will be applied correctly when the sprite or background exits. +::: + +## Advanced Animation Features + +### Temporary Animation (setTempAnimation) + +Create and execute temporary custom animations defined in JSON format: + +``` ws +setTempAnimation:[{"alpha":0,"duration":0},{"alpha":1,"duration":300}] -target=fig-center; +``` + +### Transform Animation (setTransform) + +Create transformation animations from current state to target state: + +``` ws +setTransform:{"position":{"x":100,"y":0},"scale":{"x":1.2,"y":1.2}} -duration=1000 -ease=easeInOut -target=fig-center; +``` + +Supported parameters: +- `duration` - Animation duration in milliseconds +- `ease` - Easing function name (such as easeInOut, easeIn, easeOut, etc.) +- `target` - Target object +- `keep` - Whether to maintain the final state + +### Complex Animation (setComplexAnimation) + +Execute pre-registered complex animation functions: + +``` ws +setComplexAnimation:customEffect -duration=2000 -target=bg-main; +``` + +### Animation Parameter Reference + +#### Common Parameters +- `target` - Target object (fig-left, fig-center, fig-right, bg-main, or custom ID) +- `writeDefault` - Whether to write default values (optional, default false) +- `keep` - Whether to keep animation running or maintain final state (optional, default false) + +#### Easing Functions +WebGAL supports various easing functions, including: +- `easeIn` - Slow start +- `easeOut` - Slow end +- `easeInOut` - Slow start and end +- And many other easing functions + +### Animation Best Practices + +1. **Performance Considerations**: Avoid running too many complex animations simultaneously +2. **User Experience**: Ensure animations don't interfere with text reading +3. **Combination Usage**: Properly combine different types of animations to create richer effects +4. **Debugging Tips**: Use shorter durations for testing, then adjust after confirming the effect \ No newline at end of file diff --git a/src/en/webgal-script/audio.md b/src/en/webgal-script/audio.md index af3c51d41..bf3613a4d 100644 --- a/src/en/webgal-script/audio.md +++ b/src/en/webgal-script/audio.md @@ -26,10 +26,19 @@ Finally, you can use the following statement to fade out the background music. bgm:none -enter=3000; ``` +### BGM Unlock Feature + +While playing BGM, you can also unlock BGM to appreciation mode: + +``` ws +bgm:Summer_Shadow.mp3 -unlockname=Summer Shadow -series=season; +``` + ::: tip `-volume` and `-enter` are both optional parameters. When `-volume` is not used, or a value other than 0 to 100 is used, the default value of 100 will be used. When `-enter` is not used, or a value other than 0 to is used, the default value of 0 will be used. +`-unlockname` and `-series` parameters are used to unlock BGM to appreciation mode. ::: ## Playing Voice @@ -53,9 +62,20 @@ At the same time, you can set a `-volume` parameter to adjust its volume. Hachiman Hikigaya:Just arrived -V3.ogg -volume=30; ``` +### Voice and Character Animation Integration + +Voice playback can be integrated with character animation to achieve lip-sync and blinking animations: + +``` ws +Character Name:This dialogue has voice -V1.ogg -left; // Associated with left character +Character Name:This dialogue has voice -V2.ogg -figureId=char1; // Associated with specific ID character +``` + ::: tip `-volume` is an optional parameter. When `-volume` is not set, or a value other than 0 to 100 is used, the default value of 100 will be used. +`-left`, `-right`, `-center` parameters are used to specify the character position associated with the voice. +`-figureId` parameter is used to specify a specific character ID. ::: ## Playing Sound Effects @@ -93,4 +113,7 @@ Use `unlockBgm` to unlock the audio in the audio appreciation. ``` ws ; // Unlock bgm and give it a name unlockBgm:s_Title.mp3 -name=Smiling-Swinging!!!; -``` \ No newline at end of file +unlockBgm:s_Title.mp3 -name=Theme Song -series=OP; +``` + +The `-series` parameter is used to set the audio's series category, making it easier to manage classifications in appreciation mode. \ No newline at end of file diff --git a/src/en/webgal-script/base.md b/src/en/webgal-script/base.md index 1cbad4411..d241149fb 100644 --- a/src/en/webgal-script/base.md +++ b/src/en/webgal-script/base.md @@ -15,7 +15,7 @@ WebGAL:Hello!; The content after semicolon will be regarded as a comment ## `none` Keyword -When setting **resources** such as立ち絵, BGM, backgrounds, you can turn off this object by setting it to `none`. +When setting **resources** such as figures, BGM, backgrounds, you can turn off this object by setting it to `none`. ## `-next` Parameter @@ -29,21 +29,21 @@ changeBg:testBG03.jpg -next; // Will execute the next statement immediately ## `-notend` and `-concat` Parameters -Sometimes, you may want to add 演出効果, such as switching expressions, when a certain stage of a dialogue is executed. +Sometimes, you may want to add performance effects, such as switching expressions, when a certain stage of a dialogue is executed. At this time, you can use the `-notend` `-concat` parameters to insert any statement in the dialogue. `-concat` means that this dialogue is connected after the previous dialogue -`-notend` means that this dialogue is not over, and there may be 演出 or dialogue connected later. +`-notend` means that this dialogue is not over, and there may be performance or dialogue connected later. -An example is given below: This is a demonstration of switching 立ち絵 in the middle of a dialogue. +An example is given below: This is a demonstration of switching figures in the middle of a dialogue. ``` ws -WebGAL:Test statement insert 演出！Switch 立ち絵 immediately...... -notend; +WebGAL:Test statement insert performance! Switch figure immediately...... -notend; changeFigure:k1.png -next; -Switch 立ち絵！Switch expression immediately...... -notend -concat; +Switch figure! Switch expression immediately...... -notend -concat; changeFigure:k2.png -next; -Switch expression！ -concat; +Switch expression! -concat; ``` You can also use only the `-concat` parameter to connect the next sentence after the previous dialogue, because the `-notend` parameter will move to the next sentence after the dialogue fades in. @@ -52,3 +52,88 @@ You can also use only the `-concat` parameter to connect the next sentence after This is the first sentence...; This sentence will only appear after the user clicks the mouse -concat; ``` + +## Dialogue Commands + +In WebGAL, the most basic function is displaying dialogue. + +### Basic Dialogue + +You can display dialogue by directly inputting text: + +```ws +This is a dialogue; +``` + +### Character Dialogue + +You can specify a speaker for the dialogue: + +```ws +Character Name:This is what the character says; +``` + +### Dialogue Parameters + +Dialogue supports the following parameters: + +- `-speaker=name` - Set the speaker name +- `-clear` - Clear the current speaker name +- `-vocal=voice file` - Play voice file +- `-fontSize=small/medium/large/default` - Set text size +- `-left/-right/-center` - Set speaking character position (for lip sync animation) +- `-figureId=ID` - Specify the speaking character ID (for lip sync animation) + +```ws +Character Name:This is a dialogue -speaker=Character Name; +This dialogue plays voice -vocal=voice01.ogg; +This dialogue uses large font -fontSize=large; +Clear speaker dialogue -clear; +``` + +## Wait Command + +Use the `wait` command to pause the game for a specified time: + +```ws +wait:1000; // Wait for 1 second +wait:500; // Wait for 0.5 seconds +``` + +## End Game Command + +Use the `end` command to end the current game and return to the title screen: + +```ws +end; // End the game +``` + +## Textbox Control + +Use the `setTextbox` command to control the display and hiding of the text box: + +```ws +setTextbox:hide; // Hide the text box +setTextbox:; // Show the text box +``` + +This is very useful when you need to display full-screen images or special performances. + +## Debug Function + +Use the `showVars` command to display the values of all current variables: + +```ws +showVars:; // Show all variables +``` + +## Intro Demo + +Use the `intro` command to create black screen text demo effects: + +```ws +intro:Welcome to the world of WebGAL; +intro:Chapter 1|Autumn Memories|On that golden afternoon -fontSize=large; +``` + +For more parameters, please refer to the specific chapter descriptions. diff --git a/src/en/webgal-script/bg-and-figure.md b/src/en/webgal-script/bg-and-figure.md index af7abfa49..7cd23ecf7 100644 --- a/src/en/webgal-script/bg-and-figure.md +++ b/src/en/webgal-script/bg-and-figure.md @@ -86,6 +86,83 @@ unlockCg:xgmain.jpeg -name="Starlight Cafe and the Butterfly of Death" -series=1 Among them, the `-series` parameter is optional, which represents which series the current figure belongs to. Figures of the same series will be merged and displayed later (ie, displayed as switchable CGs of the same series). +## Advanced Background Switching Features + +### Unlock Background CG + +The `changeBg` command also supports CG unlock functionality, allowing you to unlock CGs while switching backgrounds: + +``` ws +changeBg:cg_scene1.jpg -unlockname="Chapter 1 Scene" -series="Main Story CG"; +``` + +### Background Transform Effects + +You can set transform effects for background switching: + +``` ws +changeBg:bg_night.jpg -transform={"position":{"x":-100,"y":0},"scale":{"x":1.2,"y":1.2}} -duration=3000; +``` + +### Preset Animation Effects + +You can use preset enter and exit animations: + +``` ws +changeBg:bg_morning.jpg -enter=fadeIn -exit=fadeOut; +``` + +## Advanced Figure Features + +### Live2D Support + +WebGAL supports Live2D figures, allowing you to control motions and expressions: + +``` ws +changeFigure:live2d/model.json -motion=idle -expression=happy; +``` + +### Figure Mouth and Eye Animation + +You can set mouth and eye animation materials for figures: + +``` ws +changeFigure:char.png -mouthOpen=mouth_open.png -mouthClose=mouth_close.png -eyesOpen=eyes_open.png -eyesClose=eyes_close.png; +``` + +### Figure Layer Control + +You can control the layer order of figures using the `zIndex` parameter: + +``` ws +changeFigure:foreground_char.png -zIndex=100; +changeFigure:background_char.png -zIndex=1; +``` + +### Different Ways to Clear Figures + +Besides using `none`, you can also use the `clear` parameter to clear figures: + +``` ws +changeFigure:any -left -clear; +``` + +### Live2D Boundary Settings + +For Live2D models, you can set display boundaries: + +``` ws +changeFigure:live2d/model.json -bounds=0,0,800,600; +``` + +### Figure Animation Effects + +You can set animation effects for figures: + +``` ws +changeFigure:char.png -duration=2000 -ease=easeInOut; +``` + ## Set Effects When Setting Figures For a description of the effect fields, please refer to [Animation](animation.md) diff --git a/src/en/webgal-script/intro.md b/src/en/webgal-script/intro.md new file mode 100644 index 000000000..d9ec90fe8 --- /dev/null +++ b/src/en/webgal-script/intro.md @@ -0,0 +1,114 @@ +# Intro Presentation + +WebGAL provides powerful intro presentation features that create black-screen text demonstrations, commonly used for game openings, chapter transitions, or atmospheric setups for important plot points. + +## Basic Usage + +Use the `intro` command to create intro presentations: + +``` ws +intro:Welcome to the world of WebGAL; +``` + +## Multi-line Text + +Use `|` separator to create multi-line text presentations: + +``` ws +intro:Chapter 1|Autumn Memories|On that golden afternoon; +``` + +## Supported Parameters + +### Background Settings + +- `-backgroundImage=imageName` - Set background image (loaded from game/background/ directory) +- `-backgroundColor=colorValue` - Set background color (default is black) + +``` ws +intro:Once upon a time...|In a distant land... -backgroundImage=sunset.jpg -backgroundColor=rgba(0,0,0,0.8); +``` + +### Text Styling + +- `-fontColor=colorValue` - Set font color (default is white) +- `-fontSize=size` - Set font size + +Font size options: +- `small` - Small font (280%) +- `medium` - Medium font (350%) +- `large` - Large font (420%) +- `default` - Default font + +``` ws +intro:Important Notice -fontSize=large -fontColor=rgba(255,200,100,1); +``` + +### Animation Effects + +- `-animation=animationType` - Set animation effect + +Supported animation types: +- `fadeIn` - Fade in effect (default) +- `slideIn` - Slide in effect +- `typingEffect` - Typing effect +- `pixelateEffect` - Pixelate effect +- `revealAnimation` - Reveal animation + +``` ws +intro:Chapter 1|Autumn Memories|On that golden afternoon -animation=typingEffect; +``` + +### Timing Control + +- `-delayTime=milliseconds` - Set delay time for each line of text (default 1500ms) + +``` ws +intro:Slowly revealed text -delayTime=3000; +``` + +### Interaction Control + +- `-hold` - Hold display, don't auto-continue +- `-userForward` - User manual control (implies hold effect) + +``` ws +intro:Press any key to continue -hold -fontSize=small; +intro:Click to continue to next chapter -userForward; +``` + +## Complete Example + +``` ws +intro:WebGAL Visual Novel Engine; +intro:Chapter 1|Autumn Encounter|On that golden afternoon -fontSize=large -animation=fadeIn -delayTime=2000; +intro:The story is about to begin...|Get ready -backgroundImage=autumn_bg.jpg -fontColor=rgba(255,215,0,1) -animation=slideIn; +intro:Press any key to start the game -hold -fontSize=small -fontColor=rgba(200,200,200,1); +``` + +## Special Features + +### Escape Characters + +If you need to use literal `|` characters in text, use escape characters: + +``` ws +intro:This is an example\|this won't create a new line; +``` + +### Fast-forward Support + +Intro presentations support user interaction for fast-forwarding: +- Mouse clicks can accelerate text display +- Any key press can accelerate text display +- Automatically proceeds to next script after presentation ends + +## Usage Tips + +1. **Reasonable background use**: Choose appropriate background images or colors for different scenarios +2. **Control pacing**: Adjust pacing of text display through `delayTime` +3. **Font size**: Choose appropriate font size based on text importance +4. **Animation effects**: Choose suitable animation effects based on atmosphere +5. **Interaction design**: Use `-hold` at appropriate moments to let users control pacing + +Intro presentations are important tools for creating immersive experiences, and proper use can greatly enhance the game's expressiveness. \ No newline at end of file diff --git a/src/en/webgal-script/other-features.md b/src/en/webgal-script/other-features.md new file mode 100644 index 000000000..30b483d96 --- /dev/null +++ b/src/en/webgal-script/other-features.md @@ -0,0 +1,204 @@ +# Other Features + +WebGAL also provides some other useful features that can help you create richer game experiences. + +## Film Mode + +Film mode creates a more immersive viewing experience, similar to a video player's "cinema mode". + +### Enable Film Mode + +``` ws +filmMode:on; // Enable film mode +filmMode:cinematic; // Enable film mode (with parameter) +``` + +### Disable Film Mode + +``` ws +filmMode:; // Disable film mode +filmMode:none; // Disable film mode +``` + +### Features + +- Hides some UI elements +- Takes effect immediately, doesn't block script execution +- Suitable for important plot points or special scenes + +### Usage Example + +``` ws +; Enter important plot scene +filmMode:on; +changeBg:important_scene.jpg; +This is important plot dialogue...; +; Exit film mode after plot ends +filmMode:; +``` + +## Unlock CG + +Besides automatically unlocking CG when changing backgrounds, you can also unlock CG separately without displaying it. + +### Basic Usage + +``` ws +unlockCg:cg/scene1.jpg; +``` + +### Set CG Name and Series + +``` ws +unlockCg:cg/ending_a.jpg -name=Happy Ending; +unlockCg:cg/chapter2_01.jpg -name=First Meeting -series=Chapter 2; +``` + +### Parameter Description + +- `-name=name` - Set display name for CG (default uses file path) +- `-series=seriesName` - Set CG series/category (default is "default") + +### Features + +- Unlocked CG is saved to user data +- Supports CG category management +- Takes effect immediately, doesn't block script execution + +## Unlock BGM + +You can unlock BGM to appreciation mode separately without playing it. + +### Basic Usage + +``` ws +unlockBgm:s_Title.mp3; +``` + +### Set BGM Name and Series + +``` ws +unlockBgm:s_Title.mp3 -name=Smiling-Swinging!!!; +unlockBgm:s_Title.mp3 -name=Theme Song -series=OP; +``` + +### Parameter Description + +- `-name=name` - Set display name for BGM (default uses file path) +- `-series=seriesName` - Set BGM series/category (default is "default") + +## Textbox Control + +Control the display and hiding of textboxes, suitable for fullscreen presentations. + +### Hide Textbox + +``` ws +setTextbox:hide; +``` + +### Show Textbox + +``` ws +setTextbox:; +setTextbox:show; +``` + +### Usage Scenarios + +``` ws +; Display fullscreen CG +setTextbox:hide; +changeBg:fullscreen_cg.jpg; +wait:3000; +; Restore textbox +setTextbox:; +What a beautiful scenery!; +``` + +## Dynamic Style Switching + +You can dynamically replace CSS class names of UI elements to implement theme switching and other features. + +### Single Style Replacement + +``` ws +applyStyle:textbox-default->textbox-dark; +``` + +### Batch Style Replacement + +``` ws +applyStyle:btn-primary->btn-dark,text-light->text-dark,bg-light->bg-dark; +``` + +### Usage Scenarios + +- Dynamic theme switching (e.g., day/night mode) +- UI style changes for specific scenes +- Interface style changes based on plot needs + +### Example + +``` ws +; Switch to night mode +applyStyle:textbox-light->textbox-dark,btn-light->btn-dark; +; Special scene style +applyStyle:ui-normal->ui-horror; +``` + +## Debug Features + +### Display All Variables + +``` ws +showVars:; +``` + +Displays the values of all current variables, including regular variables and global variables, in JSON format in the dialogue box. + +### Usage Scenarios + +- Debug complex variable logic +- Check variable states +- Troubleshoot during development + +## End Game + +Used when the game ends, returns to the title screen. + +``` ws +end; +``` + +### Functions + +- Reset game stage state +- Clear quick save +- Reload initial scene (start.txt) +- Play title screen BGM + +## Wait Command + +Pause the game for a specified time. + +``` ws +wait:1000; // Wait 1 second +wait:500; // Wait 0.5 seconds +``` + +### Features + +- Time unit is milliseconds +- Automatically jumps to next statement +- Suitable for controlling presentation pacing + +## Usage Tips + +1. **Reasonable use of film mode**: Use in important plot points or special scenes, don't switch frequently +2. **CG unlock timing**: Unlock CG at appropriate plot points to enhance player sense of achievement +3. **Textbox control**: Mainly used for fullscreen presentations, remember to restore afterwards +4. **Style switching**: Ensure switched styles exist to avoid style errors +5. **Debug features**: Use frequently during development, remember to remove debug code before release + +Although these features may seem simple, proper use can greatly enhance the game's professionalism and user experience. \ No newline at end of file diff --git a/src/en/webgal-script/scenes.md b/src/en/webgal-script/scenes.md index 8fe75b9cd..106704546 100644 --- a/src/en/webgal-script/scenes.md +++ b/src/en/webgal-script/scenes.md @@ -137,4 +137,76 @@ label:label_2; // Create a label named label_2 ...... ``` -In this script, if you select `Branch 2`, everything seems to be fine. But if you select `Branch 1`, you will be surprised to find that after `Branch 1` is executed, `Branch 2` will continue to be executed. That's because the program continues to execute the next line in order, and you didn't specify where to jump after the branch ended. \ No newline at end of file +In this script, if you select `Branch 2`, everything seems to be fine. But if you select `Branch 1`, you will be surprised to find that after `Branch 1` is executed, `Branch 2` will continue to be executed. That's because the program continues to execute the next line in order, and you didn't specify where to jump after the branch ended. + +## User Input + +WebGAL supports obtaining user text input and saving it to variables. + +### Getting User Input + +Use `getUserInput` to display an input box for players to enter text content: + +``` ws +getUserInput:playerName -title=Please enter your name -buttonText=Confirm; +``` + +### Supported Parameters + +- `title` - Title text for the input box +- `buttonText` - Text for the confirmation button +- `defaultValue` - Default value for the input box + +### Usage Examples + +``` ws +getUserInput:playerName -title=Please enter your name -buttonText=Confirm; +Hello, {playerName}! Welcome to our world.; + +getUserInput:answer -title=What is 1+1? -buttonText=Submit Answer; +choose:(answer==2)->Correct answer:correct|(answer!=2)->Wrong answer:wrong; +``` + +### Notes + +- Input content is automatically saved to the specified variable +- Variables can be used in subsequent scripts, including conditional judgments and dialogue display +- The game will pause during input, waiting for user input completion + +## Advanced Branch Features + +### Complex Conditions for Choice Options + +Choice options support complex conditional expressions: + +``` ws +choose:(score>50&&hasKey)->Open the treasure chest:treasure.txt|(score<=50)->Insufficient strength:fail.txt|Turn back and leave:leave.txt; +``` + +### Scene Jump vs Label Jump + +- **Scene Jump**: Used to jump to other `.txt` files, suitable for chapter switching +- **Label Jump**: Used to jump within the same file, suitable for simple branches + +Recognition method: If the jump target contains a `.` character, it is treated as a scene jump; otherwise it is treated as a label jump. + +``` ws +choose:Next chapter:Chapter-2.txt|Retry:retry; // The first is scene jump, the second is label jump +``` + +### Label Jump Limitations + +- Label jumps can only be performed within the current scene file +- Cannot jump to labels in other files +- Label names must be unique within the same file + +## Film Mode + +WebGAL supports film mode, which can create a more immersive viewing experience: + +``` ws +filmMode:on; // Enable film mode +filmMode:; // Disable film mode +``` + +Film mode will hide some UI elements, creating a "cinema mode" effect similar to video players. \ No newline at end of file diff --git a/src/en/webgal-script/variable.md b/src/en/webgal-script/variable.md index 2b821e4e6..e65ca16fb 100644 --- a/src/en/webgal-script/variable.md +++ b/src/en/webgal-script/variable.md @@ -10,8 +10,9 @@ To set a variable: ``` ws setVar:a=1; // You can set a number -setVar:a=true // You can set a boolean -setVar:a=Character Name // You can set a string +setVar:a=true; // You can set a boolean +setVar:a=Character Name; // You can set a string +setVar:a=; // You can set an empty value (empty string) ``` To set a random number, use `random()` @@ -34,12 +35,12 @@ setVar:a=random(); Of course, we can also specify **Range**. For example, if you want a random number between 5 and 10, You can write: ```ws -SetVar: a = the random (5, 10); +setVar:a=random(5,10); ``` Of course you want it to use ranges to generate values that also have decimals, then specify a third argument: ```ws -SetVar: a = the random (5, 10, true); # will generate a floating point number between 5 and 10 +setVar:a=random(5,10,true); // Will generate a floating point number between 5 and 10 ``` You can also use previously defined variables when setting variables. @@ -49,6 +50,25 @@ setVar:a=1; setVar:b=a+1; ``` +### Advanced Expression Support + +`setVar` supports complex mathematical expressions and string operations: + +``` ws +// Supports parentheses and operator precedence +setVar:result=(a+b)*2-c/3; + +// Strings are automatically concatenated +setVar:a=hello; +setVar:b=world; +setVar:c=a+b; // c will be "helloworld" + +// Variable references +setVar:baseScore=100; +setVar:bonus=50; +setVar:totalScore=baseScore+bonus; // totalScore will be 150 +``` + ## Conditional Execution You can add a `-when=(condition)` parameter after a statement to conditionally execute the current statement. @@ -80,7 +100,36 @@ Use the `getUserInput` statement to get user input, for example: getUserInput:name -title=What's your name? -buttonText=OK; Store the user input in the variable name ``` -Where `title` is the prompt text, `buttonText` is the text on the OK button +Where `title` is the prompt text, `buttonText` is the text on the OK button, and `defaultValue` is the default value. + +## Debugging Variables + +Use the `showVars` command to display the current values of all variables, including normal variables and global variables: + +``` ws +setVar:score=100; +setVar:playerName=Alice -global; +showVars:; // Will display all variables in JSON format in the dialog box +``` + +This command is mainly used for debugging and helps you understand the state of all variables in the current game. + +## Dynamic UI Style Switching + +Use the `applyStyle` command to dynamically replace CSS class names of UI elements: + +``` ws +// Switch single style +applyStyle:textbox-default->textbox-dark; + +// Batch switch styles +applyStyle:btn-primary->btn-dark,text-light->text-dark,bg-light->bg-dark; +``` + +This feature can be used to implement: +- Dynamic theme switching (such as day/night mode) +- UI style changes for specific scenes +- Interface style changes based on story needs ## Variable Interpolation @@ -158,7 +207,7 @@ The same goes for modifications. When changing the game title to a new one, the Adding the `global` flag indicates that we are modifying a configuration variable: ```ws -setVar:Game_name=('New Game Title') -global; +setVar:Game_name=New Game Title -global; WebGAL:The current title of the game is{Game_name}; ``` @@ -174,7 +223,7 @@ To do this, use `Clear all data` in the game options. Of course, you can also create a custom configuration variable in `config.txt`, such as a version number: ```text -Game_name:欢迎使用WebGAL！; +Game_name:Welcome to WebGAL!; Game_key:f60ad5725c1588; Title_img:WebGAL_New_Enter_Image.png; Title_bgm:s_Title.mp3; diff --git a/src/en/webgal-script/video.md b/src/en/webgal-script/video.md index 0e8f190fb..f68325765 100644 --- a/src/en/webgal-script/video.md +++ b/src/en/webgal-script/video.md @@ -8,4 +8,33 @@ Put the video inside `video` folder, then use `playVideo` to play it. playVideo:OP.mp4; ``` -If you want to prevent user from skipping the video, you can use `-skipOff` parameter. \ No newline at end of file +If you want to prevent user from skipping the video, you can use `-skipOff` parameter. + +``` ws +playVideo:OP.mp4 -skipOff; +``` + +## Video Playback Behavior + +When playing videos, the following behaviors occur: + +1. **Audio Control**: Video playback will automatically pause the current BGM and voice, and the volume will be automatically restored after the video ends. + +2. **Skip Function**: By default, users can double-click the video to skip playback. Use the `-skipOff` parameter to disable this feature. + +3. **Fullscreen Playback**: Videos will play in fullscreen mode, covering the entire game interface. + +4. **Auto Continue**: After the video finishes playing, it will automatically continue to execute the next script. + +## Supported Video Formats + +WebGAL supports video formats that can be played by browsers. It is recommended to use: +- MP4 format (H.264 encoding) +- WebM format +- OGV format + +## Usage Recommendations + +- Video files should be placed in the `video` folder +- It is recommended to use compressed video files to reduce loading time +- For important story videos, it is recommended to use the `-skipOff` parameter to prevent accidental skipping \ No newline at end of file diff --git a/src/ja/spine.md b/src/ja/spine.md index 69558ef4e..51271f1d4 100644 --- a/src/ja/spine.md +++ b/src/ja/spine.md @@ -79,6 +79,131 @@ changeFigure:exampleSpine/data.json?type=spine; 6. 本番用パッケージをビルドする場合、またはWebGAL Terreで使用する場合は、`yarn build`コマンドを実行してWebGALをビルドします。完了したら、[カスタムエンジンの使用方法](derivative) を参照して、変更後のエンジンを使用してください。 +## Spineアニメーション使用ガイド + +上記のライセンス要件と技術統合を完了した後、以下の説明に従ってWebGALでSpineアニメーション機能を使用できます。 + +### ファイル形式 + +Spineアニメーションには通常、以下のファイルが含まれます： +- `.skel` - 骨格データファイル（バイナリ形式） +- `.json` - 骨格データファイル（JSON形式） +- `.atlas` - テクスチャアトラス記述ファイル +- `.png` - テクスチャ画像ファイル + +### 基本的な使用方法 + +#### Spine立ち絵の設定 + +`.skel`ファイル拡張子または`type=spine`パラメータを使用してSpineアニメーションを指定します： + +``` ws +changeFigure:character.skel; +changeFigure:character.json?type=spine; +``` + +#### Spine背景の設定 + +同様に、Spineアニメーションを背景として使用できます： + +``` ws +changeBg:background.skel; +changeBg:background.json?type=spine; +``` + +#### 立ち絵位置の設定 + +Spine立ち絵は、通常の立ち絵と同じプリセット位置をサポートします： + +``` ws +changeFigure:character.skel -left; +changeFigure:character.skel -right; +changeFigure:character.skel; // デフォルトは中央位置 +``` + +### アニメーション制御 + +#### アクションの切り替え + +Live2Dと同様に、`-motion`パラメータを使用してSpineアニメーションを切り替えることができます： + +``` ws +changeFigure:character.skel -motion=idle; +changeFigure:character.skel -motion=walk -left; +``` + +#### カスタムIDのSpine立ち絵 + +Spine立ち絵にカスタムIDを指定し、`-motion`パラメータを使用してアニメーションを制御できます： + +``` ws +changeFigure:character.skel -id=mainCharacter -left; +changeFigure:character.skel -id=mainCharacter -motion=happy; +``` + +### アニメーションの動作 + +- Spineアニメーションの読み込み時に、最初に利用可能なアニメーションが自動的に再生されます +- ステートで特定のアニメーションが指定されている場合、指定されたアニメーションが優先的に再生されます +- Spineアニメーションは画面サイズに合わせて自動的にスケーリングされます + +### 使用例 + +``` ws +; 主人公の立ち絵を設定 +changeFigure:mainCharacter.skel -id=hero -center; + +; 歩行アニメーションを再生 +changeFigure:hero.skel -motion=walk -id=hero; + +; 脇役の立ち絵を設定 +changeFigure:sidekick.skel -left; + +; 動的背景を設定 +changeBg:forest.skel; +``` + +### 他機能との組み合わせ使用 + +Spineアニメーションは他のWebGAL機能と組み合わせて使用できます： + +``` ws +; 音声再生と組み合わせ +キャラクター名:こんにちは！ -V1.ogg -figureId=hero; +changeFigure:character.skel -id=hero -motion=speaking; + +; シーン切り替えと組み合わせ +changeFigure:character.skel -id=hero; +changeFigure:character.skel -id=hero -motion=idle; +changeScene:next_scene.txt; +``` + +### パフォーマンス考慮 + +1. **メモリ使用量**：Spineアニメーションは静的画像よりも多くのメモリを使用します +2. **読み込み時間**：初回読み込みに時間がかかる場合があります +3. **互換性**：ブラウザのWebGLサポートが必要です + +### トラブルシューティング + +#### よくある問題 + +1. **アニメーションが再生されない**：アニメーション名がSpineファイルで定義された名前と一致しているか確認してください +2. **ファイルの読み込みに失敗**：`.skel`、`.atlas`、テクスチャファイルがすべて同じディレクトリにあることを確認してください +3. **表示異常**：Spineバージョンの互換性を確認してください + +#### デバッグのヒント + +- ブラウザの開発者ツールを使用してコンソールログを確認する +- ネットワークパネルでファイルが正しく読み込まれているかを確認する +- Spineファイルのエクスポート設定が正しいことを確認する + +### 注意事項 + +- アニメーション名はSpineファイルで定義されたアニメーション名と一致している必要があります +- 立ち絵は縦横比を保持し、画面に合わせてスケーリングされます +- 背景は画面全体を埋めるように伸縮またはスケーリングされます +- すべてのSpineライセンス要件を遵守してください ### 重要な注意点 diff --git a/src/ja/webgal-script/README.md b/src/ja/webgal-script/README.md index b4631787e..3b7238be1 100644 --- a/src/ja/webgal-script/README.md +++ b/src/ja/webgal-script/README.md @@ -2,20 +2,23 @@ ## 目次 +### 基本機能 - [基礎](base.md) - - [会話](dialogue.md) +### 視覚コンテンツ - [背景と立ち絵](bg-and-figure.md) +- [アニメーション効果](animation.md) +- [特殊効果](special-effect.md) +### 音声・映像 - [オーディオ](audio.md) - - [ビデオ](video.md) +### インタラクション・フロー - [シーンと分岐](scenes.md) - - [変数](variable.md) -- [アニメーション効果](animation.md) - -- [特殊効果](special-effect.md) \ No newline at end of file +### 高度な機能 +- [イントロプレゼンテーション](intro.md) +- [その他の機能](other-features.md) \ No newline at end of file diff --git a/src/ja/webgal-script/animation.md b/src/ja/webgal-script/animation.md index 1eec6d382..73ce2bc6d 100644 --- a/src/ja/webgal-script/animation.md +++ b/src/ja/webgal-script/animation.md @@ -9,6 +9,8 @@ ``` ws ; // 中央の立ち絵に下から入ってくるアニメーションを設定し、次の行に移動します setAnimation:enter-from-bottom -target=fig-center -next; +; // 継続的にアニメーションを再生する +setAnimation:shake -target=bg-main -keep; ``` 現在、プリセットされたアニメーションは以下の通りです。 @@ -19,7 +21,7 @@ setAnimation:enter-from-bottom -target=fig-center -next; | フェードアウト | exit | 300 | | 左右に一度揺れる | shake | 1000 | | 下側から入ってくる | enter-from-bottom | 500 | -| 左側から入ってくる | enter-from-right | 500 | +| 左側から入ってくる | enter-from-left | 500 | | 右側から入ってくる | enter-from-right | 500 | | 前後に一度移動する | move-front-and-back | 1000 | @@ -89,6 +91,26 @@ setAnimation:enter-from-bottom -target=fig-center -next; | rotation | 回転角度、単位はラジアン | | blur | ガウスぼかしの半径 | | duration | このタイムスライスの持続時間、単位はミリ秒 (ms) | +| brightness | 明度調整 | +| contrast | コントラスト調整 | +| saturation | 彩度調整 | +| gamma | ガンマ値調整 | +| colorRed | 赤色チャンネル調整（0-255） | +| colorGreen | 緑色チャンネル調整（0-255） | +| colorBlue | 青色チャンネル調整（0-255） | +| bevel | ベベル効果の強度 | +| bevelThickness | ベベルの厚さ | +| bevelRotation | ベベルの回転 | +| bevelSoftness | ベベルの柔らかさ | +| bevelRed | ベベルの赤色チャンネル（0-255） | +| bevelGreen | ベベルの緑色チャンネル（0-255） | +| bevelBlue | ベベルの青色チャンネル（0-255） | +| bloom | 発光効果 | +| bloomBrightness | 発光の明度 | +| bloomBlur | 発光のぼかし | +| bloomThreshold | 発光の閾値 | +| shockwaveFilter | 衝撃波効果 | +| radiusAlphaFilter | 放射状透明度 | | oldFilm | オールドフィルム効果、0 はオフ、1 はオン | | dotFilm | ドット状のフィルム効果、0 はオフ、1 はオン | | reflectionFilm | 反射フィルム効果、0 はオフ、1 はオン | @@ -162,5 +184,58 @@ setTransition: -target=fig-center -enter=enter-from-bottom -exit=exit; 立ち絵や背景を設定した後、すぐに登場・退場エフェクトを設定するステートメントを実行すると、デフォルトの登場・退場アニメーションを上書きして、登場・退場エフェクトをカスタマイズすることができます。設定しない場合は、登場・退場時にデフォルトのアニメーションが実行されます。 -立ち絵や背景を設定した後、すぐに登場・退場エフェクトを設定せずに、画像がすでに登場してから登場アニメーションを上書きしても意味がありません。しかし、この時点で画像がまだ登場していない場合は、設定した登場アニメーションに意味があります。立ち絵や背景が登場する際に正しく適用されます。 -::: \ No newline at end of file +立ち絵や背景を設定した後、すぐに登場・退場エフェクトを設定せずに、画像がすでに登場してから登場アニメーションを上書きしても意味がありません。しかし、この時点で画像がまだ退場していない場合は、設定した退場アニメーションに意味があります。立ち絵や背景が退場する際に正しく適用されます。 +::: + +## 高度なアニメーション機能 + +### 一時的なアニメーション (setTempAnimation) + +JSON形式でアニメーション効果を定義して、一時的なカスタムアニメーションを作成・実行します： + +``` ws +setTempAnimation:[{"alpha":0,"duration":0},{"alpha":1,"duration":300}] -target=fig-center; +``` + +### 変換アニメーション (setTransform) + +現在の状態から目標状態への変換アニメーションを作成します： + +``` ws +setTransform:{"position":{"x":100,"y":0},"scale":{"x":1.2,"y":1.2}} -duration=1000 -ease=easeInOut -target=fig-center; +``` + +サポートされるパラメータ： +- `duration` - アニメーションの持続時間（ミリ秒） +- `ease` - イージング関数名（easeInOut、easeIn、easeOut など） +- `target` - 作用対象 +- `keep` - 最終状態を維持するかどうか + +### 複雑なアニメーション (setComplexAnimation) + +事前に登録された複雑なアニメーション関数を実行します： + +``` ws +setComplexAnimation:customEffect -duration=2000 -target=bg-main; +``` + +### アニメーションパラメータの説明 + +#### 共通パラメータ +- `target` - 作用対象（fig-left、fig-center、fig-right、bg-main または カスタム ID） +- `writeDefault` - デフォルト値を書き込むかどうか（オプション、デフォルト false） +- `keep` - アニメーションを継続するか最終状態を維持するかどうか（オプション、デフォルト false） + +#### イージング関数 +WebGALは複数のイージング関数をサポートしています： +- `easeIn` - ゆっくり開始 +- `easeOut` - ゆっくり終了 +- `easeInOut` - ゆっくり開始・終了 +- その他多くのイージング関数 + +### アニメーションのベストプラクティス + +1. **パフォーマンスの考慮**：同時に実行する複雑なアニメーションが多すぎないよう注意 +2. **ユーザーエクスペリエンス**：アニメーションがテキストの読み取りを妨げないよう確認 +3. **組み合わせ使用**：異なるタイプのアニメーションを適切に組み合わせて、より豊かな効果を作成 +4. **デバッグのコツ**：テスト時には短い持続時間を使用し、効果を確認した後に調整 \ No newline at end of file diff --git a/src/ja/webgal-script/audio.md b/src/ja/webgal-script/audio.md index 211bba224..843520b57 100644 --- a/src/ja/webgal-script/audio.md +++ b/src/ja/webgal-script/audio.md @@ -26,10 +26,19 @@ bgm:夏影.mp3 -enter=3000; bgm:none -enter=3000; ``` +### BGMアンロック機能 + +BGMを再生すると同時に、BGMを鑑賞モードにアンロックすることもできます： + +``` ws +bgm:夏影.mp3 -unlockname=夏之影 -series=season; +``` + ::: tip `-volume`と`-enter`はどちらもオプションのパラメータです。 `-volume`を使用しない場合、または0〜100以外の値を使用した場合は、デフォルト値100が使用されます。 `-enter`を使用しない場合、または0〜以外の値を使用した場合は、デフォルト値0が使用されます。 +`-unlockname`と`-series`パラメータは、BGMを鑑賞モードにアンロックするために使用されます。 ::: ## 音声を再生する @@ -53,9 +62,20 @@ bgm:none -enter=3000; 比企谷八幡:今来たばかりだ -V3.ogg -volume=30; ``` +### 音声と立ち絵アニメーションの連動 + +音声再生時に立ち絵アニメーションと連動して、口の動きと瞬きアニメーションを実現できます： + +``` ws +キャラクター名:このセリフには音声があります -V1.ogg -left; // 左側の立ち絵と関連付け +キャラクター名:このセリフには音声があります -V2.ogg -figureId=char1; // 指定IDの立ち絵と関連付け +``` + ::: tip `-volume`はオプションのパラメータです。 `-volume`を設定しない場合、または0〜100以外の値を使用した場合は、デフォルト値100が使用されます。 +`-left`、`-right`、`-center`パラメータは、音声と関連付ける立ち絵の位置を指定するために使用されます。 +`-figureId`パラメータは、特定の立ち絵IDを指定するために使用されます。 ::: ## 効果音を再生する @@ -93,4 +113,7 @@ playEffect:none -id=xxx; // このループ効果音を停止する ``` ws ; // bgmのロックを解除して名前を付ける unlockBgm:s_Title.mp3 -name=Smiling-Swinging!!!; -``` \ No newline at end of file +unlockBgm:s_Title.mp3 -name=主題歌 -series=OP; +``` + +`-series`パラメータは、オーディオの所属シリーズを設定するために使用され、鑑賞モードでの分類管理に便利です。 \ No newline at end of file diff --git a/src/ja/webgal-script/base.md b/src/ja/webgal-script/base.md index fe2151425..49cd6a6fb 100644 --- a/src/ja/webgal-script/base.md +++ b/src/ja/webgal-script/base.md @@ -46,9 +46,94 @@ changeFigure:k2.png -next; 表情を切り替えます！ -concat; ``` -`-concat` パラメータのみを使用して、次の文を前の文の会話に接続することもできます。`-notend` パラメータは、会話のフェードアウト後に次の文に移動するためです。 +`-concat` パラメータのみを使用して、次の文を前の文の会話に接続することもできます。`-notend` パラメータは、会話のフェードアウト後に次の文に移動するためです。 ``` ws -これは最初の文です......; -ユーザーがマウスをクリックすると、2 番目の文に移ります -concat; +これは最初の文です......; +ユーザーがマウスをクリックすると、2 番目の文に移ります -concat; ``` + +## 会話コマンド + +WebGALでは、最も基本的な機能は会話の表示です。 + +### 基本的な会話 + +テキストを直接入力することで会話を表示できます： + +``` ws +これは会話です; +``` + +### キャラクターの会話 + +会話に話者を指定できます： + +``` ws +キャラクター名:これはキャラクターが話した内容です; +``` + +### 会話パラメータ + +会話は以下のパラメータをサポートします： + +- `-speaker=名前` - 話者名を設定 +- `-clear` - 現在の話者名をクリア +- `-vocal=音声ファイル` - 音声ファイルを再生 +- `-fontSize=small/medium/large/default` - 文字サイズを設定 +- `-left/-right/-center` - 話者の位置を設定（口パク動画用） +- `-figureId=ID` - 話者のキャラクターIDを指定（口パク動画用） + +``` ws +キャラクター名:これは会話です -speaker=キャラクター名; +この会話は音声を再生します -vocal=voice01.ogg; +この会話は大きいフォントを使用します -fontSize=large; +話者をクリアする会話 -clear; +``` + +## 待機コマンド + +`wait`コマンドを使用してゲームを指定時間一時停止できます： + +``` ws +wait:1000; // 1秒待機 +wait:500; // 0.5秒待機 +``` + +## ゲーム終了コマンド + +`end`コマンドを使用して現在のゲームを終了し、タイトル画面に戻ることができます： + +``` ws +end; // ゲーム終了 +``` + +## テキストボックスコントロール + +`setTextbox`指令を使用してテキストボックスの表示と非表示を制御できます： + +``` ws +setTextbox:hide; // テキストボックスを非表示 +setTextbox:; // テキストボックスを表示 +``` + +これは全画面画像や特別な演出を表示する際に非常に便利です。 + +## デバッグ機能 + +`showVars`指令を使用して現在のすべての変数の値を表示できます： + +``` ws +showVars:; // すべての変数を表示 +``` + +## イントロ演出 + +`intro`指令を使用して黒画面テキスト演出効果を作成できます： + +``` ws +intro:WebGALの世界へようこそ; +intro:第一章|秋の思い出|あの金色の午後に -fontSize=large; +``` + +詳細なパラメータについては、各章の説明を参照してください。 \ No newline at end of file diff --git a/src/ja/webgal-script/bg-and-figure.md b/src/ja/webgal-script/bg-and-figure.md index 6b2c63e26..9e3a16705 100644 --- a/src/ja/webgal-script/bg-and-figure.md +++ b/src/ja/webgal-script/bg-and-figure.md @@ -86,6 +86,83 @@ unlockCg:xgmain.jpeg -name=星光咖啡馆与死神之蝶 -series=1; ここで、`-series`パラメータはオプションであり、現在の立ち絵がどのシリーズに属するかを表します。同じシリーズの立ち絵は、後で統合して表示されます（つまり、同じシリーズのCGを切り替えて表示できます）。 +## 高度な背景切り替え機能 + +### 背景CGのアンロック + +`changeBg`コマンドも CGアンロック機能をサポートしており、背景の切り替えと同時にCGをアンロックできます： + +``` ws +changeBg:cg_scene1.jpg -unlockname=第一章場景 -series=主線CG; +``` + +### 背景変換エフェクト + +背景切り替えに変換エフェクトを設定できます： + +``` ws +changeBg:bg_night.jpg -transform={"position":{"x":-100,"y":0},"scale":{"x":1.2,"y":1.2}} -duration=3000; +``` + +### プリセットアニメーションエフェクト + +プリセットの入場・退場アニメーションを使用できます： + +``` ws +changeBg:bg_morning.jpg -enter=fadeIn -exit=fadeOut; +``` + +## 高度な立ち絵機能 + +### Live2D サポート + +WebGAL は Live2D 立ち絵をサポートし、動作と表情を制御できます： + +``` ws +changeFigure:live2d/model.json -motion=idle -expression=happy; +``` + +### 立ち絵の口の動きとまばたきアニメーション + +立ち絵に口の動きとまばたきアニメーションの素材を設定できます： + +``` ws +changeFigure:char.png -mouthOpen=mouth_open.png -mouthClose=mouth_close.png -eyesOpen=eyes_open.png -eyesClose=eyes_close.png; +``` + +### 立ち絵レイヤー制御 + +`zIndex`パラメータで立ち絵のレイヤーを制御できます： + +``` ws +changeFigure:foreground_char.png -zIndex=100; +changeFigure:background_char.png -zIndex=1; +``` + +### 立ち絵を消去する異なる方法 + +`none`を使用する以外に、`clear`パラメータを使用して立ち絵を消去することもできます： + +``` ws +changeFigure:any -left -clear; +``` + +### Live2D 境界設定 + +Live2D モデルの場合、表示境界を設定できます： + +``` ws +changeFigure:live2d/model.json -bounds=0,0,800,600; +``` + +### 立ち絵アニメーションエフェクト + +立ち絵にアニメーションエフェクトを設定できます： + +``` ws +changeFigure:char.png -duration=2000 -ease=easeInOut; +``` + ## 立ち絵を設定するときにエフェクトを設定する エフェクトのフィールドの説明については、[アニメーション](animation.md)を参照してください。 diff --git a/src/ja/webgal-script/intro.md b/src/ja/webgal-script/intro.md new file mode 100644 index 000000000..e10e7cb72 --- /dev/null +++ b/src/ja/webgal-script/intro.md @@ -0,0 +1,114 @@ +# イントロプレゼンテーション + +WebGALは強力なイントロプレゼンテーション機能を提供し、黒画面テキストデモンストレーションを作成できます。これは通常、ゲームのオープニング、章の遷移、または重要なプロットポイントの雰囲気作りに使用されます。 + +## 基本的な使用方法 + +`intro`コマンドを使用してイントロプレゼンテーションを作成します： + +``` ws +intro:WebGALの世界へようこそ; +``` + +## 複数行テキスト + +`|`区切り文字を使用して複数行テキストプレゼンテーションを作成します： + +``` ws +intro:第1章|秋の思い出|あの黄金の午後に; +``` + +## サポートされるパラメータ + +### 背景設定 + +- `-backgroundImage=画像名` - 背景画像を設定（game/background/ディレクトリから読み込み） +- `-backgroundColor=色の値` - 背景色を設定（デフォルトは黒） + +``` ws +intro:昔々...|遠い土地で... -backgroundImage=sunset.jpg -backgroundColor=rgba(0,0,0,0.8); +``` + +### テキストスタイル + +- `-fontColor=色の値` - フォント色を設定（デフォルトは白） +- `-fontSize=サイズ` - フォントサイズを設定 + +フォントサイズオプション： +- `small` - 小さいフォント（280%） +- `medium` - 中サイズフォント（350%） +- `large` - 大きいフォント（420%） +- `default` - デフォルトフォント + +``` ws +intro:重要なお知らせ -fontSize=large -fontColor=rgba(255,200,100,1); +``` + +### アニメーション効果 + +- `-animation=アニメーションタイプ` - アニメーション効果を設定 + +サポートされるアニメーションタイプ： +- `fadeIn` - フェードイン効果（デフォルト） +- `slideIn` - スライドイン効果 +- `typingEffect` - タイピング効果 +- `pixelateEffect` - ピクセル化効果 +- `revealAnimation` - 表示アニメーション + +``` ws +intro:第1章|秋の思い出|あの黄金の午後に -animation=typingEffect; +``` + +### タイミング制御 + +- `-delayTime=ミリ秒` - 各行のテキスト表示の遅延時間を設定（デフォルト1500ms） + +``` ws +intro:ゆっくりと表示されるテキスト -delayTime=3000; +``` + +### インタラクション制御 + +- `-hold` - 表示を保持し、自動継続しない +- `-userForward` - ユーザーの手動制御（hold効果を含む） + +``` ws +intro:何かキーを押して続行 -hold -fontSize=small; +intro:クリックして次の章へ -userForward; +``` + +## 完全な例 + +``` ws +intro:WebGAL ビジュアルノベルエンジン; +intro:第1章|秋の出会い|あの黄金の午後に -fontSize=large -animation=fadeIn -delayTime=2000; +intro:物語が始まろうとしています...|準備してください -backgroundImage=autumn_bg.jpg -fontColor=rgba(255,215,0,1) -animation=slideIn; +intro:何かキーを押してゲームを開始 -hold -fontSize=small -fontColor=rgba(200,200,200,1); +``` + +## 特別な機能 + +### エスケープ文字 + +テキストでリテラル`|`文字を使用する必要がある場合は、エスケープ文字を使用します： + +``` ws +intro:これは例です\|これは改行されません; +``` + +### 早送りサポート + +イントロプレゼンテーションは早送りのためのユーザーインタラクションをサポートします： +- マウスクリックでテキスト表示を加速できます +- 任意のキー押下でテキスト表示を加速できます +- プレゼンテーション終了後、自動的に次のスクリプトに進みます + +## 使用のヒント + +1. **合理的な背景使用**: 異なるシナリオに適した背景画像や色を選択 +2. **ペースの制御**: `delayTime`を通じてテキスト表示のペースを調整 +3. **フォントサイズ**: テキストの重要度に基づいて適切なフォントサイズを選択 +4. **アニメーション効果**: 雰囲気に基づいて適切なアニメーション効果を選択 +5. **インタラクション設計**: 適切な場所で`-hold`を使用してユーザーがペースを制御できるようにする + +イントロプレゼンテーションは没入感のある体験を創造する重要なツールであり、適切な使用によりゲームの表現力を大幅に向上させることができます。 \ No newline at end of file diff --git a/src/ja/webgal-script/other-features.md b/src/ja/webgal-script/other-features.md new file mode 100644 index 000000000..753421d60 --- /dev/null +++ b/src/ja/webgal-script/other-features.md @@ -0,0 +1,204 @@ +# その他の機能 + +WebGALは、より豊かなゲーム体験を作成するのに役立つその他の便利な機能も提供しています。 + +## 映画モード + +映画モードは、ビデオプレーヤーの「シネマモード」のような、より没入感のある視聴体験を作成します。 + +### 映画モードを有効にする + +``` ws +filmMode:on; // 映画モードを有効にする +filmMode:cinematic; // 映画モードを有効にする（パラメータ付き） +``` + +### 映画モードを無効にする + +``` ws +filmMode:; // 映画モードを無効にする +filmMode:none; // 映画モードを無効にする +``` + +### 特徴 + +- 一部のUI要素を非表示にします +- 即座に効果を発揮し、スクリプトの実行をブロックしません +- 重要なプロットポイントや特別なシーンに適しています + +### 使用例 + +``` ws +; 重要なプロットシーンに入る +filmMode:on; +changeBg:important_scene.jpg; +これは重要なプロットの対話です...; +; プロット終了後に映画モードを終了 +filmMode:; +``` + +## CGのアンロック + +背景変更時にCGを自動的にアンロックするほか、表示せずに別々にCGをアンロックすることもできます。 + +### 基本的な使用方法 + +``` ws +unlockCg:cg/scene1.jpg; +``` + +### CG名とシリーズの設定 + +``` ws +unlockCg:cg/ending_a.jpg -name=ハッピーエンディング; +unlockCg:cg/chapter2_01.jpg -name=初めての出会い -series=第2章; +``` + +### パラメータの説明 + +- `-name=名前` - CGの表示名を設定（デフォルトはファイルパスを使用） +- `-series=シリーズ名` - CGのシリーズ/カテゴリを設定（デフォルトは"default"） + +### 特徴 + +- アンロックされたCGはユーザーデータに保存されます +- CGカテゴリ管理をサポートします +- 即座に効果を発揮し、スクリプトの実行をブロックしません + +## BGMのアンロック + +再生せずにBGMを鑑賞モードに別々にアンロックできます。 + +### 基本的な使用方法 + +``` ws +unlockBgm:s_Title.mp3; +``` + +### BGM名とシリーズの設定 + +``` ws +unlockBgm:s_Title.mp3 -name=Smiling-Swinging!!!; +unlockBgm:s_Title.mp3 -name=テーマソング -series=OP; +``` + +### パラメータの説明 + +- `-name=名前` - BGMの表示名を設定（デフォルトはファイルパスを使用） +- `-series=シリーズ名` - BGMのシリーズ/カテゴリを設定（デフォルトは"default"） + +## テキストボックスの制御 + +テキストボックスの表示と非表示を制御し、フルスクリーンプレゼンテーションに適しています。 + +### テキストボックスを非表示にする + +``` ws +setTextbox:hide; +``` + +### テキストボックスを表示する + +``` ws +setTextbox:; +setTextbox:show; +``` + +### 使用シナリオ + +``` ws +; フルスクリーンCGを表示 +setTextbox:hide; +changeBg:fullscreen_cg.jpg; +wait:3000; +; テキストボックスを復元 +setTextbox:; +なんて美しい風景でしょう！; +``` + +## 動的スタイル切り替え + +UI要素のCSSクラス名を動的に置き換えて、テーマ切り替えなどの機能を実装できます。 + +### 単一スタイル置換 + +``` ws +applyStyle:textbox-default->textbox-dark; +``` + +### 一括スタイル置換 + +``` ws +applyStyle:btn-primary->btn-dark,text-light->text-dark,bg-light->bg-dark; +``` + +### 使用シナリオ + +- 動的テーマ切り替え（例：昼/夜モード） +- 特定のシーンのUIスタイル変更 +- プロットの必要に応じたインターフェーススタイル変更 + +### 例 + +``` ws +; 夜モードに切り替え +applyStyle:textbox-light->textbox-dark,btn-light->btn-dark; +; 特別なシーンスタイル +applyStyle:ui-normal->ui-horror; +``` + +## デバッグ機能 + +### すべての変数を表示 + +``` ws +showVars:; +``` + +現在のすべての変数の値（通常の変数とグローバル変数を含む）をJSON形式で対話ボックスに表示します。 + +### 使用シナリオ + +- 複雑な変数ロジックのデバッグ +- 変数の状態確認 +- 開発中のトラブルシューティング + +## ゲーム終了 + +ゲーム終了時に使用し、タイトル画面に戻ります。 + +``` ws +end; +``` + +### 機能 + +- ゲームステージの状態をリセット +- クイックセーブをクリア +- 初期シーン（start.txt）を再読み込み +- タイトル画面のBGMを再生 + +## 待機コマンド + +指定した時間だけゲームを一時停止します。 + +``` ws +wait:1000; // 1秒間待機 +wait:500; // 0.5秒間待機 +``` + +### 特徴 + +- 時間単位はミリ秒 +- 自動的に次のステートメントにジャンプ +- プレゼンテーションのペース制御に適している + +## 使用のヒント + +1. **映画モードの合理的使用**: 重要なプロットポイントや特別なシーンで使用し、頻繁に切り替えない +2. **CGアンロックタイミング**: 適切なプロットポイントでCGをアンロックし、プレイヤーの達成感を向上させる +3. **テキストボックス制御**: 主にフルスクリーンプレゼンテーションに使用し、使用後は復元することを忘れない +4. **スタイル切り替え**: 切り替えるスタイルが存在することを確認し、スタイルエラーを避ける +5. **デバッグ機能**: 開発中に頻繁に使用し、リリース前にデバッグコードを削除することを忘れない + +これらの機能は簡単に見えるかもしれませんが、適切に使用することでゲームの専門性とユーザー体験を大幅に向上させることができます。 \ No newline at end of file diff --git a/src/ja/webgal-script/scenes.md b/src/ja/webgal-script/scenes.md index 8390f350d..819ab79f5 100644 --- a/src/ja/webgal-script/scenes.md +++ b/src/ja/webgal-script/scenes.md @@ -138,4 +138,76 @@ label:label_2; // label_2という名前のラベルを作成します ...... ``` -このスクリプトでは、`分岐2`を選択した場合、すべて問題ないように見えます。しかし、`分岐1`を選択すると、`分岐1`の実行後に`分岐2`が実行されることに驚かれるでしょう。これは、プログラムが順番に次の行を実行し続け、分岐の終了後にジャンプする場所を指定していないためです。 \ No newline at end of file +このスクリプトでは、`分岐2`を選択した場合、すべて問題ないように見えます。しかし、`分岐1`を選択すると、`分岐1`の実行後に`分岐2`が実行されることに驚かれるでしょう。これは、プログラムが順番に次の行を実行し続け、分岐の終了後にジャンプする場所を指定していないためです。 + +## ユーザー入力 + +WebGALはユーザーのテキスト入力を取得し、変数に保存することをサポートしています。 + +### ユーザー入力の取得 + +`getUserInput`を使用すると、入力ボックスを表示し、プレイヤーにテキストコンテンツを入力させることができます： + +``` ws +getUserInput:playerName -title=お名前を入力してください -buttonText=決定; +``` + +### サポートされているパラメータ + +- `title` - 入力ボックスのタイトル文字 +- `buttonText` - 確認ボタンの文字 +- `defaultValue` - 入力ボックスのデフォルト値 + +### 使用例 + +``` ws +getUserInput:playerName -title=お名前を入力してください -buttonText=決定; +こんにちは、{playerName}！私たちの世界へようこそ。; + +getUserInput:answer -title=1+1は何ですか？ -buttonText=答えを送信; +choose:(answer==2)->正解です:correct|(answer!=2)->不正解です:wrong; +``` + +### 注意事項 + +- 入力された内容は指定された変数に自動的に保存されます +- 変数は後続のスクリプトで使用でき、条件判定や対話表示などに使用できます +- 入力プロセス中はゲームが一時停止し、ユーザーの入力完了を待ちます + +## 高度な分岐機能 + +### 選択肢の複雑な条件 + +選択肢は複雑な条件式をサポートしています： + +``` ws +choose:(score>50&&hasKey)->宝箱を開く:treasure.txt|(score<=50)->力が足りない:fail.txt|引き返す:leave.txt; +``` + +### シーンジャンプ vs ラベルジャンプ + +- **シーンジャンプ**：他の`.txt`ファイルへのジャンプに使用、章の切り替えに適している +- **ラベルジャンプ**：同じファイル内でのジャンプに使用、シンプルな分岐に適している + +識別方法：ジャンプ先に`.`文字が含まれている場合はシーンジャンプとみなされ、そうでない場合はラベルジャンプとみなされます。 + +``` ws +choose:次の章:Chapter-2.txt|再試行:retry; // 最初はシーンジャンプ、二番目はラベルジャンプ +``` + +### ラベルジャンプの制限 + +- ラベルジャンプは現在のシーンファイル内でのみ実行できます +- 他のファイル内のラベルにはジャンプできません +- ラベル名は同じファイル内で一意である必要があります + +## フィルムモード + +WebGALはフィルムモードをサポートしており、より没入感のある視聴体験を作り出すことができます： + +``` ws +filmMode:on; // フィルムモードを有効化 +filmMode:; // フィルムモードを無効化 +``` + +フィルムモードは一部のUI要素を非表示にし、ビデオプレイヤーの「シアターモード」のような効果を作り出します。 \ No newline at end of file diff --git a/src/ja/webgal-script/variable.md b/src/ja/webgal-script/variable.md index bbf03ef47..999cdf1fe 100644 --- a/src/ja/webgal-script/variable.md +++ b/src/ja/webgal-script/variable.md @@ -10,8 +10,9 @@ ``` ws setVar:a=1; // 数字を設定可能 -setVar:a=true // 真偽値を設定可能 -setVar:a=キャラクター名 // 文字列を設定可能 +setVar:a=true; // 真偽値を設定可能 +setVar:a=キャラクター名; // 文字列を設定可能 +setVar:a=; // 空の値（空の文字列）を設定可能 ``` 乱数を設定する場合は、`random()` を使用してください。 @@ -49,6 +50,25 @@ setVar:a=1; setVar:b=a+1; ``` +### 高度な式サポート + +`setVar` は複雑な数学式と文字列演算をサポートしています： + +``` ws +; 括弧と演算子優先度をサポート +setVar:result=(a+b)*2-c/3; + +; 文字列は自動的に連結されます +setVar:a=hello; +setVar:b=world; +setVar:c=a+b; // c の値は "helloworld" になります + +; 変数参照 +setVar:baseScore=100; +setVar:bonus=50; +setVar:totalScore=baseScore+bonus; // totalScore は 150 になります +``` + ## 条件付き実行 文の後に `-when=(condition)` パラメータを追加すると、現在の文を実行するかどうかを条件で判断することができます。 @@ -80,7 +100,36 @@ changeScene:3.txt; getUserInput:name -title=あなたの名前を教えてください -buttonText=確認; ユーザー入力を name 変数に書き込む ``` -ここで、`title` パラメータはプロンプトのテキストで、`buttonText` は確認ボタンのテキストです。 +ここで、`title` パラメータはプロンプトのテキストで、`buttonText` は確認ボタンのテキストで、`defaultValue` はデフォルト値です。 + +## 変数のデバッグ + +`showVars` 命令を使用すると、現在のすべての変数の値（通常の変数とグローバル変数の両方）を表示できます： + +``` ws +setVar:score=100; +setVar:playerName=Alice -global; +showVars:; // すべての変数のJSON形式をダイアログボックスに表示 +``` + +この命令は主にデバッグ用で、ゲーム内のすべての変数の状態を理解するのに役立ちます。 + +## 動的なUIスタイル切り替え + +`applyStyle` 命令を使用すると、UI要素のCSSクラス名を動的に置き換えることができます： + +``` ws +; 単一のスタイルを切り替え +applyStyle:textbox-default->textbox-dark; + +; 複数のスタイルを一括切り替え +applyStyle:btn-primary->btn-dark,text-light->text-dark,bg-light->bg-dark; +``` + +この機能は以下の用途に使用できます： +- 動的なテーマ切り替え（昼間/夜間モードなど） +- 特定シーンでのUIスタイル変更 +- ストーリーに応じたインターフェイススタイルの変更 ## 変数補間 @@ -118,7 +167,7 @@ label:turn-2; changeScene:二周目ストーリー.txt; ``` -## 高级用法（`>=4.5.4`） +## 高度な使用法（`>=4.5.4`） 組み込み変数は、構成変数の変更や、組み込み変数に基づいて論理的に実行して条件を指定するなど、より高度な操作に使用します。 WebGAL には現在、`stage` と `userData` の 2 つの組み込み変数フィールドがあります。 @@ -174,7 +223,7 @@ WebGAL:現在のゲームのタイトルは次のとおりです{Game_name}; もちろん、`config.txt`でカスタム構成変数を作成することもできます。たとえば、バージョン番号を作成します： ```text -Game_name:欢迎使用WebGAL！; +Game_name:WebGALへようこそ！; Game_key:f60ad5725c1588; Title_img:WebGAL_New_Enter_Image.png; Title_bgm:s_Title.mp3; diff --git a/src/ja/webgal-script/video.md b/src/ja/webgal-script/video.md index 49c8420e9..e9e5beb99 100644 --- a/src/ja/webgal-script/video.md +++ b/src/ja/webgal-script/video.md @@ -8,4 +8,33 @@ playVideo:OP.mp4; ``` -ユーザーが動画をスキップできないようにするには、`-skipOff` パラメータを使用できます。 \ No newline at end of file +ユーザーが動画をスキップできないようにするには、`-skipOff` パラメータを使用できます。 + +``` ws +playVideo:OP.mp4 -skipOff; +``` + +## 動画再生の動作 + +動画再生時には以下の動作があります： + +1. **音声制御**：動画再生時は現在のBGMと音声が自動的に一時停止され、動画終了後に音量が自動的に復元されます。 + +2. **スキップ機能**：デフォルトでは、ユーザーは動画をダブルクリックして再生をスキップできます。`-skipOff` パラメータを使用してこの機能を無効にできます。 + +3. **フルスクリーン再生**：動画はフルスクリーンモードで再生され、ゲーム画面全体をカバーします。 + +4. **自動継続**：動画再生完了後、自動的に次のスクリプトの実行が継続されます。 + +## サポートされる動画形式 + +WebGAL はブラウザで再生可能な動画形式をサポートしています。推奨形式： +- MP4 形式（H.264 エンコード） +- WebM 形式 +- OGV 形式 + +## 使用上の推奨事項 + +- 動画ファイルは `video` フォルダに配置してください +- 読み込み時間を短縮するため、圧縮された動画ファイルの使用を推奨します +- 重要なストーリー動画については、誤操作によるスキップを防ぐため `-skipOff` パラメータの使用を推奨します \ No newline at end of file diff --git a/src/spine.md b/src/spine.md index d4e36aedf..85d8c6a9a 100644 --- a/src/spine.md +++ b/src/spine.md @@ -97,4 +97,131 @@ changeFigure:exampleSpine/data.json?type=spine; 总而言之，如果您选择在 WebGAL 中集成或使用 Spine 功能，您必须确保已经合法获得了 Spine 编辑器的授权许可证，并且承诺遵守所有相关的许可证条款与规定。否则，所有由此产生的风险、责任及后果，均由您个人或您的组织承担，与 WebGAL 项目团队无关。 -使用本软件即表示您已阅读、理解并同意以上免责声明的全部内容。如果您不同意这些条款，请立即停止使用集成了 Spine 功能的 WebGAL 版本。 \ No newline at end of file +使用本软件即表示您已阅读、理解并同意以上免责声明的全部内容。如果您不同意这些条款，请立即停止使用集成了 Spine 功能的 WebGAL 版本。 + +## Spine 动画使用指南 + +在完成上述许可证要求和技术集成后，您可以按照以下说明在 WebGAL 中使用 Spine 动画功能。 + +### 文件格式 + +Spine 动画通常包含以下文件： +- `.skel` - 骨骼数据文件（二进制格式） +- `.json` - 骨骼数据文件（JSON格式） +- `.atlas` - 纹理图集描述文件 +- `.png` - 纹理图片文件 + +### 基本使用方法 + +#### 设置 Spine 立绘 + +使用 `.skel` 文件扩展名或 `type=spine` 参数来指定 Spine 动画： + +``` ws +changeFigure:character.skel; +changeFigure:character.json?type=spine; +``` + +#### 设置 Spine 背景 + +同样可以将 Spine 动画用作背景： + +``` ws +changeBg:background.skel; +changeBg:background.json?type=spine; +``` + +#### 立绘位置设置 + +Spine 立绘支持预设位置，与普通立绘相同： + +``` ws +changeFigure:character.skel -left; +changeFigure:character.skel -right; +changeFigure:character.skel; // 默认为中间位置 +``` + +### 动画控制 + +#### 切换动作 + +可以使用 `-motion` 参数来切换 Spine 动画，就像 Live2D 一样： + +``` ws +changeFigure:character.skel -motion=idle; +changeFigure:character.skel -motion=walk -left; +``` + +#### 自定义ID的Spine立绘 + +可以为 Spine 立绘指定自定义ID，然后使用 `-motion` 参数控制动画： + +``` ws +changeFigure:character.skel -id=mainCharacter -left; +changeFigure:character.skel -id=mainCharacter -motion=happy; +``` + + +### 动画行为 + +- 当 Spine 动画加载时，会自动播放第一个可用动画 +- 如果状态中指定了特定动画，会优先播放指定动画 +- Spine 动画会自动缩放以适应屏幕大小 + +### 使用示例 + +``` ws +; 设置主角立绘 +changeFigure:mainCharacter.skel -id=hero -center; + +; 播放问候动画 +changeFigure:hero.skel -motion=greeting -id=hero; + +; 设置配角立绘 +changeFigure:sidekick.skel -left; + +; 设置动态背景 +changeBg:forest.skel; +``` + +### 与其他功能的组合使用 + +Spine 动画可以与其他 WebGAL 功能结合使用： + +``` ws +; 结合语音播放 +角色名:你好！ -V1.ogg -figureId=hero; +changeFigure:character.skel -id=hero -motion=speaking; + +; 结合场景切换 +changeFigure:character.skel -id=hero; +changeFigure:character.skel -id=hero -motion=idle; +changeScene:next_scene.txt; +``` + +### 性能考虑 + +1. **内存使用**：Spine 动画比静态图片占用更多内存 +2. **加载时间**：首次加载可能需要更长时间 +3. **兼容性**：需要浏览器支持 WebGL + +### 故障排除 + +#### 常见问题 + +1. **动画不播放**：检查动画名称是否与 Spine 文件中定义的名称一致 +2. **文件加载失败**：确保 `.skel`、`.atlas` 和纹理文件都在同一目录 +3. **显示异常**：检查 Spine 版本兼容性 + +#### 调试提示 + +- 使用浏览器开发者工具查看控制台日志 +- 检查网络面板确认所有文件都已正确加载 +- 确认 Spine 文件导出设置正确 + +### 注意事项 + +- 动画名称必须与 Spine 文件中定义的动画名称一致 +- 立绘会保持宽高比，并缩放至适合屏幕 +- 背景会拉伸或缩放以填充整个屏幕 +- 请确保遵守所有 Spine 许可证要求 \ No newline at end of file diff --git a/src/webgal-script/README.md b/src/webgal-script/README.md index fa24fa1ba..553387f8e 100644 --- a/src/webgal-script/README.md +++ b/src/webgal-script/README.md @@ -2,20 +2,23 @@ ## 目录 +### 基础功能 - [基础](base.md) - - [对话](dialogue.md) +### 视觉内容 - [背景与立绘](bg-and-figure.md) +- [动画效果](animation.md) +- [特效](special-effect.md) +### 音视频 - [音频](audio.md) - - [视频](video.md) +### 交互与流程 - [场景与分支](scenes.md) - - [变量](variable.md) -- [动画效果](animation.md) - -- [特效](special-effect.md) +### 高级功能 +- [片头演示](intro.md) +- [其他功能](other-features.md) diff --git a/src/webgal-script/animation.md b/src/webgal-script/animation.md index ffff28e44..a3187cb9e 100644 --- a/src/webgal-script/animation.md +++ b/src/webgal-script/animation.md @@ -9,6 +9,8 @@ ``` ws ; // 为中间立绘设置一个从下方进入的动画，并转到下一句 setAnimation:enter-from-bottom -target=fig-center -next; +; // 持续播放动画 +setAnimation:shake -target=bg-main -keep; ``` 目前，预制的动画有： @@ -89,6 +91,26 @@ setAnimation:enter-from-bottom -target=fig-center -next; | rotation | 旋转角度，单位为弧度 | | blur | 高斯模糊半径 | | duration | 这个时间片的持续时间，单位为毫秒(ms) | +| brightness | 亮度调整 | +| contrast | 对比度调整 | +| saturation | 饱和度调整 | +| gamma | 伽马值调整 | +| colorRed | 红色通道调整（0-255） | +| colorGreen | 绿色通道调整（0-255） | +| colorBlue | 蓝色通道调整（0-255） | +| bevel | 斜面效果强度 | +| bevelThickness | 斜面厚度 | +| bevelRotation | 斜面旋转 | +| bevelSoftness | 斜面柔和度 | +| bevelRed | 斜面红色通道（0-255） | +| bevelGreen | 斜面绿色通道（0-255） | +| bevelBlue | 斜面蓝色通道（0-255） | +| bloom | 发光效果 | +| bloomBrightness | 发光亮度 | +| bloomBlur | 发光模糊 | +| bloomThreshold | 发光阈值 | +| shockwaveFilter | 冲击波效果 | +| radiusAlphaFilter | 径向透明度 | | oldFilm | 老电影效果，0代表关闭，1代表开启 | | dotFilm | 点状电影效果，0代表关闭，1代表开启 | | reflectionFilm | 反射电影效果，0代表关闭，1代表开启 | @@ -164,3 +186,56 @@ setTransition: -target=fig-center -enter=enter-from-bottom -exit=exit; 如果不在立绘或背景设置后立即执行进出场效果的设置，等到图像已经进场了，再覆盖进场动画就没有意义了。但如果此时图像还没有出场，设置的出场动画仍有意义。其会在立绘或背景出场时正确地被应用。 ::: + +## 高级动画功能 + +### 临时动画 (setTempAnimation) + +创建并执行临时的自定义动画，通过 JSON 格式定义动画效果： + +``` ws +setTempAnimation:[{"alpha":0,"duration":0},{"alpha":1,"duration":300}] -target=fig-center; +``` + +### 变换动画 (setTransform) + +创建从当前状态到目标状态的变换动画： + +``` ws +setTransform:{"position":{"x":100,"y":0},"scale":{"x":1.2,"y":1.2}} -duration=1000 -ease=easeInOut -target=fig-center; +``` + +支持的参数： +- `duration` - 动画持续时间（毫秒） +- `ease` - 缓动函数名称（如 easeInOut、easeIn、easeOut 等） +- `target` - 作用目标 +- `keep` - 是否保持最终状态 + +### 复杂动画 (setComplexAnimation) + +执行预注册的复杂动画函数： + +``` ws +setComplexAnimation:customEffect -duration=2000 -target=bg-main; +``` + +### 动画参数说明 + +#### 通用参数 +- `target` - 作用目标（fig-left、fig-center、fig-right、bg-main 或自定义 ID） +- `writeDefault` - 是否写入默认值（可选，默认 false） +- `keep` - 是否保持动画持续或保持最终状态（可选，默认 false） + +#### 缓动函数 +WebGAL 支持多种缓动函数，包括： +- `easeIn` - 缓慢开始 +- `easeOut` - 缓慢结束 +- `easeInOut` - 缓慢开始和结束 +- 以及其他更多缓动函数 + +### 动画最佳实践 + +1. **性能考虑**：避免同时运行过多复杂动画 +2. **用户体验**：确保动画不会影响文本阅读 +3. **组合使用**：合理组合不同类型的动画创造更丰富的效果 +4. **调试技巧**：使用较短的持续时间进行测试，确认效果后再调整 diff --git a/src/webgal-script/audio.md b/src/webgal-script/audio.md index dcc0a853c..a3fea2f56 100644 --- a/src/webgal-script/audio.md +++ b/src/webgal-script/audio.md @@ -26,10 +26,19 @@ bgm:夏影.mp3 -enter=3000; bgm:none -enter=3000; ``` +### 解锁BGM功能 + +在播放BGM的同时，也可以解锁BGM到鉴赏模式： + +``` ws +bgm:夏影.mp3 -unlockname=夏之影 -series=season; +``` + ::: tip `-volume` 和 `-enter` 都是可选参数。 `-volume` 未使用时，或使用了 0 ~ 100 以外的值时，将使用默认值 100。 `-enter` 未使用时，或使用了 0 ~ 以外的值时，将使用默认值 0。 +`-unlockname` 和 `-series` 参数用于解锁BGM到鉴赏模式。 ::: ## 播放语音 @@ -53,9 +62,20 @@ bgm:none -enter=3000; 比企谷八幡:刚到而已 -V3.ogg -volume=30; ``` +### 语音与立绘动画联动 + +语音播放时可以与立绘动画联动，实现口型和眨眼动画： + +``` ws +角色名:这段对话有语音 -V1.ogg -left; // 关联左侧立绘 +角色名:这段对话有语音 -V2.ogg -figureId=char1; // 关联指定ID的立绘 +``` + ::: tip `-volume` 是可选参数。 `-volume` 未设置时，或使用了 0 ~ 100 以外的值时，将使用默认值 100。 +`-left`、`-right`、`-center` 参数用于指定语音关联的立绘位置。 +`-figureId` 参数用于指定特定的立绘ID。 ::: ## 播放效果音 @@ -93,4 +113,7 @@ playEffect:none -id=xxx; // 停止这个循环的效果音 ``` ws ; // 解锁bgm并赋予名称 unlockBgm:s_Title.mp3 -name=Smiling-Swinging!!!; +unlockBgm:s_Title.mp3 -name=主题曲 -series=OP; ``` + +`-series` 参数用于设置音频的所属系列，便于在鉴赏模式中分类管理。 diff --git a/src/webgal-script/base.md b/src/webgal-script/base.md index e8c7d2822..eb474914d 100644 --- a/src/webgal-script/base.md +++ b/src/webgal-script/base.md @@ -52,3 +52,88 @@ changeFigure:k2.png -next; 这是第一句......; 用户点击鼠标后才会转到第二句 -concat; ``` + +## 对话命令 + +在 WebGAL 中，最基本的功能是显示对话。 + +### 基本对话 + +直接输入文本即可显示对话： + +``` ws +这是一段对话; +``` + +### 角色对话 + +你可以为对话指定说话者： + +``` ws +角色名:这是角色说的话; +``` + +### 对话参数 + +对话支持以下参数： + +- `-speaker=名称` - 设置说话者名称 +- `-clear` - 清除当前说话者名称 +- `-vocal=语音文件` - 播放语音文件 +- `-fontSize=small/medium/large/default` - 设置文字大小 +- `-left/-right/-center` - 设置说话角色位置（用于口型动画） +- `-figureId=ID` - 指定说话的角色ID（用于口型动画） + +``` ws +角色名:这是一段对话 -speaker=角色名; +这段对话播放语音 -vocal=voice01.ogg; +这段对话使用大字体 -fontSize=large; +清除说话者的对话 -clear; +``` + +## 等待命令 + +使用 `wait` 命令可以让游戏暂停指定时间： + +``` ws +wait:1000; // 等待1秒 +wait:500; // 等待0.5秒 +``` + +## 结束游戏命令 + +使用 `end` 命令可以结束当前游戏并返回标题画面： + +``` ws +end; // 结束游戏 +``` + +## 文本框控制 + +使用 `setTextbox` 指令可以控制文本框的显示和隐藏： + +``` ws +setTextbox:hide; // 隐藏文本框 +setTextbox:; // 显示文本框 +``` + +这在需要展示全屏图片或特殊演出时非常有用。 + +## 调试功能 + +使用 `showVars` 指令可以显示当前所有变量的值： + +``` ws +showVars:; // 显示所有变量 +``` + +## 片头演示 + +使用 `intro` 指令可以创建黑屏文字演示效果： + +``` ws +intro:欢迎来到WebGAL的世界; +intro:第一章|秋日的回忆|在那个金色的午后 -fontSize=large; +``` + +更多参数请查看具体章节的说明。 diff --git a/src/webgal-script/bg-and-figure.md b/src/webgal-script/bg-and-figure.md index 6f2502d97..ac63ebb78 100644 --- a/src/webgal-script/bg-and-figure.md +++ b/src/webgal-script/bg-and-figure.md @@ -86,6 +86,83 @@ unlockCg:xgmain.jpeg -name=星光咖啡馆与死神之蝶 -series=1; 其中，`-series` 参数可选，代表当前立绘属于哪个系列。同系列的立绘以后会合并展示（即展示成可以切换的同系列CG）。 +## 高级背景切换功能 + +### 解锁背景CG + +`changeBg` 命令也支持解锁CG功能，可以在切换背景的同时解锁CG： + +``` ws +changeBg:cg_scene1.jpg -unlockname=第一章场景 -series=主线CG; +``` + +### 背景变换效果 + +可以为背景切换设置变换效果： + +``` ws +changeBg:bg_night.jpg -transform={"position":{"x":-100,"y":0},"scale":{"x":1.2,"y":1.2}} -duration=3000; +``` + +### 预设动画效果 + +可以使用预设的进入和退出动画： + +``` ws +changeBg:bg_morning.jpg -enter=fadeIn -exit=fadeOut; +``` + +## 高级立绘功能 + +### Live2D 支持 + +WebGAL 支持 Live2D 立绘，可以控制动作和表情： + +``` ws +changeFigure:live2d/model.json -motion=idle -expression=happy; +``` + +### 立绘口型和眨眼动画 + +可以为立绘设置口型和眨眼动画素材： + +``` ws +changeFigure:char.png -mouthOpen=mouth_open.png -mouthClose=mouth_close.png -eyesOpen=eyes_open.png -eyesClose=eyes_close.png; +``` + +### 立绘层级控制 + +可以通过 `zIndex` 参数控制立绘的层级： + +``` ws +changeFigure:foreground_char.png -zIndex=100; +changeFigure:background_char.png -zIndex=1; +``` + +### 清除立绘的不同方式 + +除了使用 `none` 外，还可以使用 `clear` 参数清除立绘： + +``` ws +changeFigure:any -left -clear; +``` + +### Live2D 边界设置 + +对于 Live2D 模型，可以设置显示边界： + +``` ws +changeFigure:live2d/model.json -bounds=0,0,800,600; +``` + +### 立绘动画效果 + +可以为立绘设置动画效果： + +``` ws +changeFigure:char.png -duration=2000 -ease=easeInOut; +``` + ## 设置立绘时设置效果 有关效果的字段说明，请参考 [动画](animation.md) diff --git a/src/webgal-script/intro.md b/src/webgal-script/intro.md new file mode 100644 index 000000000..20daa015c --- /dev/null +++ b/src/webgal-script/intro.md @@ -0,0 +1,114 @@ +# 片头演示 + +WebGAL 提供了强大的片头演示功能，可以创建黑屏文字演示效果，通常用于游戏的片头、章节过渡或重要剧情的氛围营造。 + +## 基本用法 + +使用 `intro` 命令创建片头演示： + +``` ws +intro:欢迎来到WebGAL的世界; +``` + +## 多行文本 + +使用 `|` 分隔符创建多行文本演示： + +``` ws +intro:第一章|秋日的回忆|在那个金色的午后; +``` + +## 支持的参数 + +### 背景设置 + +- `-backgroundImage=图片名称` - 设置背景图片（从 game/background/ 目录加载） +- `-backgroundColor=颜色值` - 设置背景颜色（默认为黑色） + +``` ws +intro:很久很久以前...|在一个遥远的地方... -backgroundImage=sunset.jpg -backgroundColor=rgba(0,0,0,0.8); +``` + +### 文字样式 + +- `-fontColor=颜色值` - 设置字体颜色（默认为白色） +- `-fontSize=尺寸` - 设置字体大小 + +字体大小选项： +- `small` - 小字体（280%） +- `medium` - 中等字体（350%） +- `large` - 大字体（420%） +- `default` - 默认字体 + +``` ws +intro:重要公告 -fontSize=large -fontColor=rgba(255,200,100,1); +``` + +### 动画效果 + +- `-animation=动画类型` - 设置动画效果 + +支持的动画类型： +- `fadeIn` - 淡入效果（默认） +- `slideIn` - 滑入效果 +- `typingEffect` - 打字机效果 +- `pixelateEffect` - 像素化效果 +- `revealAnimation` - 揭示动画 + +``` ws +intro:第一章|秋日的回忆|在那个金色的午后 -animation=typingEffect; +``` + +### 时间控制 + +- `-delayTime=毫秒数` - 设置每行文字显示的延迟时间（默认 1500ms） + +``` ws +intro:慢慢展示的文字 -delayTime=3000; +``` + +### 交互控制 + +- `-hold` - 保持显示，不自动继续 +- `-userForward` - 用户手动控制前进（隐含 hold 效果） + +``` ws +intro:按任意键继续 -hold -fontSize=small; +intro:点击继续下一章 -userForward; +``` + +## 完整示例 + +``` ws +intro:WebGAL 视觉小说引擎; +intro:第一章|秋日的邂逅|在那个金桂飘香的午后 -fontSize=large -animation=fadeIn -delayTime=2000; +intro:故事即将开始...|请做好准备 -backgroundImage=autumn_bg.jpg -fontColor=rgba(255,215,0,1) -animation=slideIn; +intro:按任意键开始游戏 -hold -fontSize=small -fontColor=rgba(200,200,200,1); +``` + +## 特殊功能 + +### 转义字符 + +如果需要在文本中使用字面上的 `|` 字符，可以使用转义字符： + +``` ws +intro:这是一个例子\|这不会换行; +``` + +### 快进支持 + +片头演示支持用户交互快进： +- 点击鼠标可以加速文字显示 +- 按任意键可以加速文字显示 +- 演出结束后自动进入下一条脚本 + +## 使用建议 + +1. **合理使用背景**：为不同的情景选择合适的背景图片或颜色 +2. **控制节奏**：通过调整 `delayTime` 控制文字显示的节奏 +3. **字体大小**：根据文本重要性选择合适的字体大小 +4. **动画效果**：根据氛围选择合适的动画效果 +5. **交互设计**：在适当的地方使用 `-hold` 让用户控制节奏 + +片头演示是创造沉浸式体验的重要工具，合理使用可以大大提升游戏的表现力。 \ No newline at end of file diff --git a/src/webgal-script/other-features.md b/src/webgal-script/other-features.md new file mode 100644 index 000000000..f3609d8c7 --- /dev/null +++ b/src/webgal-script/other-features.md @@ -0,0 +1,204 @@ +# 其他功能 + +WebGAL 还提供了一些其他实用的功能，这些功能可以帮助你创建更丰富的游戏体验。 + +## 电影模式 + +电影模式可以创造更沉浸的观看体验，类似于视频播放器的"影院模式"。 + +### 启用电影模式 + +``` ws +filmMode:on; // 启用电影模式 +filmMode:cinematic; // 启用电影模式（带参数） +``` + +### 关闭电影模式 + +``` ws +filmMode:; // 关闭电影模式 +filmMode:none; // 关闭电影模式 +``` + +### 特点 + +- 会隐藏部分UI元素 +- 立即生效，不阻塞脚本执行 +- 适合用于重要剧情或特殊场景 + +### 使用示例 + +``` ws +; 进入重要剧情场景 +filmMode:on; +changeBg:important_scene.jpg; +这里是重要的剧情对话...; +; 剧情结束后退出电影模式 +filmMode:; +``` + +## 解锁CG + +除了在切换背景时自动解锁CG，你也可以单独解锁CG而不显示。 + +### 基本用法 + +``` ws +unlockCg:cg/scene1.jpg; +``` + +### 设置CG名称和系列 + +``` ws +unlockCg:cg/ending_a.jpg -name=美好的结局; +unlockCg:cg/chapter2_01.jpg -name=初次相遇 -series=第二章; +``` + +### 参数说明 + +- `-name=名称` - 为CG设置显示名称（默认使用文件路径） +- `-series=系列名` - 设置CG所属的系列/分类（默认为 "default"） + +### 特点 + +- 解锁的CG会保存到用户数据中 +- 支持CG分类管理 +- 立即生效，不阻塞脚本执行 + +## 解锁BGM + +可以单独解锁BGM到鉴赏模式而不播放。 + +### 基本用法 + +``` ws +unlockBgm:s_Title.mp3; +``` + +### 设置BGM名称和系列 + +``` ws +unlockBgm:s_Title.mp3 -name=Smiling-Swinging!!!; +unlockBgm:s_Title.mp3 -name=主题曲 -series=OP; +``` + +### 参数说明 + +- `-name=名称` - 为BGM设置显示名称（默认使用文件路径） +- `-series=系列名` - 设置BGM所属的系列/分类（默认为 "default"） + +## 文本框控制 + +控制文本框的显示和隐藏，适合用于全屏演出。 + +### 隐藏文本框 + +``` ws +setTextbox:hide; +``` + +### 显示文本框 + +``` ws +setTextbox:; +setTextbox:show; +``` + +### 使用场景 + +``` ws +; 展示全屏CG +setTextbox:hide; +changeBg:fullscreen_cg.jpg; +wait:3000; +; 恢复文本框 +setTextbox:; +这真是美丽的风景啊！; +``` + +## 动态样式切换 + +可以动态替换UI元素的CSS类名，实现主题切换等功能。 + +### 单个样式替换 + +``` ws +applyStyle:textbox-default->textbox-dark; +``` + +### 批量样式替换 + +``` ws +applyStyle:btn-primary->btn-dark,text-light->text-dark,bg-light->bg-dark; +``` + +### 使用场景 + +- 动态主题切换（如日间/夜间模式） +- 特定场景的UI风格变化 +- 根据剧情需要改变界面样式 + +### 示例 + +``` ws +; 切换到夜间模式 +applyStyle:textbox-light->textbox-dark,btn-light->btn-dark; +; 特殊场景样式 +applyStyle:ui-normal->ui-horror; +``` + +## 调试功能 + +### 显示所有变量 + +``` ws +showVars:; +``` + +显示当前所有变量的值，包括普通变量和全局变量，以JSON格式显示在对话框中。 + +### 使用场景 + +- 调试复杂的变量逻辑 +- 检查变量状态 +- 开发过程中的问题排查 + +## 结束游戏 + +在游戏结束时使用，会返回到标题画面。 + +``` ws +end; +``` + +### 功能 + +- 重置游戏舞台状态 +- 清除快速存档 +- 重新加载初始场景（start.txt） +- 播放标题画面BGM + +## 等待命令 + +让游戏暂停指定的时间。 + +``` ws +wait:1000; // 等待1秒 +wait:500; // 等待0.5秒 +``` + +### 特点 + +- 时间单位为毫秒 +- 会自动跳转到下一条语句 +- 适合用于控制演出节奏 + +## 使用建议 + +1. **合理使用电影模式**：在重要剧情或特殊场景中使用，不要频繁切换 +2. **CG解锁时机**：在合适的剧情节点解锁CG，增强玩家的成就感 +3. **文本框控制**：主要用于全屏演出，使用后记得恢复 +4. **样式切换**：确保切换的样式存在，避免样式错误 +5. **调试功能**：在开发过程中多使用，发布时记得移除调试代码 + +这些功能虽然看起来简单，但合理使用可以大大提升游戏的专业度和用户体验。 \ No newline at end of file diff --git a/src/webgal-script/scenes.md b/src/webgal-script/scenes.md index 04de36c3b..46b701876 100644 --- a/src/webgal-script/scenes.md +++ b/src/webgal-script/scenes.md @@ -138,3 +138,75 @@ label:label_2; // 创建名为 label_2 的 label ``` 在这个剧本中，如果你选择了 `分支 2`，那么一切看起来好像没有问题。但是如果你选择了 `分支 1`，你会惊讶地发现，在 `分支 1` 执行完后，会继续执行 `分支 2`。那是因为程序按顺序继续执行下一行了，而你没有指定在分支结束后跳到哪里。 + +## 用户输入 + +WebGAL 支持获取用户的文本输入并保存到变量中。 + +### 获取用户输入 + +使用 `getUserInput` 可以显示一个输入框，让玩家输入文本内容： + +``` ws +getUserInput:playerName -title=请输入你的名字 -buttonText=确定; +``` + +### 支持的参数 + +- `title` - 输入框的标题文字 +- `buttonText` - 确认按钮的文字 +- `defaultValue` - 输入框的默认值 + +### 使用示例 + +``` ws +getUserInput:playerName -title=请输入你的名字 -buttonText=确定; +你好，{playerName}！欢迎来到我们的世界。; + +getUserInput:answer -title=1+1等于几？ -buttonText=提交答案; +choose:(answer==2)->回答正确:correct|(answer!=2)->回答错误:wrong; +``` + +### 注意事项 + +- 输入的内容会自动保存到指定的变量中 +- 变量可以在后续的脚本中使用，包括条件判断和对话显示 +- 输入过程中游戏会暂停，等待用户输入完成 + +## 高级分支功能 + +### 选择项的复杂条件 + +选择项支持复杂的条件表达式： + +``` ws +choose:(score>50&&hasKey)->打开宝箱:treasure.txt|(score<=50)->力量不足:fail.txt|回头离开:leave.txt; +``` + +### 场景跳转 vs 标签跳转 + +- **场景跳转**：用于跳转到其他 `.txt` 文件，适合章节切换 +- **标签跳转**：用于在同一文件内跳转，适合简单的分支 + +识别方法：如果跳转目标包含 `.` 字符，则被视为场景跳转；否则被视为标签跳转。 + +``` ws +choose:下一章:Chapter-2.txt|重试:retry; // 第一个是场景跳转，第二个是标签跳转 +``` + +### 标签跳转的限制 + +- 标签跳转只能在当前场景文件内进行 +- 无法跳转到其他文件中的标签 +- 标签名称在同一文件中必须唯一 + +## 电影模式 + +WebGAL 支持电影模式，可以创造更沉浸的观看体验： + +``` ws +filmMode:on; // 启用电影模式 +filmMode:; // 关闭电影模式 +``` + +电影模式会隐藏部分UI元素，创造类似于视频播放器的"影院模式"效果。 diff --git a/src/webgal-script/variable.md b/src/webgal-script/variable.md index 7ad804bca..20c19f24a 100644 --- a/src/webgal-script/variable.md +++ b/src/webgal-script/variable.md @@ -10,8 +10,9 @@ ``` ws setVar:a=1; // 可以设置数字 -setVar:a=true // 可以设置布尔值 -setVar:a=人物名称 // 可以设置字符串 +setVar:a=true; // 可以设置布尔值 +setVar:a=人物名称; // 可以设置字符串 +setVar:a=; // 可以设置空值（空字符串） ``` 设置随机数，请使用 `random()` @@ -49,6 +50,25 @@ setVar:a=1; setVar:b=a+1; ``` +### 高级表达式支持 + +`setVar` 支持复杂的数学表达式和字符串运算： + +``` ws +; 支持括号和运算优先级 +setVar:result=(a+b)*2-c/3; + +; 字符串会自动拼接 +setVar:a=hello; +setVar:b=world; +setVar:c=a+b; // c 的值将是 "helloworld" + +; 变量引用 +setVar:baseScore=100; +setVar:bonus=50; +setVar:totalScore=baseScore+bonus; // totalScore 将是 150 +``` + ## 条件执行 在语句后加上 `-when=(condition)` 参数，可以根据条件判断当前语句是否要执行。 @@ -80,7 +100,36 @@ changeScene:3.txt; getUserInput:name -title=如何称呼你 -buttonText=确认; 将用户输入写入 name 变量中 ``` -其中，`title` 参数是提示的文本，`buttonText` 是确认按钮的文本 +其中，`title` 参数是提示的文本，`buttonText` 是确认按钮的文本，`defaultValue` 是默认值。 + +## 调试变量 + +使用 `showVars` 指令可以显示当前所有变量的值，包括普通变量和全局变量： + +``` ws +setVar:score=100; +setVar:playerName=Alice -global; +showVars:; // 将在对话框中显示所有变量的 JSON 格式 +``` + +这个指令主要用于调试，可以帮助你了解当前游戏中所有变量的状态。 + +## 动态切换 UI 样式 + +使用 `applyStyle` 指令可以动态替换 UI 元素的 CSS 类名： + +``` ws +; 切换单个样式 +applyStyle:textbox-default->textbox-dark; + +; 批量切换样式 +applyStyle:btn-primary->btn-dark,text-light->text-dark,bg-light->bg-dark; +``` + +这个功能可以用于实现： +- 动态主题切换（如日间/夜间模式） +- 特定场景的 UI 风格变化 +- 根据剧情需要改变界面样式 ## 变量插值 diff --git a/src/webgal-script/video.md b/src/webgal-script/video.md index 6139fabdb..fea228924 100644 --- a/src/webgal-script/video.md +++ b/src/webgal-script/video.md @@ -9,3 +9,32 @@ playVideo:OP.mp4; ``` 如果要阻止用户跳过视频，你可以使用 `-skipOff` 参数。 + +``` ws +playVideo:OP.mp4 -skipOff; +``` + +## 视频播放行为 + +播放视频时会有以下行为： + +1. **音频控制**：视频播放时会自动暂停当前的BGM和语音，视频结束后会自动恢复音量。 + +2. **跳过功能**：默认情况下，用户可以双击视频来跳过播放。使用 `-skipOff` 参数可以禁用此功能。 + +3. **全屏播放**：视频会以全屏模式播放，覆盖整个游戏界面。 + +4. **自动继续**：视频播放完毕后会自动继续执行下一条脚本。 + +## 支持的视频格式 + +WebGAL 支持浏览器能够播放的视频格式，建议使用： +- MP4 格式（H.264 编码） +- WebM 格式 +- OGV 格式 + +## 使用建议 + +- 视频文件应该放置在 `video` 文件夹中 +- 建议使用压缩后的视频文件以减少加载时间 +- 对于重要的剧情视频，建议使用 `-skipOff` 参数防止误操作跳过