Skip to content

CONTRIBUTING.en.md

Latest commit

 

History

History
103 lines (61 loc) · 4.27 KB

CONTRIBUTING.en.md

File metadata and controls

103 lines (61 loc) · 4.27 KB

Development Guide

中文

This project involves: CMake, Cubism Native SDK, Python C Extension, and OpenGL.

Project Structure

The entire project consists of two parts: live2d.v2 and live2d.v3, corresponding to the package/live2d/v2 and package/live2d/v3 directories respectively.

live2d.v2

Loads Live2D models for Cubism 2.1 and below.

live2d.v2 is implemented entirely in Python. It was generated by deobfuscating and converting live2d.min.js to Python using tools, with manual fixes needed 💦. Based on live2d.min.js functionality, it adds features like precise click detection on parts and part color setting. Performance is suboptimal, partially due to preserving some JavaScript characteristics.

live2d.v3

Loads Live2D models for Cubism 3.0 and above.

live2d.v3 uses python c extension to wrap the Cubism Native SDK.

live2d.v3 Composition

live2d.v3 uses dynamically linkable libraries that can be called from Python (.pyd or .so), generated by compiling the CMake-managed project.

The C++ modules in live2d.v3 include: Core, Framework, Main, and Wrapper.

Core

Cubism Native Core, including a header file (.h) and platform-specific static libraries. Used to read .moc3 files for Live2D models of Cubism 3.0 and above.

Framework

Cubism Native Framework, extending the Core layer with features such as JSON file reading, physics calculations, and graphics rendering.

The above two modules are released by Cubism officially. When official releases update, they can be directly replaced with almost no modifications needed (currently handled automatically by CMake).

Main

Corresponds to the application layer of the original Cubism Native SDK, with simplifications. Main implements a drawable LAppModel cpp class on top of Framework. Modifications mainly involve the class defined in Live2D/Main/src/LAppModel.cpp. Other files in Main are rarely modified.

Framework and Main each generate their own static libraries.

The three modules above are independent of Python and can be used to bind other programming languages.

Wrapper

Wraps the LAppModel cpp class implemented in Main as a Python module. This is the only location in the entire project that introduces Python-related dependencies.

The Wrapper module is located in the Wrapper/ directory and includes the following files:

  • Live2D.cpp - Main wrapper file
  • PyLAppModel.cpp / PyLAppModel.hpp - Python bindings for LAppModel
  • PyModel.cpp / PyModel.hpp - Python bindings for Model
  • Python.hpp - Python API header file

Build Process

The project uses the CMake build system and integrates through setup.py:

  1. SDK Download: setup.py automatically downloads the Cubism Native SDK from the official Live2D website
  2. CMake Build: Calls CMake to compile each module
    • Framework module compiles to generate a static library
    • Main module compiles to generate a static library
    • Wrapper module compiles to generate the Live2DWrapper dynamic library
  3. File Copy: After building, dynamic libraries and shader files are copied to the package/live2d/v3/ directory

Build Commands

# Build from source
pip install .

# Download SDK only
python setup.py download

# Build wheel package
python setup.py bdist_wheel

For detailed build instructions, please refer to Wiki - Build from Source

Platform Support

Currently, builds are supported for the following platforms:

  • Windows (x86/x64)
  • Linux (x64/ARM64)
  • macOS (Intel/Apple Silicon, Python >=3.11)

Build workflows for each platform have been configured in GitHub Actions.

TODO

  • Performance improvements for live2d.v2