API Reference

Export Overview

export type { ExpressionInfo, MotionInfo, ParameterValueRange } from './core/types'
export { Live2DSprite } from './Live2DSprite'
export { Config, ConfigType, LogLevel, Priority } from './utils/config'
export { CubismSetting } from './utils/cubismSetting'

Application code imports from the root package:

import type { ConfigType } from 'easy-live2d'
import {
  Config,

  CubismSetting,
  Live2DSprite,
  LogLevel,
  Priority
} from 'easy-live2d'

---

Live2DSprite

Extends Pixi Sprite. The core facade class of the library.

Constructor

new Live2DSprite(initConfig?: Live2DSpriteInit)

init

sprite.init(config: Live2DSpriteInit): boolean

Live2DSpriteInit:

interface Live2DSpriteInit {
  modelPath?: string
  modelSetting?: CubismSetting
  /** @deprecated Unused; retained for compatibility. */
  ticker?: Ticker
  draggable?: boolean
}

Field	Type	Description
modelPath	string	Path to the model .model3.json
modelSetting	CubismSetting	Manually constructed model setting
ticker	Ticker	Deprecated; compatibility only
draggable	boolean	Enable dragging. Default false

• At least one of modelPath or modelSetting is required.
• If both are present, modelPath takes precedence.
• Model loading is triggered on Pixi's first render, not at construction time.

Public Properties

Property	Type	Description
modelPath	string | null	Model path
modelSetting	CubismSetting | null	Model setting object
ticker	Ticker | null	Deprecated; compatibility only
renderer	Renderer	Pixi renderer, available after first render
draggable	boolean	Whether dragging is enabled
width	number	Logical model width (read/write)
height	number	Logical model height (read/write)
ready	Promise<void>	Stable Promise that resolves once the sprite is ready (see below)

Inherited Pixi Sprite properties also work: x, y, anchor, scale, rotation, visible, etc.

Promise-based Ready API

In addition to the event-based onLive2D('ready', callback) pattern, the instance exposes one async/await-friendly API: ready, which resolves when the model, textures, and interaction layer have finished loading.

ready

sprite.ready: Promise<void>

A stable Promise that resolves once the sprite becomes ready. The same Promise instance is returned on every access, so awaiting it multiple times does not attach extra listeners.

Initialization failures, including unsupported Core/context or unavailable declared resources, reject this Promise. Destruction before readiness also rejects it; initialization does not retry every frame. With autoStart: false, call app.render() after adding the sprite and before awaiting readiness. Synchronous ready listener errors are logged without releasing the model; async listener rejections must be handled inside the listener.

try {
  await sprite.ready
  await sprite.startMotion({ group: 'TapBody', no: 0, priority: Priority.Normal })
} catch (error) {
  console.error('Model initialization or motion loading failed', error)
}

Events

sprite.onLive2D(eventName, callback)

Event	Callback Args	Description
ready	()	Model, textures, and interaction initialized
hit	({ hitAreaName, x, y })	Click hit a model hit area
dragStart	({ x, y, deltaX, deltaY })	Drag started
dragMove	({ x, y, deltaX, deltaY })	Dragging
dragEnd	({ x, y, deltaX, deltaY })	Drag ended

• hit x, y are model-view coordinates.
• drag* x, y are sprite position.

Motion Control

startMotion

sprite.startMotion(params: MotionParams): Promise<CubismMotionQueueEntryHandle>

interface MotionParams {
  group: string
  no: number
  priority: number
  onStarted?: (motion: any) => void
  onFinished?: (motion: any) => void
}

Plays a specific motion by group and index. Calls before ready are queued, but their returned Promise does not wait for actual playback. Await sprite.ready first when you need the real handle or loading errors. Each playback uses only the callbacks supplied for that call. Dynamic resource failures reject and release the reserved priority so later motions can start.

startRandomMotion

sprite.startRandomMotion(params: Omit<MotionParams, 'no'>): Promise<CubismMotionQueueEntryHandle>

Plays a random motion from the specified group.

releaseMotions

sprite.releaseMotions(): void

Releases cached motion data.

getMotions

sprite.getMotions(): MotionInfo[]

interface MotionInfo {
  group: string
  no: number
  name: string
}

Returns all available motions of the model. Each entry contains the group name, index, and a combined name. Returns an empty array if called before the model is ready.

Expression Control

setExpression

sprite.setExpression(params: { expressionId: string } | { index: number }): void

Sets the specified expression. Pass either expressionId or index. Logs a warning if the value does not exist.

setRandomExpression

sprite.setRandomExpression(): void

Switches to a random expression.

releaseExpressions

sprite.releaseExpressions(): void

Releases cached expression data.

getExpressions

sprite.getExpressions(): ExpressionInfo[]

interface ExpressionInfo {
  name: string
}

Returns all available expressions of the model. Returns an empty array if called before the model is ready.

Parameter Control

setParameterValueById

sprite.setParameterValueById(id: string, value: number, weight?: number): void

Sets a model parameter value by its string ID. weight is the blend weight (default 1). Calls before ready are automatically queued.

The value persists across frames — it is re-applied every render cycle.

sprite.setParameterValueById('ParamAngleX', 15.0)

// With weight
sprite.setParameterValueById('ParamMouthOpenY', 1.0, 0.8)

setParameterValueByIndex

sprite.setParameterValueByIndex(index: number, value: number, weight?: number): void

Sets a model parameter value by its numeric index. weight is the blend weight (default 1). Calls before ready are automatically queued.

Like setParameterValueById, the value persists across frames.

sprite.setParameterValueByIndex(0, 0.5)

getParameterValueRangeById

sprite.getParameterValueRangeById(id: string): { min: number, max: number } | null

Returns the value range of a model parameter by its string ID. Returns null if the model is not ready or the parameter does not exist.

const range = sprite.getParameterValueRangeById('ParamAngleX')
// range => { min: -30, max: 30 }

getParameterValueRangeByIndex

sprite.getParameterValueRangeByIndex(index: number): { min: number, max: number } | null

Returns the value range of a model parameter by its numeric index. Returns null if the model is not ready or the index is out of range.

const range = sprite.getParameterValueRangeByIndex(0)
// range => { min: -30, max: 30 }

Voice Control

playVoice

sprite.playVoice(params: VoiceParams): Promise<void>

interface VoiceParams {
  voicePath: string
  immediate?: boolean
}

• voicePath: Audio resource path. Supports browser-decodable formats.
• immediate: Default true. Stops current voice before playing the new one.
• Lip sync requires LipSync parameter mapping in the model.

Playback and lip sync share one download/decode. playVoice() completes the playback-start request, not the entire audio; before readiness it only queues the request. Load/decode failures are logged and playback is skipped. The latest pending voice request supersedes an older pending request.

Voice resources belong to each sprite. Stopping or destroying one sprite does not interrupt another. Destroying a sprite cancels pending audio loads. immediate: false preserves voices already playing on the same sprite.

stopVoice

sprite.stopVoice(): void

Stops all voices owned by this sprite and cancels its pending voice load/decode result. Other sprites are unaffected.

Size and Lifecycle

getModelCanvasSize

sprite.getModelCanvasSize(): { width: number, height: number, pixelsPerUnit: number } | null

Returns the model's original canvas size. Returns null if the model is not ready.

getSize

sprite.getSize(out?: Size): Size

Returns the current display size.

setSize

sprite.setSize(value: number | { width: number, height?: number }, height?: number): void

Sets the display size.

onResize

sprite.onResize(): void

Manually triggers view recalculation. Usually not needed — the internal ResizeObserver handles this.

destroy

sprite.destroy(options?: DestroyOptions): void

Releases this sprite's listeners, model, motions, expressions, textures, VAO, and voice resources. Repeated calls are safe. Destruction during loading cancels requests and rejects unresolved readiness; an already resolved ready stays resolved. Shared Framework resources are released only after the last active/loading sprite finishes. Pixi Application/canvas lifecycle remains the host's responsibility.

---

Config

Global configuration singleton. Set before creating Live2DSprite instances.

import { Config, LogLevel } from 'easy-live2d'

Config.MotionGroupIdle = 'Idle'
Config.MouseFollow = true
Config.CubismLoggingLevel = LogLevel.LogLevel_Warning

Fields

Field	Type	Default	Description
ViewScale	number	1.0	Initial view scale
ViewMaxScale	number	2.0	Maximum scale
ViewMinScale	number	0.8	Minimum scale
ViewLogicalLeft	number	-1.0	Logical view left bound
ViewLogicalRight	number	1.0	Logical view right bound
ViewLogicalBottom	number	-1.0	Logical view bottom bound
ViewLogicalTop	number	1.0	Logical view top bound
ViewLogicalMaxLeft	number	-2.0	Max movement left bound
ViewLogicalMaxRight	number	2.0	Max movement right bound
ViewLogicalMaxBottom	number	-2.0	Max movement bottom bound
ViewLogicalMaxTop	number	2.0	Max movement top bound
MotionGroupIdle	string	'Idle'	Idle motion group to fall back to
MOCConsistencyValidationEnable	boolean	true	moc consistency validation
DebugLogEnable	boolean	true	Enable Cubism logging
DebugTouchLogEnable	boolean	false	Log touch coordinates
CubismLoggingLevel	LogLevel	LogLevel_Verbose	Cubism log level
MouseFollow	boolean	true	Model follows mouse
MotionSound	boolean	true	Whether to automatically play motion-bound sound effects when calling startMotion
crossOrigin	string | undefined	'anonymous'	The crossOrigin attribute applied to all texture images before upload via texImage2D. Prevents WebGL canvas tainting and SecurityError. Accepted values: 'anonymous', 'use-credentials', or undefined (disabled, not recommended).

crossOrigin Details

Config.crossOrigin sets img.crossOrigin on every texture image before it is uploaded to WebGL, preventing the browser from marking the canvas as "tainted" and avoiding:

SecurityError: The operation is insecure.

Type and accepted values:

Value	Description
'anonymous'	Sends an anonymous cross-origin request (no cookies/credentials). The server must return Access-Control-Allow-Origin. (Default)
'use-credentials'	Sends credentials (cookies, client certificates, etc.). The server must return Access-Control-Allow-Credentials: true and Access-Control-Allow-Origin must not be *.
undefined	Disables the attribute. Cross-origin textures may cause a WebGL upload failure. Not recommended.

Usage example:

import { Config } from 'easy-live2d'

// Default — usually no change needed
Config.crossOrigin = 'anonymous'

// When credentials (e.g. cookies) must be sent
Config.crossOrigin = 'use-credentials'

// Disabled (not recommended — cross-origin resources may throw SecurityError)
Config.crossOrigin = undefined

Notes

• Set this option before creating any Live2DSprite instance so that all texture loads are affected.
• The asset server must return a valid Access-Control-Allow-Origin header. When using 'use-credentials', the server must also return Access-Control-Allow-Credentials: true, and Access-Control-Allow-Origin must not be the wildcard *.
• Setting this to undefined may cause WebGL to throw a SecurityError when loading cross-origin textures.

resetConfig

Config.resetConfig(): void

Restores all fields to defaults.

---

ConfigType

TypeScript type definition for the Config object. Type-only, no runtime value.

---

Priority

Motion priority enum.

enum Priority {
  None = 0, // No preemption
  Idle = 1, // Idle motion
  Normal = 2, // Normal motion
  Force = 3, // Force-interrupt current motion
}

---

LogLevel

Log level enum re-exported from Cubism Framework. Used with Config.CubismLoggingLevel.

Member	Description
LogLevel.LogLevel_Verbose	Verbose logging
LogLevel.LogLevel_Debug	Debug logging
LogLevel.LogLevel_Info	Info logging
LogLevel.LogLevel_Warning	Warning logging
LogLevel.LogLevel_Error	Error logging
LogLevel.LogLevel_Off	Logging disabled

---

CubismSetting

Model configuration wrapper. Use when receiving model3.json at runtime and controlling asset paths.

Constructor

new CubismSetting({ modelJSON: any, prefixPath?: string })

Field	Description
modelJSON	Parsed model3.json object
prefixPath	Shared prefix for relative asset paths

redirectPath

setting.redirectPath(redirFn: ({ file: string }) => string): void

Rewrites paths for moc, textures, physics, pose, expressions, motions, and user data. Takes precedence over prefixPath.

const setting = new CubismSetting({
  modelJSON,
  prefixPath: '/Resources/Hiyori/',
})

setting.redirectPath(({ file }) => {
  return `https://cdn.example.com/live2d/hiyori/${file}`
})