メインコンテンツまでスキップ

Asset IDs

Asset IDs are unique identifiers that reference files across the entire MOD system. Whenever you attach a VRM model to a persona, play an animation, or open a WebView, you use an asset ID to tell the engine which file to load. The only hard requirement is that every asset ID is globally unique — duplicate IDs are logged as warnings and skipped.

The recommended convention is:

<mod-name>:<asset-name>

The engine treats asset IDs as opaque strings — it does not validate or parse this format. However, prefixing with the mod name prevents collisions between MODs and makes IDs self-documenting.

PartSourceExample
mod-nameDerived from the name field in package.json@hmcs/stt becomes stt
asset-nameThe key in the homunculus.assets objectvrm, open, ui

The mod name is extracted from the package name by stripping the scope prefix. For example:

  • @hmcs/stt -- mod name is stt
  • @hmcs/persona -- mod name is persona
  • my-character -- mod name is my-character (no scope to strip)

The asset name is whatever you chose as the key when declaring the asset in package.json.

Example​

Given this package.json:

{
"name": "my-character",
"homunculus": {
"assets": {
"my-character:vrm": {
"path": "assets/MyModel.vrm",
"type": "vrm",
"description": "Custom VRM character model"
},
"my-character:open": {
"path": "assets/open.mp3",
"type": "sound",
"description": "Sound effect for opening action"
}
}
}
}

The asset IDs are my-character:vrm and my-character:open. You use these strings anywhere the SDK or API expects an asset reference.

Built-in Assets​

The engine ships a default character model, animations, and sound effects that all MODs can use. They are always available; there is nothing to install:

Asset IDTypeDescription
vrm:elmervrmVRM model named Elmer
vrma:idle-maidvrmaMaid-style standing idle with hands clasped in front
vrma:grabbedvrmaReactive pose while being dragged by the user
vrma:idle-sittingvrmaSeated idle loop with legs together
se:opensoundSound effect for opening a HUD panel
se:closesoundSound effect for closing a HUD panel

Built-in assets are listed by GET /assets (and assets.list() in the SDK) with mod set to "builtin", so assets.list({ mod: "builtin" }) returns exactly these. Imported files are listed with mod set to "local".

Built-in asset IDs are reserved:

  • A MOD that declares one of these IDs in its package.json is ignored for that ID, with a warning in the log.
  • Importing a file under one of these IDs (POST /assets/import) fails with 409 Conflict.
  • MOD packages named builtin or local are not loaded.
Migrating from @hmcs/assets

These assets used to come from the @hmcs/assets MOD. They keep the same IDs, so existing code keeps working. Filtering by the old MOD name (assets.list({ mod: "@hmcs/assets" })) no longer returns them — filter by "builtin" instead. The old MOD is no longer needed and can be removed with hmcs mod uninstall @hmcs/assets.

ヒント

You do not need to create your own idle animations unless you want custom ones.

Using Asset IDs in Code​

The @hmcs/sdk accepts asset IDs as strings wherever an asset is needed.

Attaching a VRM character to a persona​

import { persona } from "@hmcs/sdk";

const p = await persona.create({ id: "elmer" });
const vrm = await p.attachVrm("elmer:vrm");

Playing a VRMA animation​

import { repeat } from "@hmcs/sdk";

await vrm.playVrma({
asset: "vrma:idle-maid",
repeat: repeat.forever(),
transitionSecs: 0.5,
});

Opening a WebView​

import { Webview, webviewSource } from "@hmcs/sdk";

await Webview.open({
source: webviewSource.local("my-mod:ui"),
size: [1, 0.9],
viewportSize: [900, 700],
});

The webviewSource.local("my-mod:ui") source tells the engine to load the HTML file registered under the my-mod:ui asset ID.

Using Asset IDs in the HTTP API​

Asset IDs appear in HTTP API request bodies as well. For example, to attach a VRM model to a persona via the API:

curl -X POST http://localhost:3100/personas/elmer/vrm \
-H "Content-Type: application/json" \
-d '{"assetId": "elmer:vrm"}'

The same asset ID string is used consistently across the SDK and the HTTP API.

Referencing Assets from Other MODs​

A MOD can reference built-in assets and assets from any other installed MOD. For example, a MOD that creates a character commonly uses the built-in animations:

// This MOD uses a built-in animation
await vrm.playVrma({
asset: "vrma:idle-maid", // Built into the engine, not declared by this MOD
});
警告

If the MOD that owns the asset is not installed, the engine will return an error when you try to use its asset ID. Make sure the MOD that provides the asset is installed (hmcs mod install <mod-name>).