cube-character

A 3D cube-style character customization engine built with Babylon.js and Vue 3.

Features

• Real-time 3D character rendering via Babylon.js
• Customizable hair, tops, bottoms, accessories, beards, aprons, held items, eyes, skin tones, and colors
• Animation support with FSM-based serial playback
• Head-mounted labels and status indicators
• Face snapshot (base64 PNG export)
• Vue 3 component CubeCharacterSelector for drop-in character editor UI
• Vite plugin helper to prevent dep pre-bundling issues

Installation

npm install cube-character
# peer deps
npm install @babylonjs/core @babylonjs/loaders

Quick Start

1. Add the Vite plugin (recommended)

// vite.config.ts
import { defineConfig } from 'vite'
import { cubeCharacterVitePlugin } from 'cube-character'

export default defineConfig({
  plugins: [cubeCharacterVitePlugin()],
})

2. Create a character in your Babylon.js scene

import { Engine, Scene } from '@babylonjs/core'
import {
  createCubeCharacterFactory,
  buildRandomConfig,
} from 'cube-character'

const engine = new Engine(canvas, true)
const scene = new Scene(engine)

const factory = createCubeCharacterFactory(scene, {
  scale: 1,
  rotate: [0, Math.PI, 0],
})

await factory.init()

const config = buildRandomConfig()
const bot = await factory.generate(config)

bot.animate('Armature|Stand_Pose')
engine.runRenderLoop(() => scene.render())

3. Use the Vue selector component

<script setup lang="ts">
import { ref } from 'vue'
import { CubeCharacterSelector } from 'cube-character'
import type { CharacterConfig } from 'cube-character'

const open = ref(false)
const config = ref<CharacterConfig | null>(null)

function onSave(payload: { config: CharacterConfig; image: string }) {
  config.value = payload.config
  // payload.image is a base64 PNG face snapshot
}
</script>

<template>
  <button @click="open = true">Customize Character</button>
  <CubeCharacterSelector
    v-model:open="open"
    :initial-config="config"
    @save="onSave"
  />
</template>

API

createCubeCharacterFactory(scene, option?)

Returns a factory object with:

| Method | Description | |---|---| | init() | Initialize assets (call once before generate) | | generate(config, botOption?) | Create a CubeCharacterBot instance | | assets() | Return all asset categories with preview image URLs | | randomConfig() | Generate a random CharacterConfig |

FactoryOption

| Property | Type | Description | |---|---|---| | scale | number | Uniform scale, default 1 | | rotate | [x, y, z] | Euler rotation in radians | | transform | [x, y, z] | World position offset | | assetsBaseUrl | string | Override base URL for assets folder | | heldItemEnable | boolean | Enable held item rendering | | previewFace | boolean | Enable top-left face preview viewport | | debug | boolean | Draw bounding box wireframe |

CubeCharacterBot

| Member | Description | |---|---| | config | Current CharacterConfig | | animationNames | Available animation names | | meshRoot | Root TransformNode for positioning | | animate(name) | Play an animation by exact name | | animateAlias(alias) | Play via alias: idle / walk / handup / play / work | | animateSerial(alias) | FSM-based serial animation with pose transitions | | update(config) | Apply a new CharacterConfig | | snapshotFace(size?) | Export face as base64 PNG | | setBallColor(hex) | Update head status ball color | | destroy() | Dispose all meshes and materials |

CharacterConfig

interface CharacterConfig {
  hair: string | null       // HAIR_MESHES value or null (bald)
  top: string               // TOP_MESHES value
  bottom: string            // BOTTOM_MESHES value
  accessory: string | null  // ACCESSORY_MESHES value or null
  beard: string | null      // BEARD_MESHES value or null
  apron: string | null      // APRON_MESHES value or null
  item: string | null       // ITEM_MESHES value or null
  eyes: string | null       // e.g. 'EYES_00' … 'EYES_07' or null
  skintone: string          // 'Skintone_1' … 'Skintone_6'
  hairColor: string         // 'Haircolour_01' … 'Haircolour_16'
  topColor: string          // hex color e.g. '#607090'
  bottomColor: string       // hex color
  apronColor: string        // hex color
}

Helper functions

| Function | Description | |---|---| | buildRandomConfig() | Generate a random CharacterConfig | | pick(arr) | Pick a random element from an array | | maybe(arr, probability?) | Return a random element or null | | cubeCharacterVitePlugin() | Vite plugin to exclude package from pre-bundling |

Constants

HAIR_MESHES, TOP_MESHES, BOTTOM_MESHES, BEARD_MESHES, ACCESSORY_MESHES, APRON_MESHES, ITEM_MESHES, SKINTONES, HAIRCOLORS, EYE_OPTIONS, CLOTHES_COLORS

Peer Dependencies

• @babylonjs/core >= 8
• @babylonjs/loaders >= 8
• vue >= 3.4 (only required when using CubeCharacterSelector)

License

This project uses a dual license:

| Component | License | |---|---| | Source code (.ts, .vue, .js, config files) | Apache License 2.0 | | Binary 3D assets (dist/assets/ — model, textures, icons) | Non-Commercial Use Only |

The source code is freely usable under Apache 2.0. The bundled binary assets (character model, textures, icons) may only be used for non-commercial purposes. Commercial use of the binary assets requires a separate license agreement.