@luna-editor/engine 0.2.0 → 0.3.1

package/dist/sdk.d.ts

@@ -1,120 +1,49 @@
 import React from "react";
-import type { ActionNode, BacklogEntry, Character, EntityState, ScenarioBlock } from "./types";
+import { useDataAPI } from "./contexts/DataContext";
+import type { DataAPI, DataContext, DataSubscriber } from "./data-api-types";
+import type { FacePosition } from "./emotion-effect-types";
+import type { Character, ConversationBranchState, EntityState, ScenarioBlock, ScenarioBlockType } 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>;
     /** プラグインアンインストール時の処理（オプション） */
     onUninstall?(api: PluginInstallAPI): Promise<void>;
     setup(api: PluginAPI): void;
 }
-/**
- * シナリオ再生の動的データ
- */
-export interface ScenarioPlaybackData {
-    /** 現在のブロックインデックス（0始まり） */
-    currentBlockIndex: number;
-    /** 総ブロック数 */
-    totalBlocks: number;
-    /** 現在のシナリオID */
-    scenarioId: string;
-    /** シナリオ名 */
-    scenarioName: string;
-    /** 現在のブロック */
-    currentBlock: ScenarioBlock | null;
-    /** 表示中のテキスト */
-    displayText?: string;
-    /** テキストアニメーション中かどうか */
-    isTyping?: boolean;
-    /** 表示中のキャラクター */
-    displayedCharacters?: any[];
-}
-/**
- * バックログデータ
- */
-export interface BacklogData {
-    /** バックログエントリ */
-    entries: BacklogEntry[];
-    /** 総エントリ数 */
-    totalEntries: number;
-    /** ログエントリを追加 */
-    addLogEntry?: (entry: BacklogEntry) => void;
-    /** ログをクリア */
-    clearLogs?: () => void;
-}
-/**
- * プレイヤー設定データ
- */
-export interface PlayerSettingsData extends PlayerSettings {
-    /** テキスト速度 (ミリ秒/文字) */
-    textSpeed: number;
-    /** 自動再生速度 (秒) */
-    autoPlaySpeed: number;
-    /** BGM音量 (0-1) */
-    bgmVolume: number;
-    /** SE音量 (0-1) */
-    seVolume: number;
-    /** ボイス音量 (0-1) */
-    voiceVolume: number;
-    /** スキップ設定 */
-    skipMode?: "all" | "unread" | "none";
-}
-/**
- * プラグインアセットデータ
- */
-export interface PluginAssetsData {
-    /**
-     * プラグインのアセットURLを取得
-     * @param pluginName - プラグインのパッケージ名
-     * @param filename - アセットファイル名
-     * @returns アセットのURL
-     */
-    getAssetUrl: (pluginName: string, filename: string) => string;
-}
-/**
- * 全データコンテキスト
- */
-export interface DataContext {
-    /** シナリオ再生情報 */
-    playback: ScenarioPlaybackData;
-    /** バックログ情報 */
-    backlog: BacklogData;
-    /** プレイヤー設定 */
-    settings: PlayerSettingsData;
-    /** プラグインアセット */
-    pluginAssets: PluginAssetsData;
-}
-/**
- * データ購読コールバック
- */
-export type DataSubscriber<T> = (data: T) => void;
-/**
- * データAPI - プラグインからのデータアクセスインターフェース
- *
- * @example Pull型（現在値の取得）
- * ```typescript
- * const blockIndex = api.data.get('playback', 'currentBlockIndex');
- * const playback = api.data.get('playback');
- * ```
- *
- * @example Push型（変更の監視）
- * ```typescript
- * const unsubscribe = api.data.subscribe('playback', (data) => {
- *   console.log('Playback updated:', data);
- * });
- * // cleanup
- * unsubscribe();
- * ```
- *
- * @example プロパティ単位での監視
- * ```typescript
- * api.data.watch('playback', 'currentBlockIndex', (index) => {
- *   console.log('Block changed to:', index);
- * });
- * ```
- */
+export type { BacklogData, FontsData, PlayerSettingsData, PluginAssetsData, ScenarioPlaybackData, } from "./data-api-types";
+export type { DataAPI, DataContext, DataSubscriber };
 /**
  * UI表示管理API - プラグインUIコンポーネントの表示/非表示を制御
  */
@@ -141,38 +70,15 @@ export interface UIAPI {
      */
     isVisible(type: ComponentType): boolean;
 }
-export interface DataAPI {
-    /**
-     * データの現在値を取得（Pull型）
-     * @param key - データカテゴリ
-     */
-    get<K extends keyof DataContext>(key: K): DataContext[K];
-    /**
-     * データの特定プロパティを取得（Pull型）
-     * @param key - データカテゴリ
-     * @param property - プロパティ名
-     */
-    get<K extends keyof DataContext, P extends keyof DataContext[K]>(key: K, property: P): DataContext[K][P];
-    /**
-     * データカテゴリ全体の変更を監視（Push型）
-     * @param key - データカテゴリ
-     * @param callback - 変更時のコールバック
-     * @returns unsubscribe関数
-     */
-    subscribe<K extends keyof DataContext>(key: K, callback: DataSubscriber<DataContext[K]>): () => void;
-    /**
-     * 特定プロパティの変更を監視（Push型）
-     * @param key - データカテゴリ
-     * @param property - プロパティ名
-     * @param callback - 変更時のコールバック
-     * @returns unsubscribe関数
-     */
-    watch<K extends keyof DataContext, P extends keyof DataContext[K]>(key: K, property: P, callback: DataSubscriber<DataContext[K][P]>): () => void;
+/**
+ * ブロックオプション登録API
+ */
+export interface BlockOptionsAPI {
     /**
-     * プレイヤー設定を更新
-     * @param settings - 更新する設定値（部分更新可能）
+     * ブロックオプションを登録
+     * @param definition - ブロックオプションの定義
      */
-    updateSettings(settings: Partial<PlayerSettingsData>): void;
+    register(definition: BlockOptionDefinition): void;
 }
 export interface PluginAPI {
     style: StyleAPI;
@@ -184,9 +90,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 +111,8 @@ export interface StyleAPI {
         gameScreen: StyleElement;
         characterSprite: StyleElement;
         background: StyleElement;
+        fullscreenTextOverlay: StyleElement;
+        fullscreenTextContainer: StyleElement;
     };
     injectCSS(css: string): void;
     enableTailwind(): void;
@@ -230,7 +147,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 +194,7 @@ export interface ObjectAttributeDefinition {
     displayName: string;
     dataType: "string" | "number" | "boolean" | "text";
     isRequired: boolean;
-    defaultValue?: any;
+    defaultValue?: string | number | boolean;
     sortOrder?: number;
 }
 /** 簡易的なオブジェクトタイプ情報 */
@@ -299,16 +216,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;
@@ -341,12 +265,15 @@ export interface CharacterSpeakContext {
         id?: string;
         name?: string;
     };
-    facePosition?: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
+    /**
+     * 【機能概要】: 顔位置情報（感情エフェクト用）
+     * 【実装方針】: インライン定義からFacePosition型に変更し、型の再利用性を向上
+     * 【テスト対応】: TC-009を通すための実装
+     * 🔵 信頼性レベル: note.md（行301-308）の推奨事項に基づく
+     *
+     * @see FacePosition - 完全な型定義は emotion-effect-types.ts を参照
+     */
+    facePosition?: FacePosition;
 }
 export interface ScenarioContext {
     scenario: {
@@ -363,6 +290,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 +320,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 +330,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,33 +352,41 @@ export declare enum ComponentType {
     LoadMenu = "LoadMenu",
     SettingsMenu = "SettingsMenu",
     GameMenu = "GameMenu",
-    Config = "Config"
+    Config = "Config",
+    ConversationBranch = "ConversationBranch",
+    Background = "Background",
+    FullscreenTextBox = "FullscreenTextBox",
+    /**
+     * 【機能概要】: 感情エフェクトコンポーネント登録用の型定義
+     * 【実装方針】: 既存のComponentType値と同じパターン（PascalCase、文字列リテラル型）で追加
+     * 【テスト対応】: TC-001, TC-003, TC-004, TC-012を通すための実装
+     * 🔵 信頼性レベル: タスクノート、要件定義書、設計文書に明確に定義されている
+     *
+     * @see EmotionEffectState - 関連する型定義は emotion-effect-types.ts を参照
+     */
+    EmotionEffect = "EmotionEffect"
 }
 /**
  * コンポーネント登録API
- * すべてのデータはDataContext経由で提供されるため、propsは使用しません
+ * DataAPIはPluginComponentProviderから自動的にpropsとして渡されます
  */
 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;
+    registerComponent(type: ComponentType, component: React.ComponentType<{
+        dataAPI?: DataAPI;
+    }>): void;
 }
+export type { EffectPosition, EmotionEffectPosition, EmotionEffectState, EmotionType, FacePosition, PositionType, } from "./emotion-effect-types";
+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;
@@ -454,7 +411,7 @@ export declare function calculateFaceRelativePosition(options: FaceRelativeEffec
     x: number;
     y: number;
 };
-export { React };
+export { React, useDataAPI };
 /**
  * 画面サイズ変換ユーティリティの型定義
  */
@@ -515,3 +472,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,7 +1,7 @@
-/* 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";
+import { useDataAPI } from "./contexts/DataContext";
 // Component registration types
 export var ComponentType;
 (function (ComponentType) {
@@ -15,6 +15,18 @@ export var ComponentType;
     ComponentType["SettingsMenu"] = "SettingsMenu";
     ComponentType["GameMenu"] = "GameMenu";
     ComponentType["Config"] = "Config";
+    ComponentType["ConversationBranch"] = "ConversationBranch";
+    ComponentType["Background"] = "Background";
+    ComponentType["FullscreenTextBox"] = "FullscreenTextBox";
+    /**
+     * 【機能概要】: 感情エフェクトコンポーネント登録用の型定義
+     * 【実装方針】: 既存のComponentType値と同じパターン（PascalCase、文字列リテラル型）で追加
+     * 【テスト対応】: TC-001, TC-003, TC-004, TC-012を通すための実装
+     * 🔵 信頼性レベル: タスクノート、要件定義書、設計文書に明確に定義されている
+     *
+     * @see EmotionEffectState - 関連する型定義は emotion-effect-types.ts を参照
+     */
+    ComponentType["EmotionEffect"] = "EmotionEffect";
 })(ComponentType || (ComponentType = {}));
 // Component types are already exported as part of the interfaces above
 // Plugin utility function
@@ -47,7 +59,6 @@ export function calculateFaceRelativePosition(options) {
         case "chin":
             baseY = facePosition.y + facePosition.height * 0.3;
             break;
-        case "center":
         default:
             // Use face center as is
             break;
@@ -57,8 +68,32 @@ export function calculateFaceRelativePosition(options) {
         y: baseY + offsetY,
     };
 }
-// Export React for plugin use
-export { React };
+// Export React and hooks for plugin use
+export { React, useDataAPI };
 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"))));
+}