DOCSEARCHbyAlgolia
Submit Docs

WebGAL Documentation

repository·main·Indexed 26 days ago

https://github.com/openwebgal/webgal

A modern, web-based visual novel engine featuring a no-code graphical editor and a scripting interface. It supports Pixi.js customization and provides tools for animation systems, Z-index hierarchy management, and scene parsing via the @webgal/base package (v4.6.2). The engine includes a server for project detection and a parser for converting scene scripts into structured data.

Tokens
14.1K
Snippets
22
Records
106
Agent score
86%

What's inside WebGAL

  1. Overview of WebGAL

    main
    WebGAL is a web-based visual novel engine designed to make the development of visual novel games easy and accessible. It supports a wide range of features found in mainstream visual novel engines, including animations and special effects for game customization. Games created with WebGAL can be published to websites for play on PCs and smartphones, or exported as executable files for Windows.

  2. Understand the Animation and Transformation System

    main

    In WebGAL, animations are implemented as PIXI.Ticker callback functions.

    Key concepts include:

    • Transformations: A special type of animation with a duration of 0ms that sets a stage object to its final state immediately on the first frame.
    • Internal Transformations: A record of effects applied to specific stage object keys. These are applied whenever an animation ends or a stage object changes to ensure the object maintains its intended position or effect.
    • Locking Mechanism: To prevent conflicts, the WebGAL stage controller locks stage object keys while an animation is in progress. These keys are unlocked only after the animation completes. Upon completion, the animation's 'final state' is updated to the object's 'internal transformation' record.

  3. Get started with WebGAL

    main

    WebGAL is a web-based visual novel engine designed for ease of use and powerful customization. You can create games using a graphical editor, direct scripting, or specialized developer tools.

    Ways to create games:

  4. Flowchart feature overview

    main

    The flowchart feature allows players to view unlocked story nodes via the menu or the bottom control panel and jump back to previously unlocked scenes.

    Key capabilities:

    • Supports multiple routes.
    • Tracks node unlock progress.
    • Provides visibility controls for locked nodes.
    • Note: Resetting game data will also clear all flowchart progress.

  5. Implement a GameScript command

    main

    A GameScript command implementation is a function that receives an ISentence and returns an IPerform.

    Core Principle: Separate the logic of advancing recoverable state from the logic of runtime performance.

    1. Command Function: Responsible for parsing arguments and modifying calculationStageState (the authoritative state for subsequent commands, conditions, and fast previews).
    2. IPerform: Responsible for the runtime performance (visuals, audio, etc.) after the state has been committed.

    If a command has no runtime performance (e.g., it only modifies state), it should return createNonePerform().

    Command registration is handled in Core/parser/sceneParser.ts.

  6. Run WebGAL-Server in Auto-Detection Mode

    main

    WebGAL-Server can automatically detect a WebGAL project root directory in two scenarios:

    1. The current working directory is the WebGAL project root.
    2. The current working directory contains a folder named WebGAL (case-insensitive), which is treated as the project root.

    Use this mode when you are already inside the project folder or its parent directory.

  10. Create games with the WebGAL Graphical Editor

    main

    For users who want to create visual novels without programming, WebGAL provides a graphical editor called WebGAL Terre. You can download the WebGAL Web Editor from its releases page to start building your game visually.

    https://github.com/OpenWebGAL/WebGAL_Terre/releases

  11. Handle animations and state updates

    main

    When implementing animation commands (like setAnimation, setTransform), distinguish between Calculation End State and Runtime Animation.

    1. Calculation End State: The state that subsequent commands, saves, and previews read. This should be written to calculationStageState.effects during the command function stage (e.g., via applyAnimationEndState()).
    2. Runtime Animation: The frame-by-frame visual effect. This should be registered in the startFunction of the returned IPerform.

    Best Practices:

    • Parallel Animations (-parallel): Only write the specific fields the animation controls. For example, if an animation only changes scale, do not reset position to default values; use local field merging instead of full object replacement.
    • State Update Principle: Only write recoverable, saveable, and dependency-critical content to the stage state. Do not write temporary DOM, Pixi tickers, timers, or audio instances to the stage state.
    • Resource Management: Use assetSetter() for resource paths instead of manual string concatenation. Use provided tools like getStringArgByKey, getNumberArgByKey, etc., for argument parsing.