@luna-editor/engine 0.2.0 → 0.3.0

package/dist/sdk.d.ts

@@ -1,9 +1,38 @@
 import React from "react";
-import type { ActionNode, BacklogEntry, Character, EntityState, ScenarioBlock } from "./types";
+import type { BackgroundData, BacklogEntry, BranchChoiceHistory, Character, ConversationBranchState, DisplayedCharacter, EntityState, ScenarioBlock, ScenarioBlockType, WorkFont } from "./types";
+/**
+ * ブロックオプションの定義
+ * プラグインがシナリオブロックに追加できるカスタムオプションを定義
+ */
+export interface BlockOptionDefinition {
+    /** オプションのキー（プラグイン固有のプレフィックス推奨: "myplugin_option_name"） */
+    key: string;
+    /** 表示名 */
+    name: string;
+    /** 対象のブロックタイプ（nullまたは未指定で全タイプ対象） */
+    targetBlockTypes?: ScenarioBlockType[] | null;
+    /** オプションの入力タイプ */
+    type: "select" | "text" | "number" | "boolean";
+    /** select型の場合の選択肢 */
+    options?: BlockOptionChoice[];
+    /** select以外の場合のデフォルト値 */
+    default?: string | number | boolean;
+}
+/**
+ * select型オプションの選択肢
+ */
+export interface BlockOptionChoice {
+    value: string;
+    label: string;
+    /** デフォルト選択かどうか */
+    isDefault?: boolean;
+}
 export interface LunaPlugin {
     name: string;
     version: string;
     description: string;
+    /** プラグインが定義するブロックオプション */
+    blockOptions?: BlockOptionDefinition[];
     /** プラグインインストール時の処理（オプション） */
     onInstall?(api: PluginInstallAPI): Promise<void>;
     /** プラグインアンインストール時の処理（オプション） */
@@ -24,12 +53,12 @@ export interface ScenarioPlaybackData {
     scenarioName: string;
     /** 現在のブロック */
     currentBlock: ScenarioBlock | null;
-    /** 表示中のテキスト */
-    displayText?: string;
+    /** 表示中のテキスト（改行は自動的に<br />に変換されます） */
+    displayText?: string | React.ReactNode;
     /** テキストアニメーション中かどうか */
     isTyping?: boolean;
     /** 表示中のキャラクター */
-    displayedCharacters?: any[];
+    displayedCharacters?: DisplayedCharacter[];
 }
 /**
  * バックログデータ
@@ -73,6 +102,17 @@ export interface PluginAssetsData {
      */
     getAssetUrl: (pluginName: string, filename: string) => string;
 }
+/**
+ * フォントデータ
+ */
+export interface FontsData {
+    /** 利用可能なフォント一覧 */
+    fonts: WorkFont[];
+    /** 選択されているフォントファミリー */
+    selectedFontFamily: string | undefined;
+    /** フォントが読み込み完了しているかどうか */
+    isLoaded: boolean;
+}
 /**
  * 全データコンテキスト
  */
@@ -85,6 +125,16 @@ export interface DataContext {
     settings: PlayerSettingsData;
     /** プラグインアセット */
     pluginAssets: PluginAssetsData;
+    /** 会話分岐データ */
+    branchData?: ConversationBranchState;
+    /** 分岐履歴 */
+    branchHistory?: BranchChoiceHistory[];
+    /** 現在の背景データ（単一、後方互換性用） */
+    background?: BackgroundData | null;
+    /** 現在の背景データ（複数、背景グループ対応） */
+    backgrounds?: BackgroundData[];
+    /** フォント設定 */
+    fonts?: FontsData;
 }
 /**
  * データ購読コールバック
@@ -173,6 +223,63 @@ export interface DataAPI {
      * @param settings - 更新する設定値（部分更新可能）
      */
     updateSettings(settings: Partial<PlayerSettingsData>): void;
+    /**
+     * BGM音量を設定
+     * @param volume - 音量（0-1の範囲）
+     */
+    setBgmVolume(volume: number): void;
+    /**
+     * SE音量を設定
+     * @param volume - 音量（0-1の範囲）
+     */
+    setSeVolume(volume: number): void;
+    /**
+     * ボイス音量を設定
+     * @param volume - 音量（0-1の範囲）
+     */
+    setVoiceVolume(volume: number): void;
+    /**
+     * 全カテゴリの音量を一括設定
+     * @param volumes - カテゴリ別音量設定
+     */
+    setVolumes(volumes: {
+        bgm?: number;
+        se?: number;
+        voice?: number;
+    }): void;
+    /**
+     * 現在のブロックのオプション値を型安全に取得
+     *
+     * @example
+     * ```typescript
+     * // プラグイン側で型を定義
+     * type MyBlockOptions = {
+     *   ultemist_bubble_style: "normal" | "monologue" | "star";
+     *   ultemist_effect_type: "none" | "shake" | "fade";
+     * };
+     *
+     * // コンポーネントで使用
+     * const bubbleStyle = dataAPI.getBlockOption<MyBlockOptions, "ultemist_bubble_style">("ultemist_bubble_style");
+     * // 型: "normal" | "monologue" | "star" | undefined
+     *
+     * // または簡易版（キーのみ指定）
+     * const bubbleStyle = dataAPI.getBlockOption<MyBlockOptions>("ultemist_bubble_style");
+     * ```
+     *
+     * @param key - オプションのキー
+     * @returns オプションの値、または未設定の場合undefined
+     */
+    getBlockOption<T extends Record<string, unknown>, K extends keyof T = keyof T>(key: K): T[K] | undefined;
+}
+/**
+ * ブロックオプション登録API
+ */
+export interface BlockOptionsAPI {
+    /**
+     * ブロックオプションを登録
+     * @param definition - ブロックオプションの定義
+     */
+    register(definition: BlockOptionDefinition): void;
 }
 export interface PluginAPI {
     style: StyleAPI;
@@ -184,9 +291,18 @@ export interface PluginAPI {
     components: ComponentAPI;
     data: DataAPI;
     ui: UIAPI;
+    blockOptions: BlockOptionsAPI;
     React: typeof React;
     setNextCharacterSpeakHandler(callback: (context: CharacterSpeakContext) => void): void;
     getConfig?(): unknown;
+    selectChoice?(choiceId: string): void;
+    getBranchState?(): ConversationBranchState | null;
+    /**
+     * ビルトインのクリック音を上書き
+     * プラグインが独自のクリック音を再生する場合に呼び出す
+     * onBlockChangeフック内で呼び出すことで、そのブロック遷移でのビルトインクリック音を抑制する
+     */
+    overrideClickSound?(): void;
 }
 export interface StyleAPI {
     elements: {
@@ -196,6 +312,8 @@ export interface StyleAPI {
         gameScreen: StyleElement;
         characterSprite: StyleElement;
         background: StyleElement;
+        fullscreenTextOverlay: StyleElement;
+        fullscreenTextContainer: StyleElement;
     };
     injectCSS(css: string): void;
     enableTailwind(): void;
@@ -230,7 +348,7 @@ export interface AttributeDefinition {
     name: string;
     type: "text" | "textarea" | "number" | "select" | "entity";
     label: string;
-    default?: any;
+    default?: string | number | boolean;
     required?: boolean;
     placeholder?: string;
     min?: number;
@@ -277,7 +395,7 @@ export interface ObjectAttributeDefinition {
     displayName: string;
     dataType: "string" | "number" | "boolean" | "text";
     isRequired: boolean;
-    defaultValue?: any;
+    defaultValue?: string | number | boolean;
     sortOrder?: number;
 }
 /** 簡易的なオブジェクトタイプ情報 */
@@ -299,16 +417,23 @@ export interface PluginHooks {
     onScenarioReady(callback: (context: ScenarioReadyContext) => void): void;
     onBlockChange(callback: (context: BlockChangeContext) => void): void;
     onCharacterEnter(callback: (context: CharacterContext) => void): void;
-    onCharacterExit(callback: (context: CharacterContext) => void): void;
     onDialogueShow(callback: (context: DialogueContext) => void): void;
     onActionExecute(callback: (context: ActionExecutionContext) => void): void;
     onScenarioStart(callback: (context: ScenarioContext) => void): void;
     onScenarioEnd(callback: (context: ScenarioContext) => void): void;
+    onBranchStart?(callback: (context: BranchStartContext) => void): void;
+    onChoiceSelected?(callback: (context: ChoiceSelectedContext) => void): void;
+    onBranchEnd?(callback: () => void): void;
+    onBranchBlockChange?(callback: (context: BranchBlockChangeContext) => void): void;
 }
+/** 遷移の種類 */
+export type TransitionSource = "click" | "auto" | "time_wait";
 export interface BlockChangeContext {
     previousBlock?: ScenarioBlock;
     currentBlock: ScenarioBlock;
     blockIndex: number;
+    /** 遷移の種類（クリック、自動、時間待ち） */
+    transitionSource?: TransitionSource;
 }
 export interface CharacterContext {
     character: Character;
@@ -363,6 +488,22 @@ export interface ScenarioReadyContext {
     currentBlockIndex: number;
     currentBlock: ScenarioBlock;
 }
+export interface BranchStartContext {
+    branchBlockId: string;
+    choices: Array<{
+        id: string;
+        text: string;
+        order: number;
+    }>;
+}
+export interface ChoiceSelectedContext {
+    choiceId: string;
+    choiceText: string;
+}
+export interface BranchBlockChangeContext {
+    blockIndex: number;
+    block: ScenarioBlock;
+}
 export interface EffectAPI {
     show(options: EffectOptions): string;
     hide(effectId: string): void;
@@ -377,8 +518,8 @@ export interface EffectOptions {
     animation?: "fade" | "slide" | "bounce" | "none";
 }
 export interface StorageAPI {
-    get<T = any>(key: string): T | null;
-    set<T = any>(key: string, value: T): void;
+    get<T = unknown>(key: string): T | null;
+    set<T = unknown>(key: string, value: T): void;
     remove(key: string): void;
     clear(): void;
 }
@@ -387,6 +528,12 @@ export interface AssetAPI {
     preload(filenames: string[]): Promise<void>;
     playSound(filename: string, options?: SoundOptions): void;
     stopSound(filename: string): void;
+    /**
+     * 作品のサウンドをIDで再生
+     * @param soundId - 作品に登録されたサウンドのID
+     * @param options - 再生オプション（音量、ループなど）
+     */
+    playWorkSound(soundId: string, options?: SoundOptions): void;
 }
 export interface SoundOptions {
     volume?: number;
@@ -403,7 +550,10 @@ export declare enum ComponentType {
     LoadMenu = "LoadMenu",
     SettingsMenu = "SettingsMenu",
     GameMenu = "GameMenu",
-    Config = "Config"
+    Config = "Config",
+    ConversationBranch = "ConversationBranch",
+    Background = "Background",
+    FullscreenTextBox = "FullscreenTextBox"
 }
 /**
  * コンポーネント登録API
@@ -412,24 +562,17 @@ export declare enum ComponentType {
 export interface ComponentAPI {
     registerComponent(type: ComponentType, component: React.ComponentType): void;
 }
-export type { BacklogEntry };
-export interface DisplayedCharacter {
-    objectId: string;
-    stateId?: string;
-    position?: {
-        x: number;
-        y: number;
-    };
-    scale?: number;
-}
+export type { BacklogEntry, DisplayedCharacter } from "./types";
 export interface PlayerSettings {
     textSpeed: number;
     autoPlaySpeed: number;
     bgmVolume: number;
     seVolume: number;
     voiceVolume: number;
+    /** 選択されたフォントファミリー */
+    selectedFontFamily?: string;
 }
-export type { ScenarioBlock, Character, EntityState, ActionNode };
+export type { ActionNode, BackgroundData, BackgroundGroupData, BackgroundGroupItem, BackgroundMediaType, BlockOptions, Character, EntityState, FontType, ScenarioBlock, ScenarioBlockType, WorkFont, } from "./types";
 export declare function definePlugin(plugin: LunaPlugin): LunaPlugin;
 export declare function defineComponent(type: ComponentType, component: React.ComponentType): {
     type: ComponentType;
@@ -515,3 +658,17 @@ export declare function useScreenSizeAtom(): [
 ];
 export { OverlayUI } from "./components/OverlayUI";
 export { aspectRatio, BasisHeight, BasisWidth } from "./constants/screen-size";
+/**
+ * テキスト内の改行文字（\n）を<br />タグに変換してReact要素を返す
+ * プラグインがDialogueBoxなどのコンポーネントでテキストを表示する際に使用
+ *
+ * @param text 表示するテキスト（改行文字を含む可能性がある）
+ * @returns 改行が<br />タグに変換されたReact要素
+ *
+ * @example
+ * ```tsx
+ * const content = dataAPI.get("playback", "displayText") || "";
+ * return <div>{renderTextWithLineBreaks(content)}</div>;
+ * ```
+ */
+export declare function renderTextWithLineBreaks(text: string): React.ReactElement | string;

package/dist/sdk.js

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 // SDK exports for plugin development
 // This file contains all types and utilities needed for plugin development
 import React from "react";
@@ -15,6 +14,9 @@ export var ComponentType;
     ComponentType["SettingsMenu"] = "SettingsMenu";
     ComponentType["GameMenu"] = "GameMenu";
     ComponentType["Config"] = "Config";
+    ComponentType["ConversationBranch"] = "ConversationBranch";
+    ComponentType["Background"] = "Background";
+    ComponentType["FullscreenTextBox"] = "FullscreenTextBox";
 })(ComponentType || (ComponentType = {}));
 // Component types are already exported as part of the interfaces above
 // Plugin utility function
@@ -47,7 +49,6 @@ export function calculateFaceRelativePosition(options) {
         case "chin":
             baseY = facePosition.y + facePosition.height * 0.3;
             break;
-        case "center":
         default:
             // Use face center as is
             break;
@@ -62,3 +63,27 @@ export { React };
 export { OverlayUI } from "./components/OverlayUI";
 // Screen size constants
 export { aspectRatio, BasisHeight, BasisWidth } from "./constants/screen-size";
+// ============================================================================
+// Text Utilities - テキスト処理ユーティリティ
+// ============================================================================
+/**
+ * テキスト内の改行文字（\n）を<br />タグに変換してReact要素を返す
+ * プラグインがDialogueBoxなどのコンポーネントでテキストを表示する際に使用
+ *
+ * @param text 表示するテキスト（改行文字を含む可能性がある）
+ * @returns 改行が<br />タグに変換されたReact要素
+ *
+ * @example
+ * ```tsx
+ * const content = dataAPI.get("playback", "displayText") || "";
+ * return <div>{renderTextWithLineBreaks(content)}</div>;
+ * ```
+ */
+export function renderTextWithLineBreaks(text) {
+    if (!text.includes("\n")) {
+        return text;
+    }
+    return React.createElement(React.Fragment, null, text
+        .split("\n")
+        .map((line, index, array) => React.createElement("span", { key: index }, line, index < array.length - 1 && React.createElement("br"))));
+}