Cubism Web Samples

The Core/ directory contains the essential library files required to develop applications using Live2D Cubism. Depending on your development environment, you should use the following files:

• For TypeScript development: Use live2dcubismcore.d.ts alongside live2dcubismcore.js to provide type information.
• For JavaScript development: Use live2dcubismcore.js to access CubismCore functionality and its wrappers.
• For Production: Use the minified version live2dcubismcore.min.js to optimize performance and file size.
• For Debugging: Ensure live2dcubismcore.js.map is available to enable source mapping between the TypeScript definitions and the JavaScript implementation.

The repository is organized as follows:

• .vscode: Project settings for Visual Studio Code.
• Core: Contains the Live2D Cubism Core (must be manually populated from the official SDK).
• Framework: Source code for rendering and animation features.
• Samples:
  • Resources: Model files, images, and other assets.
  • TypeScript: TypeScript-based sample projects (e.g., the Demo).

.
├─ .vscode          # Visual Studio Code settings
├─ Core             # Live2D Cubism Core files
├─ Framework        # Rendering and animation source code
└─ Samples
   ├─ Resources     # Model files and images
   └─ TypeScript    # TypeScript sample projects

The repository is organized as follows:

• .vscode: Project settings for Visual Studio Code.
• Core: Contains the Live2D Cubism Core (must be manually populated from the official SDK).
• Framework: Source code for rendering and animation functions.
• Samples:
  • Resources: Model files and images.
  • TypeScript: TypeScript sample projects (e.g., the Demo project).

The project uses Vite to bundle TypeScript into a single JavaScript file located in the dist directory.

• Development Build: Use npm build to generate the standard build deliverable and copy necessary operation files.
• Production Build: Use npm build:prod to generate an optimized build with a reduced file size suitable for production environments.

Configuration for the build process can be modified via tsconfig.json and vite.config.mts.

Debugging is pre-configured for Visual Studio Code. To start debugging:

1. Open the top directory of the SDK in Visual Studio Code.
2. Press F5 to launch the integrated JavaScript debugger (targeting Chrome or Edge).
3. You can set breakpoints directly in the VS Code editor to debug code running in the browser.

Debug configurations are defined in .vscode/launch.json and task configurations in .vscode/tasks.json.

The sample demo is located in Samples/TypeScript/Demo. You can manage its lifecycle using Visual Studio Code Tasks via the Command Palette (View > Command Palette... then type >Tasks: Run Task):

1. Install Dependencies: Select npm: install - Samples/TypeScript/Demo.
2. Build Project: Select npm: build - Samples/TypeScript/Demo.
3. Start Local Server: Select npm: serve - Samples/TypeScript/Demo.
4. Access Demo: Open http://localhost:5000 in your browser.
5. Stop Server: Use the Command Palette to run >Tasks: Terminate Task and select npm: serve.

For other tasks, refer to the README.md inside Samples/TypeScript/.

1. npm: install - Samples/TypeScript/Demo
2. npm: build - Samples/TypeScript/Demo
3. npm: serve - Samples/TypeScript/Demo

To ensure code quality and type safety, use the following commands:

• Type Checking: Run npm test to perform a TypeScript type check. Settings are controlled by tsconfig.json.
• Static Analysis (Linting): Run npm lint to perform static analysis on TypeScript files in the src directory. Settings are controlled by eslint.config.mjs.
• Auto-fix Linting: Run npm lint:fix to perform static analysis and automatically apply fixes to TypeScript files in the src directory.

To develop with Cubism Web Samples, you need to install Node.js and Visual Studio Code. Follow these steps to initialize the environment:

1. Install [Node.js] and [Visual Studio Code].
2. Open the top directory of this SDK in Visual Studio Code.
3. Install the recommended VS Code extensions (search for @recommended in the Extensions tab).
4. Important: This repository does not manage the Core directory. You must download the Cubism SDK for Web from the official Live2D website and manually copy the files into the Core directory of this project.

1. Download the Cubism SDK for Web from [here](https://www.live2d.com/download/cubism-sdk/download-web/)
2. Copy the files in the Core directory to the project's `Core` directory.

Use these commands to output TypeScript build artifacts to the dist directory. Vite is used to bundle the output into JavaScript files, and necessary assets are copied automatically.

• npm build: Standard build.
• npm build:prod: Optimized build for production. This reduces build size and is intended for production environments.

Configuration can be modified by editing tsconfig.json and vite.config.mts.

The Core/ directory provides the essential library files required to build applications using Live2D Cubism. Depending on your development environment and target runtime, you should use the following files:

For TypeScript Development

Use live2dcubismcore.js for the runtime logic and live2dcubismcore.d.ts to provide type information and IntelliSense.

For JavaScript Development

Use live2dcubismcore.js for development or live2dcubismcore.min.js for production environments.

For Debugging

Include live2dcubismcore.js.map to enable source mapping between the TypeScript definitions and the JavaScript implementation.

Starts a local development server with watch mode enabled. Changes to the project will trigger an automatic rebuild and browser reload. You can debug the project directly within Visual Studio Code.

To terminate the task in Visual Studio Code, open the Command Palette and run >Tasks: Terminate Task.

npm start

With the release of Cubism 4 SDK for Web R1, the package and repository structures have changed to align more closely with Cubism 4 SDK for Native and to remove unnecessary files.

If you are updating a project from Cubism 4 SDK for Web beta2 or earlier, you must follow the specific migration steps outlined in the Cubism SDK Manual to handle the structural changes.