add Android bulid and add javadoc

Author: Eatgrapes

.github/workflows/build.yml

@@ -30,11 +30,17 @@ jobs:
         run: |
           sudo apt-get install -y libgles2-mesa-dev
 
+      - name: Setup Android NDK
+        if: contains(matrix.os, 'ubuntu')
+        uses: nttld/setup-ndk@v1
+        with:
+          ndk-version: r26b
+
       - name: Build and Package
         run: python3 scripts/build.py
 
       - name: Upload Artifacts
         uses: actions/upload-artifact@v4
         with:
           name: live2d-jars-${{ matrix.os }}
-          path: out/*.jar
+          path: out/*.jar

binding/src/main/java/dev/eatgrapes/live2d/CubismFramework.java

@@ -1,10 +1,19 @@
 package dev.eatgrapes.live2d;
 
+/**
+ * Entry point for the Live2D Cubism Framework.
+ * <p>
+ * This class manages the lifecycle of the Cubism native framework (startup, initialization, disposal)
+ * and provides logging capabilities.
+ */
 public class CubismFramework {
     static {
         LibraryLoader.load();
     }
 
+    /**
+     * Represents the logging level for the framework.
+     */
     public enum LogLevel {
         VERBOSE(0),
         DEBUG(1),
@@ -17,30 +26,69 @@ public enum LogLevel {
         LogLevel(int value) { this.value = value; }
     }
 
+    /**
+     * Callback interface for receiving log messages from the native framework.
+     */
     public interface LogCallback {
+        /**
+         * Called when a log message is generated.
+         * @param message The log message.
+         */
         void log(String message);
     }
 
     private static LogCallback logCallback;
 
+    /**
+     * Starts the Cubism framework with default settings (no logging).
+     * Must be called before {@link #initialize()}.
+     */
     public static void startUp() {
         startUp(null, LogLevel.OFF);
     }
 
+    /**
+     * Starts the Cubism framework with a specific logger and log level.
+     * Must be called before {@link #initialize()}.
+     *
+     * @param callback The callback to handle log messages (can be null).
+     * @param level    The minimum log level to capture.
+     */
     public static void startUp(LogCallback callback, LogLevel level) {
         logCallback = callback;
         startUpNative(callback != null, level.value);
     }
 
     private static native void startUpNative(boolean hasCallback, int logLevel);
+
+    /**
+     * Initializes the framework resources.
+     * Must be called after {@link #startUp()} and before using any other framework features.
+     */
     public static native void initialize();
+
+    /**
+     * Disposes of the framework resources.
+     * Should be called when Live2D is no longer needed to free native memory.
+     */
     public static native void dispose();
+
+    /**
+     * Checks if the framework has been started.
+     * @return true if started, false otherwise.
+     */
     public static native boolean isStarted();
+
+    /**
+     * Checks if the framework has been initialized.
+     * @return true if initialized, false otherwise.
+     */
     public static native boolean isInitialized();
 
+    // Called from JNI
     private static void onLog(String message) {
         if (logCallback != null) {
             logCallback.log("[Live2D Native] " + message);
         }
     }
-}
+}

binding/src/main/java/dev/eatgrapes/live2d/CubismUserModel.java

@@ -2,9 +2,18 @@
 
 import java.util.function.Consumer;
 
+/**
+ * Represents a Live2D Cubism user model.
+ * <p>
+ * This class provides a high-level API to interact with a Live2D model, including loading assets
+ * (MOC3, physics, pose, expressions), updating the model state, and rendering it.
+ */
 public class CubismUserModel extends Native {
     private Consumer<String> motionFinishedCallback;
 
+    /**
+     * Creates a new empty user model instance.
+     */
     public CubismUserModel() {
         super(createNative());
         linkNative();
@@ -13,70 +22,155 @@ public CubismUserModel() {
     private static native long createNative();
     private native void linkNative();
 
+    /**
+     * Loads the model data (MOC3) from a byte buffer.
+     * @param buffer The byte array containing MOC3 data.
+     */
     public void loadModel(byte[] buffer) { loadModelNative(_ptr, buffer); }
     private static native void loadModelNative(long ptr, byte[] buffer);
 
+    /**
+     * Loads the physics data from a byte buffer.
+     * @param buffer The byte array containing physics3.json data.
+     */
     public void loadPhysics(byte[] buffer) { loadPhysicsNative(_ptr, buffer); }
     private static native void loadPhysicsNative(long ptr, byte[] buffer);
 
+    /**
+     * Loads the pose data from a byte buffer.
+     * @param buffer The byte array containing pose3.json data.
+     */
     public void loadPose(byte[] buffer) { loadPoseNative(_ptr, buffer); }
     private static native void loadPoseNative(long ptr, byte[] buffer);
 
+    /**
+     * Loads an expression from a byte buffer and assigns it a name.
+     * @param buffer The byte array containing exp3.json data.
+     * @param name   The unique name to identify this expression.
+     */
     public void loadExpression(byte[] buffer, String name) { loadExpressionNative(_ptr, buffer, name); }
     private static native void loadExpressionNative(long ptr, byte[] buffer, String name);
 
+    /**
+     * Sets the current active expression by name.
+     * @param name The name of the expression to activate.
+     */
     public void setExpression(String name) { setExpressionNative(_ptr, name); }
     private static native void setExpressionNative(long ptr, String name);
 
+    /**
+     * Creates the renderer for this model.
+     * Must be called before drawing.
+     */
     public void createRenderer() { createRendererNative(_ptr); }
     private static native void createRendererNative(long ptr);
 
+    /**
+     * Registers a texture with the model's renderer.
+     * @param index     The texture index (as defined in the model data).
+     * @param textureId The OpenGL texture ID.
+     */
     public void registerTexture(int index, int textureId) { registerTextureNative(_ptr, index, textureId); }
     private static native void registerTextureNative(long ptr, int index, int textureId);
 
+    /**
+     * Sets the dragging coordinates for interaction (e.g., look-at behavior).
+     * @param x The x-coordinate in model space.
+     * @param y The y-coordinate in model space.
+     */
     public void setDragging(float x, float y) { setDraggingNative(_ptr, x, y); }
     private static native void setDraggingNative(long ptr, float x, float y);
 
+    /**
+     * Checks if a point hits a specific drawable part (HitArea).
+     * @param drawableId The ID of the drawable to check.
+     * @param x          The x-coordinate to test.
+     * @param y          The y-coordinate to test.
+     * @return true if the point hits the drawable, false otherwise.
+     */
     public boolean isHit(String drawableId, float x, float y) { return isHitNative(_ptr, drawableId, x, y); }
     private static native boolean isHitNative(long ptr, String drawableId, float x, float y);
 
+    /**
+     * Starts playing a motion.
+     *
+     * @param buffer     The byte array containing motion3.json data.
+     * @param priority   The priority of the motion (1=Low, 2=Normal, 3=Force).
+     * @param loop       Whether the motion should loop.
+     * @param onFinished Callback to be invoked when the motion finishes.
+     */
     public void startMotion(byte[] buffer, int priority, boolean loop, Consumer<String> onFinished) {
         this.motionFinishedCallback = onFinished;
         startMotionNative(_ptr, buffer, priority, loop);
     }
     private static native void startMotionNative(long ptr, byte[] buffer, int priority, boolean loop);
 
+    /**
+     * Checks if the currently playing motion has finished.
+     * @return true if finished, false otherwise.
+     */
     public boolean isMotionFinished() { return isMotionFinishedNative(_ptr); }
     private static native boolean isMotionFinishedNative(long ptr);
 
+    // Called from JNI
     private void onMotionFinished(String name) {
         if (motionFinishedCallback != null) {
             motionFinishedCallback.accept(name);
         }
     }
 
+    /**
+     * Updates the model state. Should be called every frame.
+     * @param deltaTime The time elapsed since the last frame in seconds.
+     */
     public void update(float deltaTime) { updateNative(_ptr, deltaTime); }
     private static native void updateNative(long ptr, float deltaTime);
 
+    /**
+     * Sets a parameter value.
+     * @param id    The parameter ID.
+     * @param value The value to set.
+     */
     public void setParameterValue(String id, float value) { setParameterValueNative(_ptr, id, value); }
     private static native void setParameterValueNative(long ptr, String id, float value);
 
+    /**
+     * Gets the current value of a parameter.
+     * @param id The parameter ID.
+     * @return The current value.
+     */
     public float getParameterValue(String id) { return getParameterValueNative(_ptr, id); }
     private static native float getParameterValueNative(long ptr, String id);
 
+    /**
+     * Gets the width of the model's canvas.
+     * @return The canvas width.
+     */
     public float getCanvasWidth() { return getCanvasWidthNative(_ptr); }
     private static native float getCanvasWidthNative(long ptr);
 
+    /**
+     * Gets the height of the model's canvas.
+     * @return The canvas height.
+     */
     public float getCanvasHeight() { return getCanvasHeightNative(_ptr); }
     private static native float getCanvasHeightNative(long ptr);
 
+    /**
+     * Gets the list of drawable IDs in the model.
+     * @return An array of drawable ID strings.
+     */
     public String[] getDrawableIds() { return getDrawableIdsNative(_ptr); }
     private static native String[] getDrawableIdsNative(long ptr);
 
+    /**
+     * Draws the model using the provided MVP matrix.
+     * @param mvpMatrix The 4x4 Model-View-Projection matrix.
+     */
     public void draw(float[] mvpMatrix) { drawNative(_ptr, mvpMatrix); }
     private static native void drawNative(long ptr, float[] mvpMatrix);
 
     @Override
     public void close() { deleteNative(_ptr); }
     private static native void deleteNative(long ptr);
-}
+}

binding/src/main/java/dev/eatgrapes/live2d/LibraryLoader.java

@@ -4,12 +4,38 @@
 import java.nio.file.*;
 import java.util.Locale;
 
+/**
+ * Handles loading of the native Live2D JNI library.
+ * <p>
+ * This class automatically detects the current operating system and architecture,
+ * extracts the appropriate shared library from the JAR, and loads it.
+ * On Android, it delegates to the system's library loader.
+ */
 public class LibraryLoader {
     private static boolean loaded = false;
 
+    /**
+     * Loads the native library.
+     * <p>
+     * This method is idempotent; calling it multiple times has no effect.
+     * It attempts to load 'live2d_jni'. On desktop platforms, it extracts
+     * the library to a temporary location first.
+     *
+     * @throws RuntimeException if the operating system or architecture is unsupported,
+     *                          or if the native library cannot be extracted/loaded.
+     */
     public static synchronized void load() {
         if (loaded) return;
 
+        // Check for Android
+        String vendor = System.getProperty("java.vendor", "").toLowerCase(Locale.ROOT);
+        String vmName = System.getProperty("java.vm.name", "").toLowerCase(Locale.ROOT);
+        if (vendor.contains("android") || vmName.contains("dalvik")) {
+            System.loadLibrary("live2d_jni");
+            loaded = true;
+            return;
+        }
+
         String osName = System.getProperty("os.name").toLowerCase(Locale.ROOT);
         String arch = System.getProperty("os.arch").toLowerCase(Locale.ROOT);
 
@@ -43,6 +69,12 @@ public static synchronized void load() {
         }
     }
 
+    /**
+     * Loads a shader resource from the classpath.
+     *
+     * @param name The name of the shader file (e.g., "vert_shader.glsl").
+     * @return The byte content of the shader file, or null if not found.
+     */
     public static byte[] loadResource(String name) {
         String internalPath = "/live2d/shaders/" + name.substring(name.lastIndexOf("/") + 1);
         try (InputStream is = LibraryLoader.class.getResourceAsStream(internalPath)) {
@@ -52,4 +84,4 @@ public static byte[] loadResource(String name) {
             return null;
         }
     }
-}
+}

binding/src/main/java/dev/eatgrapes/live2d/Native.java

@@ -1,17 +1,37 @@
 package dev.eatgrapes.live2d;
 
+/**
+ * Base class for objects that wrap a native C++ pointer.
+ * <p>
+ * This class implements {@link AutoCloseable} to ensure native resources are properly released.
+ */
 public abstract class Native implements AutoCloseable {
+    /**
+     * The raw pointer to the native object.
+     */
     protected final long _ptr;
 
+    /**
+     * Constructs a Native wrapper around the given pointer.
+     * @param ptr The native pointer value.
+     * @throws RuntimeException if the pointer is null (0).
+     */
     protected Native(long ptr) {
         if (ptr == 0) throw new RuntimeException("Native pointer is null");
         this._ptr = ptr;
     }
 
+    /**
+     * Gets the raw native pointer.
+     * @return The pointer value.
+     */
     public long getPtr() {
         return _ptr;
     }
 
+    /**
+     * Releases the native resources associated with this object.
+     */
     @Override
     public abstract void close();
-}
+}