NarraLeaf

assets と locale

パッケージ化されたアセット id を、この実行環境が読み込める URL に解決し、プレイヤーの言語に追従する

それぞれ独立して宣言する、二つの小さな機能です。

{
  "contributes": {
    "runtimeCapabilities": ["assets", "locale"]
  }
}

assets

app.game.assets は、プロジェクトのパック内のアセット id を、現在の実行環境が読み込める URL に変換します。これがなければ、プラグインはゲーム内部のプロトコル文字列をハードコードするしかなく、しかもこの文字列はデスクトップ版と Web 版の間で異なります。

メソッドシグネチャ
url(assetId: string) => string
const src = app.game.assets?.url(String(ctx.params.iconAssetId ?? ""));

同期的なので、ウィジェットのレンダラー内でも純粋なノード内でも安全に使えます。

assets は Dev Mode には存在しません。そこでのアセット解決は非同期の IPC を経由しますが、この機能のシグネチャは同期の url() です。両者は折り合わないため、このドメインはそもそも提供されません。アセットに基づく画像を描画するプラグインは Dev Mode 用のフォールバックを持たなければなりません。さもないと、それをテストする作者は空のボックスを目にし、プラグインのせいだと考えるでしょう。Preview および、あらゆるエクスポートビルドでは利用できます。

locale

app.game.locale は ゲームの 表示言語です。プレイヤーが選んだもので、実行中のプロジェクトのローカライズデータによって設定されます。その言語に翻訳されたプロジェクトの文字も読み取れます。

メンバーシグネチャ
currentreadonly string
onChange(listener: (locale: string) => void) => RuntimePluginCleanup
text(key: string) => string | null
words(id: string, text: string) => string
const locale = app.game.locale?.current ?? "en";

const stop = app.game.locale?.onChange(next => {
    // `next` に合わせて文字を読み直す
});
  • text(key) は、プロジェクトの翻訳キーを現在の言語で読み取ります。テーブルとフォールバックチェーンは Get Text ノードと同じです。プロジェクトがそのキーを宣言していない場合は null を返します。
  • words(id, text) は、プラグインが直接書き、studio エントリーから app.services.localization.registerWords で翻訳に出した文字を読み取ります。id が指す単位の翻訳を言語のフォールバックチェーンに沿って探し、なければ text を返します。ゲームには翻訳だけが入り原文は入らないため、プラグインが書いたとおりの文字を渡します。プラグインが読めるのは自身の文字だけです。

これは読み取り専用です。プラグインはプレイヤーの言語に追従できますが、それを変更することはできません。

これを app.services.i18n と混同しないでください。あちらは エディタの UI 言語であり、studio エントリにのみ存在します。両者は異なる人が設定する異なる言語です。英語で編集している作者が、日本語で動くゲームをテストしていることもあり得ます。

text や words で読む文字は、ゲームのほかの部分と一緒にプロジェクトの翻訳テーブルで翻訳され、作者が加えるすべての言語が対象になります。onChange で読み直してください。

このページの目次

assetslocale