Fork Information

live2d-renderer-lite is a fork of Moebits/live2d-renderer . It's a streamlined version focusing on core Live2D rendering functionality. Key changes include:

• Cross platform: works in the modern browsers and Node.js.
• Removed ZIP File Support: The ability to read Live2D files directly from ZIP archives has been removed. This reduces the package size and simplifies the codebase. Consequently, dependencies related to ZIP file handling have also been removed.
• Integrated live2dcubismcore.js: The core Live2D Cubism library (live2dcubismcore.js) is now directly integrated into the project. This eliminates the need for external dependencies and ensures consistent performance.
• Build Optimization: Switched build tool from tsc to rolldown for improved performance and reduced bundle size.

Implications for Usage:

• You'll need to provide the Live2D model data in a format other than a ZIP archive. Consider extracting the model data from the ZIP file beforehand.
• The API might have slight variations due to the removal of ZIP handling. Refer to the API documentation for details.
• Live2D SDK Version: Cubism 5 SDK for Web R4.

Insallation

npm install live2d-renderer-lite

Usage

import { Live2DCubismModel } from "live2d-renderer-lite"

const loadLive2DModel = async () => {
    const canvas = document.createElement("canvas");
    canvas.width = 500;
    canvas.height = 500;
    const model = new Live2DCubismModel(canvas, options);
    await model.load("live2d_model.model3.json"); // Load model3.json
}
loadLive2DModel();

---

The Live2D Cubism SDK can be complex, and this project aims to do all the heavy lifting for you so you only have to worry about loading and interacting with your models. We support loading Live2D Cubism 5 models (which should also be backwards compatible with 3 and 4) and rendering them in a WebGL2 canvas.

Useful Links

• Demo Site
• Live2D Cubism Web SDK

Live2D Cubism Core

You need to install Live2D Cubism Core, a proprietary library for loading moc3 files. You must point the option cubismCorePath to a link containing live2dcubismcore.min.js (or the unminified version). You can download the library here.

Usage

You should import the class Live2DCubismModel and initialize it with your own HTMLCanvasElement. Also make sure that your canvas has a width and height set. From there, call the asynchronous load method with a path to either a zip containing all the json files and textures, or the path to model3.json (and the other paths will be resolved relative to it).

Options

By default, the model will begin animating automatically, but you can disable this to control it manually. The Live2DCubismModel class has all of these optional options.

export interface Live2DModelOptions {
    // Toggle whether the animation loop will get called automatically.
    autoAnimate?: boolean = true
    // Toggle whether the pointer actions will begin automatically.
    autoInteraction?: boolean = true
    // Toggle whether a motion will be played on tap.
    tapInteraction?: boolean = true
    // Toggle whether you want it to play random motions, or just play the idle animation.
    randomMotion?: boolean = true
    // Resizes the aspect ratio of your canvas to match the model dimensions.
    keepAspect?: boolean = false
    // Link to the Cubism Core Library. It will be appended as a script tag if it isn't already.
    cubismCorePath?: string
    // Whether the animations are currently paused.
    paused?: boolean = false
    // The speed of the animation eg. 0.5 is half as fast.
    speed?: number = 1
    // The starting scale of the model, aka the zoom factor.
    scale?: number = 1
    // The lowest scale/zoom that should be allowed.
    minScale?: number = 0.1
    // The highest scale/zoom that should be allowed.
    maxScale?: number = 10
    // The panning speed eg. 2 is twice as fast.
    panSpeed?: number = 1.5
    // The step used for zooming, should be pretty small like 0.005.
    zoomStep?: number = 0.005
    // Whether zooming in with the mouse wheel should be allowed.
    zoomEnabled?: boolean = true
    // Whether panning by dragging should be allowed.
    enablePan?: boolean = true
    // Reset the zoom/pan on double click.
    doubleClickReset?: boolean = true
    // Set the starting x-position. Note: it's a ratio pixels/canvas.width
    x?: number = 0
    // Set the starting y-position. Note: it's a ratio pixels/canvas.height
    y?: number = 0
    // Check moc consistency when loading the model.
    checkMocConsistency?: boolean = true
    // Whether textures have premultiplied alpha.
    premultipliedAlpha?: boolean = true
    // The smoothing factor of the lip sync.
    lipSyncSmoothing?: number = 0.1
    // Volume of audio (if enabling playback).
    volume?: number = 1
    // You may pass in your own AudioContext
    audioContext?: AudioContext = new AudioContext()
    // The first node the audio is connected to, defaults to GainNode
    connectNode?: AudioNode = audioContext.createGain()
    // Maximum texture size. Must be a power of 2. Defaults to the WebGL max (usually 8192).
    maxTextureSize?: number = 8192
    // Multiply the y-position by the scale
    scaledYPos?: boolean
    // Append value to y-position when centering
    appendYOffset?: number
    // You can toggle various features in the animation loop.
    enablePhysics?: boolean = true
    enableEyeblink?: boolean = true
    enableBreath?: boolean = true
    enableLipsync?: boolean = true
    enableMotion?: boolean = true
    enableExpression?: boolean = true
    enableMovement?: boolean = true
    enablePose?: boolean = true
}

Manual Looping

To loop the model manually, you should disable the animation in the constructor and then provide your own animation loop where you call the model's update method repeatedly.

const model = new Live2DCubismModel(canvas, {autoAnimate: false})

const loop = async () => {
    model.update()
    id = window.requestAnimationFrame(loop)
}
loop()

Parameters and Parts

Most of the functions for interacting with parameters and parts are located in the internal model, such as model.model.getParameterValueById() Additionally, if you change properties on the internal model you should call its update method at model.model.update(). For your convenience, I moved some common methods up to the top level.

// All parameters, parts, and drawables
const parameters = model.parameters
const parts = model.parts
const drawables = model.drawables

// Get parameter value
model.getParameterValue("ParamAngleX")
// Set parameters
model.setParameter("ParamAngleX", 30)
// Get part opacity
model.getPartOpacity("PartCheek")
// Set part opacity
model.setPartOpacity("PartCheek", 0.5)

Motions and Expressions

You should disable the model animation and handle it manually if you want to play your own motions and expressions.

// Sets a random expression
model.setRandomExpression()
// Sets an expression
model.setExpression("name")

// Plays a random motion
model.startRandomMotion(null, MotionPriority.Normal, startMotionCallback, endMotionCallback)
// Provide a motion group name to randomly play within that group
model.startRandomMotion("Idle", MotionPriority.Normal, startMotionCallback, endMotionCallback)
// Plays any motion
model.startMotion("Group", index, priority, startMotionCallback, endMotionCallback)

// View all motions and expressions
model.motions
model.expressions

Lipsync

Some motions contain their own audio which will sync their lips automatically. You can also pass in an audio input to the model (wav/mp3 arraybuffer).

// Lip sync smoothing factor, 0 would move the lips abruptly.
model.lipsyncSmoothing = 0.1
// Input audio
model.inputAudio(audioArrayBuffer)

Events

model.on("hit", (hitAreas: string[], x: number, y: number) => {
  console.log("Hit!")
})s

Licenses

Live2D Web Framework is licensed under the Live2D Open Software License
Live2D Cubism Core is licensed under the Live2D Proprietary Software License