[LEGACY]Ikagaka Shell API[OLD]

Ikagaka Shell APIについて

Ikagaka Shell API は SakuraScript のうち、シェル描画に関係するものを取り出し API 化したものです。

Ikagaka Shell API はベースウェアとシェル描画エンジンを分離し、疎結合にします。これにより、 Shell 描画エンジンだけを抜き出して、シェル作成用の Web アプリが作れるようになります。従来の PNG を利用したシェルだけでなく、SVG シェルや 3D シェル、物理ロボットシェル、合成音声バルーンなどへの拡張が考えられるようになります。

Ikagaka Shell API は Web ブラウザ (HTML5, DOM level 4, ES6 相当) 環境で伺かのシェルを描画するための API です。

Ikagaka Shell API は Web ブラウザを動作環境とすることで移植性を高めています。 Web ブラウザだけでなく、nw.jsやelectron、Apache Cordovaなどを使うことにより、デスクトップ、タブレット、スマートフォンなどのあらゆる GUI 環境で動作させることができます。

Ikagaka Shell API の使用例

var nmdmgr = new Ikagaka.Shell.NamedManager();
var shell = new Ikagaka.Shell.Shell(shellDir);
var balloon = new Ikagaka.Shell.Balloon(balloonDir);

var hwnd = nmdmgr.materialize(shell, balloon);
var wait = (ms, fn)=> (named)=>
  new Promise((resolve)=>
    setTimeout(()=>{
      fn(named);
      resolve(named);
    }, ms)
  );

nmdmgr.named(hwnd).load()
.then(wait(0, (named)=> named.scope(0) ))
.then(wait(0, (named)=> named.scope().surface(0) ))
.then(wait(0, (named)=> named.scope().blimp(0) ))
.then(wait(0, (named)=> named.scope().blimp().talk("H") ))
.then(wait(80, (named)=> named.scope().blimp().talk("e") ))
.then(wait(80, (named)=> named.scope().blimp().talk("l") ))
.then(wait(80, (named)=> named.scope().blimp().talk("l") ))
.then(wait(80, (named)=> named.scope().blimp().talk("o") ))
.then(wait(80, (named)=> named.scope().blimp().talk(",") ))
.then(wait(80, (named)=> named.scope().blimp().talk(" ") ))
.then(wait(80, (named)=> named.scope().blimp().talk("W") ))
.then(wait(80, (named)=> named.scope().blimp().talk("o") ))
.then(wait(80, (named)=> named.scope().blimp().talk("r") ))
.then(wait(80, (named)=> named.scope().blimp().talk("l") ))
.then(wait(80, (named)=> named.scope().blimp().talk("d") ))
.then(wait(80, (named)=> named.scope().blimp().talk("!") ))
.then(wait(0, (named)=> named.scopeAll().surface().yenE() ));

Ikagaka って？

Ikagaka と「伺か互換環境の Web ブラウザ上での実装」です。 Ikagaka は Ikagaka API 仕様に基づいて作られています。

Ikagaka API は「伺か互換環境を Web ブラウザ上で動かすための設計図」です。 Ikagaka Shell API は、 Ikagaka API のうち、シェルとバルーンの表示に関する API の設計図です。

Ikagaka Shell API 1.0 (Working Draft)

2015-04-27 時点の仕様草案です。

※この仕様は策定中です。Ikagaka Shell API 1.0 (WD)議論スレッドも参照してください。質問、提案、ご意見お待ちしています。

仕様の記述にはTypeScriptの型定義記法とJadeを利用しています。

Ikagaka.Shell.NamedManager

NamedManager クラスは、複数ゴーストの同時描画を管理するコンポジット型ウィンドウマネージャです。具体的にはゴースト間の重なり処理をします。

declare class NamedManager {
  constructor();
  // コンストラクタです。
  // body>div#namedMgr 要素を作ります。

  destructor(): void;
  // デストラクタです。
  // body>div#namedMgr 要素を消します。

  materialize( shell: Shell, balloon: Balloon ): number;
  // そのゴーストが利用する `div#namedMgr > div.named` 要素を作ります。
  // ゴーストのウィンドウハンドルを返します。

  vanish( namedId: number ): void;
  // ウィンドウハンドルのゴーストを終了します。具体的には、Named API がそのゴーストの描画に利用していたメモリを解放します。
  // このタイミングで scopeAll().destructor() が呼ばれます。
  // そのゴーストが利用していた `div#namedMgr > div.named` を消します。

  named( namedId: number ): NamedObject;
  // ウィンドウハンドルのゴーストを選択し、NamedObjectを返します。
}

NamedManager は body 要素の最後の子要素として以下のような DOM を構築します。

body
  div#namedMgr
    style(scoped)
    div.named
      div.scope
        div.surface
          ...
        div.blimp
          ...
      div.scope
      ...
    div.named
    ...

NamedObject

interface NamedObject {
  load(): Promise<NamedObject>;
  // Shell と Balloon をロードします。
  // Shell#load()とBalloon#load()はこのタイミングで呼ばれます。

  unload(): Promise<NamedObject>;
  // Shell と Balloon をアンロードします。
  // Shell#unload()とBalloon#unload()はこのタイミングで呼ばれます。

  loaded: boolean;
  // ロード済みならば true 、そうでなければ false を返します。

  scope( scopeId?: number ): ScopeObject;
  // スコープ番号の ScopeObject を返します。
  // 省略された場合、最後に呼び出されたスコープ番号の ScopeObject を返します。
  // 初期状態のスコープ番号は 0 です。
  // まだ利用されていないスコープ番号の場合、`div#namedMgr > div.named > div.scope`を随時追加します。
  // 追加されたスコープが利用するメモリは Named#vanish() されるまで解放されません。
  // ロード前に呼ばれた場合、例外を投げます。

  scopeAll(): ScopeObject;
  // 現在利用されているすべてのスコープに対して有効な ScopeObject を返します。

  openInputBox( inputId: string, placeHolder?: string ): void;
  // 入力Boxを開きます。

  openCommunicateBox( placeHolder?: string ): void;
  // コミュニケートBoxを開きます。

  on( eventType: string, callback: (eventObject: Object)=> void ): void;
  // そのゴーストのサーフェスイベント（触り反応）やバルーンイベント(選択肢クリック)、入力Boxイベントのイベントハンドラを登録します。
  // eventType と対応する eventObject は下記の表を参照してください。

  off( eventType: string, callback?: (eventObject: Object)=> void ): void;
  // イベントハンドラを登録抹消します。
  // callbackを指定しなかった場合、そのイベントのすべてのイベントハンドラを登録抹消します。
}

eventType	eventObject
mousedown	button: number, offsetX: number, offsetY: number, region: string, scope: number, type: string, wheel: number
mousemove	button: number, offsetX: number, offsetY: number, region: string, scope: number, type: string, wheel: number
mouseup	button: number, offsetX: number, offsetY: number, region: string, scope: number, type: string, wheel: number
mouseclick	button: number, offsetX: number, offsetY: number, region: string, scope: number, type: string, wheel: number
mousedblclick	button: number, offsetX: number, offsetY: number, region: string, scope: number, type: string, wheel: number
balloonclick	type: string
balloondblclick	type: string
anchorselect	type: string, id: string, text: string, args:string[]
choiceselect	type: string, id: string, text: string, args:string[]
userinput	type: string, id: string, content:string\|null
communicateinput	type: string, sender: string, content:string\|null

ScopeObject

interface ScopeObject {
  surface( surfaceId?: number ): SurfaceObject;
  // サーフェス番号の SurfaceObject を返します。
  // 省略された場合、最後に呼び出されたサーフェス番号の SurfaceObject を返します。
  // 初期状態のサーフェス番号は -1 です。
  // もしサーフェス番号が変わった場合、Shell#attatchSurface() を呼び出してシェル描画エンジンにサーフェスチェンジを促します。

  blimp( balloonSurfaceId?: number ): BlimpObject;
  // サーフェス番号の BlimpObject を返します。
  // 省略された場合、最後に呼び出されたサーフェス番号の BlimpObject を返します。
  // 初期状態のサーフェス番号は -1 です。
  // もしサーフェス番号が変わった場合、Balloon#attatchBlimp() を呼び出してバルーン描画エンジンにバルーンサーフェスチェンジを促します。

}

Ikagaka.Shell.Shell

Shell クラスは各シェルライブラリが満たすべきAPI仕様です。このAPI仕様を満たしていればIkagaka Named APIのシェル描画エンジンとして動作させることができます。 Shell描画エンジンに与えられる非同期処理の機会は load, unload 呼び出し時のみです。サーフェスチェンジは同期的に処理されることが要求されます。

declare class Shell {
  constructor( directory: { [filepath: string]: ArrayBuffer; } ): Shell;
  load(): Promise<Shell>;
  // 与えられたファイルを利用してサーフェス描画の準備を行ってください。
  // 非同期の読み込み処理等はこの機会に全て済ませるようにしてください。

  unload(): Promise<Shell>;
  // アンロード処理を行ってください。具体的には、メモリの解放などです。

  on( eventType: string, callback: (eventObject: Object)=> void ): void;
  off( eventType: string, callback?: (eventObject: Object)=> void ): void;
  // Named APIから呼ばれる、マウスイベントなどのハンドラを登録します。
  // 上記の eventType、eventObject 対応表に従ってください。

  attatchSurface( element: HTMLElement, scopeId: number, surfaceId: number|string ): SurfaceObject;
  // element には `div#namedMgr > div.named > div.scope > div.surface` が渡されます。
  // シェル描画エンジンはその中に canvas 要素や SVG 要素などを入れて利用してください。
  // scopeId はそのサーフェスが描画されるスコープIDです。サーフェスエイリアスを使うときなどに利用してください。
  // surfaceId の型が number なら、そのサーフェスIDのサーフェスを描画してください。
  // surfaceId の型が string なら、それはサーフェスエイリアスです。エイリアスが指定するサーフェスを選択して描画してください。
}

SurfaceObject

interface SurfaceObject {
  talk(): void;
  // talk アニメーション実行のタイミングです。

  yenE(): void;
  // yen-e アニメーション実行のタイミングです。

  play( animationId: number, callback?: () => void ): void;
  // animationId のアニメーションを再生してください。

  stop( animationId: number ): void;
  // animationId のアニメーションを停止してください。

  bind( animationId: number ): void;
  // animationId の着せ替えを着てください。

  unbind( animationId: number ): void;
  // animationId の着せ替えを脱いでください。
}

Ikagaka.Shell.Balloon

Balloonクラスはバルーンシェルライブラリが満たすべきAPI仕様です。このAPI仕様を満たしていればIkagaka Named APIのシェル描画エンジンとして動作させることができます。

declare class Balloon {
  constructor( directory: { [filepath: string]: ArrayBuffer; } ): Balloon;
  load(): Promise<Balloon>;
  unload(): Promise<Balloon>;
  on( eventType: string, callback: (eventObject: Object)=> void ): void;
  off( eventType: string, callback?: (eventObject: Object)=> void ): void;
  attatchBlimp( element: HTMLElement, scopeId: number, balloonSurfaceId: number ): BlimpObject;
}

BlimpObject

一般的にバルーンサーフェスと呼ばれるものです。 BalloonSurfaceでは長くSurfaceと紛らわしいのでblimpという名前にしました。異論は認めます。

interface BlimpObject {
  talk( text: string ): void;
  br( ratio?: number ): void;
  clear(): void;
  choice( label: string, choiceId: string, ...args: string[] ): void;
  choiceBegin( choiceId: string, ...args: string[] ): void;
  choiceEnd(): void;
  anchorBegin( anchorId: string, ...args: string[] ): void;
  anchorEnd(): void;
  location( x: number, y?: number ): void;
  marker(): void;
  showWait(): void;
}

Ikagaka Shell API 1.0 と SakuraScript の対応表

一部

SakuraScript	Ikagaka Named API 1.0
\p[]	Named#scope()
\s[]	Named#scope().surface()
\i[]	Named#scope().surface().play()
\b[]	Named#scope().blimp()
talk	Named#scope().blimp().talk()
\n	Named#scope().blimp().br()
\c	Named#scope().blimp().clear()
\q[]	Named#scope().blimp().choice()

Provide feedback

Saved searches

Use saved searches to filter your results more quickly