docs: Add initial Wiki documentation

Eatgrapes · Eatgrapes · commit eb05cb444bb8 · 2025-12-28T20:18:49.000+08:00
diff --git a/wiki_docs/Getting-Started.md b/wiki_docs/Getting-Started.md
@@ -0,0 +1,72 @@
+# Getting Started
+
+This guide will help you integrate Live2D-JavaBinding into your project.
+
+## Prerequisites
+
+1.  **Java 9 or higher**: The library uses JPMS (Java Platform Module System) and APIs introduced in Java 9.
+2.  **OpenGL Context**: You need a library to create a window and an OpenGL context. We recommend **LWJGL 3**, but any library that provides access to OpenGL bindings will work.
+
+## Installation
+
+Since this library is not hosted on a public Maven repository, you must download the latest release and install it manually.
+
+### 1. Download Release
+Go to the [GitHub Releases](../../releases) page and download:
+*   `live2d-shared.jar`
+*   `live2d-native-[platform].jar` (e.g., `live2d-native-windows-x64.jar`)
+
+### 2. Manual Installation
+You can install them into your local Maven repository:
+
+```bash
+mvn install:install-file -Dfile=live2d-shared.jar -DgroupId=com.example -DartifactId=live2d-shared -Dversion=1.0.0 -Dpackaging=jar
+mvn install:install-file -Dfile=live2d-native-windows-x64.jar -DgroupId=com.example -DartifactId=live2d-native -Dversion=1.0.0 -Dpackaging=jar -Dclassifier=windows-x64
+```
+
+### 3. Build Configuration
+
+#### Maven
+```xml
+<dependencies>
+    <!-- The Core Java API -->
+    <dependency>
+        <groupId>com.example</groupId>
+        <artifactId>live2d-shared</artifactId>
+        <version>1.0.0</version>
+    </dependency>
+
+    <!-- Native Implementation -->
+    <dependency>
+        <groupId>com.example</groupId>
+        <artifactId>live2d-native</artifactId>
+        <version>1.0.0</version>
+        <classifier>windows-x64</classifier> <!-- Change classifier as needed -->
+    </dependency>
+</dependencies>
+```
+
+#### Gradle
+For Gradle, the simplest way is to put the JARs directly into your project:
+
+1.  Create a `libs` folder in your project root.
+2.  Copy the downloaded JARs into it.
+3.  Add dependencies in `build.gradle`:
+
+```groovy
+dependencies {
+    implementation files('libs/live2d-shared.jar')
+    implementation files('libs/live2d-native-windows-x64.jar') // Change for your platform
+}
+```
+
+## Your First Steps
+
+The general flow of a Live2D application is:
+
+1.  **Initialize**: Call `CubismFramework.startUp()`.
+2.  **Load**: Load your model bytes and textures.
+3.  **Loop**: In your render loop, call `model.update()` and `model.draw()`.
+4.  **Dispose**: Clean up when done.
+
+Check out the specific sections in the sidebar to learn how to implement each step!
diff --git a/wiki_docs/Home.md b/wiki_docs/Home.md
@@ -0,0 +1,20 @@
+# Welcome to the Live2D-JavaBinding Wiki
+
+This project provides a high-performance, native Java binding for the **Live2D Cubism SDK**. It allows you to load, render, and interact with Live2D models directly in your Java applications using OpenGL.
+
+## Philosophy
+
+The library is designed to be **unopinionated** about your windowing system. Whether you use **LWJGL**, **JOGL**, or even **JavaFX** (with an OpenGL bridge), this binding provides the raw tools to render the model. We handle the JNI complexity; you handle the context.
+
+## Navigation
+
+*   **[Getting Started](Getting-Started)**: Installation and your first model.
+*   **[Lifecycle Management](Lifecycle-Management)**: Starting up and shutting down the native core safely.
+*   **[Loading Assets](Loading-Assets)**: How to load `.moc3` files, textures, physics, and poses.
+*   **[Rendering Loop](Rendering-Loop)**: The essential `update` and `draw` cycle.
+*   **[Motion & Expressions](Motion-and-Expressions)**: Bringing the model to life with animations.
+*   **[Interaction & Parameters](Interaction-and-Parameters)**: Hit testing, eye tracking, and manual parameter control.
+
+## Status
+
+This project is currently **Work in Progress**. APIs may change slightly as we reach feature parity with the official C++ SDK.
diff --git a/wiki_docs/Interaction-and-Parameters.md b/wiki_docs/Interaction-and-Parameters.md
@@ -0,0 +1,44 @@
+# Interaction & Parameters
+
+Interactive apps require the model to react to the user.
+
+## Mouse Dragging (Look At)
+
+You can make the character look at the mouse cursor.
+
+```java
+// Coordinates should be normalized:
+// X: -1.0 (Left) to 1.0 (Right)
+// Y: -1.0 (Bottom) to 1.0 (Top)
+model.setDragging(mouseX, mouseY);
+```
+
+Call this every time the mouse moves. The model uses this to update standard parameters like `ParamAngleX`, `ParamAngleY`, `ParamEyeBallX`, etc.
+
+## Hit Testing
+
+Detect if the user clicked a specific part of the model (like the head or chest).
+
+```java
+// The ID usually comes from the .model3.json "HitAreas" section
+String hitAreaId = "Head"; 
+
+if (model.isHit(hitAreaId, mouseX, mouseY)) {
+    System.out.println("Headpats received!");
+    model.startExpression("Blush");
+}
+```
+
+## Manual Parameter Control
+
+Sometimes you want direct control (e.g., syncing mouth open with microphone volume).
+
+```java
+// 1. Set a value (0.0 to 1.0, or -30 to 30 depending on the parameter)
+model.setParameterValue("ParamMouthOpenY", 1.0f);
+
+// 2. Get the current value
+float currentMouth = model.getParameterValue("ParamMouthOpenY");
+```
+
+> **Note**: If a motion is playing that *also* controls this parameter, the motion might overwrite your manual value in the next `update()` call. To fix this, set the parameter *after* calling `model.update()`.
diff --git a/wiki_docs/Lifecycle-Management.md b/wiki_docs/Lifecycle-Management.md
@@ -0,0 +1,41 @@
+# Lifecycle Management
+
+Because this library relies on native C++ code, managing the lifecycle of the memory and the framework is crucial. If you don't do this correctly, your app might crash or leak memory.
+
+## 1. Global Initialization
+
+Before you do *anything* else (even before creating a model), you must initialize the Cubism Framework. This sets up the internal memory allocators and logging systems.
+
+```java
+import dev.eatgrapes.live2d.CubismFramework;
+
+// Call this ONCE at the start of your application
+CubismFramework.startUp();
+CubismFramework.initialize();
+```
+
+> **Note**: This automatically extracts and loads the native `.dll`, `.so`, or `.dylib` from the jar file. You don't need to manually configure `java.library.path`.
+
+## 2. Global Disposal
+
+When your application is closing (e.g., in your window's close callback), you must tear down the framework to free native resources.
+
+```java
+// Call this ONCE when your app is exiting
+CubismFramework.dispose();
+```
+
+## 3. Model Lifecycle
+
+Individual models (`CubismUserModel`) also have native resources. Always close them when you are done with a specific character, even if the app is still running.
+
+```java
+CubismUserModel model = new CubismUserModel();
+
+// ... use the model ...
+
+// When switching characters or closing the level:
+model.close(); // IMPORTANT! Frees the C++ model instance
+```
+
+**Pro Tip**: `CubismUserModel` implements `AutoCloseable`, so you can use it in try-with-resources blocks for short-lived tests, though usually, you'll keep it alive as a field in your renderer class.
diff --git a/wiki_docs/Loading-Assets.md b/wiki_docs/Loading-Assets.md
@@ -0,0 +1,53 @@
+# Loading Assets
+
+Live2D models are composed of several files. You need to load them in a specific order. The API expects `byte[]` arrays, so you can load these files from the disk, a JAR resource, or a network stream.
+
+## 1. The Core Model (.moc3)
+
+This is the geometry and structure of the character. It is **mandatory**.
+
+```java
+byte[] mocBytes = Files.readAllBytes(Path.of("Hiyori.moc3"));
+CubismUserModel model = new CubismUserModel();
+model.loadModel(mocBytes);
+```
+
+## 2. Poses (.pose3.json)
+
+Poses handle "Part Sorting" and visibility. For example, hiding the arms when they go behind the back. It is **highly recommended**.
+
+```java
+byte[] poseBytes = Files.readAllBytes(Path.of("Hiyori.pose3.json"));
+model.loadPose(poseBytes);
+```
+
+## 3. Physics (.physics3.json)
+
+This file controls the automatic movement of hair, clothes, and accessories based on the model's movement. Without this, the model will look very stiff.
+
+```java
+byte[] physicsBytes = Files.readAllBytes(Path.of("Hiyori.physics3.json"));
+model.loadPhysics(physicsBytes);
+```
+
+## 4. Textures
+
+Textures are not loaded directly by the Live2D engine. Instead, **you** must load the image into OpenGL (using `STBImage` or similar) and give the Texture ID to the model.
+
+```java
+// 1. Load image to OpenGL and get an ID (e.g., using LWJGL)
+int glTextureId = loadTexture("texture_00.png"); 
+
+// 2. Register it with the model. 
+// The index corresponds to the texture order in the .model3.json file.
+model.registerTexture(0, glTextureId);
+```
+
+## 5. Renderer Creation
+
+Once the model is loaded, you must initialize its internal renderer. This requires an active OpenGL context.
+
+```java
+// Must be called on the render thread!
+model.createRenderer();
+```
diff --git a/wiki_docs/Motion-and-Expressions.md b/wiki_docs/Motion-and-Expressions.md
@@ -0,0 +1,43 @@
+# Motion & Expressions
+
+Static models are boring! Here is how to make them move.
+
+## Playing Motions
+
+Motions are `.motion3.json` files. You load them as byte arrays and play them.
+
+```java
+byte[] motionBytes = loadResource("tap_body.motion3.json");
+
+// Priority: 
+// 1 = Idle (can be interrupted)
+// 2 = Normal
+// 3 = Force (interrupts everything)
+int priority = 3;
+
+// Loop: true/false
+boolean loop = false;
+
+model.startMotion(motionBytes, priority, loop, name -> {
+    System.out.println("Motion " + name + " finished!");
+});
+```
+
+The model automatically fades between the current motion and the new one. You don't need to manage blending manually.
+
+## Setting Expressions
+
+Expressions are `.exp3.json` files that override specific parameters (like setting eyes to "happy").
+
+1.  **Load the Expression**:
+    ```java
+    byte[] exprBytes = loadResource("f01.exp3.json");
+    model.loadExpression(exprBytes, "Happy"); // Give it a unique name
+    ```
+
+2.  **Activate it**:
+    ```java
+    model.setExpression("Happy");
+    ```
+
+Expressions layer on top of motions. So if a motion blinks the eyes, but the expression forces them shut, they will stay shut.
diff --git a/wiki_docs/Rendering-Loop.md b/wiki_docs/Rendering-Loop.md
@@ -0,0 +1,38 @@
+# Rendering Loop
+
+To verify the model is working, you need to update its state and draw it every frame. This typically happens inside your main game loop (e.g., GLFW loop).
+
+## The Update Step
+
+The `update` method advances the physics, fades motions, and calculates the new positions of all vertices.
+
+```java
+// deltaTime: Time in seconds since the last frame (e.g., 0.016 for 60fps)
+model.update(deltaTime);
+```
+
+> **Warning**: Do not pass `0` as delta time, as physics calculations may behave unpredictably.
+
+## The Draw Step
+
+The `draw` method issues the OpenGL commands to render the mesh. It requires a Model-View-Projection (MVP) matrix to position the model on your screen.
+
+```java
+// A simple 4x4 Identity Matrix (Float array of size 16)
+float[] mvpMatrix = new float[] {
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1
+};
+
+// Adjust for aspect ratio so the model doesn't look stretched
+float aspect = (float) windowWidth / windowHeight;
+mvpMatrix[0] = 1.0f / aspect; // Scale X by 1/aspect
+
+model.draw(mvpMatrix);
+```
+
+## Context Awareness
+
+`model.draw()` calls OpenGL functions (`glDrawElements`, `glBindTexture`, etc.). Therefore, **it must be called from the thread that holds the OpenGL context**.
