VisualBean Engine

A powerful, lightweight, and customizable engine for creating Visual Novels using Java and Swing. Designed to be easy to use for developers while offering deep customization through CSS-like theming and Java-based scripting.

Features

• Native Java Scripting: Write your game logic using standard Java. Use loops, conditionals, and variables freely.
• Dynamic UI Styling: Customize every aspect of the interface (Dialog boxes, Menus, Buttons) using a simple theme.css file.
• Rich Visuals:
  • Background and Character Sprite support (PNG/JPG).
  • Sub-Windows: Create multiple floating windows for unique storytelling elements.
  • Animations: Smooth window centering, scaling, and character transitions with configurable easing.
• Kinetic Text Renderer: Animated text effects including [shake], [wave], and [color] tags for dynamic dialogue.
• Robust Save System:
  • 9 Save Slots with visual previews.
  • Save/Load game state functionality.
  • Delete save files directly from the UI.
  • Persists window positions and preferences.
• Audio: Support for Background Music (BGM) and Sound Effects (SFX) (WAV/AU formats).
• Window Management: Custom window titles, resizable windows, fullscreen mode, and animated interactions.
• Meta Features (Fourth-Wall Breaking):
  • Desktop wallpaper changing, native OS error popups, Windows notifications, opening websites, and force close window — all directly from the script.
• Quality of Life:
  • Auto-forward text reading mode.
  • Comprehensive settings panel with keybind information.
  • Dynamic window scaling (everything resizes properly).

Getting Started

Prerequisites

• Java Development Kit (JDK) 17 or higher installed.

Installation

1. Clone this repository:

   git clone https://github.com/Mishiranuuuuu/VisualBean
   cd VisualBean

Running the Engine

This project uses Gradle as its build system. A Gradle wrapper is included, so you don't need to install Gradle separately.

• Run the game (compiles and launches):

  # Windows
  gradlew.bat run
  
  # Linux / macOS
  ./gradlew run

• Build a runnable JAR (fat jar with all dependencies):

  # Windows
  gradlew.bat jar
  
  # Linux / macOS
  ./gradlew jar

  The JAR file will be generated in build/libs/.

Creating Your Story

For a detailed guide on creating your own Visual Novel, please refer to HowToCreateYourGame.md included in this repository.

Quick Example

Scripts are located in src/main/java/com/visualbean/game/. Inherit from GameScript to start:

public class MyGame extends GameScript {
    @Override
    public void run() {
        scene("classroom");
        playMusic("bgm_happy");
        
        show("Alice", "smile");
        say("Alice", "Hi! Welcome to VisualBean!");

        say("Alice", "Ready to start?");
        int choice = menu("Yes!", "Not yet.");
        if (choice == 0) {
            say("Alice", "Great! Let's go!");
        }
    }
}

Theming

Modify resources/theme.css to change the look of your game instantly:

.dialog-box {
    background-color: #222222;
    text-color: #FFFFFF;
    font-family: "Segoe UI";
    opacity: 200;
}

Build for Release

To package your game for players:

1. Run the Gradle build:

   gradlew.bat jar

2. Find your JAR in build/libs/.
3. Distribute the JAR along with the resources/ folder.

License

MIT License